com.datastax.driver.core

Interface Session

public interface Session

A session holds connections to a Cassandra cluster, allowing it to be queried. Each session maintains multiple connections to the cluster nodes, provides policies to choose which node to use for each query (round-robin on all nodes of the cluster by default), and handles retries for failed query (when it makes sense), etc...

Session instances are thread-safe and usually a single instance is enough per application. However, a given session can only be set to one keyspace at a time, so one instance per keyspace is necessary.

Method Summary

Methods

Modifier and Type	Method and Description
ResultSet	execute(Query query) Executes the provided query.
ResultSet	execute(String query) Executes the provided query.
ResultSetFuture	executeAsync(Query query) Executes the provided query asynchronously.
ResultSetFuture	executeAsync(String query) Executes the provided query asynchronously.
Cluster	getCluster() Returns the Cluster object this session is part of.
String	getLoggedKeyspace() The keyspace to which this Session is currently logged in, if any.
boolean	isShutdown() Whether shutdown has been called on this Session instance.
PreparedStatement	prepare(Statement statement) Prepares the provided query.
PreparedStatement	prepare(String query) Prepares the provided query string.
com.google.common.util.concurrent.ListenableFuture<PreparedStatement>	prepareAsync(Statement statement) Prepares the provided query asynchronously.
com.google.common.util.concurrent.ListenableFuture<PreparedStatement>	prepareAsync(String query) Prepares the provided query string asynchronously.
void	shutdown() Shuts down this session instance.
boolean	shutdown(long timeout, TimeUnit unit) Shutdown this session instance, only waiting a definite amount of time.

Method Detail

getLoggedKeyspace

String getLoggedKeyspace()

The keyspace to which this Session is currently logged in, if any.

This correspond to the name passed to Cluster.connect(String), or to the last keyspace logged into through a "USE" CQL query if one was used.

Returns:

the name of the keyspace to which this Session is currently logged in, or null if the session is logged to no keyspace.

execute

ResultSet execute(String query)

Executes the provided query. This is a convenience method for execute(new SimpleStatement(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:

NoHostAvailableException - 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).

execute

ResultSet execute(Query query)

Executes the provided query. This method blocks until at least some result has been received from the database. However, for SELECT queries, it does not guarantee that the result has been received in full. But it does guarantee that some response has been received from the database, and in particular guarantee that if the request is invalid, an exception will be thrown by this method.

Parameters:

query - the CQL query to execute (that can be either a Statement or a BoundStatement). If it is a BoundStatement, all variables must have been bound (the statement must be ready).

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:

NoHostAvailableException - 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).

IllegalStateException - if query is a BoundStatement but !query.isReady().

executeAsync

ResultSetFuture executeAsync(String query)

Executes the provided query asynchronously.

This is a convenience method for executeAsync(new SimpleStatement(query)).

Parameters:

query - the CQL query to execute.

Returns:

a future on the result of the query.

executeAsync

ResultSetFuture executeAsync(Query query)

Executes the provided query asynchronously. This method does not block. It returns as soon as the query has been passed to the underlying network stack. In particular, returning from this method does not guarantee that the query is valid or has even been submitted to a live node. Any exception pertaining to the failure of the query will be thrown when accessing the ResultSetFuture.

Note that for queries that doesn't return a result (INSERT, UPDATE and DELETE), you will need to access the ResultSetFuture (that is call one of its get method to make sure the query was successful.

Parameters:

query - the CQL query to execute (that can be either a Statement or a BoundStatement). If it is a BoundStatement, all variables must have been bound (the statement must be ready).

Returns:

a future on the result of the query.

Throws:

IllegalStateException - if query is a BoundStatement but !query.isReady().

prepare

PreparedStatement prepare(String query)

Prepares the provided query string.

Parameters:

query - the CQL query string to prepare

Returns:

the prepared statement corresponding to query.

Throws:

NoHostAvailableException - if no host in the cluster can be contacted successfully to prepare this query.

prepare

PreparedStatement prepare(Statement statement)

Prepares the provided query.

This method is essentially a shortcut for prepare(statement.getQueryString()), but note that the resulting PreparedStamenent will inherit the query properties set on statement. Concretely, this means that in the following code:

   Statement toPrepare = new SimpleStatement("SELECT * FROM test WHERE k=?").setConsistencyLevel(ConsistencyLevel.QUORUM);
   PreparedStatement prepared = session.prepare(toPrepare);
   session.execute(prepared.bind("someValue"));
 

the final execution will be performed with Quorum consistency.

Please note that if the same CQL statement is prepared more than once, all calls to this method will return the same PreparedStatement object but the method will still apply the properties of the prepared Statement to this object.

Parameters:

statement - the statement to prepare

Returns:

the prepared statement corresponding to statement.

Throws:

NoHostAvailableException - if no host in the cluster can be contacted successfully to prepare this statement.

prepareAsync

com.google.common.util.concurrent.ListenableFuture<PreparedStatement> prepareAsync(String query)

Prepares the provided query string asynchronously.

This method is equilavent to prepare(String) except that it does not block but return a future instead. Any error during preparation will be thrown when accessing the future, not by this method itself.

Parameters:

query - the CQL query string to prepare

Returns:

a future on the prepared statement corresponding to query.

prepareAsync

com.google.common.util.concurrent.ListenableFuture<PreparedStatement> prepareAsync(Statement statement)

Prepares the provided query asynchronously.

This method is essentially a shortcut for prepareAsync(statement.getQueryString()), but with the additional effect that the resulting PreparedStamenent will inherit the query properties set on statement.

Please note that if the same CQL statement is prepared more than once, all calls to this method will return the same PreparedStatement object but the method will still apply the properties of the prepared Statement to this object.

Parameters:

statement - the statement to prepare

Returns:

a future on the prepared statement corresponding to statement.

See Also:

prepare(Statement)

shutdown

void shutdown()

Shuts down this session instance.

This closes all connections used by this sessions. Note that if you want to shut down the full Cluster instance this session is part of, you should use Cluster.shutdown() instead (which will call this method for all session but also release some additional resources).

This method has no effect if the session was already shutdown.

shutdown

boolean shutdown(long timeout,
               TimeUnit unit)

Shutdown this session instance, only waiting a definite amount of time.

This closes all connections used by this sessions. Note that if you want to shutdown the full Cluster instance this session is part of, you should use Cluster.shutdown() instead (which will call this method for all session but also release some additional resources).

Note that this method is not thread safe in the sense that if another shutdown is perform in parallel, it might return true even if the instance is not yet fully shutdown.

Parameters:

timeout - how long to wait for the session to shutdown.

unit - the unit for the timeout.

Returns:

true if the session has been properly shutdown within the timeout, false otherwise.

isShutdown

boolean isShutdown()

Whether shutdown has been called on this Session instance.

Returns:

true if this instance is shut down, false otherwise.

getCluster

Cluster getCluster()

Returns the Cluster object this session is part of.

Returns:

the Cluster object this session is part of.