public class ForwardingAsyncResultSet extends ForwardingResultSet implements AsyncResultSetForwarding implementation of AsyncResultSet that forwards all calls to a delegate.
Inheritance
java.lang.Object > ForwardingStructReader > ForwardingResultSet > ForwardingAsyncResultSetImplements
AsyncResultSetConstructors
ForwardingAsyncResultSet(AsyncResultSet delegate)
public ForwardingAsyncResultSet(AsyncResultSet delegate)| Name | Description |
| delegate | AsyncResultSet |
Methods
<T>toList(Function<StructReader,T> transformer)
public List<T> <T>toList(Function<StructReader,T> transformer)Transforms the row cursor into an immutable list using the given transformer function.
transformer will be called once per row, thus the returned list will contain one entry per
row. This method will block until all the rows have been yielded by the cursor.
WARNING: This will result in consuming the entire list so this should be used judiciously after considering the memory requirements of the returned list.
WARNING: The RowBase object passed to transformer function is not immutable and is
not guaranteed to remain valid after the transformer function returns. The same RowBase
object might be passed multiple times to the transformer with different underlying data each
time. So NEVER keep a reference to the RowBase outside of the transformer.
Specifically do not use com.google.common.base.Functions#identity() function.
| Name | Description |
| transformer | com.google.common.base.Function<StructReader,T> |
| Type | Description |
| List<T> |
| Type | Description |
| SpannerException |
<T>toListAsync(Function<StructReader,T> transformer, Executor executor)
public ApiFuture<List<T>> <T>toListAsync(Function<StructReader,T> transformer, Executor executor)Transforms the row cursor into an immutable list using the given transformer function.
transformer will be called once per row, thus the returned list will contain one entry per
row. The returned future will throw a SpannerException if the row cursor encountered
any error or if the transformer threw an exception on any row.
The transformer will be run on the supplied executor. The implementation may batch multiple
transformer invocations together into a single Runnable when possible to increase
efficiency. At any point in time, there will be at most one invocation of the transformer in
progress.
WARNING: This will result in materializing the entire list so this should be used judiciously after considering the memory requirements of the returned list.
WARNING: The RowBase object passed to transformer function is not immutable and is
not guaranteed to remain valid after the transformer function returns. The same RowBase
object might be passed multiple times to the transformer with different underlying data each
time. So NEVER keep a reference to the RowBase outside of the transformer.
Specifically do not use com.google.common.base.Functions#identity() function.
| Name | Description |
| transformer | com.google.common.base.Function<StructReader,T> |
| executor | Executor |
| Type | Description |
| ApiFuture<List<T>> |
cancel()
public void cancel()Attempt to cancel this operation and free all resources. Non-blocking. This is a no-op for child row cursors and does not cancel the parent cursor.
resume()
public void resume()Resume callbacks from the cursor. If there is more data available, a callback will be dispatched immediately. This can be called from any thread.
setCallback(Executor exec, AsyncResultSet.ReadyCallback cb)
public ApiFuture<Void> setCallback(Executor exec, AsyncResultSet.ReadyCallback cb)Register a callback with the ResultSet to be made aware when more data is available, changing the usage pattern from sync to async. Details:
- The callback will be called at least once.
- The callback is run each time more results are available, or when we discover that there will be no more results. (unless paused, see below). Spurious callbacks are possible, see below.
- Spanner guarantees that one callback is ever outstanding at a time. Also, future callbacks guarantee the "happens before" property with previous callbacks.
- A callback normally consumes all available data in the ResultSet, and then returns CallbackResponse#CONTINUE.
- If a callback returns CallbackResponse#CONTINUE with data still in the ResultSet, the callback is invoked again immediately!
- Once a callback has returned CallbackResponse#PAUSE on the cursor no more callbacks will be run until a corresponding #resume().
- Callback will stop being called once any of the following occurs:
- Callback returns CallbackResponse#DONE.
- ResultSet#tryNext() returns CursorState#DONE.
- ResultSet#tryNext() throws an exception.
- Callback may possibly be invoked after a call to ResultSet#cancel() call, but the subsequent call to #tryNext() will yield a SpannerException.
- Spurious callbacks are possible where cursors are not actually ready. Typically callback should return CallbackResponse#CONTINUE any time it sees CursorState#NOT_READY.
Flow Control
If no flow control is needed (say because result sizes are known in advance to be finite in size) then async processing is simple. The following is a code example that transfers work from the cursor to an upstream sink:
{@code
| Name | Description |
| exec | Executor |
| cb | AsyncResultSet.ReadyCallback |
| Type | Description |
| ApiFuture<Void> |
tryNext()
public AsyncResultSet.CursorState tryNext()Non-blocking call that attempts to step the cursor to the next position in the stream. The
cursor may be inspected only if the cursor returns CursorState.OK.
A caller will typically call tryNext in a loop inside the ReadyCallback, consuming all results available. For more information see #setCallback(Executor, ReadyCallback).
Currently this method may only be called if a ReadyCallback has been registered. This is for safety purposes only, and may be relaxed in future.
| Type | Description |
| AsyncResultSet.CursorState |
| Type | Description |
| SpannerException |