net.sergeych.tools

Class DeferredResult

java.lang.Object

net.sergeych.tools.DeferredResult

Direct Known Subclasses:

Farcall.CommandResult

public class DeferredResult
extends java.lang.Object

Promise-like object to wait for command answer. Is returned by the send methods and provides 3 optional callbacks - one for failure and success and one when operation is done anyway. Latter is universal - if it is called with a throwable instance then the operation is failed.

DeferredResult is threadsafe and allows any number of handlers of any type to be added at any time. Handlers added after the sendSuccess(Object) or sendFailure(Object), could be called immediately if condition is met (success or failure) with the proper data.

Only first call to sendSuccess(Object) or sendFailure(Object) matters, more calls are silently ignored.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DeferredResult.Error Exception raised if operation is failed and getResult() returns Throwable, which is passed as exception cause (with stack trace this way).
static class	DeferredResult.Failure Exception raised when operation is failed and getResult() passes non-exception object, which is available as DeferredResult.Failure.failureData.
static interface	DeferredResult.Handler Callback to be executed on deferred result state changed

Constructor Summary

Constructors

Constructor and Description
DeferredResult()

Method Summary

Modifier and Type	Method and Description
<T> T	await()
<T> T	await(long millis)
DeferredResult	done(DeferredResult.Handler handler) Adds the callback that will be called when the operation is done, after success() or failure() respecive invocation.
DeferredResult	failure(DeferredResult.Handler handler) Adds failure callback.
<T> T	getResult() Get the result passed with sendFailure(Object) or sendSuccess(Object).
boolean	isDone() Whether the deferred result is available already.
boolean	isSuccess() Whether the deferred result is available already and calculated successfully.
DeferredResult	join() Wait until the operation is somehow finished
boolean	join(long millis) wait until the operation is finished with maximum timeout
void	sendFailure(java.lang.Object data) Trigger the failure event and pass argument to all failure(Handler) and to done(Handler) callbacks.
void	sendSuccess(java.lang.Object data) Trigger the success event and pass argument to all success(Handler) and then done(Handler) callbacks.
DeferredResult	success(DeferredResult.Handler handler) Adds the success callback.
<T> T	waitSuccess() waits until the operation is finished and return it's result on success, or throws an error on failure.

Methods inherited from class java.lang.Object

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

Constructor Detail

DeferredResult

public DeferredResult()

Method Detail

success

public DeferredResult success(DeferredResult.Handler handler)

Adds the success callback. The callback parameter will get the value passed to the sendSuccess(Object) call. Multiple callbacks allowed; calling in order of registration.

This handler is executed before done(Handler).

If called when isDone() and isSuccess() the callback is invoked immediately.

Parameters:

handler - callback

failure

public DeferredResult failure(DeferredResult.Handler handler)

Adds failure callback. The parameter is what is passed to the sendFailure(Object) call. Multiple callbacks allowed; calling in order of registration.

This handler is executed before done(Handler).

If called when isDone() and !isSuccess() the callback is invoked immediately.

Parameters:

handler - RemoteError instance. callback

done

public DeferredResult done(DeferredResult.Handler handler)

Adds the callback that will be called when the operation is done, after success() or failure() respecive invocation. The operation result can be distinguished by checking isSuccess() value. Multiple callbacks allowed; calling in order of registration.

If called when isDone() == true the callback is invoked immediately.

Parameters:

handler - callback

sendSuccess

public void sendSuccess(java.lang.Object data)

Trigger the success event and pass argument to all success(Handler) and then done(Handler) callbacks. Can be called only once if sendFailure(Object) was not called before. Further calls to this method and to sendFailure(Object) are silently ignored.

Parameters:

data - to pass to callbacks

sendFailure

public void sendFailure(java.lang.Object data)

Trigger the failure event and pass argument to all failure(Handler) and to done(Handler) callbacks. Can be called only once if sendSuccess(Object) was not called before. Further calls to this method and to sendSuccess(Object) are silently ignored.

Parameters:

data - to pass to callbacks

isDone

public boolean isDone()

Whether the deferred result is available already.

getResult

public <T> T getResult()

Get the result passed with sendFailure(Object) or sendSuccess(Object). Check the state using isSuccess() call.

Do not call it when isDone() is false.

Type Parameters:

T - result value.

Returns:

result passed with the first sendSuccess(Object) or sendFailure(Object) call.

waitSuccess

public <T> T waitSuccess()
                  throws DeferredResult.Error,
                         java.lang.InterruptedException

waits until the operation is finished and return it's result on success, or throws an error on failure.

Throws:

java.lang.Error - or DeferredResult.Failure if operation fails

DeferredResult.Error

java.lang.InterruptedException

await

public <T> T await()
            throws java.lang.InterruptedException

Throws:

java.lang.InterruptedException

await

public <T> T await(long millis)
            throws java.lang.InterruptedException

Throws:

java.lang.InterruptedException

join

public final DeferredResult join()
                          throws java.lang.InterruptedException

Wait until the operation is somehow finished

Throws:

java.lang.InterruptedException

isSuccess

public boolean isSuccess()

Whether the deferred result is available already and calculated successfully.

join

public final boolean join(long millis)
                   throws java.lang.InterruptedException

wait until the operation is finished with maximum timeout

Parameters:

millis - time to wait for operation to complete

Returns:

true if the operation is finished, false if timeout expired or thread was interrupted and the operation is not yet done

Throws:

java.lang.InterruptedException