1 |
dl |
1.1 |
/* |
2 |
|
|
* Written by Doug Lea with assistance from members of JCP JSR-166 |
3 |
|
|
* Expert Group and released to the public domain, as explained at |
4 |
|
|
* http://creativecommons.org/publicdomain/zero/1.0/ |
5 |
|
|
*/ |
6 |
|
|
|
7 |
|
|
package java.util.concurrent; |
8 |
jsr166 |
1.17 |
|
9 |
|
|
import java.util.function.BiConsumer; |
10 |
|
|
import java.util.function.BiFunction; |
11 |
dl |
1.1 |
import java.util.function.Consumer; |
12 |
|
|
import java.util.function.Function; |
13 |
|
|
|
14 |
|
|
/** |
15 |
|
|
* A stage of a possibly asynchronous computation, that performs an |
16 |
|
|
* action or computes a value when another CompletionStage completes. |
17 |
|
|
* A stage completes upon termination of its computation, but this may |
18 |
|
|
* in turn trigger other dependent stages. The functionality defined |
19 |
|
|
* in this interface takes only a few basic forms, which expand out to |
20 |
jsr166 |
1.21 |
* a larger set of methods to capture a range of usage styles: |
21 |
|
|
* |
22 |
|
|
* <ul> |
23 |
dl |
1.1 |
* |
24 |
|
|
* <li>The computation performed by a stage may be expressed as a |
25 |
|
|
* Function, Consumer, or Runnable (using methods with names including |
26 |
|
|
* <em>apply</em>, <em>accept</em>, or <em>run</em>, respectively) |
27 |
dl |
1.2 |
* depending on whether it requires arguments and/or produces results. |
28 |
jsr166 |
1.23 |
* For example: |
29 |
|
|
* <pre> {@code |
30 |
|
|
* stage.thenApply(x -> square(x)) |
31 |
|
|
* .thenAccept(x -> System.out.print(x)) |
32 |
jsr166 |
1.29 |
* .thenRun(() -> System.out.println());}</pre> |
33 |
jsr166 |
1.23 |
* |
34 |
|
|
* An additional form (<em>compose</em>) allows the construction of |
35 |
|
|
* computation pipelines from functions returning completion stages. |
36 |
dl |
1.1 |
* |
37 |
jsr166 |
1.19 |
* <li>One stage's execution may be triggered by completion of a |
38 |
dl |
1.1 |
* single stage, or both of two stages, or either of two stages. |
39 |
|
|
* Dependencies on a single stage are arranged using methods with |
40 |
|
|
* prefix <em>then</em>. Those triggered by completion of |
41 |
|
|
* <em>both</em> of two stages may <em>combine</em> their results or |
42 |
|
|
* effects, using correspondingly named methods. Those triggered by |
43 |
|
|
* <em>either</em> of two stages make no guarantees about which of the |
44 |
jsr166 |
1.22 |
* results or effects are used for the dependent stage's computation. |
45 |
dl |
1.1 |
* |
46 |
jsr166 |
1.19 |
* <li>Dependencies among stages control the triggering of |
47 |
dl |
1.1 |
* computations, but do not otherwise guarantee any particular |
48 |
|
|
* ordering. Additionally, execution of a new stage's computations may |
49 |
|
|
* be arranged in any of three ways: default execution, default |
50 |
|
|
* asynchronous execution (using methods with suffix <em>async</em> |
51 |
|
|
* that employ the stage's default asynchronous execution facility), |
52 |
dl |
1.2 |
* or custom (via a supplied {@link Executor}). The execution |
53 |
dl |
1.1 |
* properties of default and async modes are specified by |
54 |
|
|
* CompletionStage implementations, not this interface. Methods with |
55 |
|
|
* explicit Executor arguments may have arbitrary execution |
56 |
|
|
* properties, and might not even support concurrent execution, but |
57 |
|
|
* are arranged for processing in a way that accommodates asynchrony. |
58 |
|
|
* |
59 |
jsr166 |
1.19 |
* <li>Two method forms support processing whether the triggering |
60 |
dl |
1.1 |
* stage completed normally or exceptionally: Method {@link |
61 |
|
|
* #whenComplete whenComplete} allows injection of an action |
62 |
|
|
* regardless of outcome, otherwise preserving the outcome in its |
63 |
|
|
* completion. Method {@link #handle handle} additionally allows the |
64 |
|
|
* stage to compute a replacement result that may enable further |
65 |
|
|
* processing by other dependent stages. In all other cases, if a |
66 |
|
|
* stage's computation terminates abruptly with an (unchecked) |
67 |
|
|
* exception or error, then all dependent stages requiring its |
68 |
|
|
* completion complete exceptionally as well, with a {@link |
69 |
|
|
* CompletionException} holding the exception as its cause. If a |
70 |
|
|
* stage is dependent on <em>both</em> of two stages, and both |
71 |
|
|
* complete exceptionally, then the CompletionException may correspond |
72 |
|
|
* to either one of these exceptions. If a stage is dependent on |
73 |
|
|
* <em>either</em> of two others, and only one of them completes |
74 |
|
|
* exceptionally, no guarantees are made about whether the dependent |
75 |
|
|
* stage completes normally or exceptionally. In the case of method |
76 |
dl |
1.2 |
* {@code whenComplete}, when the supplied action itself encounters an |
77 |
jsr166 |
1.25 |
* exception, then the stage completes exceptionally with this |
78 |
|
|
* exception unless the source stage also completed exceptionally, in |
79 |
|
|
* which case the exceptional completion from the source stage is |
80 |
jsr166 |
1.27 |
* given preference and propagated to the dependent stage. |
81 |
dl |
1.1 |
* |
82 |
|
|
* </ul> |
83 |
|
|
* |
84 |
|
|
* <p>All methods adhere to the above triggering, execution, and |
85 |
|
|
* exceptional completion specifications (which are not repeated in |
86 |
|
|
* individual method specifications). Additionally, while arguments |
87 |
|
|
* used to pass a completion result (that is, for parameters of type |
88 |
|
|
* {@code T}) for methods accepting them may be null, passing a null |
89 |
|
|
* value for any other parameter will result in a {@link |
90 |
|
|
* NullPointerException} being thrown. |
91 |
|
|
* |
92 |
jsr166 |
1.3 |
* <p>This interface does not define methods for initially creating, |
93 |
dl |
1.1 |
* forcibly completing normally or exceptionally, probing completion |
94 |
|
|
* status or results, or awaiting completion of a stage. |
95 |
|
|
* Implementations of CompletionStage may provide means of achieving |
96 |
|
|
* such effects, as appropriate. Method {@link #toCompletableFuture} |
97 |
|
|
* enables interoperability among different implementations of this |
98 |
|
|
* interface by providing a common conversion type. |
99 |
|
|
* |
100 |
|
|
* @author Doug Lea |
101 |
|
|
* @since 1.8 |
102 |
|
|
*/ |
103 |
|
|
public interface CompletionStage<T> { |
104 |
|
|
|
105 |
|
|
/** |
106 |
|
|
* Returns a new CompletionStage that, when this stage completes |
107 |
|
|
* normally, is executed with this stage's result as the argument |
108 |
|
|
* to the supplied function. |
109 |
|
|
* |
110 |
jsr166 |
1.23 |
* <p>This method is analogous to |
111 |
|
|
* {@link java.util.Optional#map Optional.map} and |
112 |
|
|
* {@link java.util.stream.Stream#map Stream.map}. |
113 |
|
|
* |
114 |
|
|
* <p>See the {@link CompletionStage} documentation for rules |
115 |
dl |
1.1 |
* covering exceptional completion. |
116 |
|
|
* |
117 |
jsr166 |
1.20 |
* @param fn the function to use to compute the value of the |
118 |
|
|
* returned CompletionStage |
119 |
jsr166 |
1.9 |
* @param <U> the function's return type |
120 |
dl |
1.1 |
* @return the new CompletionStage |
121 |
|
|
*/ |
122 |
|
|
public <U> CompletionStage<U> thenApply(Function<? super T,? extends U> fn); |
123 |
|
|
|
124 |
|
|
/** |
125 |
|
|
* Returns a new CompletionStage that, when this stage completes |
126 |
|
|
* normally, is executed using this stage's default asynchronous |
127 |
|
|
* execution facility, with this stage's result as the argument to |
128 |
|
|
* the supplied function. |
129 |
|
|
* |
130 |
|
|
* See the {@link CompletionStage} documentation for rules |
131 |
|
|
* covering exceptional completion. |
132 |
|
|
* |
133 |
jsr166 |
1.20 |
* @param fn the function to use to compute the value of the |
134 |
|
|
* returned CompletionStage |
135 |
jsr166 |
1.9 |
* @param <U> the function's return type |
136 |
dl |
1.1 |
* @return the new CompletionStage |
137 |
|
|
*/ |
138 |
|
|
public <U> CompletionStage<U> thenApplyAsync |
139 |
|
|
(Function<? super T,? extends U> fn); |
140 |
|
|
|
141 |
|
|
/** |
142 |
|
|
* Returns a new CompletionStage that, when this stage completes |
143 |
|
|
* normally, is executed using the supplied Executor, with this |
144 |
|
|
* stage's result as the argument to the supplied function. |
145 |
|
|
* |
146 |
|
|
* See the {@link CompletionStage} documentation for rules |
147 |
|
|
* covering exceptional completion. |
148 |
|
|
* |
149 |
jsr166 |
1.20 |
* @param fn the function to use to compute the value of the |
150 |
|
|
* returned CompletionStage |
151 |
dl |
1.1 |
* @param executor the executor to use for asynchronous execution |
152 |
jsr166 |
1.9 |
* @param <U> the function's return type |
153 |
dl |
1.1 |
* @return the new CompletionStage |
154 |
|
|
*/ |
155 |
|
|
public <U> CompletionStage<U> thenApplyAsync |
156 |
|
|
(Function<? super T,? extends U> fn, |
157 |
|
|
Executor executor); |
158 |
|
|
|
159 |
|
|
/** |
160 |
|
|
* Returns a new CompletionStage that, when this stage completes |
161 |
|
|
* normally, is executed with this stage's result as the argument |
162 |
|
|
* to the supplied action. |
163 |
|
|
* |
164 |
|
|
* See the {@link CompletionStage} documentation for rules |
165 |
|
|
* covering exceptional completion. |
166 |
|
|
* |
167 |
|
|
* @param action the action to perform before completing the |
168 |
|
|
* returned CompletionStage |
169 |
|
|
* @return the new CompletionStage |
170 |
|
|
*/ |
171 |
|
|
public CompletionStage<Void> thenAccept(Consumer<? super T> action); |
172 |
|
|
|
173 |
|
|
/** |
174 |
|
|
* Returns a new CompletionStage that, when this stage completes |
175 |
|
|
* normally, is executed using this stage's default asynchronous |
176 |
|
|
* execution facility, with this stage's result as the argument to |
177 |
|
|
* the supplied action. |
178 |
|
|
* |
179 |
|
|
* See the {@link CompletionStage} documentation for rules |
180 |
|
|
* covering exceptional completion. |
181 |
|
|
* |
182 |
|
|
* @param action the action to perform before completing the |
183 |
|
|
* returned CompletionStage |
184 |
|
|
* @return the new CompletionStage |
185 |
|
|
*/ |
186 |
|
|
public CompletionStage<Void> thenAcceptAsync(Consumer<? super T> action); |
187 |
|
|
|
188 |
|
|
/** |
189 |
|
|
* Returns a new CompletionStage that, when this stage completes |
190 |
|
|
* normally, is executed using the supplied Executor, with this |
191 |
|
|
* stage's result as the argument to the supplied action. |
192 |
|
|
* |
193 |
|
|
* See the {@link CompletionStage} documentation for rules |
194 |
|
|
* covering exceptional completion. |
195 |
|
|
* |
196 |
|
|
* @param action the action to perform before completing the |
197 |
|
|
* returned CompletionStage |
198 |
|
|
* @param executor the executor to use for asynchronous execution |
199 |
|
|
* @return the new CompletionStage |
200 |
|
|
*/ |
201 |
|
|
public CompletionStage<Void> thenAcceptAsync(Consumer<? super T> action, |
202 |
jsr166 |
1.5 |
Executor executor); |
203 |
dl |
1.1 |
/** |
204 |
|
|
* Returns a new CompletionStage that, when this stage completes |
205 |
|
|
* normally, executes the given action. |
206 |
|
|
* |
207 |
|
|
* See the {@link CompletionStage} documentation for rules |
208 |
|
|
* covering exceptional completion. |
209 |
|
|
* |
210 |
|
|
* @param action the action to perform before completing the |
211 |
|
|
* returned CompletionStage |
212 |
|
|
* @return the new CompletionStage |
213 |
|
|
*/ |
214 |
|
|
public CompletionStage<Void> thenRun(Runnable action); |
215 |
|
|
|
216 |
|
|
/** |
217 |
|
|
* Returns a new CompletionStage that, when this stage completes |
218 |
|
|
* normally, executes the given action using this stage's default |
219 |
|
|
* asynchronous execution facility. |
220 |
|
|
* |
221 |
|
|
* See the {@link CompletionStage} documentation for rules |
222 |
|
|
* covering exceptional completion. |
223 |
|
|
* |
224 |
|
|
* @param action the action to perform before completing the |
225 |
|
|
* returned CompletionStage |
226 |
|
|
* @return the new CompletionStage |
227 |
|
|
*/ |
228 |
|
|
public CompletionStage<Void> thenRunAsync(Runnable action); |
229 |
|
|
|
230 |
|
|
/** |
231 |
|
|
* Returns a new CompletionStage that, when this stage completes |
232 |
|
|
* normally, executes the given action using the supplied Executor. |
233 |
|
|
* |
234 |
|
|
* See the {@link CompletionStage} documentation for rules |
235 |
|
|
* covering exceptional completion. |
236 |
|
|
* |
237 |
|
|
* @param action the action to perform before completing the |
238 |
|
|
* returned CompletionStage |
239 |
|
|
* @param executor the executor to use for asynchronous execution |
240 |
|
|
* @return the new CompletionStage |
241 |
|
|
*/ |
242 |
|
|
public CompletionStage<Void> thenRunAsync(Runnable action, |
243 |
|
|
Executor executor); |
244 |
|
|
|
245 |
|
|
/** |
246 |
|
|
* Returns a new CompletionStage that, when this and the other |
247 |
|
|
* given stage both complete normally, is executed with the two |
248 |
|
|
* results as arguments to the supplied function. |
249 |
|
|
* |
250 |
|
|
* See the {@link CompletionStage} documentation for rules |
251 |
|
|
* covering exceptional completion. |
252 |
|
|
* |
253 |
|
|
* @param other the other CompletionStage |
254 |
jsr166 |
1.20 |
* @param fn the function to use to compute the value of the |
255 |
|
|
* returned CompletionStage |
256 |
jsr166 |
1.9 |
* @param <U> the type of the other CompletionStage's result |
257 |
|
|
* @param <V> the function's return type |
258 |
dl |
1.1 |
* @return the new CompletionStage |
259 |
|
|
*/ |
260 |
|
|
public <U,V> CompletionStage<V> thenCombine |
261 |
|
|
(CompletionStage<? extends U> other, |
262 |
|
|
BiFunction<? super T,? super U,? extends V> fn); |
263 |
|
|
|
264 |
|
|
/** |
265 |
|
|
* Returns a new CompletionStage that, when this and the other |
266 |
jsr166 |
1.31 |
* given stage both complete normally, is executed using this |
267 |
|
|
* stage's default asynchronous execution facility, with the two |
268 |
|
|
* results as arguments to the supplied function. |
269 |
dl |
1.1 |
* |
270 |
|
|
* See the {@link CompletionStage} documentation for rules |
271 |
|
|
* covering exceptional completion. |
272 |
|
|
* |
273 |
|
|
* @param other the other CompletionStage |
274 |
jsr166 |
1.20 |
* @param fn the function to use to compute the value of the |
275 |
|
|
* returned CompletionStage |
276 |
jsr166 |
1.9 |
* @param <U> the type of the other CompletionStage's result |
277 |
|
|
* @param <V> the function's return type |
278 |
dl |
1.1 |
* @return the new CompletionStage |
279 |
|
|
*/ |
280 |
|
|
public <U,V> CompletionStage<V> thenCombineAsync |
281 |
|
|
(CompletionStage<? extends U> other, |
282 |
|
|
BiFunction<? super T,? super U,? extends V> fn); |
283 |
|
|
|
284 |
|
|
/** |
285 |
|
|
* Returns a new CompletionStage that, when this and the other |
286 |
jsr166 |
1.31 |
* given stage both complete normally, is executed using the |
287 |
|
|
* supplied executor, with the two results as arguments to the |
288 |
|
|
* supplied function. |
289 |
dl |
1.1 |
* |
290 |
|
|
* See the {@link CompletionStage} documentation for rules |
291 |
|
|
* covering exceptional completion. |
292 |
|
|
* |
293 |
|
|
* @param other the other CompletionStage |
294 |
jsr166 |
1.20 |
* @param fn the function to use to compute the value of the |
295 |
|
|
* returned CompletionStage |
296 |
dl |
1.1 |
* @param executor the executor to use for asynchronous execution |
297 |
jsr166 |
1.9 |
* @param <U> the type of the other CompletionStage's result |
298 |
|
|
* @param <V> the function's return type |
299 |
dl |
1.1 |
* @return the new CompletionStage |
300 |
|
|
*/ |
301 |
|
|
public <U,V> CompletionStage<V> thenCombineAsync |
302 |
|
|
(CompletionStage<? extends U> other, |
303 |
|
|
BiFunction<? super T,? super U,? extends V> fn, |
304 |
|
|
Executor executor); |
305 |
|
|
|
306 |
|
|
/** |
307 |
|
|
* Returns a new CompletionStage that, when this and the other |
308 |
|
|
* given stage both complete normally, is executed with the two |
309 |
|
|
* results as arguments to the supplied action. |
310 |
|
|
* |
311 |
|
|
* See the {@link CompletionStage} documentation for rules |
312 |
|
|
* covering exceptional completion. |
313 |
|
|
* |
314 |
|
|
* @param other the other CompletionStage |
315 |
|
|
* @param action the action to perform before completing the |
316 |
|
|
* returned CompletionStage |
317 |
jsr166 |
1.9 |
* @param <U> the type of the other CompletionStage's result |
318 |
dl |
1.1 |
* @return the new CompletionStage |
319 |
|
|
*/ |
320 |
|
|
public <U> CompletionStage<Void> thenAcceptBoth |
321 |
|
|
(CompletionStage<? extends U> other, |
322 |
|
|
BiConsumer<? super T, ? super U> action); |
323 |
|
|
|
324 |
|
|
/** |
325 |
|
|
* Returns a new CompletionStage that, when this and the other |
326 |
jsr166 |
1.31 |
* given stage both complete normally, is executed using this |
327 |
|
|
* stage's default asynchronous execution facility, with the two |
328 |
|
|
* results as arguments to the supplied action. |
329 |
dl |
1.1 |
* |
330 |
jsr166 |
1.32 |
* See the {@link CompletionStage} documentation for rules |
331 |
|
|
* covering exceptional completion. |
332 |
|
|
* |
333 |
dl |
1.1 |
* @param other the other CompletionStage |
334 |
|
|
* @param action the action to perform before completing the |
335 |
|
|
* returned CompletionStage |
336 |
jsr166 |
1.9 |
* @param <U> the type of the other CompletionStage's result |
337 |
dl |
1.1 |
* @return the new CompletionStage |
338 |
|
|
*/ |
339 |
|
|
public <U> CompletionStage<Void> thenAcceptBothAsync |
340 |
|
|
(CompletionStage<? extends U> other, |
341 |
|
|
BiConsumer<? super T, ? super U> action); |
342 |
|
|
|
343 |
|
|
/** |
344 |
|
|
* Returns a new CompletionStage that, when this and the other |
345 |
jsr166 |
1.31 |
* given stage both complete normally, is executed using the |
346 |
|
|
* supplied executor, with the two results as arguments to the |
347 |
|
|
* supplied action. |
348 |
dl |
1.1 |
* |
349 |
jsr166 |
1.32 |
* See the {@link CompletionStage} documentation for rules |
350 |
|
|
* covering exceptional completion. |
351 |
|
|
* |
352 |
dl |
1.1 |
* @param other the other CompletionStage |
353 |
|
|
* @param action the action to perform before completing the |
354 |
|
|
* returned CompletionStage |
355 |
|
|
* @param executor the executor to use for asynchronous execution |
356 |
jsr166 |
1.9 |
* @param <U> the type of the other CompletionStage's result |
357 |
dl |
1.1 |
* @return the new CompletionStage |
358 |
|
|
*/ |
359 |
|
|
public <U> CompletionStage<Void> thenAcceptBothAsync |
360 |
|
|
(CompletionStage<? extends U> other, |
361 |
|
|
BiConsumer<? super T, ? super U> action, |
362 |
|
|
Executor executor); |
363 |
|
|
|
364 |
|
|
/** |
365 |
|
|
* Returns a new CompletionStage that, when this and the other |
366 |
|
|
* given stage both complete normally, executes the given action. |
367 |
|
|
* |
368 |
|
|
* See the {@link CompletionStage} documentation for rules |
369 |
|
|
* covering exceptional completion. |
370 |
|
|
* |
371 |
|
|
* @param other the other CompletionStage |
372 |
|
|
* @param action the action to perform before completing the |
373 |
|
|
* returned CompletionStage |
374 |
|
|
* @return the new CompletionStage |
375 |
|
|
*/ |
376 |
|
|
public CompletionStage<Void> runAfterBoth(CompletionStage<?> other, |
377 |
|
|
Runnable action); |
378 |
|
|
/** |
379 |
|
|
* Returns a new CompletionStage that, when this and the other |
380 |
jsr166 |
1.31 |
* given stage both complete normally, executes the given action |
381 |
|
|
* using this stage's default asynchronous execution facility. |
382 |
dl |
1.1 |
* |
383 |
|
|
* See the {@link CompletionStage} documentation for rules |
384 |
|
|
* covering exceptional completion. |
385 |
|
|
* |
386 |
|
|
* @param other the other CompletionStage |
387 |
|
|
* @param action the action to perform before completing the |
388 |
|
|
* returned CompletionStage |
389 |
|
|
* @return the new CompletionStage |
390 |
|
|
*/ |
391 |
|
|
public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other, |
392 |
|
|
Runnable action); |
393 |
|
|
|
394 |
|
|
/** |
395 |
|
|
* Returns a new CompletionStage that, when this and the other |
396 |
jsr166 |
1.31 |
* given stage both complete normally, executes the given action |
397 |
|
|
* using the supplied executor. |
398 |
dl |
1.1 |
* |
399 |
|
|
* See the {@link CompletionStage} documentation for rules |
400 |
|
|
* covering exceptional completion. |
401 |
|
|
* |
402 |
|
|
* @param other the other CompletionStage |
403 |
|
|
* @param action the action to perform before completing the |
404 |
|
|
* returned CompletionStage |
405 |
|
|
* @param executor the executor to use for asynchronous execution |
406 |
|
|
* @return the new CompletionStage |
407 |
|
|
*/ |
408 |
|
|
public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other, |
409 |
|
|
Runnable action, |
410 |
|
|
Executor executor); |
411 |
|
|
/** |
412 |
|
|
* Returns a new CompletionStage that, when either this or the |
413 |
|
|
* other given stage complete normally, is executed with the |
414 |
|
|
* corresponding result as argument to the supplied function. |
415 |
|
|
* |
416 |
|
|
* See the {@link CompletionStage} documentation for rules |
417 |
|
|
* covering exceptional completion. |
418 |
|
|
* |
419 |
|
|
* @param other the other CompletionStage |
420 |
jsr166 |
1.20 |
* @param fn the function to use to compute the value of the |
421 |
|
|
* returned CompletionStage |
422 |
jsr166 |
1.9 |
* @param <U> the function's return type |
423 |
dl |
1.1 |
* @return the new CompletionStage |
424 |
|
|
*/ |
425 |
|
|
public <U> CompletionStage<U> applyToEither |
426 |
|
|
(CompletionStage<? extends T> other, |
427 |
|
|
Function<? super T, U> fn); |
428 |
|
|
|
429 |
|
|
/** |
430 |
|
|
* Returns a new CompletionStage that, when either this or the |
431 |
|
|
* other given stage complete normally, is executed using this |
432 |
|
|
* stage's default asynchronous execution facility, with the |
433 |
|
|
* corresponding result as argument to the supplied function. |
434 |
|
|
* |
435 |
|
|
* See the {@link CompletionStage} documentation for rules |
436 |
|
|
* covering exceptional completion. |
437 |
|
|
* |
438 |
|
|
* @param other the other CompletionStage |
439 |
jsr166 |
1.20 |
* @param fn the function to use to compute the value of the |
440 |
|
|
* returned CompletionStage |
441 |
jsr166 |
1.9 |
* @param <U> the function's return type |
442 |
dl |
1.1 |
* @return the new CompletionStage |
443 |
|
|
*/ |
444 |
|
|
public <U> CompletionStage<U> applyToEitherAsync |
445 |
|
|
(CompletionStage<? extends T> other, |
446 |
|
|
Function<? super T, U> fn); |
447 |
|
|
|
448 |
|
|
/** |
449 |
|
|
* Returns a new CompletionStage that, when either this or the |
450 |
|
|
* other given stage complete normally, is executed using the |
451 |
|
|
* supplied executor, with the corresponding result as argument to |
452 |
|
|
* the supplied function. |
453 |
|
|
* |
454 |
|
|
* See the {@link CompletionStage} documentation for rules |
455 |
|
|
* covering exceptional completion. |
456 |
|
|
* |
457 |
|
|
* @param other the other CompletionStage |
458 |
jsr166 |
1.20 |
* @param fn the function to use to compute the value of the |
459 |
|
|
* returned CompletionStage |
460 |
dl |
1.1 |
* @param executor the executor to use for asynchronous execution |
461 |
jsr166 |
1.9 |
* @param <U> the function's return type |
462 |
dl |
1.1 |
* @return the new CompletionStage |
463 |
|
|
*/ |
464 |
|
|
public <U> CompletionStage<U> applyToEitherAsync |
465 |
|
|
(CompletionStage<? extends T> other, |
466 |
|
|
Function<? super T, U> fn, |
467 |
|
|
Executor executor); |
468 |
|
|
|
469 |
|
|
/** |
470 |
|
|
* Returns a new CompletionStage that, when either this or the |
471 |
|
|
* other given stage complete normally, is executed with the |
472 |
|
|
* corresponding result as argument to the supplied action. |
473 |
|
|
* |
474 |
|
|
* See the {@link CompletionStage} documentation for rules |
475 |
|
|
* covering exceptional completion. |
476 |
|
|
* |
477 |
|
|
* @param other the other CompletionStage |
478 |
|
|
* @param action the action to perform before completing the |
479 |
|
|
* returned CompletionStage |
480 |
|
|
* @return the new CompletionStage |
481 |
|
|
*/ |
482 |
|
|
public CompletionStage<Void> acceptEither |
483 |
|
|
(CompletionStage<? extends T> other, |
484 |
|
|
Consumer<? super T> action); |
485 |
|
|
|
486 |
|
|
/** |
487 |
|
|
* Returns a new CompletionStage that, when either this or the |
488 |
|
|
* other given stage complete normally, is executed using this |
489 |
|
|
* stage's default asynchronous execution facility, with the |
490 |
|
|
* corresponding result as argument to the supplied action. |
491 |
|
|
* |
492 |
|
|
* See the {@link CompletionStage} documentation for rules |
493 |
|
|
* covering exceptional completion. |
494 |
|
|
* |
495 |
|
|
* @param other the other CompletionStage |
496 |
|
|
* @param action the action to perform before completing the |
497 |
|
|
* returned CompletionStage |
498 |
|
|
* @return the new CompletionStage |
499 |
|
|
*/ |
500 |
|
|
public CompletionStage<Void> acceptEitherAsync |
501 |
|
|
(CompletionStage<? extends T> other, |
502 |
|
|
Consumer<? super T> action); |
503 |
|
|
|
504 |
|
|
/** |
505 |
|
|
* Returns a new CompletionStage that, when either this or the |
506 |
|
|
* other given stage complete normally, is executed using the |
507 |
|
|
* supplied executor, with the corresponding result as argument to |
508 |
jsr166 |
1.30 |
* the supplied action. |
509 |
dl |
1.1 |
* |
510 |
|
|
* See the {@link CompletionStage} documentation for rules |
511 |
|
|
* covering exceptional completion. |
512 |
|
|
* |
513 |
|
|
* @param other the other CompletionStage |
514 |
|
|
* @param action the action to perform before completing the |
515 |
|
|
* returned CompletionStage |
516 |
|
|
* @param executor the executor to use for asynchronous execution |
517 |
|
|
* @return the new CompletionStage |
518 |
|
|
*/ |
519 |
|
|
public CompletionStage<Void> acceptEitherAsync |
520 |
|
|
(CompletionStage<? extends T> other, |
521 |
|
|
Consumer<? super T> action, |
522 |
|
|
Executor executor); |
523 |
|
|
|
524 |
|
|
/** |
525 |
|
|
* Returns a new CompletionStage that, when either this or the |
526 |
|
|
* other given stage complete normally, executes the given action. |
527 |
|
|
* |
528 |
|
|
* See the {@link CompletionStage} documentation for rules |
529 |
|
|
* covering exceptional completion. |
530 |
|
|
* |
531 |
|
|
* @param other the other CompletionStage |
532 |
|
|
* @param action the action to perform before completing the |
533 |
|
|
* returned CompletionStage |
534 |
|
|
* @return the new CompletionStage |
535 |
|
|
*/ |
536 |
|
|
public CompletionStage<Void> runAfterEither(CompletionStage<?> other, |
537 |
|
|
Runnable action); |
538 |
jsr166 |
1.6 |
|
539 |
dl |
1.1 |
/** |
540 |
|
|
* Returns a new CompletionStage that, when either this or the |
541 |
|
|
* other given stage complete normally, executes the given action |
542 |
|
|
* using this stage's default asynchronous execution facility. |
543 |
|
|
* |
544 |
|
|
* See the {@link CompletionStage} documentation for rules |
545 |
|
|
* covering exceptional completion. |
546 |
|
|
* |
547 |
|
|
* @param other the other CompletionStage |
548 |
|
|
* @param action the action to perform before completing the |
549 |
|
|
* returned CompletionStage |
550 |
|
|
* @return the new CompletionStage |
551 |
|
|
*/ |
552 |
|
|
public CompletionStage<Void> runAfterEitherAsync |
553 |
|
|
(CompletionStage<?> other, |
554 |
|
|
Runnable action); |
555 |
|
|
|
556 |
|
|
/** |
557 |
|
|
* Returns a new CompletionStage that, when either this or the |
558 |
|
|
* other given stage complete normally, executes the given action |
559 |
jsr166 |
1.11 |
* using the supplied executor. |
560 |
dl |
1.1 |
* |
561 |
|
|
* See the {@link CompletionStage} documentation for rules |
562 |
|
|
* covering exceptional completion. |
563 |
|
|
* |
564 |
|
|
* @param other the other CompletionStage |
565 |
|
|
* @param action the action to perform before completing the |
566 |
|
|
* returned CompletionStage |
567 |
|
|
* @param executor the executor to use for asynchronous execution |
568 |
|
|
* @return the new CompletionStage |
569 |
|
|
*/ |
570 |
|
|
public CompletionStage<Void> runAfterEitherAsync |
571 |
|
|
(CompletionStage<?> other, |
572 |
|
|
Runnable action, |
573 |
|
|
Executor executor); |
574 |
|
|
|
575 |
|
|
/** |
576 |
jsr166 |
1.23 |
* Returns a new CompletionStage that is completed with the same |
577 |
|
|
* value as the CompletionStage returned by the given function. |
578 |
|
|
* |
579 |
|
|
* <p>When this stage completes normally, the given function is |
580 |
|
|
* invoked with this stage's result as the argument, returning |
581 |
|
|
* another CompletionStage. When that stage completes normally, |
582 |
|
|
* the CompletionStage returned by this method is completed with |
583 |
|
|
* the same value. |
584 |
|
|
* |
585 |
dl |
1.24 |
* <p>To ensure progress, the supplied function must arrange |
586 |
|
|
* eventual completion of its result. |
587 |
jsr166 |
1.23 |
* |
588 |
|
|
* <p>This method is analogous to |
589 |
|
|
* {@link java.util.Optional#flatMap Optional.flatMap} and |
590 |
|
|
* {@link java.util.stream.Stream#flatMap Stream.flatMap}. |
591 |
dl |
1.1 |
* |
592 |
jsr166 |
1.23 |
* <p>See the {@link CompletionStage} documentation for rules |
593 |
dl |
1.1 |
* covering exceptional completion. |
594 |
|
|
* |
595 |
jsr166 |
1.23 |
* @param fn the function to use to compute another CompletionStage |
596 |
jsr166 |
1.9 |
* @param <U> the type of the returned CompletionStage's result |
597 |
jsr166 |
1.23 |
* @return the new CompletionStage |
598 |
dl |
1.1 |
*/ |
599 |
|
|
public <U> CompletionStage<U> thenCompose |
600 |
|
|
(Function<? super T, ? extends CompletionStage<U>> fn); |
601 |
|
|
|
602 |
|
|
/** |
603 |
jsr166 |
1.23 |
* Returns a new CompletionStage that is completed with the same |
604 |
|
|
* value as the CompletionStage returned by the given function, |
605 |
|
|
* executed using this stage's default asynchronous execution |
606 |
|
|
* facility. |
607 |
|
|
* |
608 |
|
|
* <p>When this stage completes normally, the given function is |
609 |
|
|
* invoked with this stage's result as the argument, returning |
610 |
|
|
* another CompletionStage. When that stage completes normally, |
611 |
|
|
* the CompletionStage returned by this method is completed with |
612 |
|
|
* the same value. |
613 |
|
|
* |
614 |
dl |
1.24 |
* <p>To ensure progress, the supplied function must arrange |
615 |
|
|
* eventual completion of its result. |
616 |
dl |
1.1 |
* |
617 |
jsr166 |
1.23 |
* <p>See the {@link CompletionStage} documentation for rules |
618 |
dl |
1.1 |
* covering exceptional completion. |
619 |
|
|
* |
620 |
jsr166 |
1.23 |
* @param fn the function to use to compute another CompletionStage |
621 |
jsr166 |
1.9 |
* @param <U> the type of the returned CompletionStage's result |
622 |
jsr166 |
1.23 |
* @return the new CompletionStage |
623 |
dl |
1.1 |
*/ |
624 |
|
|
public <U> CompletionStage<U> thenComposeAsync |
625 |
|
|
(Function<? super T, ? extends CompletionStage<U>> fn); |
626 |
|
|
|
627 |
|
|
/** |
628 |
jsr166 |
1.23 |
* Returns a new CompletionStage that is completed with the same |
629 |
|
|
* value as the CompletionStage returned by the given function, |
630 |
|
|
* executed using the supplied Executor. |
631 |
|
|
* |
632 |
|
|
* <p>When this stage completes normally, the given function is |
633 |
|
|
* invoked with this stage's result as the argument, returning |
634 |
|
|
* another CompletionStage. When that stage completes normally, |
635 |
|
|
* the CompletionStage returned by this method is completed with |
636 |
|
|
* the same value. |
637 |
|
|
* |
638 |
dl |
1.24 |
* <p>To ensure progress, the supplied function must arrange |
639 |
|
|
* eventual completion of its result. |
640 |
dl |
1.1 |
* |
641 |
jsr166 |
1.23 |
* <p>See the {@link CompletionStage} documentation for rules |
642 |
dl |
1.1 |
* covering exceptional completion. |
643 |
|
|
* |
644 |
jsr166 |
1.23 |
* @param fn the function to use to compute another CompletionStage |
645 |
dl |
1.1 |
* @param executor the executor to use for asynchronous execution |
646 |
jsr166 |
1.9 |
* @param <U> the type of the returned CompletionStage's result |
647 |
jsr166 |
1.23 |
* @return the new CompletionStage |
648 |
dl |
1.1 |
*/ |
649 |
|
|
public <U> CompletionStage<U> thenComposeAsync |
650 |
|
|
(Function<? super T, ? extends CompletionStage<U>> fn, |
651 |
|
|
Executor executor); |
652 |
|
|
|
653 |
|
|
/** |
654 |
|
|
* Returns a new CompletionStage that, when this stage completes |
655 |
|
|
* exceptionally, is executed with this stage's exception as the |
656 |
|
|
* argument to the supplied function. Otherwise, if this stage |
657 |
|
|
* completes normally, then the returned stage also completes |
658 |
|
|
* normally with the same value. |
659 |
|
|
* |
660 |
|
|
* @param fn the function to use to compute the value of the |
661 |
|
|
* returned CompletionStage if this CompletionStage completed |
662 |
|
|
* exceptionally |
663 |
|
|
* @return the new CompletionStage |
664 |
|
|
*/ |
665 |
|
|
public CompletionStage<T> exceptionally |
666 |
|
|
(Function<Throwable, ? extends T> fn); |
667 |
|
|
|
668 |
|
|
/** |
669 |
jsr166 |
1.14 |
* Returns a new CompletionStage with the same result or exception as |
670 |
|
|
* this stage, that executes the given action when this stage completes. |
671 |
|
|
* |
672 |
dl |
1.16 |
* <p>When this stage is complete, the given action is invoked |
673 |
|
|
* with the result (or {@code null} if none) and the exception (or |
674 |
|
|
* {@code null} if none) of this stage as arguments. The returned |
675 |
jsr166 |
1.27 |
* stage is completed when the action returns. |
676 |
|
|
* |
677 |
jsr166 |
1.28 |
* <p>Unlike method {@link #handle}, this method is not designed |
678 |
jsr166 |
1.27 |
* to translate completion outcomes, so the supplied action should |
679 |
|
|
* not throw an exception. However, if it does, the following |
680 |
|
|
* rules apply: if this stage completed normally but the supplied |
681 |
|
|
* action throws an exception, then the returned stage completes |
682 |
|
|
* exceptionally with the supplied action's exception. Or, if this |
683 |
|
|
* stage completed exceptionally and the supplied action throws an |
684 |
|
|
* exception, then the returned stage completes exceptionally with |
685 |
|
|
* this stage's exception. |
686 |
dl |
1.1 |
* |
687 |
|
|
* @param action the action to perform |
688 |
jsr166 |
1.7 |
* @return the new CompletionStage |
689 |
dl |
1.1 |
*/ |
690 |
|
|
public CompletionStage<T> whenComplete |
691 |
|
|
(BiConsumer<? super T, ? super Throwable> action); |
692 |
|
|
|
693 |
|
|
/** |
694 |
jsr166 |
1.14 |
* Returns a new CompletionStage with the same result or exception as |
695 |
|
|
* this stage, that executes the given action using this stage's |
696 |
|
|
* default asynchronous execution facility when this stage completes. |
697 |
|
|
* |
698 |
|
|
* <p>When this stage is complete, the given action is invoked with the |
699 |
|
|
* result (or {@code null} if none) and the exception (or {@code null} |
700 |
|
|
* if none) of this stage as arguments. The returned stage is completed |
701 |
jsr166 |
1.27 |
* when the action returns. |
702 |
|
|
* |
703 |
jsr166 |
1.28 |
* <p>Unlike method {@link #handle}, this method is not designed |
704 |
jsr166 |
1.27 |
* to translate completion outcomes, so the supplied action should |
705 |
|
|
* not throw an exception. However, if it does, the following |
706 |
|
|
* rules apply: If this stage completed normally but the supplied |
707 |
|
|
* action throws an exception, then the returned stage completes |
708 |
|
|
* exceptionally with the supplied action's exception. Or, if this |
709 |
|
|
* stage completed exceptionally and the supplied action throws an |
710 |
|
|
* exception, then the returned stage completes exceptionally with |
711 |
|
|
* this stage's exception. |
712 |
dl |
1.1 |
* |
713 |
|
|
* @param action the action to perform |
714 |
jsr166 |
1.7 |
* @return the new CompletionStage |
715 |
dl |
1.1 |
*/ |
716 |
|
|
public CompletionStage<T> whenCompleteAsync |
717 |
|
|
(BiConsumer<? super T, ? super Throwable> action); |
718 |
|
|
|
719 |
|
|
/** |
720 |
jsr166 |
1.14 |
* Returns a new CompletionStage with the same result or exception as |
721 |
|
|
* this stage, that executes the given action using the supplied |
722 |
|
|
* Executor when this stage completes. |
723 |
|
|
* |
724 |
|
|
* <p>When this stage is complete, the given action is invoked with the |
725 |
|
|
* result (or {@code null} if none) and the exception (or {@code null} |
726 |
|
|
* if none) of this stage as arguments. The returned stage is completed |
727 |
jsr166 |
1.27 |
* when the action returns. |
728 |
|
|
* |
729 |
jsr166 |
1.28 |
* <p>Unlike method {@link #handle}, this method is not designed |
730 |
jsr166 |
1.27 |
* to translate completion outcomes, so the supplied action should |
731 |
|
|
* not throw an exception. However, if it does, the following |
732 |
|
|
* rules apply: If this stage completed normally but the supplied |
733 |
|
|
* action throws an exception, then the returned stage completes |
734 |
|
|
* exceptionally with the supplied action's exception. Or, if this |
735 |
|
|
* stage completed exceptionally and the supplied action throws an |
736 |
|
|
* exception, then the returned stage completes exceptionally with |
737 |
|
|
* this stage's exception. |
738 |
dl |
1.1 |
* |
739 |
|
|
* @param action the action to perform |
740 |
jsr166 |
1.7 |
* @param executor the executor to use for asynchronous execution |
741 |
|
|
* @return the new CompletionStage |
742 |
dl |
1.1 |
*/ |
743 |
|
|
public CompletionStage<T> whenCompleteAsync |
744 |
|
|
(BiConsumer<? super T, ? super Throwable> action, |
745 |
|
|
Executor executor); |
746 |
|
|
|
747 |
|
|
/** |
748 |
|
|
* Returns a new CompletionStage that, when this stage completes |
749 |
|
|
* either normally or exceptionally, is executed with this stage's |
750 |
|
|
* result and exception as arguments to the supplied function. |
751 |
jsr166 |
1.14 |
* |
752 |
|
|
* <p>When this stage is complete, the given function is invoked |
753 |
|
|
* with the result (or {@code null} if none) and the exception (or |
754 |
|
|
* {@code null} if none) of this stage as arguments, and the |
755 |
|
|
* function's result is used to complete the returned stage. |
756 |
dl |
1.1 |
* |
757 |
|
|
* @param fn the function to use to compute the value of the |
758 |
|
|
* returned CompletionStage |
759 |
jsr166 |
1.9 |
* @param <U> the function's return type |
760 |
dl |
1.1 |
* @return the new CompletionStage |
761 |
|
|
*/ |
762 |
|
|
public <U> CompletionStage<U> handle |
763 |
|
|
(BiFunction<? super T, Throwable, ? extends U> fn); |
764 |
|
|
|
765 |
|
|
/** |
766 |
|
|
* Returns a new CompletionStage that, when this stage completes |
767 |
|
|
* either normally or exceptionally, is executed using this stage's |
768 |
|
|
* default asynchronous execution facility, with this stage's |
769 |
|
|
* result and exception as arguments to the supplied function. |
770 |
jsr166 |
1.14 |
* |
771 |
|
|
* <p>When this stage is complete, the given function is invoked |
772 |
|
|
* with the result (or {@code null} if none) and the exception (or |
773 |
|
|
* {@code null} if none) of this stage as arguments, and the |
774 |
|
|
* function's result is used to complete the returned stage. |
775 |
dl |
1.1 |
* |
776 |
|
|
* @param fn the function to use to compute the value of the |
777 |
|
|
* returned CompletionStage |
778 |
jsr166 |
1.9 |
* @param <U> the function's return type |
779 |
dl |
1.1 |
* @return the new CompletionStage |
780 |
|
|
*/ |
781 |
|
|
public <U> CompletionStage<U> handleAsync |
782 |
|
|
(BiFunction<? super T, Throwable, ? extends U> fn); |
783 |
|
|
|
784 |
|
|
/** |
785 |
|
|
* Returns a new CompletionStage that, when this stage completes |
786 |
|
|
* either normally or exceptionally, is executed using the |
787 |
|
|
* supplied executor, with this stage's result and exception as |
788 |
jsr166 |
1.14 |
* arguments to the supplied function. |
789 |
|
|
* |
790 |
|
|
* <p>When this stage is complete, the given function is invoked |
791 |
|
|
* with the result (or {@code null} if none) and the exception (or |
792 |
|
|
* {@code null} if none) of this stage as arguments, and the |
793 |
|
|
* function's result is used to complete the returned stage. |
794 |
dl |
1.1 |
* |
795 |
|
|
* @param fn the function to use to compute the value of the |
796 |
|
|
* returned CompletionStage |
797 |
jsr166 |
1.7 |
* @param executor the executor to use for asynchronous execution |
798 |
jsr166 |
1.9 |
* @param <U> the function's return type |
799 |
dl |
1.1 |
* @return the new CompletionStage |
800 |
|
|
*/ |
801 |
|
|
public <U> CompletionStage<U> handleAsync |
802 |
|
|
(BiFunction<? super T, Throwable, ? extends U> fn, |
803 |
|
|
Executor executor); |
804 |
|
|
|
805 |
|
|
/** |
806 |
|
|
* Returns a {@link CompletableFuture} maintaining the same |
807 |
|
|
* completion properties as this stage. If this stage is already a |
808 |
|
|
* CompletableFuture, this method may return this stage itself. |
809 |
|
|
* Otherwise, invocation of this method may be equivalent in |
810 |
|
|
* effect to {@code thenApply(x -> x)}, but returning an instance |
811 |
|
|
* of type {@code CompletableFuture}. A CompletionStage |
812 |
|
|
* implementation that does not choose to interoperate with others |
813 |
jsr166 |
1.4 |
* may throw {@code UnsupportedOperationException}. |
814 |
dl |
1.1 |
* |
815 |
|
|
* @return the CompletableFuture |
816 |
dl |
1.10 |
* @throws UnsupportedOperationException if this implementation |
817 |
|
|
* does not interoperate with CompletableFuture |
818 |
dl |
1.1 |
*/ |
819 |
|
|
public CompletableFuture<T> toCompletableFuture(); |
820 |
|
|
|
821 |
|
|
} |