Cursor (Carbonado 1.2.3 API)

All Known Implementing Classes:

AbstractCursor, ControllerCursor, DifferenceCursor, EmptyCursor, FetchAheadCursor, 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

Methods
Modifier and Type	Method and Description
`void`	`close()` Call close to release any resources being held by this cursor.
`int`	`copyInto(java.util.Collection<? super S> c)` Copies all remaining next elements into the given collection.
`int`	`copyInto(java.util.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.
`java.util.List<S>`	`toList()` Copies all remaining next elements into a new modifiable list.
`java.util.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
    
    java.util.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
    
    java.lang.IllegalArgumentException - if amount is negative
  - copyInto
```
int copyInto(java.util.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(java.util.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
    
    java.lang.IllegalArgumentException - if limit is negative
  - toList
```
java.util.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
```
java.util.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
    
    java.lang.IllegalArgumentException - if limit is negative

Interface Cursor<S>

Method Summary

Method Detail

close

hasNext

next

skipNext

copyInto

copyInto

toList

toList