com.datastax.driver.dse

Interface DseSession

All Superinterfaces:

AutoCloseable, Closeable, Session

public interface DseSession
extends Session

Holds connections to a DSE cluster, allowing it to be queried.

This extends the CQL driver's Session with DSE-specific features.

Nested Class Summary

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

Session.State

Method Summary

Modifier and Type	Method and Description
GraphResultSet	executeGraph(GraphStatement statement) Executes the provided graph query.
GraphResultSet	executeGraph(String query) Executes the provided graph query.
GraphResultSet	executeGraph(String query, Map<String,Object> values) Executes the provided graph query with the provided named parameters.
com.google.common.util.concurrent.ListenableFuture<GraphResultSet>	executeGraphAsync(GraphStatement statement) Executes the provided Graph query asynchronously.
com.google.common.util.concurrent.ListenableFuture<GraphResultSet>	executeGraphAsync(String query) Executes the provided graph query asynchronously.
com.google.common.util.concurrent.ListenableFuture<GraphResultSet>	executeGraphAsync(String query, Map<String,Object> values) Executes the provided graph query asynchronously with the specified parameters.
DseCluster	getCluster() Returns the DseCluster object this session is part of.
String	getLoggedKeyspace() The keyspace to which this Session is currently logged in, if any.
DseSession	init() Forces the initialization of this instance if it hasn't been initialized yet.
com.google.common.util.concurrent.ListenableFuture<Session>	initAsync() Initialize this session asynchronously.

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

close, closeAsync, execute, execute, execute, execute, executeAsync, executeAsync, executeAsync, executeAsync, getState, isClosed, prepare, prepare, prepareAsync, prepareAsync

Method Detail

getCluster

DseCluster getCluster()

Returns the DseCluster object this session is part of.

Specified by:

getCluster in interface Session

Returns:

the DseCluster object this session is part of.

init

DseSession init()

Forces the initialization of this instance if it hasn't been initialized yet.

Most users won't need to call this method explicitly. If you use DseCluster.connect() to create your session, the returned object will be already initialized. Even if you create a non-initialized session through DseCluster.newSession(), that session will get automatically initialized the first time it is used for querying. This method is thus only useful if you use DseCluster.newSession() and want to explicitly force initialization without querying.

Session initialization consists in connecting to the known Cassandra hosts (at least those that should not be ignored due to the LoadBalancingPolicy in place).

If the DseCluster 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.

Specified by:

init in interface Session

Returns:

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

initAsync

com.google.common.util.concurrent.ListenableFuture<Session> initAsync()

Initialize this session asynchronously.

The Session object returned by the future's get method can be safely cast to DseSession.

Specified by:

initAsync in interface Session

Returns:

a future that will complete when the session is fully initialized.

See Also:

init()

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.

The keyspace name returned by this method is only relevant for CQL queries; for graph queries, the graph to target is determined by the graph name specified via GraphStatement.setGraphName(String)} or GraphOptions.setGraphName(String).

Specified by:

getLoggedKeyspace in interface Session

Returns:

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

executeGraph

GraphResultSet executeGraph(String query)

Executes the provided graph query.

This is a convenience method for execute(new SimpleGraphStatement(query)).

Parameters:

query - the graph query to execute.

Returns:

the result of the query. That result will never be null but can be empty (and will be for any query that returns no results).

Throws:

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

executeGraph

GraphResultSet executeGraph(String query,
                            Map<String,Object> values)

Executes the provided graph query with the provided named parameters.

This is a convenience method for execute(new SimpleGraphStatement(query, values)).

Parameters:

query - the graph query to execute.

values - the named parameters to send associated to the query. You can use Guava's ImmutableMap to build the map with a one-liner: ImmutableMap.<String, Object>of("key1", value1, "key2", value2).

Returns:

the result of the query. That result will never be null but can be empty (and will be for any query that returns no results).

Throws:

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

executeGraph

GraphResultSet executeGraph(GraphStatement statement)

Executes the provided graph query.

This method blocks until at least some result has been received from the database. However, for queries that return a result, 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 guarantees that if the request is invalid, an exception will be thrown by this method.

Parameters:

statement - the statement to execute.

Returns:

the result of the query. That result will never be null but can be empty (and will be for any query that returns no results).

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

executeGraphAsync

com.google.common.util.concurrent.ListenableFuture<GraphResultSet> executeGraphAsync(String query)

Executes the provided graph 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 ListenableFuture.

Note that for queries that don't return a result, you will need to access the Future's get method to make sure the query was successful.

Parameters:

query - the graph query to execute.

Returns:

a future on the result of the query.

executeGraphAsync

com.google.common.util.concurrent.ListenableFuture<GraphResultSet> executeGraphAsync(String query,
                                                                                     Map<String,Object> values)

Executes the provided graph query asynchronously with the specified parameters.

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

Note that for queries that don't return a result, you will need to access the Future's get method to make sure the query was successful.

Parameters:

query - the graph query to execute.

values - the named parameters to send associated to the query. You can use Guava's ImmutableMap to build the map with a one-liner: ImmutableMap.<String, Object>of("key1", value1, "key2", value2).

Returns:

a future on the result of the query.

executeGraphAsync

com.google.common.util.concurrent.ListenableFuture<GraphResultSet> executeGraphAsync(GraphStatement statement)

Executes the provided Graph 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 ListenableFuture.

Note that for queries that don't return a result, you will need to access the Future's get method to make sure the query was successful.

Parameters:

statement - the statement to execute.

Returns:

a future on the result of the query.