@InterfaceAudience.Public @InterfaceStability.Unstable @NotThreadSafe public class AsyncKuduSession extends Object implements SessionConfiguration
AsyncKuduSession belongs to a specific AsyncKuduClient, and represents a
context in which all write data access should take place. Within a session,
multiple operations may be accumulated and batched together for better
efficiency. Settings like timeouts, priorities, and trace IDs are also set
per session.
AsyncKuduSession is separate from AsyncKuduClient because, in a multi-threaded
application, different threads may need to concurrently execute
transactions. Similar to a JDBC "session", transaction boundaries will be
delineated on a per-session basis -- in between a "BeginTransaction" and
"Commit" call on a given session, all operations will be part of the same
transaction. Meanwhile another concurrent session object can safely run
non-transactional work or other transactions without interfering.
Therefore, this class is not thread-safe.
Additionally, there is a guarantee that writes from different sessions do not
get batched together into the same RPCs -- this means that latency-sensitive
clients can run through the same AsyncKuduClient object as throughput-oriented
clients, perhaps by setting the latency-sensitive session's timeouts low and
priorities high. Without the separation of batches, a latency-sensitive
single-row insert might get batched along with 10MB worth of inserts from the
batch writer, thus delaying the response significantly.
Timeouts are handled differently depending on the flush mode.
With AUTO_FLUSH_SYNC, the timeout is set
on each apply()'d operation.
With AUTO_FLUSH_BACKGROUND and
MANUAL_FLUSH, the timeout is assigned to a
whole batch of operations upon flush()'ing. It means that in a situation
with a timeout of 500ms and a flush interval of 1000ms, an operation can be outstanding for up to
1500ms before being timed out.
Warning: a note on out-of-order operations
When using AsyncKuduSession, it is not difficult to trigger concurrent flushes on
the same session. The result is that operations applied in a particular order within a single
session may be applied in a different order on the server side, even for a single tablet. To
prevent this behavior, ensure that only one flush is outstanding at a given time (the maximum
concurrent flushes per AsyncKuduSession is hard-coded to 2).
If operation interleaving would be unacceptable for your application, consider using one of the following strategies to avoid it:
MANUAL_FLUSH mode,
wait for one flush() to join() before triggering another flush.
AUTO_FLUSH_SYNC
mode, wait for each apply() to join() before applying another operation.
AUTO_FLUSH_BACKGROUND mode.
Operation on a particular row until any previous write to that
row has been successfully flushed.
For more information on per-session operation interleaving, see KUDU-1767.
SessionConfiguration.FlushMode| Modifier and Type | Field and Description |
|---|---|
static org.slf4j.Logger |
LOG |
| Modifier and Type | Method and Description |
|---|---|
com.stumbleupon.async.Deferred<OperationResponse> |
apply(Operation operation)
Apply the given operation.
|
com.stumbleupon.async.Deferred<List<OperationResponse>> |
close()
Flushes the buffered operations and marks this session as closed.
|
int |
countPendingErrors()
Return the number of errors which are pending.
|
com.stumbleupon.async.Deferred<List<OperationResponse>> |
flush()
Flush buffered writes.
|
SessionConfiguration.FlushMode |
getFlushMode()
Get the current flush mode.
|
RowErrorsAndOverflowStatus |
getPendingErrors()
Return any errors from previous calls.
|
long |
getTimeoutMillis()
Get the current timeout.
|
boolean |
hasPendingOperations()
Check if there are operations that haven't been completely applied.
|
boolean |
isClosed()
Returns true if this session has already been closed.
|
boolean |
isIgnoreAllDuplicateRows()
Tells if the session is currently ignoring row errors when the whole list returned by a tablet
server is of the AlreadyPresent type.
|
boolean |
isIgnoreAllNotFoundRows()
Tells if the session is currently ignoring row errors when the whole list returned by a tablet
server is of the NotFound type.
|
void |
setErrorCollectorSpace(int size)
Set the number of errors that can be collected.
|
void |
setExternalConsistencyMode(ExternalConsistencyMode consistencyMode)
Set the new external consistency mode for this session.
|
void |
setFlushInterval(int flushIntervalMillis)
Set the flush interval, which will be used for the next scheduling decision.
|
void |
setFlushMode(SessionConfiguration.FlushMode flushMode)
Set the new flush mode for this session.
|
void |
setIgnoreAllDuplicateRows(boolean ignoreAllDuplicateRows)
Configures the option to ignore all the row errors if they are all of the AlreadyPresent type.
|
void |
setIgnoreAllNotFoundRows(boolean ignoreAllNotFoundRows)
Configures the option to ignore all the row errors if they are all of the NotFound type.
|
void |
setMutationBufferLowWatermark(float mutationBufferLowWatermarkPercentage)
Deprecated.
|
void |
setMutationBufferSpace(int numOps)
Set the number of operations that can be buffered.
|
void |
setTimeoutMillis(long timeout)
Sets the timeout for the next applied operations.
|
public SessionConfiguration.FlushMode getFlushMode()
SessionConfigurationgetFlushMode in interface SessionConfigurationAUTO_FLUSH_SYNC by defaultpublic void setFlushMode(SessionConfiguration.FlushMode flushMode)
SessionConfigurationsetFlushMode in interface SessionConfigurationflushMode - new flush mode, can be the same as the previous one.public void setExternalConsistencyMode(ExternalConsistencyMode consistencyMode)
SessionConfigurationsetExternalConsistencyMode in interface SessionConfigurationconsistencyMode - new external consistency mode, can the same as the previous one.public void setMutationBufferSpace(int numOps)
SessionConfigurationsetMutationBufferSpace in interface SessionConfigurationnumOps - number of ops.public void setErrorCollectorSpace(int size)
SessionConfigurationsetErrorCollectorSpace in interface SessionConfigurationsize - number of errors.@Deprecated public void setMutationBufferLowWatermark(float mutationBufferLowWatermarkPercentage)
SessionConfigurationsetMutationBufferLowWatermark in interface SessionConfigurationmutationBufferLowWatermarkPercentage - a new low watermark as a percentage,
has to be between 0 and 1 (inclusive). A value of 1 disables
the low watermark since it's the same as the high onepublic void setFlushInterval(int flushIntervalMillis)
SessionConfigurationsetFlushInterval in interface SessionConfigurationflushIntervalMillis - interval in milliseconds.public void setTimeoutMillis(long timeout)
SessionConfigurationsetTimeoutMillis in interface SessionConfigurationtimeout - Timeout in milliseconds.public long getTimeoutMillis()
SessionConfigurationgetTimeoutMillis in interface SessionConfigurationpublic boolean isClosed()
SessionConfigurationisClosed in interface SessionConfigurationpublic boolean isIgnoreAllDuplicateRows()
SessionConfigurationisIgnoreAllDuplicateRows in interface SessionConfigurationpublic void setIgnoreAllDuplicateRows(boolean ignoreAllDuplicateRows)
SessionConfigurationDisabled by default.
setIgnoreAllDuplicateRows in interface SessionConfigurationignoreAllDuplicateRows - true if this session should enforce this, else falsepublic boolean isIgnoreAllNotFoundRows()
SessionConfigurationisIgnoreAllNotFoundRows in interface SessionConfigurationpublic void setIgnoreAllNotFoundRows(boolean ignoreAllNotFoundRows)
SessionConfigurationDisabled by default.
setIgnoreAllNotFoundRows in interface SessionConfigurationignoreAllNotFoundRows - true if this session should enforce this, else falsepublic int countPendingErrors()
SessionConfigurationAUTO_FLUSH_BACKGROUND mode.countPendingErrors in interface SessionConfigurationpublic RowErrorsAndOverflowStatus getPendingErrors()
SessionConfigurationClears the pending errors.
getPendingErrors in interface SessionConfigurationpublic com.stumbleupon.async.Deferred<List<OperationResponse>> close()
flush() on how to deal with exceptions coming out of this method.public com.stumbleupon.async.Deferred<List<OperationResponse>> flush()
Deferred whose callback chain will be invoked when all applied operations at
the time of the call have been flushed.public boolean hasPendingOperations()
SessionConfigurationhasPendingOperations in interface SessionConfigurationpublic com.stumbleupon.async.Deferred<OperationResponse> apply(Operation operation) throws KuduException
The behavior of this method depends on the configured
FlushMode. Regardless
of flush mode, however, apply() may begin to perform processing in the background
for the call (e.g looking up the tablet location, etc).
operation - operation to applyKuduException - if an error happens or PleaseThrottleException is triggeredFlushMode