com.datastax.driver.core

Class BatchStatement

java.lang.Object

com.datastax.driver.core.Statement

com.datastax.driver.core.BatchStatement

public class BatchStatement
extends Statement

A statement that groups a number of Statement so they get executed as a batch.

Note: BatchStatement is not supported with the native protocol version 1: you will get an UnsupportedFeatureException when submitting one if version 1 of the protocol 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). Note however that you can still use CQL Batch statements even with the protocol version 1.

Setting a BatchStatement's serial consistency level is only supported with the native protocol version 3 or higher (see setSerialConsistencyLevel(ConsistencyLevel)).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	BatchStatement.Type The type of batch to use.

Field Summary

Fields inherited from class com.datastax.driver.core.Statement

idempotent, NULL_PAYLOAD_VALUE

Constructor Summary

Constructors

Constructor and Description
BatchStatement() Creates a new LOGGED batch statement.
BatchStatement(BatchStatement.Type batchType) Creates a new batch statement of the provided type.

Method Summary

Modifier and Type	Method and Description
BatchStatement	add(Statement statement) Adds a new statement to this batch.
BatchStatement	addAll(Iterable<? extends Statement> statements) Adds multiple statements to this batch.
BatchStatement	clear() Clears this batch, removing all statements added so far.
String	getKeyspace() Returns the keyspace this query operates on.
ByteBuffer	getRoutingKey(ProtocolVersion protocolVersion, CodecRegistry codecRegistry) Returns the routing key (in binary raw form) to use for token aware routing of this query.
Collection<Statement>	getStatements() The statements that have been added to this batch so far.
Boolean	isIdempotent() Whether this statement is idempotent, i.e.
int	requestSizeInBytes(ProtocolVersion protocolVersion, CodecRegistry codecRegistry) Returns the number of bytes required to encode this statement.
BatchStatement	setSerialConsistencyLevel(ConsistencyLevel serialConsistency) Sets the serial consistency level for the query.
int	size() Returns the number of elements in this batch.

Methods inherited from class com.datastax.driver.core.Statement

disableTracing, enableTracing, getConsistencyLevel, getDefaultTimestamp, getFetchSize, getHost, getOutgoingPayload, getReadTimeoutMillis, getRetryPolicy, getSerialConsistencyLevel, isBatchIdempotent, isTracing, setConsistencyLevel, setDefaultTimestamp, setFetchSize, setHost, setIdempotent, setOutgoingPayload, setPagingState, setPagingState, setPagingStateUnsafe, setReadTimeoutMillis, setRetryPolicy

Methods inherited from class java.lang.Object

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

Constructor Detail

BatchStatement

public BatchStatement()

Creates a new LOGGED batch statement.

BatchStatement

public BatchStatement(BatchStatement.Type batchType)

Creates a new batch statement of the provided type.

Parameters:

batchType - the type of batch.

Method Detail

add

public BatchStatement add(Statement statement)

Adds a new statement to this batch.

Note that statement can be any Statement. It is allowed to mix RegularStatement and BoundStatement in the same BatchStatement in particular. Adding another BatchStatement is also allowed for convenience and is equivalent to adding all the Statement contained in that other BatchStatement.

Due to a protocol-level limitation, adding a RegularStatement with named values is currently not supported; an IllegalArgument will be thrown.

When adding a BoundStatement, all of its values must be set, otherwise an IllegalStateException will be thrown when submitting the batch statement. See BoundStatement for more details, in particular how to handle null values.

Please note that the options of the added Statement (all those defined directly by the Statement class: consistency level, fetch size, tracing, ...) will be ignored for the purpose of the execution of the Batch. Instead, the options used are the one of this BatchStatement object.

Parameters:

statement - the new statement to add.

Returns:

this batch statement.

Throws:

IllegalStateException - if adding the new statement means that this BatchStatement has more than 65536 statements (since this is the maximum number of statements for a BatchStatement allowed by the underlying protocol).

IllegalArgumentException - if adding a regular statement that uses named values.

addAll

public BatchStatement addAll(Iterable<? extends Statement> statements)

Adds multiple statements to this batch.

This is a shortcut method that calls add(com.datastax.driver.core.Statement) on all the statements from statements.

Parameters:

statements - the statements to add.

Returns:

this batch statement.

getStatements

public Collection<Statement> getStatements()

The statements that have been added to this batch so far.

Returns:

an (immutable) collection of the statements that have been added to this batch so far.

clear

public BatchStatement clear()

Clears this batch, removing all statements added so far.

Returns:

this (now empty) BatchStatement.

size

public int size()

Returns the number of elements in this batch.

Returns:

the number of elements in this batch.

requestSizeInBytes

public int requestSizeInBytes(ProtocolVersion protocolVersion,
                              CodecRegistry codecRegistry)

Description copied from class: Statement

Returns the number of bytes required to encode this statement.

The calculated size may be overestimated by a few bytes, but is never underestimated. If the size cannot be calculated, this method returns -1.

Note that the returned value is not cached, but instead recomputed at every method call.

Overrides:

requestSizeInBytes in class Statement

Returns:

the number of bytes required to encode this statement.

setSerialConsistencyLevel

public BatchStatement setSerialConsistencyLevel(ConsistencyLevel serialConsistency)

Sets the serial consistency level for the query.

This is only supported with version 3 or higher of the native protocol. If you call this method when version 2 is in use, you will get an UnsupportedFeatureException when submitting the statement. With version 2, protocol batches with conditions have their serial consistency level hardcoded to SERIAL; if you need to execute a batch with LOCAL_SERIAL, you will have to use a CQL batch.

Overrides:

setSerialConsistencyLevel in class Statement

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.

See Also:

Statement.setSerialConsistencyLevel(ConsistencyLevel)

getRoutingKey

public ByteBuffer getRoutingKey(ProtocolVersion protocolVersion,
                                CodecRegistry codecRegistry)

Description copied from class: Statement

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.

Specified by:

getRoutingKey in class Statement

Parameters:

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.

Returns:

the routing key for this query or null.

getKeyspace

public String getKeyspace()

Description copied from class: Statement

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

Specified by:

getKeyspace in class Statement

Returns:

the keyspace this query operate on if relevant or null.

isIdempotent

public Boolean isIdempotent()

Description copied from class: Statement

Whether this statement is idempotent, i.e. whether it can be applied multiple times without changing the result beyond the initial application.

If a statement is not idempotent, the driver will ensure that it never gets executed more than once, which means:

• avoiding retries on write timeouts or request errors;
• never scheduling speculative executions.

(this behavior is implemented in the driver internals, the corresponding policies will not even be invoked).

Note that this method can return 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:
  1. If any statement in batch has isIdempotent() false - return false
  2. If no statements with isIdempotent() false, but some have isIdempotent() null - return null
  3. Otherwise - return true

In all cases, calling 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 PreparedStatements created from it.

Overrides:

isIdempotent in class Statement

Returns:

whether this statement is idempotent, or null to use QueryOptions.getDefaultIdempotence().