org.rhq.enterprise.communications.command.client
Class RemotePojoInvocationFuture

java.lang.Object
  org.rhq.enterprise.communications.command.client.RemotePojoInvocationFuture

All Implemented Interfaces:

Serializable, CommandResponseCallback

public class RemotePojoInvocationFuture
extends Object
implements CommandResponseCallback

This is kind of "future" that can be used to wait for a remote POJO invocation. You typically use this to wait for an asynchronous remote pojo invocation. Because this implements CommandResponseCallback, it can be used as the callback to ClientRemotePojoFactory.setAsynch(boolean, CommandResponseCallback).

This does not implement Future because its semantics are slightly different, but it does work in a similar manner. Unlike Future, this object is not cancelable, but like Future, you can get() the results blocking indefinitely or you can supply a timeout via get(long, TimeUnit). This object can support multiple "calculation results" - once you retreive the results, you should reset() it in order to prepare this object to receive another result. If you do not reset this object, the get methods will never block again, they will always immediately return the last results it received. For this reason, it is preferable that you retreive the results via get(long, TimeUnit) or getAndReset(long, TimeUnit) to force the reset to occur.

This class is multi-thread safe, however, you must ensure that you call get() to retrieve the results before the callback method commandSent(CommandResponse) is called again. If you do not, you will lose the results for that previous invocation.

Example usage:

 ClientRemotePojoFactory factory = ...
 RemotePojoInvocationFuture future = new RemotePojoInvocationFuture();
 factory.setAsync(true, future);
 MyRemoteAPI pojo = factory.getRemotePojo(MyRemoteAPI.class);

 pojo.aMethodCall(); // will be sent asynchronously
 MyObject o = (MyObject) future.getAndReset(); // blocks until aMethodCall really finishes

 pojo.anotherCall(); // another asynchronous request
 AnotherObject o = (AnotherObject) future.getAndReset(); // blocks until anotherCall really finishes
 

Author:

John Mazzitelli

See Also:

Serialized Form

Constructor Summary

RemotePojoInvocationFuture()

Method Summary

void	commandSent(CommandResponse response) This stores the new response in this object as this future's calculation result (any previous result is lost).
Object	get() Blocks indefinitely until the remote invocation results are available, at which time those results are returned.
Object	get(long timeout, TimeUnit unit) Blocks for, at most, the specified amount of time or until the remote invocation results are available, at which time those results are returned.
Object	getAndReset() Same as get(), but before this method returns, this object is reset().
Object	getAndReset(long timeout, TimeUnit unit) Same as get(long, TimeUnit), but before this method returns, this object is reset().
boolean	isDone() Returns true if results are available and can be retrieved via the get methods without blocking.
void	reset() This will reset this object such that it can prepare to accept another remote pojo invocation result.

Methods inherited from class java.lang.Object

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

Constructor Detail

RemotePojoInvocationFuture

public RemotePojoInvocationFuture()

Method Detail

reset

public void reset()

This will reset this object such that it can prepare to accept another remote pojo invocation result. Calling this method will result in this object clearing out any current calculation result, thus making get() block until a new response is received via commandSent(CommandResponse). Note that this method will block if another thread is currently waiting in get() - it will unblock once that thread is done waiting.

commandSent

public void commandSent(CommandResponse response)

This stores the new response in this object as this future's calculation result (any previous result is lost). This new response's results object will be returned by get().

Specified by:

commandSent in interface CommandResponseCallback

Parameters:

response - the results of the command

See Also:

CommandResponseCallback.commandSent(CommandResponse)

getAndReset

public Object getAndReset()
                   throws InterruptedException,
                          ExecutionException

Same as get(), but before this method returns, this object is reset().

Returns:

the invocation results

Throws:

InterruptedException

ExecutionException

See Also:

Future.get()

getAndReset

public Object getAndReset(long timeout,
                          TimeUnit unit)
                   throws InterruptedException,
                          ExecutionException,
                          TimeoutException

Same as get(long, TimeUnit), but before this method returns, this object is reset().

Parameters:

timeout - the maximum amount of time to wait

unit - the unit of time that timeout is specified in

Returns:

the invocation results

Throws:

InterruptedException

ExecutionException

TimeoutException

See Also:

get(long, TimeUnit)

get

public Object get()
           throws InterruptedException,
                  ExecutionException

Blocks indefinitely until the remote invocation results are available, at which time those results are returned. If an exception occurred during the invocation, that exception is stored as the cause in the thrown ExecutionException.

Returns:

the remote invocation results

Throws:

InterruptedException - if the current thread waiting for the results is interrupted

ExecutionException - if the remote invocation threw an exception.

get

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

Blocks for, at most, the specified amount of time or until the remote invocation results are available, at which time those results are returned. If an exception occurred during the invocation, that exception is stored as the cause in the thrown ExecutionException.

Parameters:

timeout - the maximum amount of time to wait

unit - the unit of time that timeout is specified in

Returns:

the remote invocation results

Throws:

InterruptedException - if the current thread waiting for the results is interrupted

ExecutionException - if the remote invocation threw an exception.

TimeoutException - if the given amount of time has expired before the results have been received

isDone

public boolean isDone()

Returns true if results are available and can be retrieved via the get methods without blocking. Once the first remote invocation is done, this method will always return true, until this object is reset().

Returns:

true if results are available; false if the invocation has not completed yet