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