com.datastax.driver.core

Class BoundStatement

java.lang.Object

com.datastax.driver.core.Query

com.datastax.driver.core.BoundStatement

public class BoundStatement
extends Query

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

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. If multiple bind variables correspond to the same column (as would be the case if you prepare SELECT * FROM t WHERE x > ? AND x < ?), you will have to set values by indexes (or the bind(java.lang.Object...) method) as the methods to set by name only allows to set the first prepared occurrence of the column.

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

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
BoundStatement	bind(Object... values) Bound values to the variables of this statement.
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) Set the ith value to the provided boolean.
BoundStatement	setBool(String name, boolean v) Set the value for the first occurrence of column 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 the first occurrence of column 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 the first occurrence of column 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 the first occurrence of column 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 the first occurrence of column 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 the first occurrence of column 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 the first occurrence of column 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 the first occurrence of column 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) Set the value for the first occurrence of column 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 the first occurrence of column name to the provided list.
BoundStatement	setLong(int i, long v) Set the ith value to the provided long.
BoundStatement	setLong(String name, long v) Set the value for the first occurrence of column 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 the first occurrence of column 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 the first occurrence of column 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 the first occurrence of column 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 the first occurrence of column 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 the first occurrence of column name to the provided big integer.

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

disableTracing, enableTracing, getConsistencyLevel, getRetryPolicy, isTracing, setConsistencyLevel, setRetryPolicy

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.

NullPointerException - if one of values is a collection (List, Set or Map) containing a null value. Nulls are not supported in collections by CQL.

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 value takes precedence even if the partition key is part of the bound variables.

Specified by:

getRoutingKey in class Query

Returns:

the routing key for this statement or null.

setBool

public BoundStatement setBool(int i,
                     boolean v)

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

Set the value for the first occurrence of column name to the provided boolean.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, only the first one is 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 column 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)

Set the value for the first occurrence of column name to the provided integer.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, only the first one is 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 column i is not of type INT.

setLong

public BoundStatement setLong(int i,
                     long v)

Set 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 of type BIGINT or COUNTER.

setLong

public BoundStatement setLong(String name,
                     long v)

Set the value for the first occurrence of column name to the provided long.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, only the first one is 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 column i is 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 the first occurrence of column name to the provided date.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, only the first one is 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 column 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 the first occurrence of column name to the provided float.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, only the first one is 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 column i 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 the first occurrence of column name to the provided double.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, only the first one is 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 column i 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 the first occurrence of column name to the provided string.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, only the first one is 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 column 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 the first occurrence of column 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, only the first one is 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 column 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 the first occurrence of column 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, only the first one is 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 the first occurrence of column name to the provided big integer.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, only the first one is 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 column 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 the first occurrence of column name to the provided big decimal.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, only the first one is 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 column 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 the first occurrence of column name to the provided UUID.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, only the first one is 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 column 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 the first occurrence of column name to the provided inet address.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, only the first one is 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 column name is not of type INET.

setList

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

Sets the ith value to the provided list.

Please note that null values are not supported inside collection by CQL.

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.

NullPointerException - if v contains null values. Nulls are not supported in collections by CQL.

setList

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

Sets the value for the first occurrence of column name to the provided list.

Please note that null values are not supported inside collection by CQL.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, only the first one is 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 column name is not a list type or if the elements of v are not of the type of the elements of column name.

NullPointerException - if v contains null values. Nulls are not supported in collections by CQL.

setMap

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

Sets the ith value to the provided map.

Please note that null values are not supported inside collection by CQL.

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.

NullPointerException - if v contains null values. Nulls are not supported in collections by CQL.

setMap

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

Sets the value for the first occurrence of column name to the provided map.

Please note that null values are not supported inside collection by CQL.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, only the first one is 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 column 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.

NullPointerException - if v contains null values. Nulls are not supported in collections by CQL.

setSet

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

Sets the ith value to the provided set.

Please note that null values are not supported inside collection by CQL.

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.

NullPointerException - if v contains null values. Nulls are not supported in collections by CQL.

setSet

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

Sets the value for the first occurrence of column name to the provided set.

Please note that null values are not supported inside collection by CQL.

Parameters:

name - the name of the variable to set; if multiple variables name are prepared, only the first one is 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 column name is not a set type or if the elements of v are not of the type of the elements of column name.

NullPointerException - if v contains null values. Nulls are not supported in collections by CQL.