messif.buckets.index
Interface Search<T>

Type Parameters:
T - the type of objects that this Search searches for
All Superinterfaces:
java.lang.Cloneable
All Known Subinterfaces:
IntStorageSearch<T>, LongStorageSearch<T>, ModifiableSearch<T>, StorageSearch<T>
All Known Implementing Classes:
AbstractSearch

public interface Search<T>
extends java.lang.Cloneable

This interface represents an initialized search on an index. It allows to browse the data of an index - use next() and previous() methods to gather the next or previous object of this search. If true is returned, the next/previous found object can be retrieved by getCurrentObject().

See Also:
Index

Method Summary
 Search<T> clone()
          Creates and returns a copy of this search.
 void close()
          Closes this search indicating that no objects will be retrieved.
 T getCurrentObject()
          Returns the object found by the last search.
 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.
 boolean skip(int count)
          Skips count objects using next() or previous() search and returns false if count objects cannot be skipped.
 

Method Detail

getCurrentObject

T getCurrentObject()
                   throws java.lang.IllegalStateException
Returns the object found by the last search. That is, if method next() or previous() has returned true, this method returns the matching object. If false has been returned, this method throws an IllegalStateException.

Returns:
the object found by the last search
Throws:
java.lang.IllegalStateException - if there is no current object (next/previous method was not called or returned false)

next

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

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

previous

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

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

skip

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

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

Parameters:
count - number of objects to skip, i.e. the number of calls to next() if count is positive or 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

clone

Search<T> clone()
                throws java.lang.CloneNotSupportedException
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 next() or 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.

Returns:
a clonned instance of this search
Throws:
java.lang.CloneNotSupportedException - if this search cannot be cloned

close

void close()
Closes this search indicating that no objects will be retrieved. Note that after this method is called, the searching methods (next(), previous(), etc.) should not be called.