View Javadoc

1   /*
2    * Copyright 2013 The Netty Project
3    *
4    * The Netty Project licenses this file to you under the Apache License,
5    * version 2.0 (the "License"); you may not use this file except in compliance
6    * with the License. You may obtain a copy of the License at:
7    *
8    *   http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13   * License for the specific language governing permissions and limitations
14   * under the License.
15   */
16  package io.netty.util.concurrent;
17  
18  import java.util.concurrent.CancellationException;
19  import java.util.concurrent.TimeUnit;
20  
21  
22  /**
23   * The result of an asynchronous operation.
24   */
25  @SuppressWarnings("ClassNameSameAsAncestorName")
26  public interface Future<V> extends java.util.concurrent.Future<V> {
27  
28      /**
29       * Returns {@code true} if and only if the I/O operation was completed
30       * successfully.
31       */
32      boolean isSuccess();
33  
34      /**
35       * returns {@code true} if and only if the operation can be cancelled via {@link #cancel(boolean)}.
36       */
37      boolean isCancellable();
38  
39      /**
40       * Returns the cause of the failed I/O operation if the I/O operation has
41       * failed.
42       *
43       * @return the cause of the failure.
44       *         {@code null} if succeeded or this future is not
45       *         completed yet.
46       */
47      Throwable cause();
48  
49      /**
50       * Adds the specified listener to this future.  The
51       * specified listener is notified when this future is
52       * {@linkplain #isDone() done}.  If this future is already
53       * completed, the specified listener is notified immediately.
54       */
55      Future<V> addListener(GenericFutureListener<? extends Future<? super V>> listener);
56  
57      /**
58       * Adds the specified listeners to this future.  The
59       * specified listeners are notified when this future is
60       * {@linkplain #isDone() done}.  If this future is already
61       * completed, the specified listeners are notified immediately.
62       */
63      Future<V> addListeners(GenericFutureListener<? extends Future<? super V>>... listeners);
64  
65      /**
66       * Removes the first occurrence of the specified listener from this future.
67       * The specified listener is no longer notified when this
68       * future is {@linkplain #isDone() done}.  If the specified
69       * listener is not associated with this future, this method
70       * does nothing and returns silently.
71       */
72      Future<V> removeListener(GenericFutureListener<? extends Future<? super V>> listener);
73  
74      /**
75       * Removes the first occurrence for each of the listeners from this future.
76       * The specified listeners are no longer notified when this
77       * future is {@linkplain #isDone() done}.  If the specified
78       * listeners are not associated with this future, this method
79       * does nothing and returns silently.
80       */
81      Future<V> removeListeners(GenericFutureListener<? extends Future<? super V>>... listeners);
82  
83      /**
84       * Waits for this future until it is done, and rethrows the cause of the failure if this future
85       * failed.
86       */
87      Future<V> sync() throws InterruptedException;
88  
89      /**
90       * Waits for this future until it is done, and rethrows the cause of the failure if this future
91       * failed.
92       */
93      Future<V> syncUninterruptibly();
94  
95      /**
96       * Waits for this future to be completed.
97       *
98       * @throws InterruptedException
99       *         if the current thread was interrupted
100      */
101     Future<V> await() throws InterruptedException;
102 
103     /**
104      * Waits for this future to be completed without
105      * interruption.  This method catches an {@link InterruptedException} and
106      * discards it silently.
107      */
108     Future<V> awaitUninterruptibly();
109 
110     /**
111      * Waits for this future to be completed within the
112      * specified time limit.
113      *
114      * @return {@code true} if and only if the future was completed within
115      *         the specified time limit
116      *
117      * @throws InterruptedException
118      *         if the current thread was interrupted
119      */
120     boolean await(long timeout, TimeUnit unit) throws InterruptedException;
121 
122     /**
123      * Waits for this future to be completed within the
124      * specified time limit.
125      *
126      * @return {@code true} if and only if the future was completed within
127      *         the specified time limit
128      *
129      * @throws InterruptedException
130      *         if the current thread was interrupted
131      */
132     boolean await(long timeoutMillis) throws InterruptedException;
133 
134     /**
135      * Waits for this future to be completed within the
136      * specified time limit without interruption.  This method catches an
137      * {@link InterruptedException} and discards it silently.
138      *
139      * @return {@code true} if and only if the future was completed within
140      *         the specified time limit
141      */
142     boolean awaitUninterruptibly(long timeout, TimeUnit unit);
143 
144     /**
145      * Waits for this future to be completed within the
146      * specified time limit without interruption.  This method catches an
147      * {@link InterruptedException} and discards it silently.
148      *
149      * @return {@code true} if and only if the future was completed within
150      *         the specified time limit
151      */
152     boolean awaitUninterruptibly(long timeoutMillis);
153 
154     /**
155      * Return the result without blocking. If the future is not done yet this will return {@code null}.
156      *
157      * As it is possible that a {@code null} value is used to mark the future as successful you also need to check
158      * if the future is really done with {@link #isDone()} and not relay on the returned {@code null} value.
159      */
160     V getNow();
161 
162     /**
163      * {@inheritDoc}
164      *
165      * If the cancellation was successful it will fail the future with an {@link CancellationException}.
166      */
167     @Override
168     boolean cancel(boolean mayInterruptIfRunning);
169 }