com.datastax.driver.core

Interface ResultSetFuture

All Superinterfaces:

Future<ResultSet>, com.google.common.util.concurrent.ListenableFuture<ResultSet>

public interface ResultSetFuture
extends com.google.common.util.concurrent.ListenableFuture<ResultSet>

A future on a ResultSet. Note that this class implements Guava's ListenableFuture and can so be used with Guava's future utilities.

Method Summary

Modifier and Type	Method and Description
boolean	cancel(boolean mayInterruptIfRunning) Attempts to cancel the execution of the request corresponding to this future.
ResultSet	getUninterruptibly() Waits for the query to return and return its result.
ResultSet	getUninterruptibly(long timeout, TimeUnit unit) Waits for the provided time for the query to return and return its result if available.

Methods inherited from interface com.google.common.util.concurrent.ListenableFuture

addListener

Methods inherited from interface java.util.concurrent.Future

get, get, isCancelled, isDone

Method Detail

getUninterruptibly

ResultSet getUninterruptibly()

Waits for the query to return and return its result. This method is usually more convenient than Future.get() because it:

• Waits for the result uninterruptibly, and so doesn't throw InterruptedException.
• Returns meaningful exceptions, instead of having to deal with ExecutionException.

As such, it is the preferred way to get the future result.

Returns:

the query result set.

Throws:

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

QueryExecutionException - if the query triggered an execution exception, that is an exception thrown by Cassandra when it cannot execute the query with the requested consistency level successfully.

QueryValidationException - if the query is invalid (syntax error, unauthorized or any other validation problem).

getUninterruptibly

ResultSet getUninterruptibly(long timeout,
                             TimeUnit unit)
                      throws TimeoutException

Waits for the provided time for the query to return and return its result if available. This method is usually more convenient than Future.get() because it:

• Waits for the result uninterruptibly, and so doesn't throw InterruptedException.
• Returns meaningful exceptions, instead of having to deal with ExecutionException.

As such, it is the preferred way to get the future result.

Parameters:

timeout - the time to wait for the query to return.

unit - the unit for timeout.

Returns:

the query result set.

Throws:

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

QueryExecutionException - if the query triggered an execution exception, that is 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).

TimeoutException - if the wait timed out (Note that this is different from a Cassandra timeout, which is a QueryExecutionException).

cancel

boolean cancel(boolean mayInterruptIfRunning)

Attempts to cancel the execution of the request corresponding to this future. This attempt will fail if the request has already returned.

Please note that this only cancel the request driver side, but nothing is done to interrupt the execution of the request Cassandra side (and that even if mayInterruptIfRunning is true) since Cassandra does not support such interruption.

This method can be used to ensure no more work is performed driver side (which, while it doesn't include stopping a request already submitted to a Cassandra node, may include not retrying another Cassandra host on failure/timeout) if the ResultSet is not going to be retried. Typically, the code to wait for a request result for a maximum of 1 second could look like:

   ResultSetFuture future = session.executeAsync(...some query...);
   try {
       ResultSet result = future.get(1, TimeUnit.SECONDS);
       ... process result ...
   } catch (TimeoutException e) {
       future.cancel(true); // Ensure any resource used by this query driver
                            // side is released immediately
       ... handle timeout ...
   }
 

Specified by:

cancel in interface Future<ResultSet>

Parameters:

mayInterruptIfRunning - the value of this parameter is currently ignored.

Returns:

false if the future could not be cancelled (it has already completed normally); true otherwise.