SelfT
- the "self type" used for covariant returns in subtypes.public interface Statement<SelfT extends Statement<SelfT>> extends Request
Modifier and Type | Field and Description |
---|---|
static GenericType<CompletionStage<AsyncResultSet>> |
ASYNC
The type returned when a CQL statement is executed asynchronously.
|
static long |
NO_DEFAULT_TIMESTAMP
A special value for
getQueryTimestamp() that means "no value". |
static int |
NO_NOW_IN_SECONDS
A special value for
getNowInSeconds() that means "no value". |
static GenericType<ResultSet> |
SYNC
The type returned when a CQL statement is executed synchronously.
|
Modifier and Type | Method and Description |
---|---|
int |
computeSizeInBytes(DriverContext context)
Calculates the approximate size in bytes that the statement will have when encoded.
|
default SelfT |
copy(ByteBuffer newPagingState)
Creates a new instance with a different paging state.
|
default SelfT |
disableTracing()
Deprecated.
this method only exists to ease the transition from driver 3, it is an alias for
setTracing(false) . |
default SelfT |
enableTracing()
Deprecated.
this method only exists to ease the transition from driver 3, it is an alias for
setTracing(true) . |
ConsistencyLevel |
getConsistencyLevel()
Returns the
ConsistencyLevel to use for the statement. |
default long |
getDefaultTimestamp()
Deprecated.
this method only exists to ease the transition from driver 3, it is an alias for
getQueryTimestamp() . |
default int |
getFetchSize()
Deprecated.
this method only exists to ease the transition from driver 3, it is an alias for
getPageSize() . |
default int |
getNowInSeconds()
A custom "now in seconds" to use when applying the request (for testing purposes).
|
int |
getPageSize()
Returns the page size to use for the statement.
|
ByteBuffer |
getPagingState()
Returns the paging state to send with the statement, or
null if this statement has no
paging state. |
long |
getQueryTimestamp()
Returns the query timestamp, in microseconds, to send with the statement.
|
ConsistencyLevel |
getSerialConsistencyLevel()
Returns the serial
ConsistencyLevel to use for the statement. |
boolean |
isTracing()
Whether tracing information should be recorded for this statement.
|
SelfT |
setConsistencyLevel(ConsistencyLevel newConsistencyLevel)
Sets the
ConsistencyLevel to use for this statement. |
SelfT |
setCustomPayload(Map<String,ByteBuffer> newCustomPayload)
Sets the custom payload to use for execution.
|
default SelfT |
setDefaultTimestamp(long newTimestamp)
Deprecated.
this method only exists to ease the transition from driver 3, it is an alias for
setQueryTimestamp(long) . |
SelfT |
setExecutionProfile(DriverExecutionProfile newProfile)
Sets the execution profile to use for this statement.
|
SelfT |
setExecutionProfileName(String newConfigProfileName)
Sets the name of the execution profile that will be used for this statement.
|
default SelfT |
setFetchSize(int newPageSize)
Deprecated.
this method only exists to ease the transition from driver 3, it is an alias for
setPageSize(int) . |
SelfT |
setIdempotent(Boolean newIdempotence)
Sets the idempotence to use for execution.
|
SelfT |
setNode(Node node)
Sets the
Node that should handle this query. |
default SelfT |
setNowInSeconds(int nowInSeconds)
Sets the "now in seconds" to use when applying the request (for testing purposes).
|
SelfT |
setPageSize(int newPageSize)
Configures how many rows will be retrieved simultaneously in a single network roundtrip (the
goal being to avoid loading too many results in memory at the same time).
|
SelfT |
setPagingState(ByteBuffer newPagingState)
Sets the paging state to send with the statement, or
null if this statement has no
paging state. |
default SelfT |
setPagingState(PagingState newPagingState)
Sets the paging state to send with the statement, or
null if this statement has no
paging state. |
default SelfT |
setPagingState(PagingState newPagingState,
Session session)
Alternative to
setPagingState(PagingState) that specifies the session the statement
will be executed with. |
SelfT |
setQueryTimestamp(long newTimestamp)
Sets the query timestamp, in microseconds, to send with the statement.
|
default SelfT |
setRoutingKey(ByteBuffer... newRoutingKeyComponents)
Sets the key to use for token-aware routing, when the partition key has multiple components.
|
SelfT |
setRoutingKey(ByteBuffer newRoutingKey)
Sets the key to use for token-aware routing.
|
SelfT |
setRoutingKeyspace(CqlIdentifier newRoutingKeyspace)
Sets the keyspace to use for token-aware routing.
|
default SelfT |
setRoutingKeyspace(String newRoutingKeyspaceName)
|
SelfT |
setRoutingToken(Token newRoutingToken)
Sets the token to use for token-aware routing.
|
SelfT |
setSerialConsistencyLevel(ConsistencyLevel newSerialConsistencyLevel)
Sets the serial
ConsistencyLevel to use for this statement. |
SelfT |
setTimeout(Duration newTimeout)
Sets how long to wait for this request to complete.
|
SelfT |
setTracing(boolean newTracing)
Sets tracing for execution.
|
getCustomPayload, getExecutionProfile, getExecutionProfileName, getKeyspace, getNode, getRoutingKey, getRoutingKeyspace, getRoutingToken, getTimeout, isIdempotent
static final GenericType<ResultSet> SYNC
Most users won't use this explicitly. It is needed for the generic execute method (Session.execute(Request, GenericType)
), but CQL statements will generally be run with one of
the driver's built-in helper methods (such as SyncCqlSession.execute(Statement)
).
static final GenericType<CompletionStage<AsyncResultSet>> ASYNC
Most users won't use this explicitly. It is needed for the generic execute method (Session.execute(Request, GenericType)
), but CQL statements will generally be run with one of
the driver's built-in helper methods (such as AsyncCqlSession.executeAsync(Statement)
).
static final long NO_DEFAULT_TIMESTAMP
getQueryTimestamp()
that means "no value".
It is equal to Long.MIN_VALUE
.
static final int NO_NOW_IN_SECONDS
getNowInSeconds()
that means "no value".
It is equal to Integer.MIN_VALUE
.
@NonNull @CheckReturnValue SelfT setExecutionProfileName(@Nullable String newConfigProfileName)
For all the driver's built-in implementations, calling this method with a non-null argument
automatically resets Request.getExecutionProfile()
to null.
All the driver's built-in implementations are immutable, and return a new instance from this method. However custom implementations may choose to be mutable and return the same instance.
@NonNull @CheckReturnValue SelfT setExecutionProfile(@Nullable DriverExecutionProfile newProfile)
For all the driver's built-in implementations, calling this method with a non-null argument
automatically resets Request.getExecutionProfileName()
to null.
All the driver's built-in implementations are immutable, and return a new instance from this method. However custom implementations may choose to be mutable and return the same instance.
@NonNull @CheckReturnValue SelfT setRoutingKeyspace(@Nullable CqlIdentifier newRoutingKeyspace)
See Request.getRoutingKey()
for a description of the token-aware routing algorithm.
newRoutingKeyspace
- The keyspace to use, or null
to disable token-aware routing.@NonNull @CheckReturnValue SelfT setNode(@Nullable Node node)
Node
that should handle this query.
In the general case, use of this method is heavily discouraged and should only be used in the following cases:
system
and system_views
keyspaces.
Configuring a specific node causes the configured LoadBalancingPolicy
to be
completely bypassed. However, if the load balancing policy dictates that the node is at
distance NodeDistance.IGNORED
or there is no active connectivity to the node, the
request will fail with a NoNodeAvailableException
.
node
- The node that should be used to handle executions of this statement or null to
delegate to the configured load balancing policy.@NonNull @CheckReturnValue default SelfT setRoutingKeyspace(@Nullable String newRoutingKeyspaceName)
newRoutingKeyspaceName
- The keyspace to use, or null
to disable token-aware
routing.@NonNull @CheckReturnValue SelfT setRoutingKey(@Nullable ByteBuffer newRoutingKey)
See Request.getRoutingKey()
for a description of the token-aware routing algorithm.
newRoutingKey
- The routing key to use, or null
to disable token-aware routing.@NonNull @CheckReturnValue default SelfT setRoutingKey(@NonNull ByteBuffer... newRoutingKeyComponents)
This method assembles the components into a single byte buffer and passes it to setRoutingKey(ByteBuffer)
. Neither the individual components, nor the vararg array itself,
can be null
.
@NonNull @CheckReturnValue SelfT setRoutingToken(@Nullable Token newRoutingToken)
See Request.getRoutingKey()
for a description of the token-aware routing algorithm.
newRoutingToken
- The routing token to use, or null
to disable token-aware
routing.@NonNull @CheckReturnValue SelfT setCustomPayload(@NonNull Map<String,ByteBuffer> newCustomPayload)
All the driver's built-in statement implementations are immutable, and return a new instance from this method. However custom implementations may choose to be mutable and return the same instance.
Note that it's your responsibility to provide a thread-safe map. This can be achieved with a concurrent or immutable implementation, or by making it effectively immutable (meaning that it's never modified after being set on the statement).
@NonNull @CheckReturnValue SelfT setIdempotent(@Nullable Boolean newIdempotence)
All the driver's built-in implementations are immutable, and return a new instance from this method. However custom implementations may choose to be mutable and return the same instance.
newIdempotence
- a boolean instance to set a statement-specific value, or null
to
use the default idempotence defined in the configuration.@NonNull @CheckReturnValue SelfT setTracing(boolean newTracing)
All the driver's built-in implementations are immutable, and return a new instance from this method. However custom implementations may choose to be mutable and return the same instance.
@Deprecated @NonNull @CheckReturnValue default SelfT enableTracing()
setTracing(true)
.@Deprecated @NonNull @CheckReturnValue default SelfT disableTracing()
setTracing(false)
.long getQueryTimestamp()
setQueryTimestamp(long)
for details.
If this is equal to NO_DEFAULT_TIMESTAMP
, the TimestampGenerator
configured
for this driver instance will be used to generate a timestamp.
NO_DEFAULT_TIMESTAMP
,
TimestampGenerator
@Deprecated default long getDefaultTimestamp()
getQueryTimestamp()
.@NonNull @CheckReturnValue SelfT setQueryTimestamp(long newTimestamp)
This is an alternative to appending a USING TIMESTAMP
clause in the statement's
query string, and has the advantage of sending the timestamp separately from the query string
itself, which doesn't have to be modified when executing the same statement with different
timestamps. Note that, if both a USING TIMESTAMP
clause and a query timestamp are set
for a given statement, the timestamp from the USING TIMESTAMP
clause wins.
This method can be used on any instance of SimpleStatement
, BoundStatement
or BatchStatement
. For a BatchStatement
, the timestamp will apply to all its
child statements; it is not possible to define per-child timestamps using this method, and
consequently, if this method is called on a batch child statement, the provided timestamp will
be silently ignored. If different timestamps are required for individual child statements, this
can only be achieved with a custom USING TIMESTAMP
clause in each child query.
If this is equal to NO_DEFAULT_TIMESTAMP
, the TimestampGenerator
configured
for this driver instance will be used to generate a timestamp.
All the driver's built-in implementations are immutable, and return a new instance from this method. However custom implementations may choose to be mutable and return the same instance.
NO_DEFAULT_TIMESTAMP
,
TimestampGenerator
@Deprecated @NonNull @CheckReturnValue default SelfT setDefaultTimestamp(long newTimestamp)
setQueryTimestamp(long)
.@NonNull @CheckReturnValue SelfT setTimeout(@Nullable Duration newTimeout)
newTimeout
- the timeout to use, or null
to use the default value defined in the
configuration.DefaultDriverOption.REQUEST_TIMEOUT
@Nullable ByteBuffer getPagingState()
null
if this statement has no
paging state.
Paging states are used in scenarios where a paged result is interrupted then resumed later. The paging state can only be reused with the exact same statement (same query string, same parameters). It is an opaque value that is only meant to be collected, stored and re-used. If you try to modify its contents or reuse it with a different statement, the results are unpredictable.
@NonNull @CheckReturnValue SelfT setPagingState(@Nullable ByteBuffer newPagingState)
null
if this statement has no
paging state.
Paging states are used in scenarios where a paged result is interrupted then resumed later. The paging state can only be reused with the exact same statement (same query string, same parameters). It is an opaque value that is only meant to be collected, stored and re-used. If you try to modify its contents or reuse it with a different statement, the results are unpredictable.
All the driver's built-in implementations are immutable, and return a new instance from this
method. However custom implementations may choose to be mutable and return the same instance;
if you do so, you must override copy(ByteBuffer)
.
@NonNull @CheckReturnValue default SelfT setPagingState(@Nullable PagingState newPagingState)
null
if this statement has no
paging state.
This variant uses the "safe" paging state wrapper, it will throw immediately if the statement doesn't match the one that the state was initially extracted from (same query string, same parameters). The advantage is that it fails fast, instead of waiting for an error response from the server.
Note that, if this statement is a SimpleStatement
with bound values, those values
must be encoded in order to perform the check. This method uses the default codec registry and
default protocol version. This might fail if you use custom codecs; in that case, use setPagingState(PagingState, Session)
instead.
IllegalArgumentException
- if the given state does not match this statement.setPagingState(ByteBuffer)
,
ExecutionInfo.getSafePagingState()
@NonNull @CheckReturnValue default SelfT setPagingState(@Nullable PagingState newPagingState, @Nullable Session session)
setPagingState(PagingState)
that specifies the session the statement
will be executed with. You only need this for simple statements, and if you use custom
codecs. Bound statements already know which session they are attached to.int getPageSize()
DefaultDriverOption.REQUEST_PAGE_SIZE
@Deprecated default int getFetchSize()
getPageSize()
.@NonNull @CheckReturnValue SelfT setPageSize(int newPageSize)
newPageSize
- the page size to use, set to 0 or a negative value to use the default value
defined in the configuration.DefaultDriverOption.REQUEST_PAGE_SIZE
@Deprecated @NonNull @CheckReturnValue default SelfT setFetchSize(int newPageSize)
setPageSize(int)
.@Nullable ConsistencyLevel getConsistencyLevel()
ConsistencyLevel
to use for the statement.null
to use the default value defined in the
configuration.DefaultDriverOption.REQUEST_CONSISTENCY
@NonNull @CheckReturnValue SelfT setConsistencyLevel(@Nullable ConsistencyLevel newConsistencyLevel)
ConsistencyLevel
to use for this statement.newConsistencyLevel
- the consistency level to use, or null to use the default value
defined in the configuration.DefaultDriverOption.REQUEST_CONSISTENCY
@Nullable ConsistencyLevel getSerialConsistencyLevel()
ConsistencyLevel
to use for the statement.null
to use the default value defined in the
configuration.DefaultDriverOption.REQUEST_SERIAL_CONSISTENCY
@NonNull @CheckReturnValue SelfT setSerialConsistencyLevel(@Nullable ConsistencyLevel newSerialConsistencyLevel)
ConsistencyLevel
to use for this statement.newSerialConsistencyLevel
- the serial consistency level to use, or null to use the
default value defined in the configuration.DefaultDriverOption.REQUEST_SERIAL_CONSISTENCY
boolean isTracing()
default int getNowInSeconds()
This method's default implementation returns NO_NOW_IN_SECONDS
. The only reason it
exists is to preserve binary compatibility. Internally, the driver overrides it to return the
value that was set programmatically (if any).
NO_NOW_IN_SECONDS
@NonNull default SelfT setNowInSeconds(int nowInSeconds)
This method's default implementation returns the statement unchanged. The only reason it exists is to preserve binary compatibility. Internally, the driver overrides it to record the new value.
NO_NOW_IN_SECONDS
int computeSizeInBytes(@NonNull DriverContext context)
The size might be over-estimated by a few bytes due to global options that may be defined on
a Session
but not explicitly set on the statement itself.
The result of this method is not cached, calling it will cause some encoding to be done in order to determine some of the statement's attributes sizes. Therefore, use this method sparingly in order to avoid unnecessary computation.
@NonNull @CheckReturnValue default SelfT copy(@Nullable ByteBuffer newPagingState)
Since all the built-in statement implementations in the driver are immutable, this method's
default implementation delegates to setPagingState(ByteBuffer)
. However, if you write
your own mutable implementation, make sure it returns a different instance.
Copyright © 2017–2022. All rights reserved.