com.datastax.driver.core

Interface PagingIterable<S extends PagingIterable<S,T>,T>

All Superinterfaces:

Iterable<T>

All Known Subinterfaces:

ResultSet

All Known Implementing Classes:

Result

public interface PagingIterable<S extends PagingIterable<S,T>,T>
extends Iterable<T>

Defines an iterable whose elements can be remotely fetched and paged, possibly asynchronously.

Method Summary

Modifier and Type	Method and Description
List<T>	all() Returns all the remaining rows in this result set as a list.
ListenableFuture<S>	fetchMoreResults() Force fetching the next page of results for this result set, if any.
List<ExecutionInfo>	getAllExecutionInfo() Return the execution information for all queries made to retrieve this result set.
int	getAvailableWithoutFetching() The number of rows that can be retrieved from this result set without blocking to fetch.
ExecutionInfo	getExecutionInfo() Returns information on the execution of the last query made for this result set.
boolean	isExhausted() Returns whether this result set has more results.
boolean	isFullyFetched() Whether all results from this result set have been fetched from the database.
Iterator<T>	iterator() Returns an iterator over the rows contained in this result set.
T	one() Returns the next result from this result set.

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

isExhausted

boolean isExhausted()

Returns whether this result set has more results.

Returns:

whether this result set has more results.

isFullyFetched

boolean isFullyFetched()

Whether all results from this result set have been fetched from the database.

Note that if isFullyFetched(), then getAvailableWithoutFetching() will return how many rows remain in the result set before exhaustion. But please note that !isFullyFetched() never guarantees that the result set is not exhausted (you should call isExhausted() to verify it).

Returns:

whether all results have been fetched.

getAvailableWithoutFetching

int getAvailableWithoutFetching()

The number of rows that can be retrieved from this result set without blocking to fetch.

Returns:

the number of rows readily available in this result set. If isFullyFetched(), this is the total number of rows remaining in this result set (after which the result set will be exhausted).

fetchMoreResults

ListenableFuture<S> fetchMoreResults()

Force fetching the next page of results for this result set, if any.

This method is entirely optional. It will be called automatically while the result set is consumed (through one(), all() or iteration) when needed (i.e. when getAvailableWithoutFetching() == 0 and isFullyFetched() == false).

You can however call this method manually to force the fetching of the next page of results. This can allow to prefetch results before they are strictly needed. For instance, if you want to prefetch the next page of results as soon as there is less than 100 rows readily available in this result set, you can do:

   ResultSet rs = session.execute(...);
   Iterator<Row> iter = rs.iterator();
   while (iter.hasNext()) {
       if (rs.getAvailableWithoutFetching() == 100 && !rs.isFullyFetched())
           rs.fetchMoreResults();
       Row row = iter.next()
       ... process the row ...
   }
 

This method is not blocking, so in the example above, the call to fetchMoreResults will not block the processing of the 100 currently available rows (but iter.hasNext() will block once those rows have been processed until the fetch query returns, if it hasn't yet).

Only one page of results (for a given result set) can be fetched at any given time. If this method is called twice and the query triggered by the first call has not returned yet when the second one is performed, then the 2nd call will simply return a future on the currently in progress query.

Returns:

a future on the completion of fetching the next page of results. If the result set is already fully retrieved (isFullyFetched() == true), then the returned future will return immediately but not particular error will be thrown (you should thus call isFullyFetched() to know if calling this method can be of any use}).

one

T one()

Returns the next result from this result set.

Returns:

the next row in this result set or null if this result set is exhausted.

all

List<T> all()

Returns all the remaining rows in this result set as a list.

Note that, contrary to iterator() or successive calls to one(), this method forces fetching the full content of the result set at once, holding it all in memory in particular. It is thus recommended to prefer iterations through iterator() when possible, especially if the result set can be big.

Returns:

a list containing the remaining results of this result set. The returned list is empty if and only the result set is exhausted. The result set will be exhausted after a call to this method.

iterator

Iterator<T> iterator()

Returns an iterator over the rows contained in this result set.

The Iterator.next() method is equivalent to calling one(). So this iterator will consume results from this result set and after a full iteration, the result set will be empty.

The returned iterator does not support the Iterator.remove() method.

Specified by:

iterator in interface Iterable<T>

Returns:

an iterator that will consume and return the remaining rows of this result set.

getExecutionInfo

ExecutionInfo getExecutionInfo()

Returns information on the execution of the last query made for this result set.

Note that in most cases, a result set is fetched with only one query, but large result sets can be paged and thus be retrieved by multiple queries. In that case this method return the ExecutionInfo for the last query performed. To retrieve the information for all queries, use getAllExecutionInfo().

The returned object includes basic information such as the queried hosts, but also the Cassandra query trace if tracing was enabled for the query.

Returns:

the execution info for the last query made for this result set.

getAllExecutionInfo

List<ExecutionInfo> getAllExecutionInfo()

Return the execution information for all queries made to retrieve this result set.

Unless the result set is large enough to get paged underneath, the returned list will be singleton. If paging has been used however, the returned list contains the ExecutionInfo objects for all the queries done to obtain this result set (at the time of the call) in the order those queries were made.

Returns:

a list of the execution info for all the queries made for this result set.