Package com.datastax.driver.core

Class BatchStatement

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

      • 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:

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

      • getRoutingStatement

        @Beta
public Statement getRoutingStatement​(ProtocolVersion protocolVersion,
                                     CodecRegistry codecRegistry)
        Returns the first statement in this batch that provides a routing key for the given protocol version and codec registry.