Class ForwardingAsyncResultSet
- java.lang.Object
-
- com.google.cloud.spanner.ForwardingStructReader
-
- com.google.cloud.spanner.ForwardingResultSet
-
- com.google.cloud.spanner.ForwardingAsyncResultSet
-
- All Implemented Interfaces:
AsyncResultSet
,ResultSet
,StructReader
,AutoCloseable
public class ForwardingAsyncResultSet extends ForwardingResultSet implements AsyncResultSet
Forwarding implementation ofAsyncResultSet
that forwards all calls to a delegate.
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from interface com.google.cloud.spanner.AsyncResultSet
AsyncResultSet.CallbackResponse, AsyncResultSet.CursorState, AsyncResultSet.ReadyCallback
-
-
Constructor Summary
Constructors Constructor Description ForwardingAsyncResultSet(AsyncResultSet delegate)
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
cancel()
Attempt to cancel this operation and free all resources.void
resume()
Resume callbacks from the cursor.com.google.api.core.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.<T> List<T>
toList(com.google.common.base.Function<StructReader,T> transformer)
Transforms the row cursor into an immutable list using the given transformer function.<T> com.google.api.core.ApiFuture<List<T>>
toListAsync(com.google.common.base.Function<StructReader,T> transformer, Executor executor)
Transforms the row cursor into an immutable list using the given transformer function.AsyncResultSet.CursorState
tryNext()
Non-blocking call that attempts to step the cursor to the next position in the stream.-
Methods inherited from class com.google.cloud.spanner.ForwardingResultSet
close, getCurrentRowAsStruct, getStats, next
-
Methods inherited from class com.google.cloud.spanner.ForwardingStructReader
checkValidState, getBigDecimal, getBigDecimal, getBigDecimalList, getBigDecimalList, getBoolean, getBoolean, getBooleanArray, getBooleanArray, getBooleanList, getBooleanList, getBytes, getBytes, getBytesList, getBytesList, getColumnCount, getColumnIndex, getColumnType, getColumnType, getDate, getDate, getDateList, getDateList, getDouble, getDouble, getDoubleArray, getDoubleArray, getDoubleList, getDoubleList, getJson, getJson, getJsonList, getJsonList, getLong, getLong, getLongArray, getLongArray, getLongList, getLongList, getString, getString, getStringList, getStringList, getStructList, getStructList, getTimestamp, getTimestamp, getTimestampList, getTimestampList, getType, getValue, getValue, isNull, isNull
-
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
-
Methods inherited from interface com.google.cloud.spanner.ResultSet
close, getCurrentRowAsStruct, getStats, next
-
Methods inherited from interface com.google.cloud.spanner.StructReader
getBigDecimal, getBigDecimal, getBigDecimalList, getBigDecimalList, getBoolean, getBoolean, getBooleanArray, getBooleanArray, getBooleanList, getBooleanList, getBytes, getBytes, getBytesList, getBytesList, getColumnCount, getColumnIndex, getColumnType, getColumnType, getDate, getDate, getDateList, getDateList, getDouble, getDouble, getDoubleArray, getDoubleArray, getDoubleList, getDoubleList, getJson, getJson, getJsonList, getJsonList, getLong, getLong, getLongArray, getLongArray, getLongList, getLongList, getString, getString, getStringList, getStringList, getStructList, getStructList, getTimestamp, getTimestamp, getTimestampList, getTimestampList, getType, getValue, getValue, isNull, isNull
-
-
-
-
Constructor Detail
-
ForwardingAsyncResultSet
public ForwardingAsyncResultSet(AsyncResultSet delegate)
-
-
Method Detail
-
tryNext
public AsyncResultSet.CursorState tryNext() throws SpannerException
Description copied from interface:AsyncResultSet
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 returnsCursorState.OK
.A caller will typically call tryNext in a loop inside the ReadyCallback, consuming all results available. For more information see
AsyncResultSet.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.
- Specified by:
tryNext
in interfaceAsyncResultSet
- Returns:
- current cursor readiness state
- Throws:
SpannerException
- When an unrecoverable problem downstream occurs. Once this occurs you will get no further callbacks. You should return CallbackResponse.DONE back from callback.
-
setCallback
public com.google.api.core.ApiFuture<Void> setCallback(Executor exec, AsyncResultSet.ReadyCallback cb)
Description copied from interface:AsyncResultSet
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
AsyncResultSet.CallbackResponse.CONTINUE
. - If a callback returns
AsyncResultSet.CallbackResponse.CONTINUE
with data still in the ResultSet, the callback is invoked again immediately! - Once a callback has returned
AsyncResultSet.CallbackResponse.PAUSE
on the cursor no more callbacks will be run until a correspondingAsyncResultSet.resume()
. - Callback will stop being called once any of the following occurs:
- Callback returns
AsyncResultSet.CallbackResponse.DONE
. ResultSet#tryNext()
returnsAsyncResultSet.CursorState.DONE
.ResultSet#tryNext()
throws an exception.
- Callback returns
- Callback may possibly be invoked after a call to
ResultSet#cancel()
call, but the subsequent call toAsyncResultSet.tryNext()
will yield a SpannerException. - Spurious callbacks are possible where cursors are not actually ready. Typically callback
should return
AsyncResultSet.CallbackResponse.CONTINUE
any time it seesAsyncResultSet.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
- Specified by:
setCallback
in interfaceAsyncResultSet
- Parameters:
exec
- executor on which to run all callbacks. Typically use a threadpool. If the executor is one that runs the work on the submitting thread, you must be very careful not to throw RuntimeException up the stack, lest you do damage to calling components. For example, it may cause an event dispatcher thread to crash.cb
- ready callback- Returns:
- An
ApiFuture
that returnsnull
when the consumption of theAsyncResultSet
has finished successfully. No more calls to theAsyncResultSet.ReadyCallback
will follow and all resources used by theAsyncResultSet
have been cleaned up. TheApiFuture
throws anExecutionException
if the consumption of theAsyncResultSet
finished with an error.
-
cancel
public void cancel()
Description copied from interface:AsyncResultSet
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.- Specified by:
cancel
in interfaceAsyncResultSet
-
resume
public void resume()
Description copied from interface:AsyncResultSet
Resume callbacks from the cursor. If there is more data available, a callback will be dispatched immediately. This can be called from any thread.- Specified by:
resume
in interfaceAsyncResultSet
-
toListAsync
public <T> com.google.api.core.ApiFuture<List<T>> toListAsync(com.google.common.base.Function<StructReader,T> transformer, Executor executor)
Description copied from interface:AsyncResultSet
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 aSpannerException
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 sameRowBase
object might be passed multiple times to the transformer with different underlying data each time. So *NEVER* keep a reference to theRowBase
outside of the transformer. Specifically do not useFunctions.identity()
function.- Specified by:
toListAsync
in interfaceAsyncResultSet
- Parameters:
transformer
- function which will be used to transform the row. It should not return null.executor
- executor on which the transformer will be run. This should ideally not be an inline executor such asMoreExecutors.directExecutor()
; using such an executor may degrade the performance of the Spanner library.
-
toList
public <T> List<T> toList(com.google.common.base.Function<StructReader,T> transformer) throws SpannerException
Description copied from interface:AsyncResultSet
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 sameRowBase
object might be passed multiple times to the transformer with different underlying data each time. So *NEVER* keep a reference to theRowBase
outside of the transformer. Specifically do not useFunctions.identity()
function.- Specified by:
toList
in interfaceAsyncResultSet
- Parameters:
transformer
- function which will be used to transform the row. It should not return null.- Throws:
SpannerException
-
-