com.datastax.driver.core

Class SimpleStatement

java.lang.Object

com.datastax.driver.core.Statement

com.datastax.driver.core.RegularStatement

com.datastax.driver.core.SimpleStatement

public class SimpleStatement
extends RegularStatement

A simple RegularStatement implementation built directly from a query string.

Field Summary

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

idempotent, NULL_PAYLOAD_VALUE

Constructor Summary

Constructors

Constructor and Description
SimpleStatement(String query) Creates a new SimpleStatement with the provided query string (and no values).
SimpleStatement(String query, Map<String,Object> values) Creates a new SimpleStatement with the provided query string and named values.
SimpleStatement(String query, Object... values) Creates a new SimpleStatement with the provided query string and values.

Method Summary

Modifier and Type	Method and Description
String	getKeyspace() Returns the keyspace this query operates on.
Map<String,ByteBuffer>	getNamedValues(ProtocolVersion protocolVersion, CodecRegistry codecRegistry) The named values to use for this statement.
Object	getObject(int i) Returns the ith positional value as the Java type matching its CQL type.
Object	getObject(String name) Returns a named value as the Java type matching its CQL type.
String	getQueryString(CodecRegistry codecRegistry) Returns the query string for this statement.
ByteBuffer	getRoutingKey(ProtocolVersion protocolVersion, CodecRegistry codecRegistry) Returns the routing key for the query.
Set<String>	getValueNames() Returns the names of the named values of this statement.
ByteBuffer[]	getValues(ProtocolVersion protocolVersion, CodecRegistry codecRegistry) The positional values to use for this statement.
boolean	hasValues(CodecRegistry codecRegistry) Whether or not this statement has values, that is if getValues will return null or not.
SimpleStatement	setKeyspace(String keyspace) Sets the keyspace this query operates on.
SimpleStatement	setRoutingKey(ByteBuffer... routingKeyComponents) Sets the routing key for this query.
SimpleStatement	setRoutingKey(ByteBuffer routingKey) Sets the routing key for this query.
boolean	usesNamedValues() Whether this statement uses named values.
int	valuesCount() The number of values for this statement, that is the size of the array that will be returned by getValues.

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

getQueryString, getRoutingToken, hasValues, requestSizeInBytes, setRoutingToken, toString

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

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

Methods inherited from class java.lang.Object

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

Constructor Detail

SimpleStatement

public SimpleStatement(String query)

Creates a new SimpleStatement with the provided query string (and no values).

Parameters:

query - the query string.

SimpleStatement

public SimpleStatement(String query,
                       Object... values)

Creates a new SimpleStatement with the provided query string and values.

This version of SimpleStatement is useful when you want to execute a query only once (and thus do not want to resort to prepared statement), but do not want to convert all column values to string (typically, if you have blob values, encoding them to a hexadecimal string is not very efficient). In that case, you can provide a query string with bind markers to this constructor along with the values for those bind variables. When executed, the server will prepare the provided, bind the provided values to that prepare statement and execute the resulting statement. Thus,

   session.execute(new SimpleStatement(query, value1, value2, value3));
 

is functionally equivalent to

   PreparedStatement ps = session.prepare(query);
   session.execute(ps.bind(value1, value2, value3));
 

except that the former version:

• Requires only one round-trip to a Cassandra node.
• Does not left any prepared statement stored in memory (neither client or server side) once it has been executed.

Note that the types of the values provided to this method will not be validated by the driver as is done by BoundStatement.bind(java.lang.Object...) since query is not parsed (and hence the driver cannot know what those values should be). The codec to serialize each value will be chosen in the codec registry associated with the cluster executing this statement, based on the value's Java type (this is the equivalent to calling CodecRegistry.codecFor(Object)). If too many or too few values are provided, or if a value is not a valid one for the variable it is bound to, an InvalidQueryException will be thrown by Cassandra at execution time. A CodecNotFoundException may be thrown by this constructor however, if the codec registry does not know how to handle one of the values.

If you have a single value of type Map<String, Object>, you can't call this constructor using the varargs syntax, because the signature collides with SimpleStatement(String, Map). To prevent this, pass an explicit array object:

 new SimpleStatement("...", new Object[]{m});
 

Parameters:

query - the query string.

values - values required for the execution of query.

Throws:

IllegalArgumentException - if the number of values is greater than 65535.

SimpleStatement

public SimpleStatement(String query,
                       Map<String,Object> values)

Creates a new SimpleStatement with the provided query string and named values.

This constructor requires that the query string use named placeholders, for example:

 new SimpleStatement("SELECT * FROM users WHERE id = :i", ImmutableMap.<String, Object>of("i", 1));
 

Make sure that the map is correctly typed Map<String, Object>, otherwise you might accidentally call SimpleStatement(String, Object...) with a positional value of type map.

The types of the values will be handled the same way as with anonymous placeholders (see SimpleStatement(String, Object...)).

Simple statements with named values are only supported starting with native protocol v3. With earlier versions, an UnsupportedFeatureException will be thrown at execution time.

Parameters:

query - the query string.

values - named values required for the execution of query.

Throws:

IllegalArgumentException - if the number of values is greater than 65535.

Method Detail

getQueryString

public String getQueryString(CodecRegistry codecRegistry)

Description copied from class: RegularStatement

Returns the query string for this statement.

It is important to note that the query string is merely a CQL representation of this statement, but it does not convey all the information stored in Statement objects.

For example, Statement objects carry numerous protocol-level settings, such as the consistency level to use, or the idempotence flag, among others. None of these settings will be included in the resulting query string.

Similarly, if values have been set on this statement because it has bind markers, these values will not appear in the resulting query string.

Note: the consistency level was conveyed at CQL level in older versions of the CQL grammar, but since CASSANDRA-4734 it is now a protocol-level setting and consequently does not appear in the query string.

Specified by:

getQueryString in class RegularStatement

Parameters:

codecRegistry - the codec registry that will be used if the actual implementation needs to serialize Java objects in the process of generating the query. Note that it might be possible to use the no-arg RegularStatement.getQueryString() depending on the type of statement this is called on.

Returns:

a valid CQL query string.

See Also:

RegularStatement.getQueryString()

getValues

public ByteBuffer[] getValues(ProtocolVersion protocolVersion,
                              CodecRegistry codecRegistry)

Description copied from class: RegularStatement

The positional values to use for this statement.

A statement can use either positional or named values, but not both. So if this method returns a non-null result, RegularStatement.getNamedValues(ProtocolVersion, CodecRegistry) will return null.

Values for a RegularStatement (i.e. if either method does not return null) are not supported with the native protocol version 1: you will get an UnsupportedProtocolVersionException when submitting one if version 1 of the protocol is in use (i.e. if you've forced version 1 through Cluster.Builder.withProtocolVersion(com.datastax.driver.core.ProtocolVersion) or you use Cassandra 1.2).

Specified by:

getValues in class RegularStatement

Parameters:

protocolVersion - the protocol version that will be used to serialize the values.

codecRegistry - the codec registry that will be used to serialize the values.

See Also:

SimpleStatement(String, Object...)

getNamedValues

public Map<String,ByteBuffer> getNamedValues(ProtocolVersion protocolVersion,
                                             CodecRegistry codecRegistry)

Description copied from class: RegularStatement

The named values to use for this statement.

A statement can use either positional or named values, but not both. So if this method returns a non-null result, RegularStatement.getValues(ProtocolVersion, CodecRegistry) will return null.

Values for a RegularStatement (i.e. if either method does not return null) are not supported with the native protocol version 1: you will get an UnsupportedProtocolVersionException when submitting one if version 1 of the protocol is in use (i.e. if you've forced version 1 through Cluster.Builder.withProtocolVersion(com.datastax.driver.core.ProtocolVersion) or you use Cassandra 1.2).

Specified by:

getNamedValues in class RegularStatement

Parameters:

protocolVersion - the protocol version that will be used to serialize the values.

codecRegistry - the codec registry that will be used to serialize the values.

Returns:

the named values.

See Also:

SimpleStatement(String, Map)

valuesCount

public int valuesCount()

The number of values for this statement, that is the size of the array that will be returned by getValues.

Returns:

the number of values.

hasValues

public boolean hasValues(CodecRegistry codecRegistry)

Description copied from class: RegularStatement

Whether or not this statement has values, that is if getValues will return null or not.

Specified by:

hasValues in class RegularStatement

Parameters:

codecRegistry - the codec registry that will be used if the actual implementation needs to serialize Java objects in the process of determining if the query has values. Note that it might be possible to use the no-arg RegularStatement.hasValues() depending on the type of statement this is called on.

Returns:

false if both RegularStatement.getValues(ProtocolVersion, CodecRegistry) and RegularStatement.getNamedValues(ProtocolVersion, CodecRegistry) return null, true otherwise.

See Also:

RegularStatement.hasValues()

usesNamedValues

public boolean usesNamedValues()

Description copied from class: RegularStatement

Whether this statement uses named values.

Specified by:

usesNamedValues in class RegularStatement

Returns:

false if RegularStatement.getNamedValues(ProtocolVersion, CodecRegistry) returns null, true otherwise.

getObject

public Object getObject(int i)

Returns the ith positional value as the Java type matching its CQL type.

Note that, unlike with other driver types like Row, you can't retrieve named values by position. This getter will throw an exception if the statement was created with named values (or no values at all). Call usesNamedValues() to check the type of values, and getObject(String) if they are positional.

Parameters:

i - the index to retrieve.

Returns:

the ith value of this statement.

Throws:

IllegalStateException - if this statement does not have positional values.

IndexOutOfBoundsException - if i is not a valid index for this object.

getObject

public Object getObject(String name)

Returns a named value as the Java type matching its CQL type.

Parameters:

name - the name of the value to retrieve.

Returns:

the value that matches the name, or null if there is no such name.

Throws:

IllegalStateException - if this statement does not have named values.

getValueNames

public Set<String> getValueNames()

Returns the names of the named values of this statement.

Returns:

the names of the named values of this statement.

Throws:

IllegalStateException - if this statement does not have named values.

getRoutingKey

public ByteBuffer getRoutingKey(ProtocolVersion protocolVersion,
                                CodecRegistry codecRegistry)

Returns the routing key for the query.

Unless the routing key has been explicitly set through setRoutingKey(java.nio.ByteBuffer), this method will return null to avoid having to parse the query string to retrieve the partition key.

Specified by:

getRoutingKey in class Statement

Parameters:

protocolVersion - unused by this implementation (no internal serialization is required to compute the key).

codecRegistry - unused by this implementation (no internal serialization is required to compute the key).

Returns:

the routing key set through setRoutingKey(java.nio.ByteBuffer) if such a key was set, null otherwise.

See Also:

Statement.getRoutingKey(com.datastax.driver.core.ProtocolVersion, com.datastax.driver.core.CodecRegistry)

setRoutingKey

public SimpleStatement setRoutingKey(ByteBuffer routingKey)

Sets the routing key for this query.

This method allows you to manually provide a routing key for this query. It is thus optional since the routing key is only an hint for token aware load balancing policy but is never mandatory.

If the partition key for the query is composite, use the setRoutingKey(ByteBuffer...) method instead to build the routing key.

Parameters:

routingKey - the raw (binary) value to use as routing key.

Returns:

this SimpleStatement object.

See Also:

Statement.getRoutingKey(com.datastax.driver.core.ProtocolVersion, com.datastax.driver.core.CodecRegistry)

getKeyspace

public String getKeyspace()

Description copied from class: RegularStatement

Returns the keyspace this query operates on.

Unless the keyspace has been explicitly set through a means such as setKeyspace(java.lang.String), this method will return null to avoid having to parse the query string.

Note: This returns the internal representation of the keyspace. In the typical case, the internal representation is equivalent to the CQL representation. However, if you are using a keyspace that requires the use of quotes in CQL (a quoted identifier), i.e.: "MyKS", this method will return the unquoted representation instead, i.e. MyKS.

Overrides:

getKeyspace in class RegularStatement

Returns:

the keyspace if set, null otherwise.

See Also:

Statement.getKeyspace()

setKeyspace

public SimpleStatement setKeyspace(String keyspace)

Sets the keyspace this query operates on.

This method allows you to manually provide a keyspace for this query. It is used for the following:

1. To indicate to cassandra what keyspace the statement is applicable to (protocol V5+ only). This is useful when the query does not provide an explicit keyspace and you want to override the session's keyspace.
2. By TokenAwarePolicy to help identify which replicas are applicable to send this statement to.

Do note that if the query does not use a fully qualified keyspace, then you do not need to set the keyspace through this method as the currently logged in keyspace will be used if it is set.

Note: This expects the internal representation of the keyspace. In the typical case, the internal representation is equivalent to the CQL representation. However, if you are using a keyspace that requires the use of quotes in CQL (a quoted identifier), i.e.: "MyKS", this method will return the unquoted representation instead, i.e. MyKS.

Parameters:

keyspace - the name of the keyspace this query operates on.

Returns:

this SimpleStatement object.

See Also:

Statement.getKeyspace()

setRoutingKey

public SimpleStatement setRoutingKey(ByteBuffer... routingKeyComponents)

Sets the routing key for this query.

See setRoutingKey(ByteBuffer) for more information. This method is a variant for when the query partition key is composite and thus the routing key must be built from multiple values.

Parameters:

routingKeyComponents - the raw (binary) values to compose to obtain the routing key.

Returns:

this SimpleStatement object.

See Also:

Statement.getRoutingKey(com.datastax.driver.core.ProtocolVersion, com.datastax.driver.core.CodecRegistry)