com.datastax.driver.dse.DseSession Maven / Gradle / Ivy
/*
* Copyright DataStax, Inc.
*
* This software can be used solely with DataStax Enterprise. Please consult the license at
* http://www.datastax.com/terms/datastax-dse-driver-license-terms
*/
package com.datastax.driver.dse;
import com.datastax.driver.core.Session;
import com.datastax.driver.core.exceptions.AuthenticationException;
import com.datastax.driver.core.exceptions.NoHostAvailableException;
import com.datastax.driver.core.exceptions.QueryExecutionException;
import com.datastax.driver.core.exceptions.QueryValidationException;
import com.datastax.driver.dse.graph.GraphOptions;
import com.datastax.driver.dse.graph.GraphResultSet;
import com.datastax.driver.dse.graph.GraphStatement;
import com.google.common.util.concurrent.ListenableFuture;
import java.util.Map;
import java.util.concurrent.Future;
/**
* Holds connections to a DSE cluster, allowing it to be queried.
*
* This extends the CQL driver's {@link Session} with DSE-specific features.
*/
public interface DseSession extends Session {
/**
* Returns the {@link DseCluster} object this session is part of.
*
* @return the {@link DseCluster} object this session is part of.
*/
@Override
DseCluster getCluster();
/**
* 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 {@link DseCluster#connect}
* to create your session, the returned object will be already initialized. Even if you create a
* non-initialized session through {@link 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 {@link 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 {@code LoadBalancingPolicy} in place).
*
*
If the {@link 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.
*
* @return this object.
* @throws NoHostAvailableException if this initialization triggers the cluster initialization and
* no host amongst the contact points can be reached.
* @throws AuthenticationException if this initialization triggers the cluster initialization and
* an authentication error occurs while contacting the initial contact points.
*/
@Override
DseSession init();
/**
* {@inheritDoc}
*
*
The {@link Session} object returned by the future's {@link Future#get() get} method can be
* safely cast to {@link DseSession}.
*
* @return a future that will complete when the session is fully initialized.
* @see #init()
*/
@Override
ListenableFuture initAsync();
/**
* {@inheritDoc}
*
* 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 {@link
* GraphStatement#setGraphName(String)}} or {@link GraphOptions#setGraphName(String)}.
*/
@Override
String getLoggedKeyspace();
/**
* Executes the provided graph query.
*
*
This is a convenience method for {@code execute(new SimpleGraphStatement(query))}.
*
* @param query the graph query to execute.
* @return 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.
*/
GraphResultSet executeGraph(String query);
/**
* Executes the provided graph query with the provided named parameters.
*
*
This is a convenience method for {@code execute(new SimpleGraphStatement(query, values))}.
*
* @param query the graph query to execute.
* @param values the named parameters to send associated to the query. You can use Guava's {@link
* com.google.common.collect.ImmutableMap ImmutableMap} to build the map with a one-liner:
* {@code ImmutableMap.of("key1", value1, "key2", value2)}.
* @return 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.
*/
GraphResultSet executeGraph(String query, Map values);
/**
* 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.
*
* @param statement the statement to execute.
* @return 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.
* @throws 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.
* @throws QueryValidationException if the query if invalid (syntax error, unauthorized or any
* other validation problem).
*/
GraphResultSet executeGraph(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 {@link ListenableFuture}.
*
*
Note that for queries that don't return a result, you will need to access the Future's
* {@link java.util.concurrent.Future#get() get} method to make sure the query was successful.
*
* @param query the graph query to execute.
* @return a future on the result of the query.
*/
ListenableFuture executeGraphAsync(String query);
/**
* 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 {@link ListenableFuture}.
*
*
Note that for queries that don't return a result, you will need to access the Future's
* {@link java.util.concurrent.Future#get() get} method to make sure the query was successful.
*
* @param query the graph query to execute.
* @param values the named parameters to send associated to the query. You can use Guava's {@link
* com.google.common.collect.ImmutableMap ImmutableMap} to build the map with a one-liner:
* {@code ImmutableMap.of("key1", value1, "key2", value2)}.
* @return a future on the result of the query.
*/
ListenableFuture executeGraphAsync(String query, Map values);
/**
* 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 {@link ListenableFuture}.
*
*
Note that for queries that don't return a result, you will need to access the Future's
* {@link java.util.concurrent.Future#get() get} method to make sure the query was successful.
*
* @param statement the statement to execute.
* @return a future on the result of the query.
*/
ListenableFuture executeGraphAsync(GraphStatement statement);
}