EDU.oswego.cs.dl.util.concurrent
Class FutureResult

java.lang.Object
  extended by EDU.oswego.cs.dl.util.concurrent.FutureResult

public class FutureResult
extends java.lang.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:
Executor

Field Summary
protected  java.lang.reflect.InvocationTargetException exception_
          the exception encountered by operation producing result
protected  boolean ready_
          Status -- true after first set
protected  java.lang.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  java.lang.Object doGet()
          internal utility: either get the value or throw the exception
 java.lang.Object get()
          Access the reference, waiting if necessary until it is ready.
 java.lang.reflect.InvocationTargetException getException()
          Get the exception, or null if there isn't one (yet).
 boolean isReady()
          Return whether the reference or exception have been set.
 java.lang.Object peek()
          Access the reference, even if not ready
 void set(java.lang.Object newValue)
          Set the reference, and signal that it is ready.
 void setException(java.lang.Throwable ex)
          Set the exception field, also setting ready status.
 java.lang.Runnable setter(Callable function)
          Return a Runnable object that, when run, will set the result value.
 java.lang.Object timedGet(long msecs)
          Wait at most msecs to access the reference.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

value_

protected java.lang.Object value_
The result of the operation


ready_

protected boolean ready_
Status -- true after first set


exception_

protected java.lang.reflect.InvocationTargetException exception_
the exception encountered by operation producing result

Constructor Detail

FutureResult

public FutureResult()
Create an initially unset FutureResult

Method Detail

setter

public java.lang.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.

doGet

protected java.lang.Object doGet()
                          throws java.lang.reflect.InvocationTargetException
internal utility: either get the value or throw the exception

Throws:
java.lang.reflect.InvocationTargetException

get

public java.lang.Object get()
                     throws java.lang.InterruptedException,
                            java.lang.reflect.InvocationTargetException
Access the reference, waiting if necessary until it is ready.

Returns:
current value
Throws:
java.lang.InterruptedException - if current thread has been interrupted
java.lang.reflect.InvocationTargetException - if the operation producing the value encountered an exception.

timedGet

public java.lang.Object timedGet(long msecs)
                          throws TimeoutException,
                                 java.lang.InterruptedException,
                                 java.lang.reflect.InvocationTargetException
Wait at most msecs to access the reference.

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

set

public void set(java.lang.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(java.lang.Throwable ex)
Set the exception field, also setting ready status.

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

getException

public java.lang.reflect.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 java.lang.Object peek()
Access the reference, even if not ready

Returns:
current value

clear

public void clear()
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.