T
- the type of result produced when the result includes a value@API(value=STABLE) public class RecordCursorResult<T> extends Object
RecordCursor
advances.
A RecordCursorResult
represents everything that one can learn each time a RecordCursor
advances.
This is precisely 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 includes a continuation that can be used to continue the cursor after the last record returned.
If the result's NoNextReason
is anything other than 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".
The implementation of RecordCursorResult
guarantees the dichotomy described above using an API that encourages
static correctness (for example, the withNextValue(T, com.apple.foundationdb.record.RecordCursorContinuation)
and withoutNextValue(com.apple.foundationdb.record.RecordCursorContinuation, com.apple.foundationdb.record.RecordCursor.NoNextReason)
builder methods) and a
large number of correctness checks that encourage fast failures instead of subtle contract violations.
Modifier and Type | Class and Description |
---|---|
static class |
RecordCursorResult.IllegalResultNoNextReasonAccessException
An exception thrown when
getNoNextReason() is called on a result that has a next value. |
static class |
RecordCursorResult.IllegalResultValueAccessException
An exception thrown when
get() is called on a result without a next value. |
Modifier and Type | Method and Description |
---|---|
boolean |
equals(Object o) |
static <T> RecordCursorResult<T> |
exhausted()
Obtain the static result that a cursor can return when it is completely exhausted.
|
T |
get()
Return the value of this result.
|
RecordCursorContinuation |
getContinuation()
Return the continuation of this result.
|
RecordCursor.NoNextReason |
getNoNextReason()
Return the no-next-reason of this result.
|
int |
hashCode() |
boolean |
hasNext()
Return whether or not this result includes a next value.
|
boolean |
hasStoppedBeforeEnd()
Returns
true if the cursor has reached its end but a continuation is not an end continuation (i.e., the source is not yet exhausted). |
<U> RecordCursorResult<U> |
map(Function<? super T,? extends U> func)
Apply a function to the value inside this result, like
Optional.map(Function) . |
<U> CompletableFuture<RecordCursorResult<U>> |
mapAsync(Function<? super T,? extends CompletableFuture<? extends U>> func)
Apply an asynchronous function inside this result and return a future for the result containing the future's value.
|
String |
toString() |
static <T> RecordCursorResult<T> |
withNextValue(T nextValue,
RecordCursorContinuation continuation)
Create a new
RecordCursorResult that has a value, using the given value and continuation. |
static <T> RecordCursorResult<T> |
withoutNextValue(RecordCursorContinuation continuation,
RecordCursor.NoNextReason noNextReason)
Create a new
RecordCursorResult that does not have a next value, using the given continuation and no-next-reason. |
static <T,U> RecordCursorResult<T> |
withoutNextValue(RecordCursorResult<U> withoutNext)
Cast a
RecordCursorResult to one with a new type from a result without a next value. |
public boolean hasNext()
true
if this result includes a next value and false
if it does not@Nullable public T get()
RecordCursorResult.IllegalResultValueAccessException
- if this result does not contain a value@Nonnull public RecordCursorContinuation getContinuation()
RecordCursorContinuation.isEnd()
return true
only if this result has a no-next-reason and that reason is SOURCE_EXHAUSTED
.@Nonnull public RecordCursor.NoNextReason getNoNextReason()
RecordCursorResult.IllegalResultNoNextReasonAccessException
- if this result contains a value@Nonnull public <U> RecordCursorResult<U> map(Function<? super T,? extends U> func)
Optional.map(Function)
.
If a value is present, apply the given function to the value and return a new result with that value.
If no value is present in this result, simply return a value-less result of the correct type.U
- the type of the function's result and the type of value in the returned resultfunc
- the function to apply to the value, if present@Nonnull public <U> CompletableFuture<RecordCursorResult<U>> mapAsync(Function<? super T,? extends CompletableFuture<? extends U>> func)
U
- the type of the value for the returned resultfunc
- a function taking a value of type T
and returning a CompletableFuture<U>
U
public boolean hasStoppedBeforeEnd()
true
if the cursor has reached its end but a continuation is not an end continuation (i.e., the source is not yet exhausted).true
if the cursor has reached its end but a continuation is not an end continuation and false
otherwise@Nonnull public static <T> RecordCursorResult<T> withNextValue(@Nullable T nextValue, @Nonnull RecordCursorContinuation continuation)
RecordCursorResult
that has a value, using the given value and continuation.T
- the type of the valuenextValue
- the value of the resultcontinuation
- the continuation of the resultRecordCursorResult
with the given value and continuationRecordCoreException
- if the given continuation is an end continuation@Nonnull public static <T> RecordCursorResult<T> withoutNextValue(@Nonnull RecordCursorContinuation continuation, @Nonnull RecordCursor.NoNextReason noNextReason)
RecordCursorResult
that does not have a next value, using the given continuation and no-next-reason.
The continuation may be an end continuation if and only if the no-next-reason is SOURCE_EXHAUSTED
.T
- the type of the value if it were presentcontinuation
- the continuation of the resultnoNextReason
- the RecordCursor.NoNextReason
that no value was presentRecordCursorResult
with the given continuation and no-next-reasonRecordCoreException
- if an incompatible continuation and no-next-reason are provided@Nonnull public static <T,U> RecordCursorResult<T> withoutNextValue(@Nonnull RecordCursorResult<U> withoutNext)
RecordCursorResult
to one with a new type from a result without a next value.T
- the type of value that would be included in the desired result if one were presentU
- the type of value that would be included in the given result if one were presentwithoutNext
- a result without a next valuewithoutNext
with the same continuation and no-next-reason@Nonnull public static <T> RecordCursorResult<T> exhausted()
T
- the type of value that would be returned if a value were presentRecordCursorResult
containing an end continuation and a no-next-reason of SOURCE_EXHAUSTED