messif.buckets.index.impl
Class AbstractSearch<C,T>

java.lang.Object
  extended by messif.buckets.index.impl.AbstractSearch<C,T>
Type Parameters:
C - the type the boundaries used by the search
T - the type of objects that this Search searches for
All Implemented Interfaces:
java.lang.Cloneable, Search<T>

public abstract class AbstractSearch<C,T>
extends java.lang.Object
implements Search<T>, java.lang.Cloneable

This class represents a search on an index. Search parameters are specified in the constructor, namely the objects are searched using the specified comparator that is checked on the [from, to] boundaries. Specifically, all objects that are bigger or equal to from and smaller or equal to to are returned, i.e. comparator.indexCompare(from, o) &lp= 0 and comparator.indexCompare(to, o) == 0 holds.

The comparator.indexCompare method will always have the from/to attributes passesed as the first argument and the object that is checked as the second argument.

See Also:
Index

Constructor Summary
protected AbstractSearch(IndexComparator<? super C,? super T> comparator, C fromKey, C toKey)
          Creates a new instance of Search for the specified search comparator and lower and upper key bounds.
protected AbstractSearch(IndexComparator<? super C,? super T> comparator, java.util.Collection<? extends C> keys)
          Creates a new instance of Search for the specified search comparator and keys to search.
 
Method Summary
 AbstractSearch<C,T> clone()
          Creates and returns a copy of this search.
 IndexComparator<? super C,? super T> getComparator()
          Returns the comparator that this search uses on keys.
 T getCurrentObject()
          Returns the object found by the last search.
protected  C getKey(int index)
          Returns the key with specified index.
protected  int getKeyCount()
          Returns the number of keys that this search currently searches for.
protected  boolean checkKeys(T object)
          Checks if the specified object satisfies the given keys (either boundaries or equality).
protected  boolean isKeyBounds()
          Returns true if the searched keys are treated as bounds.
 boolean next()
          Searches for the next object (forward search) and returns false if none is found.
 boolean previous()
          Searches for the previous object (backward search) and returns false if none is found.
protected abstract  T readNext()
          Returns the next sibling object of the current one.
protected abstract  T readPrevious()
          Returns the previous sibling object of the current one.
 boolean skip(int count)
          Skips count objects using Search.next() or Search.previous() search and returns false if count objects cannot be skipped.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface messif.buckets.index.Search
close
 

Constructor Detail

AbstractSearch

protected AbstractSearch(IndexComparator<? super C,? super T> comparator,
                         java.util.Collection<? extends C> keys)
Creates a new instance of Search for the specified search comparator and keys to search. Any object the key of which is equal (according to the given comparator) to any of the keys is returned.

Parameters:
comparator - the comparator that is used to compare the keys
keys - list of keys to search for

AbstractSearch

protected AbstractSearch(IndexComparator<? super C,? super T> comparator,
                         C fromKey,
                         C toKey)
Creates a new instance of Search for the specified search comparator and lower and upper key bounds. Any object the key of which is within interval [fromKey, toKey] is returned.

Parameters:
comparator - the comparator that is used to compare the keys
fromKey - the lower bound on the searched object keys (inclusive)
toKey - the upper bound on the searched object keys (inclusive)
Method Detail

getComparator

public IndexComparator<? super C,? super T> getComparator()
Returns the comparator that this search uses on keys.

Returns:
the comparator that this search uses on keys

isKeyBounds

protected boolean isKeyBounds()
Returns true if the searched keys are treated as bounds. Or false if the search returns object only for the given keys.

Returns:
true if the searched keys are treated as bounds or false if the search returns object only for the given keys

getKeyCount

protected int getKeyCount()
Returns the number of keys that this search currently searches for.

Returns:
the number of keys

getKey

protected C getKey(int index)
            throws java.lang.IndexOutOfBoundsException
Returns the key with specified index. The index must be greater than or equal to 0 and less than getKeyCount().

Parameters:
index - the index of the key to return
Returns:
a searched key
Throws:
java.lang.IndexOutOfBoundsException - if the specified index is less than zero or bigger than or equal to getKeyCount()

getCurrentObject

public T getCurrentObject()
Description copied from interface: Search
Returns the object found by the last search. That is, if method Search.next() or Search.previous() has returned true, this method returns the matching object. If false has been returned, this method throws an IllegalStateException.

Specified by:
getCurrentObject in interface Search<T>
Returns:
the object found by the last search

next

public boolean next()
             throws java.lang.IllegalStateException
Description copied from interface: Search
Searches for the next object (forward search) and returns false if none is found. Otherwise, the found object can be retrieved by Search.getCurrentObject().

Specified by:
next in interface Search<T>
Returns:
true if a next satisfying object is found
Throws:
java.lang.IllegalStateException - if there was a problem retrieving the next object from the underlying storage

skip

public boolean skip(int count)
             throws java.lang.IllegalStateException
Description copied from interface: Search
Skips count objects using Search.next() or Search.previous() search and returns false if count objects cannot be skipped. Otherwise, the found object can be retrieved by Search.getCurrentObject().

Note that this is equivalent to calling Search.next() or Search.previous() while true is returned up to count times. So if the method returns false, the Search.getCurrentObject() may not return a valid object.

Specified by:
skip in interface Search<T>
Parameters:
count - number of objects to skip, i.e. the number of calls to Search.next() if count is positive or Search.previous() if count is negative
Returns:
true if the count objects has been skipped
Throws:
java.lang.IllegalStateException - if there was a problem retrieving the next/previous object from the underlying storage

previous

public boolean previous()
                 throws java.lang.IllegalStateException
Description copied from interface: Search
Searches for the previous object (backward search) and returns false if none is found. Otherwise, the found object can be retrieved by Search.getCurrentObject().

Specified by:
previous in interface Search<T>
Returns:
true if a previous satisfying object is found
Throws:
java.lang.IllegalStateException - if there was a problem retrieving the next object from the underlying storage

checkKeys

protected boolean checkKeys(T object)
Checks if the specified object satisfies the given keys (either boundaries or equality). If the comparator is null or no keys are specified, the check succeeds.

Parameters:
object - the object to check the boundaries for
Returns:
true if object satisfies the keys

readNext

protected abstract T readNext()
                       throws BucketStorageException
Returns the next sibling object of the current one. No checks on boundaries are required. If there is no next object, null is returned.

Returns:
the next sibling object of the current one
Throws:
BucketStorageException - if there was a problem retrieving the next object from the underlying storage

readPrevious

protected abstract T readPrevious()
                           throws BucketStorageException
Returns the previous sibling object of the current one. No checks on boundaries are required. If there is no previous object, null is returned.

Returns:
the previous sibling object of the current one
Throws:
BucketStorageException - if there was a problem retrieving the previous object from the underlying storage

clone

public AbstractSearch<C,T> clone()
                          throws java.lang.CloneNotSupportedException
Description copied from interface: Search
Creates and returns a copy of this search. The new search instance retains the search state at the time of clonning, thus continuing the search via calls to Search.next() or Search.previous() will return the same values as for the original search.

In practice, the clonned search is often used to do the search in both directions from the same starting point.

Specified by:
clone in interface Search<T>
Overrides:
clone in class java.lang.Object
Returns:
a clonned instance of this search
Throws:
java.lang.CloneNotSupportedException - if this search cannot be cloned