public class SimpleStatement extends RegularStatement
RegularStatement
implementation built directly from a query string.idempotent, NULL_PAYLOAD_VALUE
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. |
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
i th 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 . |
getQueryString, hasValues, requestSizeInBytes, toString
disableTracing, enableTracing, getConsistencyLevel, getDefaultTimestamp, getFetchSize, getHost, getOutgoingPayload, getReadTimeoutMillis, getRetryPolicy, getSerialConsistencyLevel, isBatchIdempotent, isIdempotent, isTracing, setConsistencyLevel, setDefaultTimestamp, setFetchSize, setHost, setIdempotent, setOutgoingPayload, setPagingState, setPagingState, setPagingStateUnsafe, setReadTimeoutMillis, setRetryPolicy, setSerialConsistencyLevel
public SimpleStatement(String query)
SimpleStatement
with the provided query string (and no values).query
- the query string.public SimpleStatement(String query, Object... values)
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:
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});
query
- the query string.values
- values required for the execution of query
.IllegalArgumentException
- if the number of values is greater than 65535.public SimpleStatement(String query, Map<String,Object> values)
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.
query
- the query string.values
- named values required for the execution of query
.IllegalArgumentException
- if the number of values is greater than 65535.public String getQueryString(CodecRegistry codecRegistry)
RegularStatement
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.
getQueryString
in class RegularStatement
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.RegularStatement.getQueryString()
public ByteBuffer[] getValues(ProtocolVersion protocolVersion, CodecRegistry codecRegistry)
RegularStatement
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).
getValues
in class RegularStatement
protocolVersion
- the protocol version that will be used to serialize the values.codecRegistry
- the codec registry that will be used to serialize the values.SimpleStatement(String, Object...)
public Map<String,ByteBuffer> getNamedValues(ProtocolVersion protocolVersion, CodecRegistry codecRegistry)
RegularStatement
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).
getNamedValues
in class RegularStatement
protocolVersion
- the protocol version that will be used to serialize the values.codecRegistry
- the codec registry that will be used to serialize the values.SimpleStatement(String, Map)
public int valuesCount()
getValues
.public boolean hasValues(CodecRegistry codecRegistry)
RegularStatement
getValues
will return null
or not.hasValues
in class RegularStatement
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.false
if both RegularStatement.getValues(ProtocolVersion, CodecRegistry)
and RegularStatement.getNamedValues(ProtocolVersion, CodecRegistry)
return null
, true
otherwise.RegularStatement.hasValues()
public boolean usesNamedValues()
RegularStatement
usesNamedValues
in class RegularStatement
false
if RegularStatement.getNamedValues(ProtocolVersion, CodecRegistry)
returns null
, true
otherwise.public Object getObject(int i)
i
th 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.
i
- the index to retrieve.i
th value of this statement.IllegalStateException
- if this statement does not have positional values.IndexOutOfBoundsException
- if i
is not a valid index for this object.public Object getObject(String name)
name
- the name of the value to retrieve.null
if there is no such name.IllegalStateException
- if this statement does not have named values.public Set<String> getValueNames()
IllegalStateException
- if this statement does not have named values.public ByteBuffer getRoutingKey(ProtocolVersion protocolVersion, CodecRegistry codecRegistry)
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.
getRoutingKey
in class Statement
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).setRoutingKey(java.nio.ByteBuffer)
if such a key was set, null
otherwise.Statement.getRoutingKey(com.datastax.driver.core.ProtocolVersion, com.datastax.driver.core.CodecRegistry)
public SimpleStatement setRoutingKey(ByteBuffer routingKey)
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.
routingKey
- the raw (binary) value to use as routing key.SimpleStatement
object.Statement.getRoutingKey(com.datastax.driver.core.ProtocolVersion, com.datastax.driver.core.CodecRegistry)
public String getKeyspace()
Unless the keyspace has been explicitly set through setKeyspace(java.lang.String)
, this method will
return null
to avoid having to parse the query string.
getKeyspace
in class Statement
setKeyspace(java.lang.String)
if such keyspace was set, null
otherwise.Statement.getKeyspace()
public SimpleStatement setKeyspace(String keyspace)
This method allows you to manually provide a keyspace for this query. It is thus optional since the value returned by this method is only an hint for token aware load balancing policy but is never mandatory.
Do note that if the query does not use a fully qualified keyspace, then you do not need to set the keyspace through that method as the currently logged in keyspace will be used.
keyspace
- the name of the keyspace this query operates on.SimpleStatement
object.Statement.getKeyspace()
public SimpleStatement setRoutingKey(ByteBuffer... routingKeyComponents)
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.
routingKeyComponents
- the raw (binary) values to compose to obtain the routing key.SimpleStatement
object.Statement.getRoutingKey(com.datastax.driver.core.ProtocolVersion, com.datastax.driver.core.CodecRegistry)
Copyright © 2012–2018. All rights reserved.