com.datastax.driver.core
Class BoundStatement

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

public class BoundStatement
extends Statement

A prepared statement with values bound to the bind variables.

Once values has been provided for the variables of the PreparedStatement it has been created from, such BoundStatement can be executed (through Session.execute(Statement)).

The values of a BoundStatement can be set by either index or name. When setting them by name, names follow the case insensitivity rules explained in ColumnDefinitions but with the difference that if multiple bind variables have the same name, setting that name will set all the variables for that name.

Any variable that hasn't been specifically set will be considered null.

Constructor Summary

BoundStatement(PreparedStatement statement)
Creates a new BoundStatement from the provided prepared statement.

Method Summary

BoundStatement	bind(Object... values) Bound values to the variables of this statement.
String	getKeyspace() Returns the keyspace this query operates on.
ByteBuffer	getRoutingKey() The routing key for this bound query.
boolean	isSet(int i) Returns whether the ith variable has been bound to a non null value.
boolean	isSet(String name) Returns whether the first occurrence of variable name has been bound to a non-null value.
PreparedStatement	preparedStatement() Returns the prepared statement on which this BoundStatement is based.
BoundStatement	setBool(int i, boolean v) Sets the ith value to the provided boolean.
BoundStatement	setBool(String name, boolean v) Sets the value for (all occurrences of) variable name to the provided boolean.
BoundStatement	setBytes(int i, ByteBuffer v) Sets the ith value to the provided byte buffer.
BoundStatement	setBytes(String name, ByteBuffer v) Sets the value for (all occurrences of) variable name to the provided byte buffer.
BoundStatement	setBytesUnsafe(int i, ByteBuffer v) Sets the ith value to the provided byte buffer.
BoundStatement	setBytesUnsafe(String name, ByteBuffer v) Sets the value for (all occurrences of) variable name to the provided byte buffer.
BoundStatement	setDate(int i, Date v) Set the ith value to the provided date.
BoundStatement	setDate(String name, Date v) Sets the value for (all occurrences of) variable name to the provided date.
BoundStatement	setDecimal(int i, BigDecimal v) Sets the ith value to the provided big decimal.
BoundStatement	setDecimal(String name, BigDecimal v) Sets the value for (all occurrences of) variable name to the provided big decimal.
BoundStatement	setDouble(int i, double v) Sets the ith value to the provided double.
BoundStatement	setDouble(String name, double v) Sets the value for (all occurrences of) variable name to the provided double.
BoundStatement	setFloat(int i, float v) Sets the ith value to the provided float.
BoundStatement	setFloat(String name, float v) Sets the value for (all occurrences of) variable name to the provided float.
BoundStatement	setInet(int i, InetAddress v) Sets the ith value to the provided inet address.
BoundStatement	setInet(String name, InetAddress v) Sets the value for (all occurrences of) variable name to the provided inet address.
BoundStatement	setInt(int i, int v) Set the ith value to the provided integer.
BoundStatement	setInt(String name, int v) Sets the value for (all occurrences of) variable name to the provided integer.
<T> BoundStatement	setList(int i, List<T> v) Sets the ith value to the provided list.
<T> BoundStatement	setList(String name, List<T> v) Sets the value for (all occurrences of) variable name to the provided list.
BoundStatement	setLong(int i, long v) Sets the ith value to the provided long.
BoundStatement	setLong(String name, long v) Sets the value for (all occurrences of) variable name to the provided long.
<K,V> BoundStatement	setMap(int i, Map<K,V> v) Sets the ith value to the provided map.
<K,V> BoundStatement	setMap(String name, Map<K,V> v) Sets the value for (all occurrences of) variable name to the provided map.
<T> BoundStatement	setSet(int i, Set<T> v) Sets the ith value to the provided set.
<T> BoundStatement	setSet(String name, Set<T> v) Sets the value for (all occurrences of) variable name to the provided set.
BoundStatement	setString(int i, String v) Sets the ith value to the provided string.
BoundStatement	setString(String name, String v) Sets the value for (all occurrences of) variable name to the provided string.
BoundStatement	setUUID(int i, UUID v) Sets the ith value to the provided UUID.
BoundStatement	setUUID(String name, UUID v) Sets the value for (all occurrences of) variable name to the provided UUID.
BoundStatement	setVarint(int i, BigInteger v) Sets the ith value to the provided big integer.
BoundStatement	setVarint(String name, BigInteger v) Sets the value for (all occurrences of) variable name to the provided big integer.

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

disableTracing, enableTracing, getConsistencyLevel, getFetchSize, getRetryPolicy, getSerialConsistencyLevel, isTracing, setConsistencyLevel, setFetchSize, setRetryPolicy, setSerialConsistencyLevel

Methods inherited from class java.lang.Object

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

Constructor Detail

BoundStatement

public BoundStatement(PreparedStatement statement)

Creates a new BoundStatement from the provided prepared statement.

Parameters:

statement - the prepared statement from which to create a BoundStatement.

Method Detail

preparedStatement

public PreparedStatement preparedStatement()

Returns the prepared statement on which this BoundStatement is based.

Returns:

the prepared statement on which this BoundStatement is based.

isSet

public boolean isSet(int i)

Returns whether the ith variable has been bound to a non null value.

Parameters:

i - the index of the variable to check.

Returns:

whether the ith variable has been bound to a non null value.

Throws:

IndexOutOfBoundsException - if i < 0 || i >= this.preparedStatement().variables().size().

isSet

public boolean isSet(String name)

Returns whether the first occurrence of variable name has been bound to a non-null value.

Parameters:

name - the name of the variable to check.

Returns:

whether the first occurrence of variable name has been bound to a non-null value.

Throws:

IllegalArgumentException - if name is not a prepared variable, that is if !this.preparedStatement().variables().names().contains(name).

bind

public BoundStatement bind(Object... values)

Bound values to the variables of this statement. This is a convenience method to bind all the variables of the BoundStatement in one call.

Parameters:

values - the values to bind to the variables of the newly created BoundStatement. The first element of values will be bound to the first bind variable, etc. It is legal to provide fewer values than the statement has bound variables. In that case, the remaining variable need to be bound before execution. If more values than variables are provided however, an IllegalArgumentException wil be raised.

Returns:

this bound statement.

Throws:

IllegalArgumentException - if more values are provided than there is of bound variables in this statement.

InvalidTypeException - if any of the provided value is not of correct type to be bound to the corresponding bind variable.

getRoutingKey

public ByteBuffer getRoutingKey()

The routing key for this bound query.

This method will return a non-null value if either of the following occur:

• All the columns composing the partition key are bound variables of this BoundStatement. The routing key will then be built using the values provided for these partition key columns.
• The routing key has been set through PreparedStatement.setRoutingKey(java.nio.ByteBuffer) for the PreparedStatement this statement has been built from.

Otherwise, null is returned.

Note that if the routing key has been set through PreparedStatement.setRoutingKey(java.nio.ByteBuffer), that latter value takes precedence even if the partition key is part of the bound variables.

Specified by:

getRoutingKey in class Statement

Returns:

the routing key for this statement or null.

getKeyspace

public String getKeyspace()

Returns the keyspace this query operates on.

This method will always return a non-null value (unless the statement has no variables, but you should avoid prepared statement in the first in that case). The keyspace returned will be the one corresponding to the first variable prepared in this statement (which in almost all case will be the keyspace for the operation, though it's possible in CQL to build a batch statement that acts on multiple keyspace).

Specified by:

getKeyspace in class Statement

Returns:

the keyspace for this statement (see above), or null if the statement has no variables.

setBool

public BoundStatement setBool(int i,
                              boolean v)

Sets the ith value to the provided boolean.

Parameters:

i - the index of the variable to set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IndexOutOfBoundsException - if i < 0 || i >= this.preparedStatement().variables().size().

InvalidTypeException - if column i is not of type BOOLEAN.

setBool

public BoundStatement setBool(String name,
                              boolean v)

Sets the value for (all occurrences of) variable name to the provided boolean.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, all of them are set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IllegalArgumentException - if name is not a prepared variable, that is, if !this.preparedStatement().variables().names().contains(name).

InvalidTypeException - if (any one occurrence of) name is not of type BOOLEAN.

setInt

public BoundStatement setInt(int i,
                             int v)

Set the ith value to the provided integer.

Parameters:

i - the index of the variable to set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IndexOutOfBoundsException - if i < 0 || i >= this.preparedStatement().variables().size().

InvalidTypeException - if column i is not of type INT.

setInt

public BoundStatement setInt(String name,
                             int v)

Sets the value for (all occurrences of) variable name to the provided integer.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, all of them are set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IllegalArgumentException - if name is not a prepared variable, that is, if !this.preparedStatement().variables().names().contains(name).

InvalidTypeException - if (any one occurrence of) name is not of type INT.

setLong

public BoundStatement setLong(int i,
                              long v)

Sets the ith value to the provided long.

Parameters:

i - the index of the variable to set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IndexOutOfBoundsException - if i < 0 || i >= this.preparedStatement().variables().size().

InvalidTypeException - if column i is not of type BIGINT or COUNTER.

setLong

public BoundStatement setLong(String name,
                              long v)

Sets the value for (all occurrences of) variable name to the provided long.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, all of them are set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IllegalArgumentException - if name is not a prepared variable, that is, if !this.preparedStatement().variables().names().contains(name).

InvalidTypeException - if (nany one occurrence of) name is not of type BIGINT or COUNTER.

setDate

public BoundStatement setDate(int i,
                              Date v)

Set the ith value to the provided date.

Parameters:

i - the index of the variable to set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IndexOutOfBoundsException - if i < 0 || i >= this.preparedStatement().variables().size().

InvalidTypeException - if column i is not of type TIMESTAMP.

setDate

public BoundStatement setDate(String name,
                              Date v)

Sets the value for (all occurrences of) variable name to the provided date.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, all of them are set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IllegalArgumentException - if name is not a prepared variable, that is, if !this.preparedStatement().variables().names().contains(name).

InvalidTypeException - if (nany one occurrence of) name is not of type TIMESTAMP.

setFloat

public BoundStatement setFloat(int i,
                               float v)

Sets the ith value to the provided float.

Parameters:

i - the index of the variable to set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IndexOutOfBoundsException - if i < 0 || i >= this.preparedStatement().variables().size().

InvalidTypeException - if column i is not of type FLOAT.

setFloat

public BoundStatement setFloat(String name,
                               float v)

Sets the value for (all occurrences of) variable name to the provided float.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, all of them are set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IllegalArgumentException - if name is not a prepared variable, that is, if !this.preparedStatement().variables().names().contains(name).

InvalidTypeException - if (nany one occurrence of) name is not of type FLOAT.

setDouble

public BoundStatement setDouble(int i,
                                double v)

Sets the ith value to the provided double.

Parameters:

i - the index of the variable to set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IndexOutOfBoundsException - if i < 0 || i >= this.preparedStatement().variables().size().

InvalidTypeException - if column i is not of type DOUBLE.

setDouble

public BoundStatement setDouble(String name,
                                double v)

Sets the value for (all occurrences of) variable name to the provided double.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, all of them are set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IllegalArgumentException - if name is not a prepared variable, that is, if !this.preparedStatement().variables().names().contains(name).

InvalidTypeException - if (nany one occurrence of) name is not of type DOUBLE.

setString

public BoundStatement setString(int i,
                                String v)

Sets the ith value to the provided string.

Parameters:

i - the index of the variable to set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IndexOutOfBoundsException - if i < 0 || i >= this.preparedStatement().variables().size().

InvalidTypeException - if column i is of neither of the following types: VARCHAR, TEXT or ASCII.

setString

public BoundStatement setString(String name,
                                String v)

Sets the value for (all occurrences of) variable name to the provided string.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, all of them are set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IllegalArgumentException - if name is not a prepared variable, that is, if !this.preparedStatement().variables().names().contains(name).

InvalidTypeException - if (nany one occurrence of) name is of neither of the following types: VARCHAR, TEXT or ASCII.

setBytes

public BoundStatement setBytes(int i,
                               ByteBuffer v)

Sets the ith value to the provided byte buffer. This method validate that the type of the column set is BLOB. If you want to insert manually serialized data into columns of another type, use setBytesUnsafe(int, java.nio.ByteBuffer) instead.

Parameters:

i - the index of the variable to set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IndexOutOfBoundsException - if i < 0 || i >= this.preparedStatement().variables().size().

InvalidTypeException - if column i is not of type BLOB.

setBytes

public BoundStatement setBytes(String name,
                               ByteBuffer v)

Sets the value for (all occurrences of) variable name to the provided byte buffer. This method validate that the type of the column set is BLOB. If you want to insert manually serialized data into columns of another type, use setBytesUnsafe(int, java.nio.ByteBuffer) instead.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, all of them are set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IllegalArgumentException - if name is not a prepared variable, that is if !this.preparedStatement().variables().names().contains(name).

InvalidTypeException - if (nany one occurrence of) name is not of type BLOB.

setBytesUnsafe

public BoundStatement setBytesUnsafe(int i,
                                     ByteBuffer v)

Sets the ith value to the provided byte buffer. Contrary to setBytes(int, java.nio.ByteBuffer), this method does not check the type of the column set. If you insert data that is not compatible with the type of the column, you will get an InvalidQueryException at execute time.

Parameters:

i - the index of the variable to set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IndexOutOfBoundsException - if i < 0 || i >= this.preparedStatement().variables().size().

setBytesUnsafe

public BoundStatement setBytesUnsafe(String name,
                                     ByteBuffer v)

Sets the value for (all occurrences of) variable name to the provided byte buffer. Contrary to setBytes(int, java.nio.ByteBuffer), this method does not check the type of the column set. If you insert data that is not compatible with the type of the column, you will get an InvalidQueryException at execute time.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, all of them are set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IllegalArgumentException - if name is not a prepared variable, that is if !this.preparedStatement().variables().names().contains(name).

setVarint

public BoundStatement setVarint(int i,
                                BigInteger v)

Sets the ith value to the provided big integer.

Parameters:

i - the index of the variable to set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IndexOutOfBoundsException - if i < 0 || i >= this.preparedStatement().variables().size().

InvalidTypeException - if column i is not of type VARINT.

setVarint

public BoundStatement setVarint(String name,
                                BigInteger v)

Sets the value for (all occurrences of) variable name to the provided big integer.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, all of them are set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IllegalArgumentException - if name is not a prepared variable, that is, if !this.preparedStatement().variables().names().contains(name).

InvalidTypeException - if (nany one occurrence of) name is not of type VARINT.

setDecimal

public BoundStatement setDecimal(int i,
                                 BigDecimal v)

Sets the ith value to the provided big decimal.

Parameters:

i - the index of the variable to set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IndexOutOfBoundsException - if i < 0 || i >= this.preparedStatement().variables().size().

InvalidTypeException - if column i is not of type DECIMAL.

setDecimal

public BoundStatement setDecimal(String name,
                                 BigDecimal v)

Sets the value for (all occurrences of) variable name to the provided big decimal.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, all of them are set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IllegalArgumentException - if name is not a prepared variable, that is, if !this.preparedStatement().variables().names().contains(name).

InvalidTypeException - if (nany one occurrence of) name is not of type DECIMAL.

setUUID

public BoundStatement setUUID(int i,
                              UUID v)

Sets the ith value to the provided UUID.

Parameters:

i - the index of the variable to set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IndexOutOfBoundsException - if i < 0 || i >= this.preparedStatement().variables().size().

InvalidTypeException - if column i is not of type UUID or TIMEUUID, or if column i is of type TIMEUUID but v is not a type 1 UUID.

setUUID

public BoundStatement setUUID(String name,
                              UUID v)

Sets the value for (all occurrences of) variable name to the provided UUID.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, all of them are set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IllegalArgumentException - if name is not a prepared variable, that is, if !this.preparedStatement().variables().names().contains(name).

InvalidTypeException - if (nany one occurrence of) name is not of type UUID or TIMEUUID, or if column name is of type TIMEUUID but v is not a type 1 UUID.

setInet

public BoundStatement setInet(int i,
                              InetAddress v)

Sets the ith value to the provided inet address.

Parameters:

i - the index of the variable to set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IndexOutOfBoundsException - if i < 0 || i >= this.preparedStatement().variables().size().

InvalidTypeException - if column i is not of type INET.

setInet

public BoundStatement setInet(String name,
                              InetAddress v)

Sets the value for (all occurrences of) variable name to the provided inet address.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, all of them are set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IllegalArgumentException - if name is not a prepared variable, that is, if !this.preparedStatement().variables().names().contains(name).

InvalidTypeException - if (nany one occurrence of) name is not of type INET.

setList

public <T> BoundStatement setList(int i,
                                  List<T> v)

Sets the ith value to the provided list.

Parameters:

i - the index of the variable to set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IndexOutOfBoundsException - if i < 0 || i >= this.preparedStatement().variables().size().

InvalidTypeException - if column i is not a list type or if the elements of v are not of the type of the elements of column i.

setList

public <T> BoundStatement setList(String name,
                                  List<T> v)

Sets the value for (all occurrences of) variable name to the provided list.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, all of them are set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IllegalArgumentException - if name is not a prepared variable, that is, if !this.preparedStatement().variables().names().contains(name).

InvalidTypeException - if (nany one occurrence of) name is not a list type or if the elements of v are not of the type of the elements of column name.

setMap

public <K,V> BoundStatement setMap(int i,
                                   Map<K,V> v)

Sets the ith value to the provided map.

Parameters:

i - the index of the variable to set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IndexOutOfBoundsException - if i < 0 || i >= this.preparedStatement().variables().size().

InvalidTypeException - if column i is not a map type or if the elements (keys or values) of v are not of the type of the elements of column i.

setMap

public <K,V> BoundStatement setMap(String name,
                                   Map<K,V> v)

Sets the value for (all occurrences of) variable name to the provided map.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, all of them are set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IllegalArgumentException - if name is not a prepared variable, that is, if !this.preparedStatement().variables().names().contains(name).

InvalidTypeException - if (nany one occurrence of) name is not a map type or if the elements (keys or values) of v are not of the type of the elements of column name.

setSet

public <T> BoundStatement setSet(int i,
                                 Set<T> v)

Sets the ith value to the provided set.

Parameters:

i - the index of the variable to set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IndexOutOfBoundsException - if i < 0 || i >= this.preparedStatement().variables().size().

InvalidTypeException - if column i is not a set type or if the elements of v are not of the type of the elements of column i.

setSet

public <T> BoundStatement setSet(String name,
                                 Set<T> v)

Sets the value for (all occurrences of) variable name to the provided set.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, all of them are set.

v - the value to set.

Returns:

this BoundStatement.

Throws:

IllegalArgumentException - if name is not a prepared variable, that is, if !this.preparedStatement().variables().names().contains(name).

InvalidTypeException - if (nany one occurrence of) name is not a map type or if the elements of v are not of the type of the elements of column name.