Package com.apple.foundationdb.record.provider.foundationdb.cursors

Class IntersectionCursor<T>

java.lang.Object

com.apple.foundationdb.record.provider.foundationdb.cursors.MergeCursor<T,U,com.apple.foundationdb.record.provider.foundationdb.cursors.KeyedMergeCursorState<T>>

com.apple.foundationdb.record.provider.foundationdb.cursors.IntersectionCursor<T>

Type Parameters:

T - the type of elements returned by the cursor

All Implemented Interfaces:

RecordCursor<T>, AutoCloseable, Iterator<T>

@API(MAINTAINED)
public class IntersectionCursor<T>
extends MergeCursor<T,U,com.apple.foundationdb.record.provider.foundationdb.cursors.KeyedMergeCursorState<T>>

A cursor that implements an intersection of matching elements from a set of cursors all of whom are ordered compatibly. For every matching set, this will return the element from the first child cursor. If each cursor returns something slightly different and the use case requires accessing the different results from each child, then one should use the IntersectionMultiCursor which returns a list of the child cursor values rather than just the first one.

See Also:

IntersectionMultiCursor

Nested Class Summary

Nested classes/interfaces inherited from interface com.apple.foundationdb.record.RecordCursor

RecordCursor.NoNextReason

Method Summary

Modifier and Type	Method	Description
protected CompletableFuture<List<com.apple.foundationdb.record.provider.foundationdb.cursors.KeyedMergeCursorState<T>>>	computeNextResultStates()	Compute the next result states for the cursor based on the status of the existing states.
static <M extends Message,S extends FDBRecord<M>> IntersectionCursor<S>	create(FDBRecordStoreBase<M> store, KeyExpression comparisonKey, boolean reverse, Function<byte[],RecordCursor<S>> left, Function<byte[],RecordCursor<S>> right, byte[] continuation)	Create an intersection cursor from two compatibly-ordered cursors.
static <M extends Message,S extends FDBRecord<M>> IntersectionCursor<S>	create(FDBRecordStoreBase<M> store, KeyExpression comparisonKey, boolean reverse, List<Function<byte[],RecordCursor<S>>> cursorFunctions, byte[] continuation)	Create an intersection cursor from two or more compatibly-ordered cursors.
static <T> IntersectionCursor<T>	create(Function<? super T,? extends List<Object>> comparisonKeyFunction, boolean reverse, Function<byte[],RecordCursor<T>> left, Function<byte[],RecordCursor<T>> right, byte[] continuation, FDBStoreTimer timer)	Create an intersection cursor from two compatibly-ordered cursors.
static <T> IntersectionCursor<T>	create(Function<? super T,? extends List<Object>> comparisonKeyFunction, boolean reverse, List<Function<byte[],RecordCursor<T>>> cursorFunctions, byte[] continuation, FDBStoreTimer timer)	Create an intersection cursor from two or more compatibly-ordered cursors.
protected static <T> List<com.apple.foundationdb.record.provider.foundationdb.cursors.KeyedMergeCursorState<T>>	createCursorStates(Function<byte[],RecordCursor<T>> left, Function<byte[],RecordCursor<T>> right, byte[] byteContinuation, Function<? super T,? extends List<Object>> comparisonKeyFunction)
protected static <T> List<com.apple.foundationdb.record.provider.foundationdb.cursors.KeyedMergeCursorState<T>>	createCursorStates(List<Function<byte[],RecordCursor<T>>> cursorFunctions, byte[] byteContinuation, Function<? super T,? extends List<Object>> comparisonKeyFunction)
protected Function<? super T,? extends List<Object>>	getComparisonKeyFunction()
com.apple.foundationdb.record.provider.foundationdb.cursors.IntersectionCursorContinuation	getContinuationObject()	Produce a RecordCursorContinuation for this cursor.
protected T	getNextResult(List<com.apple.foundationdb.record.provider.foundationdb.cursors.KeyedMergeCursorState<T>> cursorStates)	Determine the next result to return based on the results of the child cursors.
protected RecordCursor.NoNextReason	mergeNoNextReasons()	Merges all of the cursors and whether they have stopped and returns the "weakest" reason for the result to stop.

Methods inherited from class com.apple.foundationdb.record.provider.foundationdb.cursors.MergeCursor

accept, checkNextStateTimeout, close, getChildContinuations, getContinuation, getCursorStates, getExecutor, getNoNextReason, getStrongestNoNextReason, getTimer, getWeakestNoNextReason, next, onHasNext, onNext, whenAll, whenAny

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Iterator

forEachRemaining, remove

Methods inherited from interface com.apple.foundationdb.record.RecordCursor

asIterator, asList, filter, filterAsync, filterAsyncInstrumented, filterAsyncInstrumented, filterInstrumented, filterInstrumented, first, flatMapPipelined, forEach, forEachAsync, forEachResult, forEachResultAsync, getCount, getNext, hasNext, limitRowsTo, limitTo, map, mapEffect, mapEffect, mapPipelined, orElse, reduce, skip, skipThenLimit

Method Detail

getNextResult

protected T getNextResult(@Nonnull
                          List<com.apple.foundationdb.record.provider.foundationdb.cursors.KeyedMergeCursorState<T>> cursorStates)

Description copied from class: MergeCursor

Determine the next result to return based on the results of the child cursors. This will be called with the return value of MergeCursor.computeNextResultStates().

Specified by:

getNextResult in class MergeCursor<T,T,com.apple.foundationdb.record.provider.foundationdb.cursors.KeyedMergeCursorState<T>>

Parameters:

cursorStates - the list of cursors to be included in the result

Returns:

a result somehow combining the results of the input cursors

create

@Nonnull
public static <M extends Message,S extends FDBRecord<M>> IntersectionCursor<S> create(@Nonnull
                                                                                            FDBRecordStoreBase<M> store,
                                                                                            @Nonnull
                                                                                            KeyExpression comparisonKey,
                                                                                            boolean reverse,
                                                                                            @Nonnull
                                                                                            Function<byte[],RecordCursor<S>> left,
                                                                                            @Nonnull
                                                                                            Function<byte[],RecordCursor<S>> right,
                                                                                            @Nullable
                                                                                            byte[] continuation)

Create an intersection cursor from two compatibly-ordered cursors. As its comparison key function, it will evaluate the provided comparison key on each record from each cursor. This otherwise behaves exactly the same way as the overload of this function that takes a function to extract a comparison key.

Type Parameters:

M - the type of the Protobuf record elements of the cursor

S - the type of record wrapping a record of type M

Parameters:

store - record store from which records will be fetched

comparisonKey - the key expression used to compare records from different cursors

reverse - whether records are returned in descending or ascending order by the comparison key

left - a function to produce the first RecordCursor from a continuation

right - a function to produce the second RecordCursor from a continuation

continuation - any continuation from a previous scan

Returns:

a cursor containing all records in both child cursors

See Also:

create(Function, boolean, Function, Function, byte[], FDBStoreTimer)

create

@Nonnull
public static <T> IntersectionCursor<T> create(@Nonnull
                                               Function<? super T,? extends List<Object>> comparisonKeyFunction,
                                               boolean reverse,
                                               @Nonnull
                                               Function<byte[],RecordCursor<T>> left,
                                               @Nonnull
                                               Function<byte[],RecordCursor<T>> right,
                                               @Nullable
                                               byte[] continuation,
                                               @Nullable
                                               FDBStoreTimer timer)

Create an intersection cursor from two compatibly-ordered cursors. This cursor is identical to the cursor that would be produced by calling the overload of create() that takes a list of cursors.

Type Parameters:

T - the type of elements returned by the cursor

Parameters:

comparisonKeyFunction - the function expression used to compare elements from different cursors

reverse - whether records are returned in descending or ascending order by the comparison key

left - a function to produce the first RecordCursor from a continuation

right - a function to produce the second RecordCursor from a continuation

continuation - any continuation from a previous scan

timer - the timer used to instrument events

Returns:

a cursor containing all elements in both child cursors

See Also:

create(Function, boolean, List, byte[], FDBStoreTimer)

create

@Nonnull
public static <M extends Message,S extends FDBRecord<M>> IntersectionCursor<S> create(@Nonnull
                                                                                            FDBRecordStoreBase<M> store,
                                                                                            @Nonnull
                                                                                            KeyExpression comparisonKey,
                                                                                            boolean reverse,
                                                                                            @Nonnull
                                                                                            List<Function<byte[],RecordCursor<S>>> cursorFunctions,
                                                                                            @Nullable
                                                                                            byte[] continuation)

Create an intersection cursor from two or more compatibly-ordered cursors. As its comparison key function, it will evaluate the provided comparison key on each record from each cursor. This otherwise behaves exactly the same way as the overload of this function that takes a function to extract a comparison key.

Type Parameters:

M - the type of the Protobuf record elements of the cursor

S - the type of record wrapping a record of type M

Parameters:

store - record store from which records will be fetched

comparisonKey - the key expression used to compare records from different cursors

reverse - whether records are returned in descending or ascending order by the comparison key

cursorFunctions - a list of functions to produce RecordCursors from a continuation

continuation - any continuation from a previous scan

Returns:

a cursor containing all records in all child cursors

See Also:

create(Function, boolean, List, byte[], FDBStoreTimer)

create

@Nonnull
public static <T> IntersectionCursor<T> create(@Nonnull
                                               Function<? super T,? extends List<Object>> comparisonKeyFunction,
                                               boolean reverse,
                                               @Nonnull
                                               List<Function<byte[],RecordCursor<T>>> cursorFunctions,
                                               @Nullable
                                               byte[] continuation,
                                               @Nullable
                                               FDBStoreTimer timer)

Create an intersection cursor from two or more compatibly-ordered cursors. Note that this will throw an error if the list of cursors does not have at least two elements. The returned cursor will return all elements that appear in all of the provided cursors, preserving order. All cursors must return elements in the same order, and that order should be determined by the comparison key function, i.e., if reverse is false, then the elements should be returned in ascending order by that key, and if reverse is true, they should be returned in descending order. Additionally, if the comparison key function evaluates to the same value when applied to two elements (possibly from different cursors), then those two elements should be equal. In other words, the value of the comparison key should be the only necessary data that need to be extracted from each element returned by the child cursors to perform the intersection. Additionally, the provided comparison key function should not have any side-effects and should produce the same output every time it is applied to the same input.

The cursors are provided as a list of functions rather than a list of RecordCursors. These functions should create a new RecordCursor instance with a given continuation appropriate for that cursor type. The value of that continuation will be determined by this function from the continuation parameter for the intersection cursor as a whole.

Type Parameters:

T - the type of elements returned by this cursor

Parameters:

comparisonKeyFunction - the function evaluated to compare elements from different cursors

reverse - whether records are returned in descending or ascending order by the comparison key

cursorFunctions - a list of functions to produce RecordCursors from a continuation

continuation - any continuation from a previous scan

timer - the timer used to instrument events

Returns:

a cursor containing all records in all child cursors

computeNextResultStates

@Nonnull
protected CompletableFuture<List<com.apple.foundationdb.record.provider.foundationdb.cursors.KeyedMergeCursorState<T>>> computeNextResultStates()

Compute the next result states for the cursor based on the status of the existing states. This should return a (not necessarily proper) sublist of this cursor's cursor states. By default, this assumes the cursors return results in a compatible order based on their comparison key and loops until they all have matching values. Extenders of this class may choose an alternative approach depending on the semantics of that cursor.

To indicate that the intersection cursor should stop, this function should either return an empty list of states or a list containing at least one state that does not have a next item.

Specified by:

computeNextResultStates in class MergeCursor<T,U,com.apple.foundationdb.record.provider.foundationdb.cursors.KeyedMergeCursorState<T>>

Returns:

the list of states included in the next result

getComparisonKeyFunction

@Nonnull
protected Function<? super T,? extends List<Object>> getComparisonKeyFunction()

mergeNoNextReasons

@Nonnull
protected RecordCursor.NoNextReason mergeNoNextReasons()

Merges all of the cursors and whether they have stopped and returns the "weakest" reason for the result to stop. It will return RecordCursor.NoNextReason.SOURCE_EXHAUSTED if any of the cursors are exhausted. If any of the cursors have stopped due to an in-band limit, it will return an in-band limit as well. Finally, if all of the stopped cursors have done so due to hitting an out-of-band limit, it will return an out-of-band limit as well. Note that, in practice, because an intersection cursor will return false from onHasNext if any of its child cursors have stopped, it is likely that there are only a small number (maybe one or two) cursors that have actually stopped when this method is called (e.g., the first cursor to exhaust its source or the first cursor to hit a limit imposed by the element scan limiter).

Specified by:

mergeNoNextReasons in class MergeCursor<T,U,com.apple.foundationdb.record.provider.foundationdb.cursors.KeyedMergeCursorState<T>>

Returns:

the weakest reason for stopping

getContinuationObject

@Nonnull
public com.apple.foundationdb.record.provider.foundationdb.cursors.IntersectionCursorContinuation getContinuationObject()

Description copied from class: MergeCursor

Produce a RecordCursorContinuation for this cursor. The super-class itself handles constructing the byte array continuation from this continuation. Most continuations will be based on the continuations of this cursors child cursors. These can be retrieved by calling MergeCursor.getChildContinuations(). This will only be called after MergeCursor.computeNextResultStates() has completed.

Specified by:

getContinuationObject in class MergeCursor<T,U,com.apple.foundationdb.record.provider.foundationdb.cursors.KeyedMergeCursorState<T>>

Returns:

a RecordCursorContinuation for this cursor based on the state of its child cursors

createCursorStates

@Nonnull
protected static <T> List<com.apple.foundationdb.record.provider.foundationdb.cursors.KeyedMergeCursorState<T>> createCursorStates(@Nonnull
                                                                                                                                   Function<byte[],RecordCursor<T>> left,
                                                                                                                                   @Nonnull
                                                                                                                                   Function<byte[],RecordCursor<T>> right,
                                                                                                                                   @Nullable
                                                                                                                                   byte[] byteContinuation,
                                                                                                                                   @Nonnull
                                                                                                                                   Function<? super T,? extends List<Object>> comparisonKeyFunction)

createCursorStates

@Nonnull
protected static <T> List<com.apple.foundationdb.record.provider.foundationdb.cursors.KeyedMergeCursorState<T>> createCursorStates(@Nonnull
                                                                                                                                   List<Function<byte[],RecordCursor<T>>> cursorFunctions,
                                                                                                                                   @Nullable
                                                                                                                                   byte[] byteContinuation,
                                                                                                                                   @Nonnull
                                                                                                                                   Function<? super T,? extends List<Object>> comparisonKeyFunction)