com.basho.riak.client.core

Interface RiakFuture<V,T>

Type Parameters:

V - the (response) return type

T - The query info type

All Superinterfaces:

Future<V>

All Known Implementing Classes:

BigIntIndexQuery.BigIntQueryFuture, BinIndexQuery.BinQueryFuture, CoreFutureAdapter, DeleteOperation, DtFetchOperation, DtUpdateOperation, FetchBucketPropsOperation, FetchOperation, FutureOperation, IntIndexQuery.IntQueryFuture, ListBucketsOperation, ListenableFuture, ListKeysOperation, MapReduceOperation, PingOperation, RawIndexQuery.RawQueryFuture, ResetBucketPropsOperation, SearchOperation, SecondaryIndexQueryOperation, StoreBucketPropsOperation, StoreOperation, YzDeleteIndexOperation, YzFetchIndexOperation, YzGetSchemaOperation, YzPutIndexOperation, YzPutSchemaOperation

public interface RiakFuture<V,T>
extends Future<V>

The result of an asynchronous Riak operation.

All Riak operations are asynchronous. It means when you execute an operation on the cluster it will return immediately with no guarantee that the requested operation has been completed at the end of the call. Instead, you will be returned a RiakFuture instance which gives you the information about the result or status of the operation.

A RiakFuture is either uncompleted or completed. When an operation begins, a new future object is created. The new future is uncompleted initially - it is neither succeeded, failed, nor canceled because the operation is not finished yet. If the operation is finished either successfully, with failure, or by cancellation, the future is marked as completed with more specific information, such as the cause of the failure. Please note that even failure and cancellation belong to the completed state.

                                      +---------------------------+
                                      | Completed successfully    |
                                      +---------------------------+
                                 +---->      isDone() = true      |
 +--------------------------+    |    |   isSuccess() = true      |
 |        Uncompleted       |    |    +===========================+
 +--------------------------+    |    | Completed with failure    |
 |      isDone() = false    |    |    +---------------------------+
 |   isSuccess() = false    |----+---->      isDone() = true      |
 | isCancelled() = false    |    |    |   isSuccess() = false     |
 |       cause() = null     |    |    |       cause() = non-null  |
 +--------------------------+    |    +===========================+
                                 |    | Completed by cancellation |
                                 |    +---------------------------+
                                 +---->      isDone() = true      |
                                      | isCancelled() = true      |
                                      +---------------------------+
 

The typical use pattern is to call await(), check isSuccess() then call getNow() or cause()

Since:

2.0

Author:

Brian Roach

Method Summary

Methods

Modifier and Type	Method and Description
void	addListener(RiakFutureListener<V,T> listener) Add a listener to this RiakFuture.
void	await() Waits for this RiakFuture to be completed.
void	await(long timeout, TimeUnit unit) Waits for this RiakFuture to be completed for a set amount of time.
boolean	cancel(boolean mayInterruptIfRunning) Not supported due to limitations of the Riak API.
Throwable	cause() Return information about the operation and why it failed.
V	get() Waits for this RiakFuture to be completed if necessary and returns the response if available.
V	get(long timeout, TimeUnit unit) Waits if necessary for at most the given time for the computation to complete, and then retrieves its result, if available.
V	getNow() Return the result without blocking or throwing an exception.
T	getQueryInfo() Returns information related to the operation performed.
boolean	isCancelled()
boolean	isDone()
boolean	isSuccess() Determine if the operation completed successfully.
void	removeListener(RiakFutureListener<V,T> listener) Remove a listener from this RiakFuture.

Method Detail

cancel

boolean cancel(boolean mayInterruptIfRunning)

Not supported due to limitations of the Riak API.

At present time there is no way to cancel an operation sent to Riak. This method will never succeed and always return false.

Specified by:

cancel in interface Future<V>

Parameters:

mayInterruptIfRunning -

Returns:

always false.

get

V get()
      throws InterruptedException,
             ExecutionException

Waits for this RiakFuture to be completed if necessary and returns the response if available.

Specified by:

get in interface Future<V>

Returns:

The response from the operation.

Throws:

InterruptedException - if the current thread was interrupted while waiting

ExecutionException - if the computation threw an exception

get

V get(long timeout,
    TimeUnit unit)
      throws InterruptedException,
             ExecutionException,
             TimeoutException

Waits if necessary for at most the given time for the computation to complete, and then retrieves its result, if available.

Note that the timeout value here is how long you are willing to wait for this RiakFuture to complete. If you wish to set a timeout on the command itself, use the timeout() method provided in the command's associated builder.

Specified by:

get in interface Future<V>

Parameters:

timeout - the amount of time to wait before returning.

unit - the unit of time.

Returns:

the response, or null if not completed or failed.

Throws:

InterruptedException - if the current thread was interrupted while waiting.

ExecutionException - if the computation threw an exception.

TimeoutException - if the wait timed out.

isCancelled

boolean isCancelled()

Specified by:

isCancelled in interface Future<V>

isDone

boolean isDone()

Specified by:

isDone in interface Future<V>

await

void await()
           throws InterruptedException

Waits for this RiakFuture to be completed.

Upon returning, the operation has completed. Checking isSuccess() tells you if it did so successfully.

Throws:

InterruptedException - if the current thread was interrupted while waiting

See Also:

RiakFuture.isSuccess()

await

void await(long timeout,
         TimeUnit unit)
           throws InterruptedException

Waits for this RiakFuture to be completed for a set amount of time.

Note that the timeout value here is how long you are willing to wait for this RiakFuture to complete. Upon return you can check isDone() to see if the future has completed yet or not. The operation is still in progress if that returns false.

If you wish to set a timeout on the command itself, use the timeout() method provided in the command's associated builder.

Parameters:

timeout - the amount of time to wait before returning.

unit - the unit of time.

Throws:

InterruptedException - if the current thread was interrupted while waiting

See Also:

RiakFuture.isDone(), RiakFuture.isSuccess()

getNow

V getNow()

Return the result without blocking or throwing an exception. If the future is not yet done or has failed this will return null. As it is possible that a null value is used to mark the future as successful you also need to check if the future is really done with RiakFuture.isDone() and not rely on the returned null value.

Returns:

The response, or null if the future is not yet completed or failed.

See Also:

RiakFuture.isDone(), RiakFuture.isSuccess()

isSuccess

boolean isSuccess()

Determine if the operation completed successfully.

Returns:

true if the operation succeeded, false if not yet completed or failed.

cause

Throwable cause()

Return information about the operation and why it failed.

Note this will return null if the operation completed successfully.

Returns:

The exception thrown during the operation, or null if not set.

See Also:

RiakFuture.isSuccess()

getQueryInfo

T getQueryInfo()

Returns information related to the operation performed.

Useful in async operations when you want to know what operation this future refers to.

Returns:

Information pertaining to the operation attached to this future.

addListener

void addListener(RiakFutureListener<V,T> listener)

Add a listener to this RiakFuture.

Parameters:

listener - a FiakFutureListener that will be notified when this RiakFuture completes.

removeListener

void removeListener(RiakFutureListener<V,T> listener)

Remove a listener from this RiakFuture.

Parameters:

listener - The listener to remove.