public interface Session extends AsyncAutoCloseable
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.
CqlSession.builder()
Modifier and Type | Field and Description |
---|---|
static MavenCoordinates |
OSS_DRIVER_COORDINATES
The Maven coordinates of the core driver artifact.
|
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> |
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 metrics, or
Optional.empty() if all metrics are
disabled. |
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.
|
close, closeAsync, closeFuture, forceCloseAsync, isClosed
@NonNull static final MavenCoordinates OSS_DRIVER_COORDINATES
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.
@NonNull String getName()
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.
@NonNull Metadata getMetadata()
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.
boolean isSchemaMetadataEnabled()
@NonNull CompletionStage<Metadata> setSchemaMetadataEnabled(@Nullable Boolean newValue)
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.
newValue
- a boolean value to enable or disable schema metadata programmatically, or
null
to use the driver's configuration.DefaultDriverOption.METADATA_SCHEMA_ENABLED
@NonNull CompletionStage<Metadata> refreshSchemaAsync()
setSchemaMetadataEnabled(Boolean)
).
The new metadata is returned in the resulting future (and will also be reflected by getMetadata()
when that future completes).
@NonNull default Metadata refreshSchema()
refreshSchemaAsync()
and block for the result.
This must not be called on a driver thread.
@NonNull CompletionStage<Boolean> checkSchemaAgreementAsync()
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.
true
if the nodes agree, or false
if the
timeout fired.DefaultDriverOption.CONTROL_CONNECTION_AGREEMENT_INTERVAL
,
DefaultDriverOption.CONTROL_CONNECTION_AGREEMENT_TIMEOUT
default boolean checkSchemaAgreement()
checkSchemaAgreementAsync()
and block for the result.
This must not be called on a driver thread.
@NonNull DriverContext getContext()
@NonNull Optional<CqlIdentifier> getKeyspace()
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).
@NonNull Optional<Metrics> getMetrics()
Optional.empty()
if all metrics are
disabled.@Nullable <RequestT extends Request,ResultT> ResultT execute(@NonNull RequestT request, @NonNull GenericType<ResultT> resultType)
resultType
- the type of the result, which determines the internal request processor
(built-in or custom) that will be used to handle the request.Session
Copyright © 2017–2020. All rights reserved.