Session (DataStax Java Driver for Apache Cassandra - Binary distribution 2.2.0-rc3 API)

All Superinterfaces:

AutoCloseable, Closeable

All Known Implementing Classes:

AbstractSession
```
public interface Session
extends Closeable
```
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. As a given session can only be "logged" into one keyspace at a time (where the "logged" keyspace is the one used by query if the query doesn't explicitely use a fully qualified table name), it can make sense to create one session per keyspace used. This is however not necessary to query multiple keyspaces since it is always possible to use a single session with fully qualified table name in queries.

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static interface Session.State
The state of a Session.

Nested Classes
Modifier and Type	Interface and Description
`static interface`	`Session.State` The state of a Session.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`close()` Initiates a shutdown of this session instance and blocks until that shutdown completes.
`CloseFuture`	`closeAsync()` Initiates a shutdown of this session instance.
`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.
`String`	`getLoggedKeyspace()` The keyspace to which this Session is currently logged in, if any.
`Session.State`	`getState()` Return a snapshot of the state of this Session.
`Session`	`init()` Force the initialization of this Session instance if it hasn't been initialized yet.
`boolean`	`isClosed()` Whether this Session instance has been closed.
`SimpleStatement`	`newSimpleStatement(String query)` Builds, but does not execute, a simple statement containing the provided query.
`SimpleStatement`	`newSimpleStatement(String query, Object... values)` Builds, but does not execute, a simple statement containing the provided query with the provided parameters.
`PreparedStatement`	`prepare(RegularStatement statement)` Prepares the provided query.
`PreparedStatement`	`prepare(String query)` Prepares the provided query string.
`com.google.common.util.concurrent.ListenableFuture<PreparedStatement>`	`prepareAsync(RegularStatement statement)` Prepares the provided query asynchronously.
`com.google.common.util.concurrent.ListenableFuture<PreparedStatement>`	`prepareAsync(String query)` Prepares the provided query string asynchronously.

- 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.
  - init
```
Session init()
```
    Force the initialization of this Session instance if it hasn't been initialized yet.
    Please note first that most use won't need to call this method explicitly. If you use the Cluster.connect() method Cluster to create your Session, the returned session will be already initialized. Even if you create a non-initialized session through Cluster.newSession(), that session will get automatically initialized the first time that session is used for querying. This method is thus only useful if you use Cluster.newSession() and want to explicitly force initialization without querying.
    Session initialization consists in connecting the Session to the known Cassandra hosts (at least those that should not be ignored due to the LoadBalancingPolicy in place).
    If the Cluster instance this Session depends on is not itself initialized, it will be initialized by this method.
    If the session is already initialized, this method is a no-op.
    
    Returns:
    
    this Session object.
    
    Throws:
    
    NoHostAvailableException - if this initialization triggers the Cluster initialization and no host amongst the contact points can be reached.
    
    AuthenticationException - if this initialization triggers the Cluster initialization and an authentication error occurs while contacting the initial contact points.
  - 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(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 newSimpleStatement(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).
    
    UnsupportedFeatureException - if version 1 of the protocol is in use (i.e. if you've force version 1 through Cluster.Builder.withProtocolVersion(com.datastax.driver.core.ProtocolVersion) or you use Cassandra 1.2).
  - execute
```
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).
    
    UnsupportedFeatureException - if the protocol version 1 is in use and a feature not supported has been used. Features that are not supported by the version protocol 1 include: BatchStatement, ResultSet paging and binary values in RegularStatement.
  - 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(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 newSimpleStatement(String, Object...) for more detail.
    
    Returns:
    
    a future on the result of the query.
    
    Throws:
    
    UnsupportedFeatureException - if version 1 of the protocol is in use (i.e. if you've force version 1 through Cluster.Builder.withProtocolVersion(com.datastax.driver.core.ProtocolVersion) or you use Cassandra 1.2).
  - newSimpleStatement
```
SimpleStatement newSimpleStatement(String query)
```
    Builds, but does not execute, a simple statement containing the provided query. Use this method when you want to customize certain aspects of the statement before executing it (fetch size, tracing...); you can then pass the statement to execute(Statement).
    
    Parameters:
    
    query - the CQL query to execute.
    
    Returns:
    
    the simple statement.
  - newSimpleStatement
```
SimpleStatement newSimpleStatement(String query,
                                   Object... values)
```
    Builds, but does not execute, a simple statement containing the provided query with the provided parameters. Use this method when you want to customize certain aspects of the statement before executing it (fetch size, tracing...); you can then pass the statement to execute(Statement).
    Parameterized simple statements are useful when you want to execute a query only once (and thus do not want to resort to prepared statements), but do not want to convert all column values to string (typically, if you have blob values, encoding them to a hexadecimal string is not very efficient). In that case, you can provide a query string with bind marker to this method, along with the values for those bind variables. When executed, the server will prepare the provided query, bind the provided values to that prepare statement and execute the resulting statement. Thus,
```
   session.execute(session.newSimpleStatement(query, value1, value2, value3));
 
```
    is functionally equivalent to
```
   PreparedStatement ps = session.prepare(query);
   session.execute(ps.bind(value1, value2, value3));
 
```
    except that the former version:
    - Requires only one round-trip to a Cassandra node.
    - Does not leave any prepared statement stored in memory (neither client or server side) once it has been executed.
    Note that the type of the values provided to this method will not be validated by the driver as is done by BoundStatement.bind(java.lang.Object...) since query is not parsed (and hence the driver cannot know what those value should be). The codec to serialize each value will be chosen in the codec registry associated with this session's cluster, based on the value's Java type (this is the equivalent to calling CodecRegistry.codecFor(Object)). If too many or too few values are provided, or if a value is not a valid one for the variable it is bound to, an InvalidQueryException will be thrown by Cassandra at execution time. A CodecNotFoundException may be thrown by this constructor however, if the codec registry does not know how to handle one of the values.
    Parameters:
    
    query - the CQL query to execute.
    
    values - values required for the execution of query.
    
    Returns:
    
    the simple statement.
  - executeAsync
```
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.
    
    Throws:
    
    UnsupportedFeatureException - if the protocol version 1 is in use and a feature not supported has been used. Features that are not supported by the version protocol 1 include: BatchStatement, ResultSet paging and binary values in RegularStatement.
  - 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(RegularStatement statement)
```
    Prepares the provided query.
    This method behaves like prepare(String), but note that the resulting PreparedStatement 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.
    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.
    
    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).
  - prepareAsync
```
com.google.common.util.concurrent.ListenableFuture<PreparedStatement> prepareAsync(String query)
```
    Prepares the provided query string asynchronously.
    This method is equivalent 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(RegularStatement statement)
```
    Prepares the provided query asynchronously. This method behaves like prepareAsync(String), but note that the resulting PreparedStatement 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.
    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.
    
    Throws:
    
    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).
    
    See Also:
    
    prepare(RegularStatement)
  - closeAsync
```
CloseFuture closeAsync()
```
    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. This method closes all connections of this session and reclaims all resources used by it.
    If for some reason you wish to expedite this process, the CloseFuture.force() can be called on the result future.
    This method has no particular effect if the session was already closed (in which case the returned future will return immediately).
    Note that this method does not close the corresponding Cluster instance (which holds additional resources, in particular internal executors that must be shut down in order for the client program to terminate). If you want to do so, use Cluster.close(), but note that it will close all sessions created from that cluster.
    
    Returns:
    
    a future on the completion of the shutdown process.
  - close
```
void close()
```
    Initiates a shutdown of this session instance and blocks until that shutdown completes.
    This method is a shortcut for closeAsync().get().
    Note that this method does not close the corresponding Cluster instance (which holds additional resources, in particular internal executors that must be shut down in order for the client program to terminate). If you want to do so, use Cluster.close(), but note that it will close all sessions created from that cluster.
    
    Specified by:
    
    close in interface AutoCloseable
    
    Specified by:
    
    close in interface Closeable
  - isClosed
```
boolean isClosed()
```
    Whether this Session instance has been closed.
    Note that this method returns true as soon as one closing this Session has started but it does not guarantee that the closing is done. If you want to guarantee that the closing is done, you can call close() and wait until it returns (or call the get method on closeAsync() with a very short timeout and check this doesn't timeout).
    
    Returns:
    
    true if this Session instance has been closed, false otherwise.
  - getCluster
```
Cluster getCluster()
```
    Returns the Cluster object this session is part of.
    
    Returns:
    
    the Cluster object this session is part of.
  - getState
```
Session.State getState()
```
    Return a snapshot of the state of this Session.
    The returned object provides information on which hosts the session is connected to, how many connections are opened to each host, etc... The returned object is immutable, it is a snapshot of the Session State taken when this method is called.
    
    Returns:
    
    a snapshot of the state of this Session.

Interface Session

Nested Class Summary

Method Summary

Method Detail

getLoggedKeyspace

init

execute

execute

execute

executeAsync

executeAsync

newSimpleStatement

newSimpleStatement

executeAsync

prepare

prepare

prepareAsync

prepareAsync

closeAsync

close

isClosed

getCluster

getState