Package com.apple.foundationdb.record
Class RecordCursorResult<T>
- java.lang.Object
-
- com.apple.foundationdb.record.RecordCursorResult<T>
-
- Type Parameters:
T
- the type of result produced when the result includes a value
@API(STABLE) public class RecordCursorResult<T> extends Object
A result obtained when aRecordCursor
advances. ARecordCursorResult
represents everything that one can learn each time aRecordCursor
advances. This is precisely one of the following:-
The next object of type
T
produced by the cursor. In addition to the next record, this result includes aRecordCursorContinuation
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 alwaysfalse
on the returned continuation. -
The fact that the cursor is stopped and cannot produce another record and a
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'sNoNextReason
is anything other thanSOURCE_EXHAUSTED
, the returned continuation must not be an end continuation. Conversely, if the result'sNoNextReason
isSOURCE_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, thewithNextValue(T, com.apple.foundationdb.record.RecordCursorContinuation)
andwithoutNextValue(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.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
RecordCursorResult.IllegalResultNoNextReasonAccessException
An exception thrown whengetNoNextReason()
is called on a result that has a next value.static class
RecordCursorResult.IllegalResultValueAccessException
An exception thrown whenget()
is called on a result without a next value.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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()
Returnstrue
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, likeOptional.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()
RecordCursorResult<T>
withContinuation(RecordCursorContinuation newContinuation)
Return a new result with the given continuation in place of this result's continuation, but the same value or no-next-reason as this result.static <T> RecordCursorResult<T>
withNextValue(T nextValue, RecordCursorContinuation continuation)
Create a newRecordCursorResult
that has a value, using the given value and continuation.static <T> RecordCursorResult<T>
withoutNextValue(RecordCursorContinuation continuation, RecordCursor.NoNextReason noNextReason)
Create a newRecordCursorResult
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 aRecordCursorResult
to one with a new type from a result without a next value.
-
-
-
Method Detail
-
hasNext
public boolean hasNext()
Return whether or not this result includes a next value.- Returns:
true
if this result includes a next value andfalse
if it does not
-
get
@Nullable public T get()
Return the value of this result. If no result is present, throw an exception.- Returns:
- the value of this result
- Throws:
RecordCursorResult.IllegalResultValueAccessException
- if this result does not contain a value
-
getContinuation
@Nonnull public RecordCursorContinuation getContinuation()
Return the continuation of this result. The continuation will haveRecordCursorContinuation.isEnd()
returntrue
only if this result has a no-next-reason and that reason isSOURCE_EXHAUSTED
.- Returns:
- the continuation of this result
-
getNoNextReason
@Nonnull public RecordCursor.NoNextReason getNoNextReason()
Return the no-next-reason of this result. If a result is present, throw an exception.- Returns:
- the no-next-reason of this result
- Throws:
RecordCursorResult.IllegalResultNoNextReasonAccessException
- if this result contains a value
-
map
@Nonnull public <U> RecordCursorResult<U> map(Function<? super T,? extends U> func)
Apply a function to the value inside this result, likeOptional.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.- Type Parameters:
U
- the type of the function's result and the type of value in the returned result- Parameters:
func
- the function to apply to the value, if present- Returns:
- a new result with a value equal to the value of the function on the current result, if one is present
-
mapAsync
@Nonnull public <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. If a value is present, apply the given function to the value and return a future that, when complete, contains a result wrapping the value of the function's completed future. If no value is present, return a completed future containing a result with this result's continuation and no-next-reason.- Type Parameters:
U
- the type of the value for the returned result- Parameters:
func
- a function taking a value of typeT
and returning aCompletableFuture<U>
- Returns:
- a future that, when complete, contains the result of type
U
-
withContinuation
@Nonnull public RecordCursorResult<T> withContinuation(@Nonnull RecordCursorContinuation newContinuation)
Return a new result with the given continuation in place of this result's continuation, but the same value or no-next-reason as this result.- Parameters:
newContinuation
- the new continuation for the result- Returns:
- a new result with the same value or no-next-reason, but the given continuation
-
hasStoppedBeforeEnd
public boolean hasStoppedBeforeEnd()
Returnstrue
if the cursor has reached its end but a continuation is not an end continuation (i.e., the source is not yet exhausted).- Returns:
true
if the cursor has reached its end but a continuation is not an end continuation andfalse
otherwise
-
withNextValue
@Nonnull public static <T> RecordCursorResult<T> withNextValue(@Nullable T nextValue, @Nonnull RecordCursorContinuation continuation)
Create a newRecordCursorResult
that has a value, using the given value and continuation.- Type Parameters:
T
- the type of the value- Parameters:
nextValue
- the value of the resultcontinuation
- the continuation of the result- Returns:
- a new
RecordCursorResult
with the given value and continuation - Throws:
RecordCoreException
- if the given continuation is an end continuation
-
withoutNextValue
@Nonnull public static <T> RecordCursorResult<T> withoutNextValue(@Nonnull RecordCursorContinuation continuation, @Nonnull RecordCursor.NoNextReason noNextReason)
Create a newRecordCursorResult
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 isSOURCE_EXHAUSTED
.- Type Parameters:
T
- the type of the value if it were present- Parameters:
continuation
- the continuation of the resultnoNextReason
- theRecordCursor.NoNextReason
that no value was present- Returns:
- a new
RecordCursorResult
with the given continuation and no-next-reason - Throws:
RecordCoreException
- if an incompatible continuation and no-next-reason are provided
-
withoutNextValue
@Nonnull public static <T,U> RecordCursorResult<T> withoutNextValue(@Nonnull RecordCursorResult<U> withoutNext)
Cast aRecordCursorResult
to one with a new type from a result without a next value.- Type Parameters:
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 present- Parameters:
withoutNext
- a result without a next value- Returns:
- a cast version of
withoutNext
with the same continuation and no-next-reason
-
exhausted
@Nonnull public static <T> RecordCursorResult<T> exhausted()
Obtain the static result that a cursor can return when it is completely exhausted.- Type Parameters:
T
- the type of value that would be returned if a value were present- Returns:
- a
RecordCursorResult
containing an end continuation and a no-next-reason ofSOURCE_EXHAUSTED
-
-