1 /*
2 * To change this template, choose Tools | Templates
3 * and open the template in the editor.
4 */
5 package cz.cuni.amis.utils.future;
6
7 import java.util.concurrent.Future;
8 import java.util.concurrent.TimeUnit;
9
10 /**
11 *
12 * @author Martin Cerny
13 */
14 public interface IFutureWithListeners<RESULT> extends Future<RESULT> {
15
16 /**
17 * Adds a listener on a future status (using strong reference). Listeners are automatically
18 * removed whenever the future gets its result (or is cancelled or an exception happens).
19 * @param listener
20 */
21 void addFutureListener(IFutureListener<RESULT> listener);
22
23 @Override
24 boolean cancel(boolean mayInterruptIfRunning);
25
26 /**
27 *
28 * Informs the future that it can't be computed due to the exception.
29 * <p><p>
30 * Switches the status to EXCEPTION (notifying listeners along the way).
31 * <p><p>
32 * The result can be set only iff NOT {@link FutureWithListeners#isDone()}, i.e., status is {@link FutureStatus}:FUTURE_IS_BEING_COMPUTED.
33 * @param e
34 */
35 void computationException(Exception e);
36
37 @Override
38 RESULT get();
39
40 /**
41 * Returns a result or waits for the computation till timeout.
42 * <p><p>
43 * Does not throw {@link TimeoutException}! It returns null instead - always examine status of the future
44 * via {@link FutureWithListeners#getStatus()} if the null is returned to tell whether the 'null' is the
45 * result of the computation (if the status is FUTURE_IS_READY than the 'null' is truly the result).
46 * @param timeout
47 * @param unit
48 * @return
49 */
50 @Override
51 RESULT get(long timeout, TimeUnit unit);
52
53 /**
54 * Contains an exception that has happened during the computation in the case of ({@link FutureWithListeners#getStatus()} == EXCEPTION).
55 * @return
56 */
57 Exception getException();
58
59 /**
60 * Current status of the future computation.
61 * @return
62 */
63 FutureStatus getStatus();
64
65 @Override
66 boolean isCancelled();
67
68 @Override
69 boolean isDone();
70
71 /**
72 * Whether some listener is listening on the future.
73 * @param listener
74 * @return
75 */
76 boolean isListening(IFutureListener<RESULT> listener);
77
78 /**
79 * Removes a listener from the future.
80 * @param listener
81 */
82 void removeFutureListener(IFutureListener<RESULT> listener);
83
84 /**
85 * Sets the result of the future computation.
86 * <p><p>
87 * Switches the status to FUTURE_IS_READY (notifying listeners along the way).
88 * <p><p>
89 * The result can be set only iff NOT {@link FutureWithListeners#isDone()}, i.e., status is {@link FutureStatus}:FUTURE_IS_BEING_COMPUTED.
90 * @param result
91 */
92 void setResult(RESULT result);
93
94 }