public abstract class StatementWrapper extends Statement
Statement
implementations that wrap another statement.
This is intended for use with a custom RetryPolicy
, LoadBalancingPolicy
or
SpeculativeExecutionPolicy
. The client code can wrap a statement to "mark" it, or
add information that will lead to special handling in the policy.
Example:
// Define your own subclass
public class MyCustomStatement extends StatementWrapper {
public MyCustomStatement(Statement wrapped) {
super(wrapped);
}
}
// In your load balancing policy, add a special case for that new type
public class MyLoadBalancingPolicy implements LoadBalancingPolicy {
public Iterator<Host> newQueryPlan(String loggedKeyspace, Statement statement) {
if (statement instanceof MyCustomStatement) {
// return specially crafted plan
} else {
// return default plan
}
}
}
// The client wraps whenever it wants to trigger the special plan
Statement s = new SimpleStatement("...");
session.execute(s); // will use default plan
session.execute(new MyCustomStatement(s)); // will use special plan
idempotent, NULL_PAYLOAD_VALUE
Modifier | Constructor and Description |
---|---|
protected |
StatementWrapper(Statement wrapped)
Builds a new instance.
|
Modifier and Type | Method and Description |
---|---|
Statement |
disableTracing()
Disables tracing for this query.
|
Statement |
enableTracing()
Enables tracing for this query.
|
ConsistencyLevel |
getConsistencyLevel()
The consistency level for this query.
|
long |
getDefaultTimestamp()
The default timestamp for this query.
|
int |
getFetchSize()
The fetch size for this query.
|
String |
getKeyspace()
Returns the keyspace this query operates on.
|
Map<String,ByteBuffer> |
getOutgoingPayload()
Returns this statement's outgoing payload.
|
ByteBuffer |
getPagingState() |
int |
getReadTimeoutMillis()
Return the per-host read timeout that was set for this statement.
|
RetryPolicy |
getRetryPolicy()
Returns the retry policy sets for this query, if any.
|
ByteBuffer |
getRoutingKey(ProtocolVersion protocolVersion,
CodecRegistry codecRegistry)
Returns the routing key (in binary raw form) to use for token aware
routing of this query.
|
ConsistencyLevel |
getSerialConsistencyLevel()
The serial consistency level for this query.
|
Boolean |
isIdempotent()
Whether this statement is idempotent, i.e.
|
boolean |
isIdempotentWithDefault(QueryOptions queryOptions) |
boolean |
isTracing()
Returns whether tracing is enabled for this query or not.
|
Statement |
setConsistencyLevel(ConsistencyLevel consistency)
Sets the consistency level for the query.
|
Statement |
setDefaultTimestamp(long defaultTimestamp)
Sets the default timestamp for this query (in microseconds since the epoch).
|
Statement |
setFetchSize(int fetchSize)
Sets the query fetch size.
|
Statement |
setIdempotent(boolean idempotent)
Sets whether this statement is idempotent.
|
Statement |
setOutgoingPayload(Map<String,ByteBuffer> payload)
Set the given outgoing payload on this statement.
|
Statement |
setPagingState(PagingState pagingState)
Sets the paging state.
|
Statement |
setPagingState(PagingState pagingState,
CodecRegistry codecRegistry)
Sets the paging state.
|
Statement |
setPagingStateUnsafe(byte[] pagingState)
Sets the paging state.
|
Statement |
setReadTimeoutMillis(int readTimeoutMillis)
Overrides the default per-host read timeout (
SocketOptions.getReadTimeoutMillis() )
for this statement. |
Statement |
setRetryPolicy(RetryPolicy policy)
Sets the retry policy to use for this query.
|
Statement |
setSerialConsistencyLevel(ConsistencyLevel serialConsistency)
Sets the serial consistency level for the query.
|
isBatchIdempotent
protected StatementWrapper(Statement wrapped)
wrapped
- the wrapped statement.public Statement setConsistencyLevel(ConsistencyLevel consistency)
Statement
setConsistencyLevel
in class Statement
consistency
- the consistency level to set.Statement
object.public ConsistencyLevel getConsistencyLevel()
Statement
getConsistencyLevel
in class Statement
null
if no
consistency level has been specified (through setConsistencyLevel
).
In the latter case, the default consistency level will be used.public Statement setSerialConsistencyLevel(ConsistencyLevel serialConsistency)
Statement
INSERT
, UPDATE
or DELETE
statements with an IF
condition).
For those, the serial consistency level defines
the consistency level of the serial phase (or "paxos" phase) while the
normal consistency level defines the consistency for the "learn" phase, i.e. what
type of reads will be guaranteed to see the update right away. For instance, if
a conditional write has a regular consistency of QUORUM (and is successful), then a
QUORUM read is guaranteed to see that write. But if the regular consistency of that
write is ANY, then only a read with a consistency of SERIAL is guaranteed to see it
(even a read with consistency ALL is not guaranteed to be enough).
The serial consistency can only be one of ConsistencyLevel.SERIAL
or
ConsistencyLevel.LOCAL_SERIAL
. While ConsistencyLevel.SERIAL
guarantees full
linearizability (with other SERIAL updates), ConsistencyLevel.LOCAL_SERIAL
only
guarantees it in the local data center.
The serial consistency level is ignored for any query that is not a conditional
update (serial reads should use the regular consistency level for instance).setSerialConsistencyLevel
in class Statement
serialConsistency
- the serial consistency level to set.Statement
object.public ConsistencyLevel getSerialConsistencyLevel()
Statement
Statement.setSerialConsistencyLevel(ConsistencyLevel)
for more detail on the serial consistency level.getSerialConsistencyLevel
in class Statement
null
if no serial
consistency level has been specified (through Statement.setSerialConsistencyLevel(ConsistencyLevel)
).
In the latter case, the default serial consistency level will be used.public Statement enableTracing()
Statement
enableTracing
in class Statement
Statement
object.public Statement disableTracing()
Statement
disableTracing
in class Statement
Statement
object.public boolean isTracing()
Statement
public ByteBuffer getRoutingKey(ProtocolVersion protocolVersion, CodecRegistry codecRegistry)
Statement
null
. The routing key is an hint used for token-aware routing (see
TokenAwarePolicy
), and
if provided should correspond to the binary value for the query
partition key. However, not providing a routing key never causes a query
to fail and if the load balancing policy used is not token aware, then
the routing key can be safely ignored.getRoutingKey
in class Statement
protocolVersion
- the protocol version that will be used if the actual
implementation needs to serialize something to compute
the key.codecRegistry
- the codec registry that will be used if the actual
implementation needs to serialize something to compute
this key.null
.public String getKeyspace()
Statement
null
. Firstly, some queries do
not operate inside a keyspace: keyspace creation, USE
queries,
user creation, etc. Secondly, even query that operate within a keyspace
do not have to specify said keyspace directly, in which case the
currently logged in keyspace (the one set through a USE
query
(or through the use of Cluster.connect(String)
)). Lastly, as
for the routing key, this keyspace information is only a hint for
token-aware routing (since replica placement depend on the replication
strategy in use which is a per-keyspace property) and having this method
return null
(or even a bogus keyspace name) will never cause the
query to fail.getKeyspace
in class Statement
null
.public Statement setRetryPolicy(RetryPolicy policy)
Statement
Policies.getRetryPolicy()
in the
cluster configuration. This method is thus only useful in case you want
to punctually override the default policy for this request.setRetryPolicy
in class Statement
policy
- the retry policy to use for this query.Statement
object.public RetryPolicy getRetryPolicy()
Statement
getRetryPolicy
in class Statement
null
if no query specific
retry policy has been set through Statement.setRetryPolicy(com.datastax.driver.core.policies.RetryPolicy)
(in which case
the Cluster retry policy will apply if necessary).public Statement setFetchSize(int fetchSize)
Statement
SELECT
queries only ever make use of that setting.
Note: Paging is not supported with the native protocol version 1. If
you call this method with fetchSize > 0
and
fetchSize != Integer.MAX_VALUE
and the protocol version is in
use (i.e. if you've force version 1 through Cluster.Builder.withProtocolVersion(com.datastax.driver.core.ProtocolVersion)
or you use Cassandra 1.2), you will get UnsupportedProtocolVersionException
when submitting this statement for execution.setFetchSize
in class Statement
fetchSize
- the fetch size to use. If fetchSize <e; 0
,
the default fetch size will be used. To disable paging of the
result set, use fetchSize == Integer.MAX_VALUE
.Statement
object.public int getFetchSize()
Statement
getFetchSize
in class Statement
Statement.setFetchSize(int)
is used), the default
fetch size will be used.public Statement setDefaultTimestamp(long defaultTimestamp)
Statement
V3
or
higher of the native protocol is in use. With earlier versions, calling this
method has no effect.
The actual timestamp that will be used for this query is, in order of
preference:
USING TIMESTAMP
syntax);Long.MIN_VALUE
;TimestampGenerator
currently in use,
if different from Long.MIN_VALUE
.setDefaultTimestamp
in class Statement
defaultTimestamp
- the default timestamp for this query (must be strictly
positive).Statement
object.Cluster.Builder.withTimestampGenerator(TimestampGenerator)
public long getDefaultTimestamp()
Statement
getDefaultTimestamp
in class Statement
public Statement setReadTimeoutMillis(int readTimeoutMillis)
Statement
SocketOptions.getReadTimeoutMillis()
)
for this statement.
You should override this only for statements for which the coordinator may allow a longer server-side
timeout (for example aggregation queries).setReadTimeoutMillis
in class Statement
readTimeoutMillis
- the timeout to set. Negative values are not allowed. If it is 0, the read timeout will
be disabled for this statement.Statement
object.public int getReadTimeoutMillis()
Statement
getReadTimeoutMillis
in class Statement
SocketOptions.getReadTimeoutMillis()
will be used.public Statement setPagingState(PagingState pagingState, CodecRegistry codecRegistry)
Statement
ExecutionInfo.getPagingState()
.
This is typically used to iterate in a "stateless" manner (e.g. across HTTP requests):
Statement st = new SimpleStatement("your query");
ResultSet rs = session.execute(st.setFetchSize(20));
int available = rs.getAvailableWithoutFetching();
for (int i = 0; i < available; i++) {
Row row = rs.one();
// Do something with row (e.g. display it to the user...)
}
// Get state and serialize as string or byte[] to store it for the next execution
// (e.g. pass it as a parameter in the "next page" URI)
PagingState pagingState = rs.getExecutionInfo().getPagingState();
String savedState = pagingState.toString();
// Next execution:
// Get serialized state back (e.g. get URI parameter)
String savedState = ...
Statement st = new SimpleStatement("your query");
st.setPagingState(PagingState.fromString(savedState));
ResultSet rs = session.execute(st.setFetchSize(20));
int available = rs.getAvailableWithoutFetching();
for (int i = 0; i < available; i++) {
...
}
The paging state can only be reused between perfectly identical statements
(same query string, same bound parameters). Altering the contents of the paging state
or trying to set it on a different statement will cause this method to fail.
Note that, due to internal implementation details, the paging state is not portable
across native protocol versions (see the
online documentation
for more explanations about the native protocol).
This means that PagingState
instances generated with an old version won't work
with a higher version. If that is a problem for you, consider using the "unsafe" API (see
Statement.setPagingStateUnsafe(byte[])
).setPagingState
in class Statement
pagingState
- the paging state to set, or null
to remove any state that was
previously set on this statement.codecRegistry
- the codec registry that will be used if this method needs to serialize the
statement's values in order to check that the paging state matches.Statement
object.Statement.setPagingState(PagingState)
public Statement setPagingState(PagingState pagingState)
Statement
Statement.setPagingState(PagingState, CodecRegistry)
with CodecRegistry.DEFAULT_INSTANCE
.
Whether you should use this or the other variant depends on the type of statement this is
called on:
BoundStatement
, the codec registry isn't actually needed, so it's always safe to
use this method;SimpleStatement
or BuiltStatement
, you can use this method if you use no
custom codecs, or if your custom codecs are registered with the default registry. Otherwise, use
the other method and provide the registry that contains your codecs.setPagingState
in class Statement
pagingState
- the paging state to set, or null
to remove any state that was
previously set on this statement.public Statement setPagingStateUnsafe(byte[] pagingState)
Statement
Statement.setPagingState(PagingState)
, this method takes the "raw" form of the
paging state (previously extracted with ExecutionInfo.getPagingStateUnsafe()
.
It won't validate that this statement matches the one that the paging state was extracted from.
If the paging state was altered in any way, you will get unpredictable behavior from
Cassandra (ranging from wrong results to a query failure). If you decide to use this variant,
it is strongly recommended to add your own validation (for example, signing the raw state with
a private key).setPagingStateUnsafe
in class Statement
pagingState
- the paging state to set, or null
to remove any state that was
previously set on this statement.Statement
object.public ByteBuffer getPagingState()
public Statement setIdempotent(boolean idempotent)
Statement
Statement.isIdempotent()
for more explanations about this property.setIdempotent
in class Statement
idempotent
- the new value.Statement
object.public Boolean isIdempotent()
Statement
retries
on write timeouts or request errors;speculative executions
.
null
, in which case the driver will default to
QueryOptions.getDefaultIdempotence()
.
By default, this method returns null
for all statements, except for
BuiltStatement
- value will be inferred from the query: if it updates counters,
prepends/appends to a list, or uses a function call or
QueryBuilder.raw(String)
anywhere in an inserted value,
the result will be false
; otherwise it will be true
.
Batch
and BatchStatement
:
Statement.setIdempotent(boolean)
forces a value that overrides calculated value.
Note that when a statement is prepared (Session.prepare(String)
), its idempotence flag will be propagated
to all PreparedStatement
s created from it.isIdempotent
in class Statement
null
to use
QueryOptions.getDefaultIdempotence()
.public boolean isIdempotentWithDefault(QueryOptions queryOptions)
public Map<String,ByteBuffer> getOutgoingPayload()
Statement
null
if no payload has been set, otherwise
it always returns immutable maps.
This feature is only available with ProtocolVersion.V4
or above.
Trying to include custom payloads in requests sent by the driver
under lower protocol versions will result in an
UnsupportedFeatureException
(wrapped in a NoHostAvailableException
).getOutgoingPayload
in class Statement
null
if no payload has been set.public Statement setOutgoingPayload(Map<String,ByteBuffer> payload)
Statement
ProtocolVersion.V4
or above.
Trying to include custom payloads in requests sent by the driver
under lower protocol versions will result in an
UnsupportedFeatureException
(wrapped in a NoHostAvailableException
).setOutgoingPayload
in class Statement
payload
- the outgoing payload to include with this statement,
or null
to clear any previously entered payload.Statement
object.Copyright © 2012–2017. All rights reserved.