com.datastax.driver.core

Class Session

java.lang.Object

com.datastax.driver.core.Session

public class Session
extends Object

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(Statement statement) Executes the provided query.
ResultSet	execute(String query) Executes the provided query.
ResultSet	execute(String query, Object... values) Executes the provided query using the provided value.
ResultSetFuture	executeAsync(Statement statement) Executes the provided query asynchronously.
ResultSetFuture	executeAsync(String query) Executes the provided query asynchronously.
ResultSetFuture	executeAsync(String query, Object... values) Executes the provided query asynchronously using the provided values.
Cluster	getCluster() Returns the Cluster object this session is part of.
PreparedStatement	prepare(RegularStatement statement) Prepares the provided query.
PreparedStatement	prepare(String query) Prepares the provided query string.
ShutdownFuture	shutdown() Initiates a shutdown of this session instance.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

execute

public 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

public ResultSet execute(String query,
                Object... values)

Executes the provided query using the provided value. This is a convenience method for execute(new SimpleStatement(query, values)).

Parameters:

query - the CQL query to execute.

values - values required for the execution of query. See SimpleStatement.SimpleStatement(String, Object...) for more detail.

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

public ResultSet execute(Statement statement)

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:

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:

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

executeAsync

public 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

public ResultSetFuture executeAsync(String query,
                           Object... values)

Executes the provided query asynchronously using the provided values. This is a convenience method for executeAsync(new SimpleStatement(query, values)).

Parameters:

query - the CQL query to execute.

values - values required for the execution of query. See SimpleStatement.SimpleStatement(String, Object...) for more detail.

Returns:

a future on the result of the query.

executeAsync

public ResultSetFuture executeAsync(Statement statement)

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:

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

Returns:

a future on the result of the query.

prepare

public 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

public PreparedStatement prepare(RegularStatement 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:

   RegularStatement 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.

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.

IllegalArgumentException - if statement.getValues() != null (values for executing a prepared statement should be provided after preparation though the PreparedStatement.bind(java.lang.Object...) method or through a corresponding BoundStatement).

shutdown

public ShutdownFuture shutdown()

Initiates a shutdown of this session instance. This method is asynchronous and return a future on the completion of the shutdown process. As soon a the session is shutdown, no new request will be accepted, but already submitted queries are allowed to complete. Shutdown closes all connections of this session and reclaims all resources used by it.

If for some reason you wish to expedite this process, the ShutdownFuture.force() can be called on the result future.

This method has no particular effect if the session was already shut down (in which case the returned future will return immediately).

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 sessions but also release some additional resources).

Returns:

a future on the completion of the shutdown process.

getCluster

public Cluster getCluster()

Returns the Cluster object this session is part of.

Returns:

the Cluster object this session is part of.