org.grouplens.lenskit.cursors

Interface Cursor<T>

Type Parameters:

T - The type of data returned by the cursor

All Superinterfaces:

AutoCloseable, Closeable, Iterable<T>

All Known Implementing Classes:

AbstractCursor, AbstractPollingCursor

public interface Cursor<T>
extends Iterable<T>, Closeable

Cursors over data connections. These are basically closable iterators which also implement Iterable for convenience. Cursors are not allowed to contain null elements.

Note that the Iterable.iterator() method does not return a fresh iterator but rather a wrapper of this cursor; it is only present to allow for-each loops over cursors. After it is exhausted, any iterator returned will be null.

This class does not implement Iterator because the 'is-a' relationship does not hold; cursors must be closed by their clients while iterators do not have such a requirement.

Author:

GroupLens Research

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Close the cursor.
Iterable<T>	fast() Convert the cursor to an iterable whose Iterator.next() method is implemented in terms of fastNext().
T	fastNext() Variant of next() that may mutate and return the same object avoid excess allocations.
int	getRowCount() Get an upper bound on the number of rows available from the cursor.
boolean	hasNext() Query whether the cursor has any more items.
T	next() Fetch the next item from the cursor.

Methods inherited from interface java.lang.Iterable

iterator

Method Detail

getRowCount

int getRowCount()

Get an upper bound on the number of rows available from the cursor.

Returns:

the maximum number of rows which may be returned by next(), or -1 if that count is not available.

hasNext

boolean hasNext()

Query whether the cursor has any more items. If the cursor or underlying source has been closed, this may return even if the end has not been reached.

Returns:

true if there remains another item to fetch.

next

@Nonnull
T next()

Fetch the next item from the cursor.

Returns:

The next item in the cursor.

Throws:

NoSuchElementException - if there are no more elements.

RuntimeException - if the cursor or its data source have been closed (optional).

fastNext

@Nonnull
T fastNext()

Variant of next() that may mutate and return the same object avoid excess allocations. Since many loops don't do anything with the object after the iteration in which it is retrieved, using this iteration method can improve both speed and memory use.

Returns:

The next element from the cursor, reusing objects if possible.

See Also:

next()

fast

Iterable<T> fast()

Convert the cursor to an iterable whose Iterator.next() method is implemented in terms of fastNext().

Returns:

An iterable for fast iteration.

close

void close()

Close the cursor. This invalidates the cursor; no more elements may be fetched after a call to close() (although implementations are not required to enforce this). It is not an error to close a cursor multiple times.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable