com.amazon.carbonado
Interface Cursor<S>

All Known Implementing Classes:

AbstractCursor, DifferenceCursor, EmptyCursor, FilteredCursor, GroupedCursor, IntersectionCursor, IteratorCursor, LimitCursor, MultiTransformedCursor, RawCursor, SingletonCursor, SkipCursor, SortedCursor, SymmetricDifferenceCursor, ThrottledCursor, TransformedCursor, UnionCursor

public interface Cursor<S>

Represents the results of a Query's fetch operation. Cursors must be closed promptly when no longer needed. Failure to do so may result in excessive resource consumption or deadlock. As a convenience, the close operation is automatically performed when the end is reached or when an exception is thrown.

Note: because a Cursor manages resources, it is inapproprate to create a long-lived one and pass it around in your code. A cursor is expected to live close to the Query which vended it. To discourage inappropriate retention, the cursor does not implement methods (like "getQuery" or "reset") which would make it more convenient to operate on in isolation.

Similarly, it is difficult to guarantee that the results of a cursor will be the same in case of a "reset" or reverse iteration. For this reason, neither is supported; if you need to iterate the same set of objects twice, simply retain the query object and reissue it. Be aware that the results may not be identical, if any relevant objects are added to or removed the repository in the interim. To guard against this, operate within a serializable isolation level.

Cursor instances are mutable and not guaranteed to be thread-safe. Only one thread should ever operate on a cursor instance.

Author:

Brian S O'Neill, Don Schneider

Method Summary

void	close() Call close to release any resources being held by this cursor.
int	copyInto(Collection<? super S> c) Copies all remaining next elements into the given collection.
int	copyInto(Collection<? super S> c, int limit) Copies a limited amount of remaining next elements into the given collection.
boolean	hasNext() Returns true if this cursor has more elements.
S	next() Returns the next element from this cursor.
int	skipNext(int amount) Skips forward by the specified amount of elements, returning the actual amount skipped.
List<S>	toList() Copies all remaining next elements into a new modifiable list.
List<S>	toList(int limit) Copies a limited amount of remaining next elements into a new modifiable list.

Method Detail

close

void close()
           throws FetchException

Call close to release any resources being held by this cursor. Further operations on this cursor will behave as if there are no results.

Throws:

FetchException

hasNext

boolean hasNext()
                throws FetchException

Returns true if this cursor has more elements. In other words, returns true if next would return an element rather than throwing an exception.

Throws:

FetchException - if storage layer throws an exception

next

S next()
       throws FetchException

Returns the next element from this cursor. This method may be called repeatedly to iterate through the results.

Throws:

FetchException - if storage layer throws an exception

NoSuchElementException - if the cursor has no next element.

skipNext

int skipNext(int amount)
             throws FetchException

Skips forward by the specified amount of elements, returning the actual amount skipped. The actual amount is less than the requested amount only if the end of the results was reached.

Parameters:

amount - maximum amount of elements to skip

Returns:

actual amount skipped

Throws:

FetchException - if storage layer throws an exception

IllegalArgumentException - if amount is negative

copyInto

int copyInto(Collection<? super S> c)
             throws FetchException

Copies all remaining next elements into the given collection. This method is roughly equivalent to the following:

 Cursor cursor;
 ...
 while (cursor.hasNext()) {
     c.add(cursor.next());
 }
 

As a side-effect of calling this method, the cursor is closed.

Returns:

actual amount of results added

Throws:

FetchException - if storage layer throws an exception

copyInto

int copyInto(Collection<? super S> c,
             int limit)
             throws FetchException

Copies a limited amount of remaining next elements into the given collection. This method is roughly equivalent to the following:

 Cursor cursor;
 ...
 while (--limit >= 0 && cursor.hasNext()) {
     c.add(cursor.next());
 }
 

Parameters:

limit - maximum amount of elements to copy

Returns:

actual amount of results added

Throws:

FetchException - if storage layer throws an exception

IllegalArgumentException - if limit is negative

toList

List<S> toList()
               throws FetchException

Copies all remaining next elements into a new modifiable list. This method is roughly equivalent to the following:

 Cursor<S> cursor;
 ...
 List<S> list = new ...
 cursor.copyInto(list);
 

As a side-effect of calling this method, the cursor is closed.

Returns:

a new modifiable list

Throws:

FetchException - if storage layer throws an exception

toList

List<S> toList(int limit)
               throws FetchException

Copies a limited amount of remaining next elements into a new modifiable list. This method is roughly equivalent to the following:

 Cursor<S> cursor;
 ...
 List<S> list = new ...
 cursor.copyInto(list, limit);
 

Parameters:

limit - maximum amount of elements to copy

Returns:

a new modifiable list

Throws:

FetchException - if storage layer throws an exception

IllegalArgumentException - if limit is negative