com.datastax.oss.driver.api.core.session

Interface Request

All Known Subinterfaces:

BatchableStatement<SelfT>, BatchGraphStatement, BatchStatement, BoundStatement, FluentGraphStatement, GraphStatement<SelfT>, PrepareRequest, ScriptGraphStatement, SimpleStatement, Statement<SelfT>

public interface Request

A request executed by a Session.

This is a high-level abstraction, agnostic to the actual language (e.g. CQL). A request is anything that can be converted to a protocol message, provided that you register a request processor with the driver to do that conversion.

Method Summary

Modifier and Type	Method and Description
Map<String,ByteBuffer>	getCustomPayload() Returns the custom payload to send alongside the request.
DriverExecutionProfile	getExecutionProfile() The execution profile to use for this request, or null if no profile has been set.
String	getExecutionProfileName() The name of the execution profile that will be used for this request, or null if no profile has been set.
CqlIdentifier	getKeyspace() The CQL keyspace to execute this request in, or null if this request does not specify any keyspace.
Node	getNode()
default Partitioner	getPartitioner() The partitioner to use for token-aware routing.
ByteBuffer	getRoutingKey() The partition key to use for token-aware routing.
CqlIdentifier	getRoutingKeyspace() The keyspace to use for token-aware routing.
Token	getRoutingToken() The token to use for token-aware routing.
Duration	getTimeout() How long to wait for this request to complete.
Boolean	isIdempotent() Whether the request is idempotent; that is, whether applying the request twice leaves the database in the same state.

Method Detail

getExecutionProfileName

@Nullable
String getExecutionProfileName()

The name of the execution profile that will be used for this request, or null if no profile has been set.

Note that this will be ignored if getExecutionProfile() returns a non-null value.

See Also:

DriverConfig

getExecutionProfile

@Nullable
DriverExecutionProfile getExecutionProfile()

The execution profile to use for this request, or null if no profile has been set.

It is generally simpler to specify a profile name with getExecutionProfileName(). However, this method can be used to provide a "derived" profile that was built programmatically by the client code. If specified, it overrides the profile name.

See Also:

DriverExecutionProfile

getKeyspace

@Nullable
CqlIdentifier getKeyspace()

The CQL keyspace to execute this request in, or null if this request does not specify any keyspace.

This overrides Session.getKeyspace() for this particular request, providing a way to specify the keyspace without forcing it globally on the session, nor hard-coding it in the query string.

This feature is only available with native protocol v5 or higher. Specifying a per-request keyspace with lower protocol versions will cause a runtime error.

See Also:

CASSANDRA-10145

getRoutingKeyspace

@Nullable
CqlIdentifier getRoutingKeyspace()

The keyspace to use for token-aware routing.

Note that if a per-request keyspace is already defined for this request, it takes precedence over this method.

See getRoutingKey() for a detailed explanation of token-aware routing.

getRoutingKey

@Nullable
ByteBuffer getRoutingKey()

The partition key to use for token-aware routing.

For each request, the driver tries to determine a routing keyspace and a routing key by calling the following methods:

• routing keyspace:
  • the result of getKeyspace(), if not null;
  • otherwise, the result of getRoutingKeyspace(), if not null;
  • otherwise, the result of Session.getKeyspace(), if not empty;
  • otherwise, null.
• routing key:
  • the result of getRoutingToken(), if not null;
  • otherwise, the result of getRoutingKey(), if not null;
  • otherwise, null.

This provides a hint of the partition that the request operates on. When the driver picks a coordinator for execution, it will prioritize the replicas that own that partition, in order to avoid an extra network jump on the server side.

Routing information is optional: if either keyspace or key is null, token-aware routing is disabled for this request.

getRoutingToken

@Nullable
Token getRoutingToken()

The token to use for token-aware routing.

This is an alternative to getRoutingKey(). Both methods represent the same information, a request can provide one or the other.

See getRoutingKey() for a detailed explanation of token-aware routing.

getPartitioner

default Partitioner getPartitioner()

The partitioner to use for token-aware routing. If null, the cluster-wide partitioner will be used.

getCustomPayload

@NonNull
Map<String,ByteBuffer> getCustomPayload()

Returns the custom payload to send alongside the request.

This is used to exchange extra information with the server. By default, Cassandra doesn't do anything with this, you'll only need it if you have a custom request handler on the server-side.

Returns:

The custom payload, or an empty map if no payload is present.

isIdempotent

@Nullable
Boolean isIdempotent()

Whether the request is idempotent; that is, whether applying the request twice leaves the database in the same state.

This is used internally for retries and speculative executions: if a request is not idempotent, the driver will take extra care to ensure that it is not sent twice (for example, don't retry if there is the slightest chance that the request reached a coordinator).

Returns:

a boolean value, or null to use the default value defined in the configuration.

See Also:

DefaultDriverOption.REQUEST_DEFAULT_IDEMPOTENCE

getTimeout

@Nullable
Duration getTimeout()

How long to wait for this request to complete. This is a global limit on the duration of a session.execute() call, including any retries the driver might do.

Returns:

the set duration, or null to use the default value defined in the configuration.

See Also:

DefaultDriverOption.REQUEST_TIMEOUT

getNode

@Nullable
Node getNode()

Returns:

The node configured on this statement, or null if none is configured.