FutureResult


1   /*
2     File: FutureResult.java
3   
4     Originally written by Doug Lea and released into the public domain.
5     This may be used for any purposes whatsoever without acknowledgment.
6     Thanks for the assistance and support of Sun Microsystems Labs,
7     and everyone contributing, testing, and using this code.
8   
9     History:
10    Date       Who                What
11    30Jun1998  dl               Create public version
12  */
13  
14  package org.logicalcobwebs.concurrent;
15  
16  import java.lang.reflect.InvocationTargetException  ;
17  
18  /**
19   * A  class maintaining a single reference variable serving as the result
20   * of an operation. The result cannot be accessed until it has been set.
21   * <p>
22   * <b>Sample Usage</b> <p>
23   * <pre>
24   * class ImageRenderer { Image render(byte[] raw); }
25   * class App {
26   *   Executor executor = ...
27   *   ImageRenderer renderer = ...
28   *   void display(byte[] rawimage) {
29   *     try {
30   *       FutureResult futureImage = new FutureResult();
31   *       Runnable command = futureImage.setter(new Callable() {
32   *          public Object call() { return renderer.render(rawImage); }
33   *       });
34   *       executor.execute(command);
35   *       drawBorders();             // do other things while executing
36   *       drawCaption();
37   *       drawImage((Image)(futureImage.get())); // use future
38   *     }
39   *     catch (InterruptedException ex) { return; }
40   *     catch (InvocationTargetException ex) { cleanup(); return; }
41   *   }
42   * }
43   * </pre>
44   * <p>[<a HREF="http://gee.cs.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/intro.html"> Introduction to this package. </a>]
45   * @see Executor
46   **/
47  
48  public class FutureResult {
49      /** The result of the operation **/
50      protected Object   value_ = null;
51  
52      /** Status -- true after first set **/
53      protected boolean ready_ = false;
54  
55      /** the exception encountered by operation producing result **/
56      protected InvocationTargetException   exception_ = null;
57  
58      /**
59       * Create an initially unset FutureResult
60       **/
61      public FutureResult() {
62      }
63  
64  
65      /**
66       * Return a Runnable object that, when run, will set the result value.
67       * @param function - a Callable object whose result will be
68       * held by this FutureResult.
69       * @return A Runnable object that, when run, will call the
70       * function and (eventually) set the result.
71       **/
72  
73      public Runnable   setter(final Callable function) {
74          return new Runnable  () {
75              public void run() {
76                  try {
77                      set(function.call());
78                  } catch (Throwable   ex) {
79                      setException(ex);
80                  }
81              }
82          };
83      }
84  
85      /** internal utility: either get the value or throw the exception **/
86      protected Object   doGet() throws InvocationTargetException   {
87          if (exception_ != null)
88              throw exception_;
89          else
90              return value_;
91      }
92  
93      /**
94       * Access the reference, waiting if necessary until it is ready.
95       * @return current value
96       * @exception InterruptedException if current thread has been interrupted
97       * @exception InvocationTargetException if the operation
98       * producing the value encountered an exception.
99       **/
100     public synchronized Object   get()
101             throws InterruptedException  , InvocationTargetException   {
102         while (!ready_) wait();
103         return doGet();
104     }
105 
106 
107     /**
108      * Wait at most msecs to access the reference.
109      * @return current value
110      * @exception TimeoutException if not ready after msecs
111      * @exception InterruptedException if current thread has been interrupted
112      * @exception InvocationTargetException if the operation
113      * producing the value encountered an exception.
114      **/
115     public synchronized Object   timedGet(long msecs)
116             throws TimeoutException, InterruptedException  , InvocationTargetException   {
117         long startTime = (msecs <= 0) ? 0 : System.currentTimeMillis();
118         long waitTime = msecs;
119         if (ready_)
120             return doGet();
121         else if (waitTime <= 0)
122             throw new TimeoutException(msecs);
123         else {
124             for (; ;) {
125                 wait(waitTime);
126                 if (ready_)
127                     return doGet();
128                 else {
129                     waitTime = msecs - (System.currentTimeMillis() - startTime);
130                     if (waitTime <= 0)
131                         throw new TimeoutException(msecs);
132                 }
133             }
134         }
135     }
136 
137     /**
138      * Set the reference, and signal that it is ready. It is not
139      * considered an error to set the value more than once,
140      * but it is not something you would normally want to do.
141      * @param newValue The value that will be returned by a subsequent get();
142      **/
143     public synchronized void set(Object   newValue) {
144         value_ = newValue;
145         ready_ = true;
146         notifyAll();
147     }
148 
149     /**
150      * Set the exception field, also setting ready status.
151      * @param ex The exception. It will be reported out wrapped
152      * within an InvocationTargetException
153      **/
154     public synchronized void setException(Throwable   ex) {
155         exception_ = new InvocationTargetException  (ex);
156         ready_ = true;
157         notifyAll();
158     }
159 
160 
161     /**
162      * Get the exception, or null if there isn't one (yet).
163      * This does not wait until the future is ready, so should
164      * ordinarily only be called if you know it is.
165      * @return the exception encountered by the operation
166      * setting the future, wrapped in an InvocationTargetException
167      **/
168     public synchronized InvocationTargetException   getException() {
169         return exception_;
170     }
171 
172     /**
173      * Return whether the reference or exception have been set.
174      * @return true if has been set. else false
175      **/
176     public synchronized boolean isReady() {
177         return ready_;
178     }
179 
180     /**
181      * Access the reference, even if not ready
182      * @return current value
183      **/
184     public synchronized Object   peek() {
185         return value_;
186     }
187 
188 
189     /**
190      * Clear the value and exception and set to not-ready,
191      * allowing this FutureResult to be reused. This is not
192      * particularly recommended and must be done only
193      * when you know that no other object is depending on the
194      * properties of this FutureResult.
195      **/
196     public synchronized void clear() {
197         value_ = null;
198         exception_ = null;
199         ready_ = false;
200     }
201 
202 }
203 
204 
205 
206
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags