T
- the type of elements returned by the cursor@API(value=MAINTAINED) public class IntersectionCursor<T> extends Object
IntersectionMultiCursor
which returns a list of the child cursor values rather than just the first one.IntersectionMultiCursor
RecordCursor.NoNextReason
Modifier and Type | Method and Description |
---|---|
boolean |
accept(RecordCursorVisitor visitor)
Accept a visit from hierarchical visitor, which implements
RecordCursorVisitor . |
void |
close() |
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>> |
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>> |
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() |
byte[] |
getContinuation()
Deprecated.
|
com.apple.foundationdb.record.provider.foundationdb.cursors.IntersectionCursorContinuation |
getContinuationObject()
Produce a
RecordCursorContinuation for this cursor. |
Executor |
getExecutor() |
RecordCursor.NoNextReason |
getNoNextReason()
Deprecated.
|
FDBStoreTimer |
getTimer()
Get the
FDBStoreTimer used to instrument events of this cursor. |
protected RecordCursor.NoNextReason |
mergeNoNextReasons()
Merges all of the cursors and whether they have stopped and returns the "weakest" reason for the result to stop.
|
U |
next()
Deprecated.
|
CompletableFuture<Boolean> |
onHasNext()
Deprecated.
|
CompletableFuture<RecordCursorResult<U>> |
onNext()
Asynchronously return the next result from this cursor.
|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
asIterator, asList, empty, empty, filter, filterAsync, filterAsyncInstrumented, filterAsyncInstrumented, filterInstrumented, filterInstrumented, first, flatMapPipelined, flatMapPipelined, flatMapPipelined, forEach, forEachAsync, forEachResult, forEachResultAsync, fromFuture, fromFuture, fromIterator, fromIterator, fromList, fromList, fromList, fromList, getCount, getNext, hasNext, limitRowsTo, limitTimeTo, limitTimeTo, limitTo, map, mapEffect, mapEffect, mapFuture, mapPipelined, orElse, reduce, skip, skipThenLimit
forEachRemaining, remove
@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)
M
- the type of the Protobuf record elements of the cursorS
- the type of record wrapping a record of type M
store
- record store from which records will be fetchedcomparisonKey
- the key expression used to compare records from different cursorsreverse
- whether records are returned in descending or ascending order by the comparison keyleft
- a function to produce the first RecordCursor
from a continuationright
- a function to produce the second RecordCursor
from a continuationcontinuation
- any continuation from a previous scancreate(Function, boolean, Function, Function, byte[], FDBStoreTimer)
@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()
that takes a list of cursors.T
- the type of elements returned by the cursorcomparisonKeyFunction
- the function expression used to compare elements from different cursorsreverse
- whether records are returned in descending or ascending order by the comparison keyleft
- a function to produce the first RecordCursor
from a continuationright
- a function to produce the second RecordCursor
from a continuationcontinuation
- any continuation from a previous scantimer
- the timer used to instrument eventscreate(Function, boolean, List, byte[], FDBStoreTimer)
@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)
M
- the type of the Protobuf record elements of the cursorS
- the type of record wrapping a record of type M
store
- record store from which records will be fetchedcomparisonKey
- the key expression used to compare records from different cursorsreverse
- whether records are returned in descending or ascending order by the comparison keycursorFunctions
- a list of functions to produce RecordCursor
s from a continuationcontinuation
- any continuation from a previous scancreate(Function, boolean, List, byte[], FDBStoreTimer)
@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)
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 RecordCursor
s.
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.
T
- the type of elements returned by this cursorcomparisonKeyFunction
- the function evaluated to compare elements from different cursorsreverse
- whether records are returned in descending or ascending order by the comparison keycursorFunctions
- a list of functions to produce RecordCursor
s from a continuationcontinuation
- any continuation from a previous scantimer
- the timer used to instrument events@Nonnull protected CompletableFuture<List<com.apple.foundationdb.record.provider.foundationdb.cursors.KeyedMergeCursorState<T>>> computeNextResultStates()
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.
@Nonnull protected Function<? super T,? extends List<Object>> getComparisonKeyFunction()
@Nonnull protected RecordCursor.NoNextReason mergeNoNextReasons()
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).@Nonnull public com.apple.foundationdb.record.provider.foundationdb.cursors.IntersectionCursorContinuation getContinuationObject()
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 getChildContinuations()
. This will only be called after computeNextResultStates()
has completed.RecordCursorContinuation
for this cursor based on the state of its child cursors@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)
@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)
@Nonnull public CompletableFuture<RecordCursorResult<U>> onNext()
RecordCursor
RecordCursorResult
, which represents exactly one of the following:
T
produced by the cursor. In addition to the next record, this result
includes a RecordCursorContinuation
that can be used to continue the cursor after the last record
returned. The returned continuation is guaranteed not to be an "end continuation" representing the end of
the cursor: specifically, RecordCursorContinuation.isEnd()
is always false
on the returned
continuation.
RecordCursor.NoNextReason
that
explains why no record could be produced. The result include a continuation that can be used to continue
the cursor after the last record returned.
If the result's NoNextReason
is anything other than RecordCursor.NoNextReason.SOURCE_EXHAUSTED
, the
returned continuation must not be an end continuation. Conversely, if the result's NoNextReason
is SOURCE_EXHAUSTED
, then the returned continuation must be an an "end continuation".
RecordCursorContinuation
can be serialized to an opaque byte array using
RecordCursorContinuation.toBytes()
. This can be passed back into a new cursor of the same type, with all
other parameters remaining the same.onNext
in interface RecordCursor<U>
RecordCursorResult
,
RecordCursorContinuation
@Nonnull @Deprecated public CompletableFuture<Boolean> onHasNext()
RecordCursor
onHasNext
in interface RecordCursor<U>
true
if RecordCursor.next()
would return a record.AsyncIterator.onHasNext()
@Nullable @Deprecated public U next()
RecordCursor
@Nullable @Deprecated public byte[] getContinuation()
RecordCursor
getContinuation
in interface RecordCursor<U>
null
if the underlying source is completely exhausted, independent of any limit
passed to the cursor creator. Since such creators generally accept null
to mean no continuation,
that is, start from the beginning, one must check for null
from getContinuation
to
keep from starting over.
Result is not always defined if called before onHasNext
or before next
after
onHasNext
has returned true
. That is, a continuation is only guaranteed when called
"between" records from a while (hasNext) next
loop or after its end.@Nonnull @Deprecated public RecordCursor.NoNextReason getNoNextReason()
RecordCursor
false
for RecordCursor.hasNext()
.
If hasNext
was not called or returned true
last time, the result is undefined and
may be an exception.getNoNextReason
in interface RecordCursor<U>
public void close()
close
in interface RecordCursor<U>
close
in interface AutoCloseable
@Nonnull public Executor getExecutor()
getExecutor
in interface RecordCursor<U>
@Nullable public FDBStoreTimer getTimer()
FDBStoreTimer
used to instrument events of this cursor.public boolean accept(@Nonnull RecordCursorVisitor visitor)
RecordCursor
RecordCursorVisitor
.
By contract, implementations of this method must return the value of visitor.visitLeave(this)
,
which determines whether or not subsequent siblings of this cursor should be visited.accept
in interface RecordCursor<U>
visitor
- a hierarchical visitortrue
if the subsequent siblings of the cursor
should be visited, and false
otherwise