public abstract class BuiltStatement extends RegularStatement
QueryBuilder
.
The actual query string will be generated and cached the first time it is requested, which is
either when the driver tries to execute the query, or when you call certain public methods (for
example RegularStatement.getQueryString(CodecRegistry)
, getObject(int,
CodecRegistry)
).
Whenever possible (and unless you call setForceNoValues(boolean)
, the builder will
try to handle values passed to its methods as standalone values bound to the query string with
placeholders. For instance:
select().all().from("foo").where(eq("k", "the key")); // Is equivalent to: new SimpleStatement("SELECT * FROM foo WHERE k=?", "the key");There are a few exceptions to this rule:
select().all().from("foo").where(eq("k", 1)); // Is equivalent to: new SimpleStatement("SELECT * FROM foo WHERE k=1");One final thing to consider is
custom codecs
. If you've registered codecs
to handle your own Java types against the cluster, then you can pass instances of those types to
query builder methods. But should the builder have to inline those values, it needs your codecs
to convert them to string form
. That is why some of the public
methods of this class take a CodecRegistry
as a parameter:
BuiltStatement s = select().all().from("foo").where(eq("k", myCustomObject)); // if we do this codecs will definitely be needed: s.forceNoValues(true); s.getQueryString(myCodecRegistry);For convenience, there are no-arg versions of those methods that use
CodecRegistry.DEFAULT_INSTANCE
. But you should only use them if you are sure that no custom
values will need to be inlined while building the statement, or if you have registered your
custom codecs with the default registry instance. Otherwise, you will get a CodecNotFoundException
.idempotent, NULL_PAYLOAD_VALUE
Modifier and Type | Method and Description |
---|---|
protected static String |
escapeId(String ident)
Deprecated.
preserved for backward compatibility, use
Metadata.quoteIfNecessary(String)
instead. |
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 value as the Java type matching its CQL type. |
Object |
getObject(int i,
CodecRegistry codecRegistry)
Returns the
i th 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 (in binary raw form) to use for token aware routing of this query.
|
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. |
Boolean |
isIdempotent()
Whether this statement is idempotent, i.e.
|
RegularStatement |
setForceNoValues(boolean forceNoValues)
Allows to force this builder to not generate values (through its
getValues() method). |
String |
toString()
Returns this statement as a CQL query string.
|
boolean |
usesNamedValues()
Whether this statement uses named values.
|
getQueryString, hasValues, requestSizeInBytes
disableTracing, enableTracing, getConsistencyLevel, getDefaultTimestamp, getFetchSize, getHost, getOutgoingPayload, getReadTimeoutMillis, getRetryPolicy, getSerialConsistencyLevel, isBatchIdempotent, isTracing, setConsistencyLevel, setDefaultTimestamp, setFetchSize, setHost, setIdempotent, setOutgoingPayload, setPagingState, setPagingState, setPagingStateUnsafe, setReadTimeoutMillis, setRetryPolicy, setSerialConsistencyLevel
@Deprecated protected static String escapeId(String ident)
Metadata.quoteIfNecessary(String)
instead.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 Object getObject(int i, CodecRegistry codecRegistry)
i
th value as the Java type matching its CQL type.i
- the index to retrieve.codecRegistry
- the codec registry that will be used if the statement must be rebuilt in
order to determine if it has values, and Java objects must be inlined in the process (see
BuiltStatement
for more explanations on why this is so).i
th value of this statement.IllegalStateException
- if this statement does not have values.IndexOutOfBoundsException
- if i
is not a valid index for this object.getObject(int)
public Object getObject(int i)
i
th value as the Java type matching its CQL type.
This method calls getObject(int, CodecRegistry)
with CodecRegistry.DEFAULT_INSTANCE
. It's safe to use if you don't use any custom codecs, or if
your custom codecs are in the default registry; otherwise, use the other method and provide the
registry that contains your codecs.
i
- the index to retrieve.i
th value of this statement.IllegalStateException
- if this statement does not have values.IndexOutOfBoundsException
- if i
is not a valid index for this object.public ByteBuffer getRoutingKey(ProtocolVersion protocolVersion, CodecRegistry codecRegistry)
Statement
The routing key is optional in that implementers are free to return null
. The
routing key is an hint used for token-aware routing (see TokenAwarePolicy
), and if provided should correspond to the
binary value for the query partition key. However, not providing a routing key never causes a
query to fail and if the load balancing policy used is not token aware, then the routing key
can be safely ignored.
getRoutingKey
in class Statement
protocolVersion
- the protocol version that will be used if the actual implementation
needs to serialize something to compute the key.codecRegistry
- the codec registry that will be used if the actual implementation needs to
serialize something to compute this key.null
.public String getKeyspace()
Statement
Note that not all query specify on which keyspace they operate on, and so this method can
always return null
. Firstly, some queries do not operate inside a keyspace: keyspace
creation, USE
queries, user creation, etc. Secondly, even query that operate within a
keyspace do not have to specify said keyspace directly, in which case the currently logged in
keyspace (the one set through a USE
query (or through the use of Cluster.connect(String)
)). Lastly, as for the routing key, this keyspace information is only a
hint for token-aware routing (since replica placement depend on the replication strategy in use
which is a per-keyspace property) and having this method return null
(or even a bogus
keyspace name) will never cause the query to fail.
getKeyspace
in class Statement
null
.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.SimpleStatement(String, Object...)
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 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.SimpleStatement(String, Map)
public boolean usesNamedValues()
RegularStatement
usesNamedValues
in class RegularStatement
false
if RegularStatement.getNamedValues(ProtocolVersion, CodecRegistry)
returns null
, true
otherwise.public Boolean isIdempotent()
Statement
If a statement is not idempotent, the driver will ensure that it never gets executed more than once, which means:
retries
on write timeouts or request errors;
speculative executions
.
Note that this method can return null
, in which case the driver will default to
QueryOptions.getDefaultIdempotence()
.
By default, this method returns null
for all statements, except for
BuiltStatement
- value will be inferred from the query: if it updates counters,
prepends/appends to a list, or uses a function call or QueryBuilder.raw(String)
anywhere in an inserted
value, the result will be false
; otherwise it will be true
.
Batch
and BatchStatement
:
Statement.setIdempotent(boolean)
forces a value that overrides calculated
value.
Note that when a statement is prepared (Session.prepare(String)
), its idempotence
flag will be propagated to all PreparedStatement
s created from it.
isIdempotent
in class Statement
null
to use QueryOptions.getDefaultIdempotence()
.public String toString()
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.
See the javadocs of RegularStatement.getQueryString()
for more information.
toString
in class RegularStatement
RegularStatement.getQueryString()
public RegularStatement setForceNoValues(boolean forceNoValues)
getValues()
method).
By default (and unless the protocol version 1 is in use, see below) and for performance
reasons, the query builder will not serialize all values provided to strings. This means that
getQueryString(CodecRegistry)
may return a query string with bind markers (where and
when is at the discretion of the builder) and getValues(com.datastax.driver.core.ProtocolVersion, com.datastax.driver.core.CodecRegistry)
will return the binary values
for those markers. This method allows to force the builder to not generate binary values but
rather to inline them all in the query string. In practice, this means that if you call setForceNoValues(true)
, you are guaranteed that getValues()
will return null
and that the string returned by getQueryString()
will contain no other bind markers
than the ones specified by the user.
If the native protocol version 1 is in use, the driver will default to not generating values
since those are not supported by that version of the protocol. In practice, the driver will
automatically call this method with true
as argument prior to execution. Hence, calling
this method when the protocol version 1 is in use is basically a no-op.
Note that this method is mainly useful for debugging purpose. In general, the default behavior should be the correct and most efficient one.
forceNoValues
- whether or not this builder may generate values.Copyright © 2012–2018. All rights reserved.