com.datastax.driver.core

Class RegularStatement

java.lang.Object

com.datastax.driver.core.Statement

com.datastax.driver.core.RegularStatement

Direct Known Subclasses:

BuiltStatement, SchemaStatement, SimpleStatement

public abstract class RegularStatement
extends Statement

A regular (non-prepared and non batched) CQL statement.

This class represents a query string along with query options (and optionally binary values, see getValues). It can be extended but SimpleStatement is provided as a simple implementation to build a RegularStatement directly from its query string.

Field Summary

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

idempotent, NULL_PAYLOAD_VALUE

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	RegularStatement() Creates a new RegularStatement.

Method Summary

Modifier and Type	Method and Description
String	getKeyspace() Returns the keyspace this query operates on.
abstract Map<String,ByteBuffer>	getNamedValues(ProtocolVersion protocolVersion, CodecRegistry codecRegistry) The named values to use for this statement.
String	getQueryString() Returns the query string for this statement.
abstract String	getQueryString(CodecRegistry codecRegistry) Returns the query string for this statement.
Token	getRoutingToken() Returns the routing token to use for token aware routing of this query.
abstract ByteBuffer[]	getValues(ProtocolVersion protocolVersion, CodecRegistry codecRegistry) The positional values to use for this statement.
boolean	hasValues() Whether or not this statement has values, that is if getValues will return null or not.
abstract boolean	hasValues(CodecRegistry codecRegistry) Whether or not this statement has values, that is if getValues will return null or not.
int	requestSizeInBytes(ProtocolVersion protocolVersion, CodecRegistry codecRegistry) Returns the number of bytes required to encode this statement.
RegularStatement	setRoutingToken(Token routingToken) Sets a routing token for this statement.
String	toString() Returns this statement as a CQL query string.
abstract boolean	usesNamedValues() Whether this statement uses named values.

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

disableTracing, enableTracing, executingAs, getConsistencyLevel, getDefaultTimestamp, getFetchSize, getOutgoingPayload, getReadTimeoutMillis, getRetryPolicy, getRoutingKey, getSerialConsistencyLevel, isBatchIdempotent, isIdempotent, isTracing, setConsistencyLevel, setDefaultTimestamp, setFetchSize, 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

RegularStatement

protected RegularStatement()

Creates a new RegularStatement.

Method Detail

getQueryString

public abstract String getQueryString(CodecRegistry codecRegistry)

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.

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 getQueryString() depending on the type of statement this is called on.

Returns:

a valid CQL query string.

See Also:

getQueryString()

getQueryString

public String getQueryString()

Returns the query string for this statement.

This method calls getQueryString(CodecRegistry) with CodecRegistry.DEFAULT_INSTANCE. Whether you should use this or the other variant depends on the type of statement this is called on:

• for a SimpleStatement or SchemaStatement, the codec registry isn't actually needed, so it's always safe to use this method;
• for a BuiltStatement you can use this method if you use no custom codecs, or if your custom codecs are registered with the default registry. Otherwise, use the other method and provide the registry that contains your codecs (see BuiltStatement for more explanations on why this is so);
• for a BatchStatement, use the first rule if it contains no built statements, or the second rule otherwise.

Returns:

a valid CQL query string.

getValues

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

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

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.

Throws:

InvalidTypeException - if one of the values is not of a type that can be serialized to a CQL3 type

See Also:

SimpleStatement.SimpleStatement(String, Object...)

getNamedValues

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

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

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.

Throws:

InvalidTypeException - if one of the values is not of a type that can be serialized to a CQL3 type

See Also:

SimpleStatement.SimpleStatement(String, Map)

hasValues

public abstract boolean hasValues(CodecRegistry codecRegistry)

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

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 hasValues() depending on the type of statement this is called on.

Returns:

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

See Also:

hasValues()

usesNamedValues

public abstract boolean usesNamedValues()

Whether this statement uses named values.

Returns:

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

hasValues

public boolean hasValues()

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

This method calls hasValues(CodecRegistry) with ProtocolVersion.NEWEST_SUPPORTED. Whether you should use this or the other variant depends on the type of statement this is called on:

• for a SimpleStatement or SchemaStatement, the codec registry isn't actually needed, so it's always safe to use this method;
• for a BuiltStatement you can use this method if you use no custom codecs, or if your custom codecs are registered with the default registry. Otherwise, use the other method and provide the registry that contains your codecs (see BuiltStatement for more explanations on why this is so);
• for a BatchStatement, use the first rule if it contains no built statements, or the second rule otherwise.

Returns:

false if getValues(com.datastax.driver.core.ProtocolVersion, com.datastax.driver.core.CodecRegistry) returns null, true otherwise.

getRoutingToken

public Token getRoutingToken()

Description copied from class: Statement

Returns the routing token to use for token aware routing of this query.

This is similar to Statement.getRoutingKey(ProtocolVersion, CodecRegistry), except that the key is already hashed. A typical use case would be analytics clients wishing to optimize a query by splitting it into chunks, each targeted to a direct replica. Such clients could call Metadata.getTokenRanges() to get a description of the ring, and then issue a separate query with the end token of each range. Unlike the routing key, the routing token is never computed automatically.

If both the routing key and token are defined, the token is used in priority.

Overrides:

getRoutingToken in class Statement

Returns:

an optional routing token for this statement or null.

setRoutingToken

public RegularStatement setRoutingToken(Token routingToken)

Sets a routing token for this statement.

See Also:

getRoutingToken()

getKeyspace

public String getKeyspace()

Returns the keyspace this query operates on.

Unless the keyspace has been explicitly set through a means such as SimpleStatement.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.

Specified by:

getKeyspace in class Statement

Returns:

the keyspace if set, null otherwise.

See Also:

Statement.getKeyspace()

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.

toString

public String toString()

Returns this statement as a CQL query string.

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.

See the javadocs of getQueryString() for more information.

Overrides:

toString in class Object

Returns:

this statement as a CQL query string.

See Also:

getQueryString()