com.datastax.oss.driver.api.core

Interface PagingIterable<ElementT>

All Superinterfaces:

Iterable<ElementT>

All Known Subinterfaces:

ResultSet

public interface PagingIterable<ElementT>
extends Iterable<ElementT>

An iterable of elements which are fetched synchronously by the driver, possibly in multiple requests.

It uses asynchronous calls internally, but blocks on the results in order to provide a synchronous API to its clients. If the query is paged, only the first page will be fetched initially, and iteration will trigger background fetches of the next pages when necessary.

Note that this object can only be iterated once: elements are "consumed" as they are read, subsequent calls to iterator() will return the same iterator instance.

Implementations of this type are not thread-safe. They can only be iterated by the thread that invoked session.execute.

This is a generalization of ResultSet, replacing rows by an arbitrary element type.

Method Summary

Modifier and Type	Method and Description
default List<ElementT>	all() Returns all the remaining elements as a list; not recommended for queries that return a large number of elements.
int	getAvailableWithoutFetching() The number of elements that can be returned from this result set before a blocking background query needs to be performed to retrieve more results.
ColumnDefinitions	getColumnDefinitions() Metadata about the columns returned by the CQL request that was used to build this result.
default ExecutionInfo	getExecutionInfo() The execution information for the last query performed for this iterable.
List<ExecutionInfo>	getExecutionInfos() The execution information for all the queries that have been performed so far to assemble this iterable.
boolean	isFullyFetched() Whether all pages have been fetched from the database.
default <TargetElementT> PagingIterable<TargetElementT>	map(Function<? super ElementT,? extends TargetElementT> elementMapper) Creates a new instance by transforming each element of this iterable with the provided function.
default ElementT	one() Returns the next element, or null if the iterable is exhausted.
default Spliterator<ElementT>	spliterator()
boolean	wasApplied() If the query that produced this result was a CQL conditional update, indicate whether it was successfully applied.

Methods inherited from interface java.lang.Iterable

forEach, iterator

Method Detail

getColumnDefinitions

@NonNull
ColumnDefinitions getColumnDefinitions()

Metadata about the columns returned by the CQL request that was used to build this result.

getExecutionInfo

@NonNull
default ExecutionInfo getExecutionInfo()

The execution information for the last query performed for this iterable.

This is a shortcut for:

 getExecutionInfos().get(getExecutionInfos().size() - 1)
 

See Also:

getExecutionInfos()

getExecutionInfos

@NonNull
List<ExecutionInfo> getExecutionInfos()

The execution information for all the queries that have been performed so far to assemble this iterable.

This will have multiple elements if the query is paged, since the driver performs blocking background queries to fetch additional pages transparently as the result set is being iterated.

one

@Nullable
default ElementT one()

Returns the next element, or null if the iterable is exhausted.

This is convenient for queries that are known to return exactly one row, for example count queries.

all

@NonNull
default List<ElementT> all()

Returns all the remaining elements as a list; not recommended for queries that return a large number of elements.

Contrary to Iterable.iterator() or successive calls to one(), this method forces fetching the full contents at once; in particular, this means that a large number of background queries might have to be run, and that all the data will be held in memory locally. Therefore it is crucial to only call this method for queries that are known to return a reasonable number of results.

isFullyFetched

boolean isFullyFetched()

Whether all pages have been fetched from the database.

If this is false, it means that more blocking background queries will be triggered as iteration continues.

getAvailableWithoutFetching

int getAvailableWithoutFetching()

The number of elements that can be returned from this result set before a blocking background query needs to be performed to retrieve more results. In other words, this is the number of elements remaining in the current page.

This is useful if you use the paging state to pause the iteration and resume it later: after you've retrieved the state (getExecutionInfo().getPagingState()), call this method and iterate the remaining elements; that way you're not leaving a gap between the last element and the position you'll restart from when you reinject the state in a new query.

wasApplied

boolean wasApplied()

If the query that produced this result was a CQL conditional update, indicate whether it was successfully applied.

For consistency, this method always returns true for non-conditional queries (although there is no reason to call the method in that case). This is also the case for conditional DDL statements (CREATE KEYSPACE... IF NOT EXISTS, CREATE TABLE... IF NOT EXISTS), for which Cassandra doesn't return an [applied] column.

Note that, for versions of Cassandra strictly lower than 2.1.0-rc2, a server-side bug (CASSANDRA-7337) causes this method to always return true for batches containing conditional queries.

map

@NonNull
default <TargetElementT> PagingIterable<TargetElementT> map(Function<? super ElementT,? extends TargetElementT> elementMapper)

Creates a new instance by transforming each element of this iterable with the provided function.

Note that both instances share the same underlying data: consuming elements from the transformed iterable will also consume them from this object, and vice-versa.

spliterator

@NonNull
default Spliterator<ElementT> spliterator()

Default spliterators created by the driver will report the following characteristics: Spliterator.ORDERED, Spliterator.IMMUTABLE, Spliterator.NONNULL. Single-page result sets will also report Spliterator.SIZED and Spliterator.SUBSIZED, since the result set size is known.

This method should be called at most once. Spliterators share the same underlying data but do not support concurrent consumption; once a spliterator for this iterable is obtained, the iterable should not be consumed through calls to other methods such as Iterable.iterator(), one() or all(); doing so will result in unpredictable results.

Specified by:

spliterator in interface Iterable<ElementT>