public interface Session extends Closeable
Modifier and Type | Interface and Description |
---|---|
static interface |
Session.State
The state of a Session.
|
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,
Map<String,Object> values)
Executes the provided query using the provided named values.
|
ResultSet |
execute(String query,
Object... values)
Executes the provided query using the provided values.
|
ResultSetFuture |
executeAsync(Statement statement)
Executes the provided query asynchronously.
|
ResultSetFuture |
executeAsync(String query)
Executes the provided query asynchronously.
|
ResultSetFuture |
executeAsync(String query,
Map<String,Object> values)
Executes the provided query asynchronously using the provided values.
|
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.
|
ListenableFuture<Session> |
initAsync()
Initialize this session asynchronously.
|
boolean |
isClosed()
Whether this Session instance has been closed.
|
PreparedStatement |
prepare(RegularStatement statement)
Prepares the provided query.
|
PreparedStatement |
prepare(String query)
Prepares the provided query string.
|
ListenableFuture<PreparedStatement> |
prepareAsync(RegularStatement statement)
Prepares the provided query asynchronously.
|
ListenableFuture<PreparedStatement> |
prepareAsync(String query)
Prepares the provided query string asynchronously.
|
String getLoggedKeyspace()
Cluster.connect(String)
, or to the
last keyspace logged into through a "USE" CQL query if one was used.null
if the session is logged to no keyspace.Session init()
Cluster.connect()
method
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 it 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.Session
object.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.ListenableFuture<Session> initAsync()
init()
ResultSet execute(String query)
execute(new SimpleStatement(query))
.query
- the CQL query to execute.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).ResultSet execute(String query, Object... values)
execute(new SimpleStatement(query, values))
.query
- the CQL query to execute.values
- values required for the execution of query
. See
SimpleStatement.SimpleStatement(String, Object...)
for more details.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 forced version 1 through Cluster.Builder.withProtocolVersion(com.datastax.driver.core.ProtocolVersion)
or you use Cassandra 1.2).ResultSet execute(String query, Map<String,Object> values)
execute(new SimpleStatement(query, values))
.query
- the CQL query to execute.values
- values required for the execution of query
. See
SimpleStatement.SimpleStatement(String, Map)
for more details.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 or 2 of the protocol
is in use (i.e. if you've forced it through Cluster.Builder.withProtocolVersion(com.datastax.driver.core.ProtocolVersion)
or you use Cassandra 1.2 or 2.0).ResultSet execute(Statement statement)
statement
- the CQL query to execute (that can be any Statement
).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.ResultSetFuture executeAsync(String query)
executeAsync(new SimpleStatement(query))
.query
- the CQL query to execute.ResultSetFuture executeAsync(String query, Object... values)
executeAsync(new SimpleStatement(query, values))
.query
- the CQL query to execute.values
- values required for the execution of query
. See
SimpleStatement.SimpleStatement(String, Object...)
for more details.UnsupportedFeatureException
- if version 1 of the protocol
is in use (i.e. if you've forced version 1 through Cluster.Builder.withProtocolVersion(com.datastax.driver.core.ProtocolVersion)
or you use Cassandra 1.2).ResultSetFuture executeAsync(String query, Map<String,Object> values)
executeAsync(new SimpleStatement(query, values))
.query
- the CQL query to execute.values
- values required for the execution of query
. See
SimpleStatement.SimpleStatement(String, Map)
for more details.UnsupportedFeatureException
- if version 1 or 2 of the protocol
is in use (i.e. if you've forced it through Cluster.Builder.withProtocolVersion(com.datastax.driver.core.ProtocolVersion)
or you use Cassandra 1.2 or 2.0).ResultSetFuture executeAsync(Statement statement)
ResultSetFuture
.
Note that for queries that don't return a result (INSERT, UPDATE and
DELETE), you will need to access the ResultSetFuture (that is, call one of
its get
methods to make sure the query was successful.statement
- the CQL query to execute (that can be any Statement
).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.PreparedStatement prepare(String query)
query
- the CQL query string to preparequery
.NoHostAvailableException
- if no host in the cluster can be
contacted successfully to prepare this query.PreparedStatement prepare(RegularStatement statement)
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.statement
- the statement to preparestatement
.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
).ListenableFuture<PreparedStatement> prepareAsync(String query)
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.query
- the CQL query string to preparequery
.ListenableFuture<PreparedStatement> prepareAsync(RegularStatement statement)
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.statement
- the statement to preparestatement
.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
).prepare(RegularStatement)
CloseFuture closeAsync()
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.void close()
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.close
in interface AutoCloseable
close
in interface Closeable
boolean isClosed()
close()
and wait until it returns (or call the get method on closeAsync()
with a very short timeout and check this doesn't timeout).true
if this Session instance has been closed, false
otherwise.Cluster getCluster()
Cluster
object this session is part of.Cluster
object this session is part of.Session.State getState()
Copyright © 2012–2017. All rights reserved.