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

Interface Session

All Superinterfaces:

AsyncAutoCloseable, AutoCloseable

All Known Subinterfaces:

AsyncCqlSession, ContinuousReactiveSession, ContinuousSession, CqlSession, DseSession, GraphSession, ReactiveGraphSession, ReactiveSession, SyncCqlSession

public interface Session
extends AsyncAutoCloseable

A nexus to send requests to a Cassandra cluster.

This is a high-level abstraction capable of handling arbitrary request and result types. The driver's built-in CqlSession is a more convenient subtype for most client applications.

The driver's request execution logic is pluggable (see RequestProcessor in the internal API) to allow custom extensions. Hence the generic execute(Request, GenericType) method in this interface, that makes no assumptions about the request or result type.

See Also:

CqlSession.builder()

Field Summary

Fields

Modifier and Type	Field and Description
static MavenCoordinates	OSS_DRIVER_COORDINATES The Maven coordinates of the core driver artifact.

Method Summary

Modifier and Type	Method and Description
default boolean	checkSchemaAgreement() Convenience method to call checkSchemaAgreementAsync() and block for the result.
CompletionStage<Boolean>	checkSchemaAgreementAsync() Checks if all nodes in the cluster agree on a common schema version.
<RequestT extends Request,ResultT> ResultT	execute(RequestT request, GenericType<ResultT> resultType) Executes an arbitrary request.
DriverContext	getContext() Returns a context that provides access to all the policies used by this driver instance.
Optional<CqlIdentifier>	getKeyspace() The keyspace that this session is currently connected to, or Optional.empty() if this session is not connected to any keyspace.
Metadata	getMetadata() Returns a snapshot of the Cassandra cluster's topology and schema metadata.
Optional<Metrics>	getMetrics() Returns a gateway to the driver's DropWizard metrics, or Optional.empty() if all metrics are disabled, or if the driver has been configured to use MicroProfile or Micrometer instead of DropWizard (see advanced.metrics.factory.class in the configuration).
String	getName() The unique name identifying this session instance.
boolean	isSchemaMetadataEnabled() Whether schema metadata is currently enabled.
default Metadata	refreshSchema() Convenience method to call refreshSchemaAsync() and block for the result.
CompletionStage<Metadata>	refreshSchemaAsync() Force an immediate refresh of the schema metadata, even if it is currently disabled (either in the configuration or via setSchemaMetadataEnabled(Boolean)).
CompletionStage<Metadata>	setSchemaMetadataEnabled(Boolean newValue) Enable or disable schema metadata programmatically.

Methods inherited from interface com.datastax.oss.driver.api.core.AsyncAutoCloseable

close, closeAsync, closeFuture, forceCloseAsync, isClosed

Field Detail

OSS_DRIVER_COORDINATES

@NonNull
static final MavenCoordinates OSS_DRIVER_COORDINATES

The Maven coordinates of the core driver artifact.

This is intended for products that wrap or extend the driver, as a way to check compatibility if end-users override the driver version in their application.

Method Detail

getName

@NonNull
String getName()

The unique name identifying this session instance. This is used as a prefix for log messages and metrics.

This gets populated from the option basic.session-name in the configuration. If that option is absent, the driver will generate an identifier composed of the letter 's' followed by an incrementing counter.

Note that this is purely a client-side identifier; in particular, it has no relation with system.local.cluster_name on the server.

getMetadata

@NonNull
Metadata getMetadata()

Returns a snapshot of the Cassandra cluster's topology and schema metadata.

In order to provide atomic updates, this method returns an immutable object: the node list, token map, and schema contained in a given instance will always be consistent with each other (but note that Node itself is not immutable: some of its properties will be updated dynamically, in particular Node.getState()).

As a consequence of the above, you should call this method each time you need a fresh view of the metadata. Do not call it once and store the result, because it is a frozen snapshot that will become stale over time.

If a metadata refresh triggers events (such as node added/removed, or schema events), then the new version of the metadata is guaranteed to be visible by the time you receive these events.

The returned object is never null, but may be empty if metadata has been disabled in the configuration.

isSchemaMetadataEnabled

boolean isSchemaMetadataEnabled()

Whether schema metadata is currently enabled.

setSchemaMetadataEnabled

@NonNull
CompletionStage<Metadata> setSchemaMetadataEnabled(@Nullable
                                                            Boolean newValue)

Enable or disable schema metadata programmatically.

Use this method to override the value defined in the driver's configuration; one typical use case is to temporarily disable schema metadata while the client issues a sequence of DDL statements.

If calling this method re-enables the metadata (that is, isSchemaMetadataEnabled() was false before, and becomes true as a result of the call), a refresh is also triggered.

Parameters:

newValue - a boolean value to enable or disable schema metadata programmatically, or null to use the driver's configuration.

Returns:

if this call triggered a refresh, a future that will complete when that refresh is complete. Otherwise, a completed future with the current metadata.

See Also:

DefaultDriverOption.METADATA_SCHEMA_ENABLED

refreshSchemaAsync

@NonNull
CompletionStage<Metadata> refreshSchemaAsync()

Force an immediate refresh of the schema metadata, even if it is currently disabled (either in the configuration or via setSchemaMetadataEnabled(Boolean)).

The new metadata is returned in the resulting future (and will also be reflected by getMetadata() when that future completes).

refreshSchema

@NonNull
default Metadata refreshSchema()

Convenience method to call refreshSchemaAsync() and block for the result.

This must not be called on a driver thread.

checkSchemaAgreementAsync

@NonNull
CompletionStage<Boolean> checkSchemaAgreementAsync()

Checks if all nodes in the cluster agree on a common schema version.

Due to the distributed nature of Cassandra, schema changes made on one node might not be immediately visible to others. Under certain circumstances, the driver waits until all nodes agree on a common schema version (namely: before a schema refresh, and before completing a successful schema-altering query). To do so, it queries system tables to find out the schema version of all nodes that are currently UP. If all the versions match, the check succeeds, otherwise it is retried periodically, until a given timeout (specified in the configuration).

A schema agreement failure is not fatal, but it might produce unexpected results (for example, getting an "unconfigured table" error for a table that you created right before, just because the two queries went to different coordinators).

Note that schema agreement never succeeds in a mixed-version cluster (it would be challenging because the way the schema version is computed varies across server versions); the assumption is that schema updates are unlikely to happen during a rolling upgrade anyway.

Returns:

a future that completes with true if the nodes agree, or false if the timeout fired.

See Also:

DefaultDriverOption.CONTROL_CONNECTION_AGREEMENT_INTERVAL, DefaultDriverOption.CONTROL_CONNECTION_AGREEMENT_TIMEOUT

checkSchemaAgreement

default boolean checkSchemaAgreement()

Convenience method to call checkSchemaAgreementAsync() and block for the result.

This must not be called on a driver thread.

getContext

@NonNull
DriverContext getContext()

Returns a context that provides access to all the policies used by this driver instance.

getKeyspace

@NonNull
Optional<CqlIdentifier> getKeyspace()

The keyspace that this session is currently connected to, or Optional.empty() if this session is not connected to any keyspace.

There are two ways that this can be set: before initializing the session (either with the session-keyspace option in the configuration, or with SessionBuilder.withKeyspace(CqlIdentifier)); or at runtime, if the client issues a request that changes the keyspace (such as a CQL USE query). Note that this second method is inherently unsafe, since other requests expecting the old keyspace might be executing concurrently. Therefore it is highly discouraged, aside from trivial cases (such as a cqlsh-style program where requests are never concurrent).

getMetrics

@NonNull
Optional<Metrics> getMetrics()

Returns a gateway to the driver's DropWizard metrics, or Optional.empty() if all metrics are disabled, or if the driver has been configured to use MicroProfile or Micrometer instead of DropWizard (see advanced.metrics.factory.class in the configuration).

Metrics was originally intended to allow programmatic access to the metrics, but it has a hard dependency to the DropWizard API, which makes it unsuitable for alternative metric frameworks. A workaround is to inject your own metric registry with SessionBuilder.withMetricRegistry(Object) when you build the session. You can then use the framework's proprietary APIs to retrieve the metrics from the registry.

execute

@Nullable
<RequestT extends Request,ResultT> ResultT execute(@NonNull
                                                             RequestT request,
                                                             @NonNull
                                                             GenericType<ResultT> resultType)

Executes an arbitrary request.

Parameters:

resultType - the type of the result, which determines the internal request processor (built-in or custom) that will be used to handle the request.

See Also:

Session