com.datastax.oss.driver.api.core.cql

Interface SyncCqlSession

All Superinterfaces:

AsyncAutoCloseable, AutoCloseable, Session

All Known Subinterfaces:

CqlSession, DseSession

public interface SyncCqlSession
extends Session

A session that offers user-friendly methods to execute CQL requests synchronously.

Since:

4.4.0

Field Summary

Fields inherited from interface com.datastax.oss.driver.api.core.session.Session

OSS_DRIVER_COORDINATES

Method Summary

Modifier and Type	Method and Description
default ResultSet	execute(Statement<?> statement) Executes a CQL statement synchronously (the calling thread blocks until the result becomes available).
default ResultSet	execute(String query) Executes a CQL statement synchronously (the calling thread blocks until the result becomes available).
default ResultSet	execute(String query, Map<String,Object> values) Executes a CQL statement synchronously (the calling thread blocks until the result becomes available).
default ResultSet	execute(String query, Object... values) Executes a CQL statement synchronously (the calling thread blocks until the result becomes available).
default PreparedStatement	prepare(PrepareRequest request) Prepares a CQL statement synchronously (the calling thread blocks until the statement is prepared).
default PreparedStatement	prepare(SimpleStatement statement) Prepares a CQL statement synchronously (the calling thread blocks until the statement is prepared).
default PreparedStatement	prepare(String query) Prepares a CQL statement synchronously (the calling thread blocks until the statement is prepared).

Methods inherited from interface com.datastax.oss.driver.api.core.session.Session

checkSchemaAgreement, checkSchemaAgreementAsync, execute, getContext, getKeyspace, getMetadata, getMetrics, getName, isSchemaMetadataEnabled, refreshSchema, refreshSchemaAsync, setSchemaMetadataEnabled

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

close, closeAsync, closeFuture, forceCloseAsync, isClosed

Method Detail

execute

@NonNull
default ResultSet execute(@NonNull
                                   Statement<?> statement)

Executes a CQL statement synchronously (the calling thread blocks until the result becomes available).

Parameters:

statement - the CQL query to execute (that can be any Statement).

Returns:

the result of the query. That result will never be null but can be empty (and will be for any non SELECT query).

Throws:

AllNodesFailedException - if no host in the cluster can be contacted successfully to execute this query.

QueryExecutionException - if the query triggered an execution exception, i.e. an exception thrown by Cassandra when it cannot execute the query with the requested consistency level successfully.

QueryValidationException - if the query is invalid (syntax error, unauthorized or any other validation problem).

execute

@NonNull
default ResultSet execute(@NonNull
                                   String query)

Executes a CQL statement synchronously (the calling thread blocks until the result becomes available).

This is an alias for execute(SimpleStatement.newInstance(query)).

Parameters:

query - the CQL query to execute.

Returns:

the result of the query. That result will never be null but can be empty (and will be for any non SELECT query).

Throws:

AllNodesFailedException - if no host in the cluster can be contacted successfully to execute this query.

QueryExecutionException - if the query triggered an execution exception, i.e. an exception thrown by Cassandra when it cannot execute the query with the requested consistency level successfully.

QueryValidationException - if the query if invalid (syntax error, unauthorized or any other validation problem).

See Also:

SimpleStatement.newInstance(String)

execute

@NonNull
default ResultSet execute(@NonNull
                                   String query,
                                   @NonNull
                                   Object... values)

Executes a CQL statement synchronously (the calling thread blocks until the result becomes available).

This is an alias for execute(SimpleStatement.newInstance(query, values)).

Parameters:

query - the CQL query to execute.

values - the values for placeholders in the query string. Individual values can be null, but the vararg array itself can't.

Returns:

the result of the query. That result will never be null but can be empty (and will be for any non SELECT query).

Throws:

AllNodesFailedException - if no host in the cluster can be contacted successfully to execute this query.

QueryExecutionException - if the query triggered an execution exception, i.e. an exception thrown by Cassandra when it cannot execute the query with the requested consistency level successfully.

QueryValidationException - if the query if invalid (syntax error, unauthorized or any other validation problem).

See Also:

SimpleStatement.newInstance(String, Object...)

execute

@NonNull
default ResultSet execute(@NonNull
                                   String query,
                                   @NonNull
                                   Map<String,Object> values)

Executes a CQL statement synchronously (the calling thread blocks until the result becomes available).

This is an alias for execute(SimpleStatement.newInstance(query, values)).

Parameters:

query - the CQL query to execute.

values - the values for named placeholders in the query string. Individual values can be null, but the map itself can't.

Returns:

the result of the query. That result will never be null but can be empty (and will be for any non SELECT query).

Throws:

AllNodesFailedException - if no host in the cluster can be contacted successfully to execute this query.

QueryExecutionException - if the query triggered an execution exception, i.e. an exception thrown by Cassandra when it cannot execute the query with the requested consistency level successfully.

QueryValidationException - if the query if invalid (syntax error, unauthorized or any other validation problem).

See Also:

SimpleStatement.newInstance(String, Map)

prepare

@NonNull
default PreparedStatement prepare(@NonNull
                                           SimpleStatement statement)

Prepares a CQL statement synchronously (the calling thread blocks until the statement is prepared).

Note that the bound statements created from the resulting prepared statement will inherit some of the attributes of the provided simple statement. That is, given:

 SimpleStatement simpleStatement = SimpleStatement.newInstance("...");
 PreparedStatement preparedStatement = session.prepare(simpleStatement);
 BoundStatement boundStatement = preparedStatement.bind();
 

Then:

• the following methods return the same value as their counterpart on simpleStatement:
  • boundStatement.getExecutionProfileName()
  • boundStatement.getExecutionProfile()
  • boundStatement.getPagingState()
  • boundStatement.getRoutingKey()
  • boundStatement.getRoutingToken()
  • boundStatement.getCustomPayload()
  • boundStatement.isIdempotent()
  • boundStatement.getTimeout()
  • boundStatement.getPagingState()
  • boundStatement.getPageSize()
  • boundStatement.getConsistencyLevel()
  • boundStatement.getSerialConsistencyLevel()
  • boundStatement.isTracing()
• boundStatement.getRoutingKeyspace() is set from either simpleStatement.getKeyspace() (if it's not null), or simpleStatement.getRoutingKeyspace();
• on the other hand, the following attributes are not propagated:
  • boundStatement.getQueryTimestamp() will be set to Statement.NO_DEFAULT_TIMESTAMP, meaning that the value will be assigned by the session's timestamp generator.
  • boundStatement.getNode() will always be null.
  • Statement.getNowInSeconds() boundStatement.getNowInSeconds()} will always be equal to Statement.NO_NOW_IN_SECONDS.

If you want to customize this behavior, you can write your own implementation of PrepareRequest and pass it to prepare(PrepareRequest).

The result of this method is cached: if you call it twice with the same SimpleStatement, you will get the same PreparedStatement instance. We still recommend keeping a reference to it (for example by caching it as a field in a DAO); if that's not possible (e.g. if query strings are generated dynamically), it's OK to call this method every time: there will just be a small performance overhead to check the internal cache. Note that caching is based on:

• the query string exactly as you provided it: the driver does not perform any kind of trimming or sanitizing.
• all other execution parameters: for example, preparing two statements with identical query strings but different consistency levels will yield distinct prepared statements.

Parameters:

statement - the CQL query to execute (that can be any SimpleStatement).

Returns:

the prepared statement corresponding to statement.

Throws:

SyntaxError - if the syntax of the query to prepare is not correct.

prepare

@NonNull
default PreparedStatement prepare(@NonNull
                                           String query)

Prepares a CQL statement synchronously (the calling thread blocks until the statement is prepared).

The result of this method is cached (see prepare(SimpleStatement) for more explanations).

Parameters:

query - the CQL string query to execute.

Returns:

the prepared statement corresponding to query.

Throws:

SyntaxError - if the syntax of the query to prepare is not correct.

prepare

@NonNull
default PreparedStatement prepare(@NonNull
                                           PrepareRequest request)

Prepares a CQL statement synchronously (the calling thread blocks until the statement is prepared).

This variant is exposed in case you use an ad hoc PrepareRequest implementation to customize how attributes are propagated when you prepare a SimpleStatement (see prepare(SimpleStatement) for more explanations). Otherwise, you should rarely have to deal with PrepareRequest directly.

The result of this method is cached (see prepare(SimpleStatement) for more explanations).

Parameters:

request - the PrepareRequest to execute.

Returns:

the prepared statement corresponding to request.

Throws:

SyntaxError - if the syntax of the query to prepare is not correct.