io.crate.data

Interface BatchIterator

All Superinterfaces:

Killable

All Known Implementing Classes:

AsyncCompositeBatchIterator, AsyncOperationBatchIterator, BatchPagingIterator, CloseAssertingBatchIterator, CollectingBatchIterator, CompositeBatchIterator, FileReadingIterator, FilteringBatchIterator, ForwardingBatchIterator, IndexWriterCountBatchIterator, LimitingBatchIterator, ListenableBatchIterator, LuceneBatchIterator, NestedLoopBatchIterator, NodeStatsIterator, RowsBatchIterator, RowTransformingBatchIterator, SkippingBatchIterator

public interface BatchIterator
extends Killable

An iterator used to navigate over data organized in batches. Though not required most implementations already hold an initial batch of data ready for use and further data can be loaded asynchronously via the loadNextBatch() method. The loaded data can be accessed by moving the iterator via the movement methods moveNext() and moveToStart() and then using the Columns object returned by rowData() to access the data at the current position. Once all loaded data has been consumed more data can be loaded with loadNextBatch() unless allLoaded() is true in which case the iterator is exhausted. A BatchIterator starts either *before* the first row or in an unloaded state. This means a consumer can consume a BatchIterator like this:

     while (it.moveNext()) {
         // do something with the row
     }
     if (it.allLoaded()) {
          // iterator is exhausted
     } else {
         it.loadNextBatch().whenComplete((r, t) -> {
             // continue consumption
         }
     }
 

Thread-safety notes: Concurrent usage of a BatchIterator is not supported.

Method Summary

Modifier and Type	Method and Description
boolean	allLoaded()
void	close() Closes the iterator and frees all resources.
java.util.concurrent.CompletionStage<?>	loadNextBatch() Loads the next batch if there is still data available for loading.
boolean	moveNext() Advances the iterator.
void	moveToStart() Moves the Iterator back to the starting position.
Columns	rowData() This method returns a columns object which can be used to access the underlying data of the current iterator position.

Methods inherited from interface io.crate.data.Killable

kill

Method Detail

rowData

Columns rowData()

This method returns a columns object which can be used to access the underlying data of the current iterator position. Note that it is only valid to call Input.value() on any of the returned columns if the iterator is positioned on a valid row, which is only the case if the last call to moveNext() returned true. This method is valid to be called over the whole lifetime of the iterator, regardless of the state of the iterator or its position. However it is good practice for consumers of this iterator to gather the columns before iterating. This method is required to always return the same object on every call.

Returns:

a columns object

moveToStart

void moveToStart()

Moves the Iterator back to the starting position. A consumer can then iterate over the rows again by calling into moveNext() and loadNextBatch() as appropriate.

Throws:

java.lang.IllegalStateException - if the cursor is closed

moveNext

boolean moveNext()

Advances the iterator.

Returns:

true if the iterator moved to the next valid row. false if the iterator is no longer on a valid row. If allLoaded() returns true the iterator is out of data. Otherwise loadNextBatch() can be used to load the next batch - after which moveNext() can be used again.

Throws:

java.lang.IllegalStateException - if the cursor is closed

close

void close()

Closes the iterator and frees all resources. After this method has been called all methods on the iterator will result in an error. There are two exceptions to that: - close: Close itself can be called multiple times, but only the first call has an effect. - loadNextBatch: This method never raises, but instead returns a failed CompletionStage.

loadNextBatch

java.util.concurrent.CompletionStage<?> loadNextBatch()

Loads the next batch if there is still data available for loading. This may only be called if allLoaded() returns false. If allLoaded() returns true, calling this method will return a failed CompletionStage.

NOTE: while loading takes place the iterator must not be moved. The iterator behaviour in this case is undetermined.

Returns:

a future which will be completed once the loading is done. Once the future completes the iterator is still in an "off-row" state, but moveNext() can be called again if the next batch contains more data.

allLoaded

boolean allLoaded()

Returns:

true if no more batches can be loaded

Throws:

java.lang.IllegalStateException - if the cursor is closed