mandala.rami
Interface FutureClient

All Superinterfaces:

Cancelable, InvocationEventsWaiter, InvocationInfo, InvocationObserver, MethodResult

All Known Subinterfaces:

RemoteFutureClient

All Known Implementing Classes:

AbstractFutureClient

public interface FutureClient

extends InvocationInfo, InvocationObserver, MethodResult, InvocationEventsWaiter, Cancelable

This interface represents the final future object any client must use to deal with an asynchronous method invocation.

This interface provides methods to poll the availability of the result of the asynchronous call, to wait the availability of the result and to check thrown exceptions.

Methods of this interface can be unrelated or related to the result returned by the asychronous method invocation. Related methods can be either safe or unsafe regarding the validity of their returned value which depends on the availability of the result. The result returned by an unsafe related method is undefined, hence unusable, if the result of the asychronous method invocation is not available. On the opposite, the result returned by a safe related method is always valid.
Unsafe related method are provided to allow efficient (non-blocking) programming scheme.

Unrelated methods can be used as any usual methods since their invocation do not depend on the asynchronous method invocation.

The behavior of a related method depends on the availaibility of the result of the asynchronous method invocation. This availability status can be tested with the isResultAvailable() method which is a safe related method.

If future is a FutureClient object used to deal with an asynchronous invocation of a method method of an object object, the following steps occurs after the asynchronous call.

If future.isResultAvailable() returns false, any call to an unsafe related method is undefined meaning that the method invocation has not yet returned.

If future.isResultAvailable() returns true, and if an exception occured during the call object.method(args), then future.exceptionOccured() returns true and future.getException() returns the exception.
Otherwise, future.getReturnedResult() returns the same object than object.method(args) did. getException(), getReturnedResult(), exceptionOccured() are unsafe related methods.

The waitForResult() method provide an easy way to wait for the result to become available. It is a safe related method which blocks the current thread until future.isResultAvailable() returns true.

Version:

1.0

Author:

eipi

See Also:

InvocationInfo, InvocationObserver, MethodResult, InvocationEventsWaiter, Cancelable

Methods inherited from interface mandala.rami.InvocationInfo

getArgs, getAsynchronousReference, getCallback, getCallerThread, getMethod

Methods inherited from interface mandala.rami.InvocationObserver

getCalleeThread, isCalleeAvailable, isCancelled, isInterrupted, isResultAvailable, isStarted

Methods inherited from interface mandala.rami.MethodResult

exceptionOccured, getException, getReturnedResult, getReturnedResultTrusted

Methods inherited from interface mandala.rami.InvocationEventsWaiter

waitForCalleeThread, waitForCalleeThread, waitForResult, waitForResult, waitUntilCalleeAvailable, waitUntilCalleeAvailable, waitUntilResultAvailable, waitUntilResultAvailable, waitUntilStarted, waitUntilStarted

Methods inherited from interface mandala.util.Cancelable

cancel, interrupt