com.datastax.driver.core

Class ResultSetFuture

java.lang.Object

com.google.common.util.concurrent.AbstractFuture<V>

com.datastax.driver.core.ResultSetFuture

All Implemented Interfaces:

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

public class ResultSetFuture
extends com.google.common.util.concurrent.AbstractFuture<V>

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

Methods

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.
boolean	set(V value) Sets the value of this future.
boolean	setException(Throwable throwable) Sets the future to having failed with the given exception.

Methods inherited from class com.google.common.util.concurrent.AbstractFuture

addListener, get, get, interruptTask, isCancelled, isDone, wasInterrupted

Methods inherited from class java.lang.Object

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

Method Detail

getUninterruptibly

public ResultSet getUninterruptibly()

Waits for the query to return and return its result. This method is usually more convenient than AbstractFuture.get(long, java.util.concurrent.TimeUnit) 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.

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

public 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 AbstractFuture.get(long, java.util.concurrent.TimeUnit) 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.

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

public 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 cancle 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 ressource used by this query driver
                            // side is released immediately
       ... handle timeout ...
   }
 

Specified by:

cancel in interface Future<ResultSet>

Overrides:

cancel in class com.google.common.util.concurrent.AbstractFuture<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.

set

public boolean set(V value)

Sets the value of this future. This method will return true if the value was successfully set, or false if the future has already been set or cancelled.

Overrides:

set in class com.google.common.util.concurrent.AbstractFuture<V>

Parameters:

value - the value the future should hold.

Returns:

true if the value was successfully set.

setException

public boolean setException(Throwable throwable)

Sets the future to having failed with the given exception. This exception will be wrapped in an ExecutionException and thrown from the get methods. This method will return true if the exception was successfully set, or false if the future has already been set or cancelled.

Overrides:

setException in class com.google.common.util.concurrent.AbstractFuture<V>

Parameters:

throwable - the exception the future should hold.

Returns:

true if the exception was successfully set.