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 a RecordCursor advances. A RecordCursorResult represents everything that one can learn each time a RecordCursor advances. This is precisely one of the following:

1. The next object of type 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.
2. 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'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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	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.

Method Summary

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()	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()
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 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.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

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 and false 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 have RecordCursorContinuation.isEnd() return true only if this result has a no-next-reason and that reason is SOURCE_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

toString

public String toString()

Overrides:

toString in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

map

@Nonnull
public <U> RecordCursorResult<U> map(Function<? super T,? extends U> func)

Apply a function to the value inside this result, like 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.

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 type T and returning a CompletableFuture<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()

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).

Returns:

true if the cursor has reached its end but a continuation is not an end continuation and false otherwise

withNextValue

@Nonnull
public static <T> RecordCursorResult<T> withNextValue(@Nullable
                                                      T nextValue,
                                                      @Nonnull
                                                      RecordCursorContinuation continuation)

Create a new RecordCursorResult that has a value, using the given value and continuation.

Type Parameters:

T - the type of the value

Parameters:

nextValue - the value of the result

continuation - 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 new 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.

Type Parameters:

T - the type of the value if it were present

Parameters:

continuation - the continuation of the result

noNextReason - the RecordCursor.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 a RecordCursorResult 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 present

U - 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 of SOURCE_EXHAUSTED