EDU.oswego.cs.dl.util.concurrent

Class FutureResult

public class FutureResult extends Object

A class maintaining a single reference variable serving as the result of an operation. The result cannot be accessed until it has been set.

Sample Usage

 class ImageRenderer { Image render(byte[] raw); }
 class App {
   Executor executor = ...
   ImageRenderer renderer = ...
   void display(byte[] rawimage) {
     try {
       FutureResult futureImage = new FutureResult();
       Runnable command = futureImage.setter(new Callable() {
          public Object call() { return renderer.render(rawImage); }
       });
       executor.execute(command);
       drawBorders();             // do other things while executing
       drawCaption();
       drawImage((Image)(futureImage.get())); // use future
     }
     catch (InterruptedException ex) { return; }
     catch (InvocationTargetException ex) { cleanup(); return; }
   }
 }

[ Introduction to this package. ]

See Also:

Field Summary
protected InvocationTargetException	exception_ the exception encountered by operation producing result *
protected boolean	ready_ Status -- true after first set *
protected Object	value_ The result of the operation *

Constructor Summary
	FutureResult() Create an initially unset FutureResult

Method Summary
void	clear() Clear the value and exception and set to not-ready, allowing this FutureResult to be reused.
protected Object	doGet() internal utility: either get the value or throw the exception *
Object	get() Access the reference, waiting if necessary until it is ready.
InvocationTargetException	getException() Get the exception, or null if there isn't one (yet).
boolean	isReady() Return whether the reference or exception have been set.
Object	peek() Access the reference, even if not ready
void	set(Object newValue) Set the reference, and signal that it is ready.
void	setException(Throwable ex) Set the exception field, also setting ready status.
Runnable	setter(Callable function) Return a Runnable object that, when run, will set the result value.
Object	timedGet(long msecs) Wait at most msecs to access the reference.

Field Detail

exception_

protected InvocationTargetException exception_

the exception encountered by operation producing result *

ready_

protected boolean ready_

Status -- true after first set *

value_

protected Object value_

The result of the operation *

Constructor Detail

FutureResult

public FutureResult()

Create an initially unset FutureResult

Clear the value and exception and set to not-ready, allowing this FutureResult to be reused. This is not particularly recommended and must be done only when you know that no other object is depending on the properties of this FutureResult.

doGet

protected Object doGet()

internal utility: either get the value or throw the exception *

get

public Object get()

Access the reference, waiting if necessary until it is ready.

Returns: current value

Throws: InterruptedException if current thread has been interrupted InvocationTargetException if the operation producing the value encountered an exception.

getException

public InvocationTargetException getException()

Get the exception, or null if there isn't one (yet). This does not wait until the future is ready, so should ordinarily only be called if you know it is.

Returns: the exception encountered by the operation setting the future, wrapped in an InvocationTargetException

isReady

public boolean isReady()

Return whether the reference or exception have been set.

Returns: true if has been set. else false

peek

public Object peek()

Access the reference, even if not ready

Returns: current value

set

public void set(Object newValue)

Set the reference, and signal that it is ready. It is not considered an error to set the value more than once, but it is not something you would normally want to do.

Parameters: newValue The value that will be returned by a subsequent get();

setException

public void setException(Throwable ex)

Set the exception field, also setting ready status.

Parameters: ex The exception. It will be reported out wrapped within an InvocationTargetException

setter

public Runnable setter(Callable function)

Return a Runnable object that, when run, will set the result value.

Parameters: function - a Callable object whose result will be held by this FutureResult.

Returns: A Runnable object that, when run, will call the function and (eventually) set the result.

timedGet

public Object timedGet(long msecs)

Wait at most msecs to access the reference.

Returns: current value

Throws: TimeoutException if not ready after msecs InterruptedException if current thread has been interrupted InvocationTargetException if the operation producing the value encountered an exception.