public interface PagingIterable<ElementT> extends Iterable<ElementT>
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.
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> |
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.
|
@NonNull ColumnDefinitions getColumnDefinitions()
@NonNull default ExecutionInfo getExecutionInfo()
This is a shortcut for:
getExecutionInfos().get(getExecutionInfos().size() - 1)
getExecutionInfos()
@NonNull List<ExecutionInfo> getExecutionInfos()
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.
@Nullable default ElementT one()
null
if the iterable is exhausted.
This is convenient for queries that are known to return exactly one row, for example count queries.
@NonNull default List<ElementT> all()
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.
boolean isFullyFetched()
If this is false
, it means that more blocking background queries will be triggered
as iteration continues.
int getAvailableWithoutFetching()
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.
boolean wasApplied()
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.
@NonNull default <TargetElementT> PagingIterable<TargetElementT> map(Function<? super ElementT,? extends TargetElementT> elementMapper)
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.
@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.
spliterator
in interface Iterable<ElementT>
Copyright © 2017–2024. All rights reserved.