com.datastax.driver.core
Class Statement

java.lang.Object
  com.datastax.driver.core.Statement

Direct Known Subclasses:

BatchStatement, BoundStatement, RegularStatement

public abstract class Statement
extends Object

An executable query.

This represents either a RegularStatement, a BoundStatement or a BatchStatement along with the querying options (consistency level, whether to trace the query, ...).

Method Summary

Statement	disableTracing() Disables tracing for this query.
Statement	enableTracing() Enables tracing for this query.
ConsistencyLevel	getConsistencyLevel() The consistency level for this query.
int	getFetchSize() The fetch size for this query.
abstract String	getKeyspace() Returns the keyspace this query operates on.
RetryPolicy	getRetryPolicy() Returns the retry policy sets for this query, if any.
abstract ByteBuffer	getRoutingKey() 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	isTracing() Returns whether tracing is enabled for this query or not.
Statement	setConsistencyLevel(ConsistencyLevel consistency) Sets the consistency level for the query.
Statement	setFetchSize(int fetchSize) Sets the query fetch size.
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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setConsistencyLevel

public Statement setConsistencyLevel(ConsistencyLevel consistency)

Sets the consistency level for the query.

Parameters:

consistency - the consistency level to set.

Returns:

this Statement object.

getConsistencyLevel

public ConsistencyLevel getConsistencyLevel()

The consistency level for this query.

Returns:

the consistency level for this query, or null if no consistency level has been specified (through setConsistencyLevel). In the latter case, the default consistency level will be used.

setSerialConsistencyLevel

public Statement setSerialConsistencyLevel(ConsistencyLevel serialConsistency)

Sets the serial consistency level for the query. The serial consistency level is only used by conditional updates (so INSERT, UPDATE and DELETE 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 datacenter.

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).

Parameters:

serialConsistency - the serial consistency level to set.

Returns:

this Statement object.

Throws:

IllegalArgumentException - if serialConsistency is not one of ConsistencyLevel.SERIAL or ConsistencyLevel.LOCAL_SERIAL.

getSerialConsistencyLevel

public ConsistencyLevel getSerialConsistencyLevel()

The serial consistency level for this query.

See setSerialConsistencyLevel(com.datastax.driver.core.ConsistencyLevel) for more detail on the serial consistency level.

Returns:

the consistency level for this query, or null if no serial consistency level has been specified (through setSerialConsistencyLevel). In the latter case, the default serial consistency level will be used.

enableTracing

public Statement enableTracing()

Enables tracing for this query. By default (that is unless you call this method), tracing is not enabled.

Returns:

this Statement object.

disableTracing

public Statement disableTracing()

Disables tracing for this query.

Returns:

this Statement object.

isTracing

public boolean isTracing()

Returns whether tracing is enabled for this query or not.

Returns:

true if this query has tracing enabled, false otherwise.

getRoutingKey

public abstract ByteBuffer getRoutingKey()

Returns the routing key (in binary raw form) to use for token aware routing of this query.

The routing key is optional in that implementers are free to return 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.

Returns:

the routing key for this query or null.

getKeyspace

public abstract String getKeyspace()

Returns the keyspace this query operates on.

Note that not all query specify on which keyspace they operate on, and so this method can always reutrn 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.

Returns:

the keyspace this query operate on if relevant or null.

setRetryPolicy

public Statement setRetryPolicy(RetryPolicy policy)

Sets the retry policy to use for this query.

The default retry policy, if this method is not called, is the one returned by 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.

Parameters:

policy - the retry policy to use for this query.

Returns:

this Statement object.

getRetryPolicy

public RetryPolicy getRetryPolicy()

Returns the retry policy sets for this query, if any.

Returns:

the retry policy sets specifically for this query or null if no query specific retry policy has been set through setRetryPolicy(com.datastax.driver.core.policies.RetryPolicy) (in which case the Cluster retry policy will apply if necessary).

setFetchSize

public Statement setFetchSize(int fetchSize)

Sets the query fetch size.

The fetch size controls how much resulting rows will be retrieved simultaneously (the goal being to avoid loading too much results in memory for queries yielding large results). Please note that while value as low as 1 can be used, it is *highly* discouraged to use such a low value in practice as it will yield very poor performance. If in doubt, leaving the default is probably a good idea.

Also note that only SELECT queries only ever make use of that setting.

Parameters:

fetchSize - the fetch size to use. If fetchSize &lte; 0, the default fetch size will be used. To disable paging of the result set, use fetchSize == Integer.MAX_VALUE.

Returns:

this Statement object.

getFetchSize

public int getFetchSize()

The fetch size for this query.

Returns:

the fetch size for this query. If that value is less or equal to 0 (the default unless setFetchSize(int) is used), the default fetch size will be used.