com.datastax.driver.core

Class AbstractSession

java.lang.Object

com.datastax.driver.core.AbstractSession

All Implemented Interfaces:

Session, Closeable, AutoCloseable

public abstract class AbstractSession
extends Object
implements Session

Abstract implementation of the Session interface. This is primarly intended to make mocking easier.

Nested Class Summary

Nested classes/interfaces inherited from interface com.datastax.driver.core.Session

Session.State

Constructor Summary

Constructors

Constructor and Description
AbstractSession()

Method Summary

Modifier and Type	Method and Description
void	close() Initiates a shutdown of this session instance and blocks until that shutdown completes.
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(String query) Executes the provided query asynchronously.
ResultSetFuture	executeAsync(String query, Object... values) Executes the provided query asynchronously using the provided values.
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.
protected abstract com.google.common.util.concurrent.ListenableFuture<PreparedStatement>	prepareAsync(String query, Map<String,ByteBuffer> customPayload) Prepares the provided query string asynchronously, sending along the provided custom payload, if any.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.datastax.driver.core.Session

closeAsync, executeAsync, getCluster, getLoggedKeyspace, getState, init, isClosed

Constructor Detail

AbstractSession

public AbstractSession()

Method Detail

execute

public ResultSet execute(String query)

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

Specified by:

execute in interface Session

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

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

Specified by:

execute in interface Session

Parameters:

query - the CQL query to execute.

values - values required for the execution of query. See Session.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).

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.

Specified by:

execute in interface Session

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

executeAsync

public ResultSetFuture executeAsync(String query)

Executes the provided query asynchronously.

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

Specified by:

executeAsync in interface Session

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

Specified by:

executeAsync in interface Session

Parameters:

query - the CQL query to execute.

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

Returns:

a future on the result of the query.

newSimpleStatement

public 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 Session.execute(Statement).

Specified by:

newSimpleStatement in interface Session

Parameters:

query - the CQL query to execute.

Returns:

the simple statement.

newSimpleStatement

public 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 Session.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.

Specified by:

newSimpleStatement in interface Session

Parameters:

query - the CQL query to execute.

values - values required for the execution of query.

Returns:

the simple statement.

prepare

public PreparedStatement prepare(String query)

Prepares the provided query string.

Specified by:

prepare in interface Session

Parameters:

query - the CQL query string to prepare

Returns:

the prepared statement corresponding to query.

prepare

public PreparedStatement prepare(RegularStatement statement)

Prepares the provided query.

This method behaves like Session.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.

Specified by:

prepare in interface Session

Parameters:

statement - the statement to prepare

Returns:

the prepared statement corresponding to statement.

prepareAsync

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

Prepares the provided query string asynchronously.

This method is equivalent to Session.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.

Specified by:

prepareAsync in interface Session

Parameters:

query - the CQL query string to prepare

Returns:

a future on the prepared statement corresponding to query.

prepareAsync

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

Prepares the provided query asynchronously. This method behaves like Session.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.

Specified by:

prepareAsync in interface Session

Parameters:

statement - the statement to prepare

Returns:

a future on the prepared statement corresponding to statement.

See Also:

Session.prepare(RegularStatement)

prepareAsync

protected abstract com.google.common.util.concurrent.ListenableFuture<PreparedStatement> prepareAsync(String query,
                                                                                                      Map<String,ByteBuffer> customPayload)

Prepares the provided query string asynchronously, sending along the provided custom payload, if any.

Parameters:

query - the CQL query string to prepare

customPayload - the custom payload to send along the query, or null if no payload is to be sent

Returns:

a future on the prepared statement corresponding to query.

close

public 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 Session

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable