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