1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3 *
4 * This code is free software; you can redistribute it and/or modify it
5 * under the terms of the GNU General Public License version 2 only, as
6 * published by the Free Software Foundation. Oracle designates this
7 * particular file as subject to the "Classpath" exception as provided
8 * by Oracle in the LICENSE file that accompanied this code.
9 *
10 * This code is distributed in the hope that it will be useful, but WITHOUT
11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * version 2 for more details (a copy is included in the LICENSE file that
14 * accompanied this code).
15 *
16 * You should have received a copy of the GNU General Public License version
17 * 2 along with this work; if not, write to the Free Software Foundation,
18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
19 *
20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
21 * or visit www.oracle.com if you need additional information or have any
22 * questions.
23 */
24
25 /*
26 * This file is available under and governed by the GNU General Public
27 * License version 2 only, as published by the Free Software Foundation.
28 * However, the following notice accompanied the original version of this
29 * file:
30 *
31 * Written by Doug Lea with assistance from members of JCP JSR-166
32 * Expert Group and released to the public domain, as explained at
33 * http://creativecommons.org/publicdomain/zero/1.0/
34 */
35
36 package java.util.concurrent;
37
38 import java.util.function.BiConsumer;
39 import java.util.function.BiFunction;
40 import java.util.function.Consumer;
41 import java.util.function.Function;
42
43 /**
44 * A stage of a possibly asynchronous computation, that performs an
45 * action or computes a value when another CompletionStage completes.
46 * A stage completes upon termination of its computation, but this may
47 * in turn trigger other dependent stages. The functionality defined
48 * in this interface takes only a few basic forms, which expand out to
49 * a larger set of methods to capture a range of usage styles:
50 *
51 * <ul>
52 *
53 * <li>The computation performed by a stage may be expressed as a
54 * Function, Consumer, or Runnable (using methods with names including
55 * <em>apply</em>, <em>accept</em>, or <em>run</em>, respectively)
56 * depending on whether it requires arguments and/or produces results.
57 * For example:
58 * <pre> {@code
59 * stage.thenApply(x -> square(x))
60 * .thenAccept(x -> System.out.print(x))
61 * .thenRun(() -> System.out.println());}</pre>
62 *
63 * An additional form (<em>compose</em>) allows the construction of
64 * computation pipelines from functions returning completion stages.
65 *
66 * <p>Any argument to a stage's computation is the outcome of a
67 * triggering stage's computation.
68 *
69 * <li>One stage's execution may be triggered by completion of a
70 * single stage, or both of two stages, or either of two stages.
71 * Dependencies on a single stage are arranged using methods with
72 * prefix <em>then</em>. Those triggered by completion of
73 * <em>both</em> of two stages may <em>combine</em> their results or
74 * effects, using correspondingly named methods. Those triggered by
75 * <em>either</em> of two stages make no guarantees about which of the
76 * results or effects are used for the dependent stage's computation.
77 *
78 * <li>Dependencies among stages control the triggering of
79 * computations, but do not otherwise guarantee any particular
80 * ordering. Additionally, execution of a new stage's computations may
81 * be arranged in any of three ways: default execution, default
82 * asynchronous execution (using methods with suffix <em>async</em>
83 * that employ the stage's default asynchronous execution facility),
84 * or custom (via a supplied {@link Executor}). The execution
85 * properties of default and async modes are specified by
86 * CompletionStage implementations, not this interface. Methods with
87 * explicit Executor arguments may have arbitrary execution
88 * properties, and might not even support concurrent execution, but
89 * are arranged for processing in a way that accommodates asynchrony.
90 *
91 * <li>Two method forms ({@link #handle handle} and {@link
92 * #whenComplete whenComplete}) support unconditional computation
93 * whether the triggering stage completed normally or exceptionally.
94 * Method {@link #exceptionally exceptionally} supports computation
95 * only when the triggering stage completes exceptionally, computing a
96 * replacement result, similarly to the java {@code catch} keyword.
97 * In all other cases, if a stage's computation terminates abruptly
98 * with an (unchecked) exception or error, then all dependent stages
99 * requiring its completion complete exceptionally as well, with a
100 * {@link CompletionException} holding the exception as its cause. If
101 * a stage is dependent on <em>both</em> of two stages, and both
102 * complete exceptionally, then the CompletionException may correspond
103 * to either one of these exceptions. If a stage is dependent on
104 * <em>either</em> of two others, and only one of them completes
105 * exceptionally, no guarantees are made about whether the dependent
106 * stage completes normally or exceptionally. In the case of method
107 * {@code whenComplete}, when the supplied action itself encounters an
108 * exception, then the stage completes exceptionally with this
109 * exception unless the source stage also completed exceptionally, in
110 * which case the exceptional completion from the source stage is
111 * given preference and propagated to the dependent stage.
112 *
113 * </ul>
114 *
115 * <p>All methods adhere to the above triggering, execution, and
116 * exceptional completion specifications (which are not repeated in
117 * individual method specifications). Additionally, while arguments
118 * used to pass a completion result (that is, for parameters of type
119 * {@code T}) for methods accepting them may be null, passing a null
120 * value for any other parameter will result in a {@link
121 * NullPointerException} being thrown.
122 *
123 * <p>Method form {@link #handle handle} is the most general way of
124 * creating a continuation stage, unconditionally performing a
125 * computation that is given both the result and exception (if any) of
126 * the triggering CompletionStage, and computing an arbitrary result.
127 * Method {@link #whenComplete whenComplete} is similar, but preserves
128 * the result of the triggering stage instead of computing a new one.
129 * Because a stage's normal result may be {@code null}, both methods
130 * should have a computation structured thus:
131 *
132 * <pre>{@code (result, exception) -> {
133 * if (exception == null) {
134 * // triggering stage completed normally
135 * } else {
136 * // triggering stage completed exceptionally
137 * }
138 * }}</pre>
139 *
140 * <p>This interface does not define methods for initially creating,
141 * forcibly completing normally or exceptionally, probing completion
142 * status or results, or awaiting completion of a stage.
143 * Implementations of CompletionStage may provide means of achieving
144 * such effects, as appropriate. Method {@link #toCompletableFuture}
145 * enables interoperability among different implementations of this
146 * interface by providing a common conversion type.
147 *
148 * @author Doug Lea
149 * @since 1.8
150 */
151 public interface CompletionStage<T> {
152
153 /**
154 * Returns a new CompletionStage that, when this stage completes
155 * normally, is executed with this stage's result as the argument
156 * to the supplied function.
157 *
158 * <p>This method is analogous to
159 * {@link java.util.Optional#map Optional.map} and
160 * {@link java.util.stream.Stream#map Stream.map}.
161 *
162 * <p>See the {@link CompletionStage} documentation for rules
163 * covering exceptional completion.
164 *
165 * @param fn the function to use to compute the value of the
166 * returned CompletionStage
167 * @param <U> the function's return type
168 * @return the new CompletionStage
169 */
170 public <U> CompletionStage<U> thenApply(Function<? super T,? extends U> fn);
171
172 /**
173 * Returns a new CompletionStage that, when this stage completes
174 * normally, is executed using this stage's default asynchronous
175 * execution facility, with this stage's result as the argument to
176 * the supplied function.
177 *
178 * See the {@link CompletionStage} documentation for rules
179 * covering exceptional completion.
180 *
181 * @param fn the function to use to compute the value of the
182 * returned CompletionStage
183 * @param <U> the function's return type
184 * @return the new CompletionStage
185 */
186 public <U> CompletionStage<U> thenApplyAsync
187 (Function<? super T,? extends U> fn);
188
189 /**
190 * Returns a new CompletionStage that, when this stage completes
191 * normally, is executed using the supplied Executor, with this
192 * stage's result as the argument to the supplied function.
193 *
194 * See the {@link CompletionStage} documentation for rules
195 * covering exceptional completion.
196 *
197 * @param fn the function to use to compute the value of the
198 * returned CompletionStage
199 * @param executor the executor to use for asynchronous execution
200 * @param <U> the function's return type
201 * @return the new CompletionStage
202 */
203 public <U> CompletionStage<U> thenApplyAsync
204 (Function<? super T,? extends U> fn,
205 Executor executor);
206
207 /**
208 * Returns a new CompletionStage that, when this stage completes
209 * normally, is executed with this stage's result as the argument
210 * to the supplied action.
211 *
212 * See the {@link CompletionStage} documentation for rules
213 * covering exceptional completion.
214 *
215 * @param action the action to perform before completing the
216 * returned CompletionStage
217 * @return the new CompletionStage
218 */
219 public CompletionStage<Void> thenAccept(Consumer<? super T> action);
220
221 /**
222 * Returns a new CompletionStage that, when this stage completes
223 * normally, is executed using this stage's default asynchronous
224 * execution facility, with this stage's result as the argument to
225 * the supplied action.
226 *
227 * See the {@link CompletionStage} documentation for rules
228 * covering exceptional completion.
229 *
230 * @param action the action to perform before completing the
231 * returned CompletionStage
232 * @return the new CompletionStage
233 */
234 public CompletionStage<Void> thenAcceptAsync(Consumer<? super T> action);
235
236 /**
237 * Returns a new CompletionStage that, when this stage completes
238 * normally, is executed using the supplied Executor, with this
239 * stage's result as the argument to the supplied action.
240 *
241 * See the {@link CompletionStage} documentation for rules
242 * covering exceptional completion.
243 *
244 * @param action the action to perform before completing the
245 * returned CompletionStage
246 * @param executor the executor to use for asynchronous execution
247 * @return the new CompletionStage
248 */
249 public CompletionStage<Void> thenAcceptAsync(Consumer<? super T> action,
250 Executor executor);
251 /**
252 * Returns a new CompletionStage that, when this stage completes
253 * normally, executes the given action.
254 *
255 * See the {@link CompletionStage} documentation for rules
256 * covering exceptional completion.
257 *
258 * @param action the action to perform before completing the
259 * returned CompletionStage
260 * @return the new CompletionStage
261 */
262 public CompletionStage<Void> thenRun(Runnable action);
263
264 /**
265 * Returns a new CompletionStage that, when this stage completes
266 * normally, executes the given action using this stage's default
267 * asynchronous execution facility.
268 *
269 * See the {@link CompletionStage} documentation for rules
270 * covering exceptional completion.
271 *
272 * @param action the action to perform before completing the
273 * returned CompletionStage
274 * @return the new CompletionStage
275 */
276 public CompletionStage<Void> thenRunAsync(Runnable action);
277
278 /**
279 * Returns a new CompletionStage that, when this stage completes
280 * normally, executes the given action using the supplied Executor.
281 *
282 * See the {@link CompletionStage} documentation for rules
283 * covering exceptional completion.
284 *
285 * @param action the action to perform before completing the
286 * returned CompletionStage
287 * @param executor the executor to use for asynchronous execution
288 * @return the new CompletionStage
289 */
290 public CompletionStage<Void> thenRunAsync(Runnable action,
291 Executor executor);
292
293 /**
294 * Returns a new CompletionStage that, when this and the other
295 * given stage both complete normally, is executed with the two
296 * results as arguments to the supplied function.
297 *
298 * See the {@link CompletionStage} documentation for rules
299 * covering exceptional completion.
300 *
301 * @param other the other CompletionStage
302 * @param fn the function to use to compute the value of the
303 * returned CompletionStage
304 * @param <U> the type of the other CompletionStage's result
305 * @param <V> the function's return type
306 * @return the new CompletionStage
307 */
308 public <U,V> CompletionStage<V> thenCombine
309 (CompletionStage<? extends U> other,
310 BiFunction<? super T,? super U,? extends V> fn);
311
312 /**
313 * Returns a new CompletionStage that, when this and the other
314 * given stage both complete normally, is executed using this
315 * stage's default asynchronous execution facility, with the two
316 * results as arguments to the supplied function.
317 *
318 * See the {@link CompletionStage} documentation for rules
319 * covering exceptional completion.
320 *
321 * @param other the other CompletionStage
322 * @param fn the function to use to compute the value of the
323 * returned CompletionStage
324 * @param <U> the type of the other CompletionStage's result
325 * @param <V> the function's return type
326 * @return the new CompletionStage
327 */
328 public <U,V> CompletionStage<V> thenCombineAsync
329 (CompletionStage<? extends U> other,
330 BiFunction<? super T,? super U,? extends V> fn);
331
332 /**
333 * Returns a new CompletionStage that, when this and the other
334 * given stage both complete normally, is executed using the
335 * supplied executor, with the two results as arguments to the
336 * supplied function.
337 *
338 * See the {@link CompletionStage} documentation for rules
339 * covering exceptional completion.
340 *
341 * @param other the other CompletionStage
342 * @param fn the function to use to compute the value of the
343 * returned CompletionStage
344 * @param executor the executor to use for asynchronous execution
345 * @param <U> the type of the other CompletionStage's result
346 * @param <V> the function's return type
347 * @return the new CompletionStage
348 */
349 public <U,V> CompletionStage<V> thenCombineAsync
350 (CompletionStage<? extends U> other,
351 BiFunction<? super T,? super U,? extends V> fn,
352 Executor executor);
353
354 /**
355 * Returns a new CompletionStage that, when this and the other
356 * given stage both complete normally, is executed with the two
357 * results as arguments to the supplied action.
358 *
359 * See the {@link CompletionStage} documentation for rules
360 * covering exceptional completion.
361 *
362 * @param other the other CompletionStage
363 * @param action the action to perform before completing the
364 * returned CompletionStage
365 * @param <U> the type of the other CompletionStage's result
366 * @return the new CompletionStage
367 */
368 public <U> CompletionStage<Void> thenAcceptBoth
369 (CompletionStage<? extends U> other,
370 BiConsumer<? super T, ? super U> action);
371
372 /**
373 * Returns a new CompletionStage that, when this and the other
374 * given stage both complete normally, is executed using this
375 * stage's default asynchronous execution facility, with the two
376 * results as arguments to the supplied action.
377 *
378 * See the {@link CompletionStage} documentation for rules
379 * covering exceptional completion.
380 *
381 * @param other the other CompletionStage
382 * @param action the action to perform before completing the
383 * returned CompletionStage
384 * @param <U> the type of the other CompletionStage's result
385 * @return the new CompletionStage
386 */
387 public <U> CompletionStage<Void> thenAcceptBothAsync
388 (CompletionStage<? extends U> other,
389 BiConsumer<? super T, ? super U> action);
390
391 /**
392 * Returns a new CompletionStage that, when this and the other
393 * given stage both complete normally, is executed using the
394 * supplied executor, with the two results as arguments to the
395 * supplied action.
396 *
397 * See the {@link CompletionStage} documentation for rules
398 * covering exceptional completion.
399 *
400 * @param other the other CompletionStage
401 * @param action the action to perform before completing the
402 * returned CompletionStage
403 * @param executor the executor to use for asynchronous execution
404 * @param <U> the type of the other CompletionStage's result
405 * @return the new CompletionStage
406 */
407 public <U> CompletionStage<Void> thenAcceptBothAsync
408 (CompletionStage<? extends U> other,
409 BiConsumer<? super T, ? super U> action,
410 Executor executor);
411
412 /**
413 * Returns a new CompletionStage that, when this and the other
414 * given stage both complete normally, executes the given action.
415 *
416 * See the {@link CompletionStage} documentation for rules
417 * covering exceptional completion.
418 *
419 * @param other the other CompletionStage
420 * @param action the action to perform before completing the
421 * returned CompletionStage
422 * @return the new CompletionStage
423 */
424 public CompletionStage<Void> runAfterBoth(CompletionStage<?> other,
425 Runnable action);
426 /**
427 * Returns a new CompletionStage that, when this and the other
428 * given stage both complete normally, executes the given action
429 * using this stage's default asynchronous execution facility.
430 *
431 * See the {@link CompletionStage} documentation for rules
432 * covering exceptional completion.
433 *
434 * @param other the other CompletionStage
435 * @param action the action to perform before completing the
436 * returned CompletionStage
437 * @return the new CompletionStage
438 */
439 public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other,
440 Runnable action);
441
442 /**
443 * Returns a new CompletionStage that, when this and the other
444 * given stage both complete normally, executes the given action
445 * using the supplied executor.
446 *
447 * See the {@link CompletionStage} documentation for rules
448 * covering exceptional completion.
449 *
450 * @param other the other CompletionStage
451 * @param action the action to perform before completing the
452 * returned CompletionStage
453 * @param executor the executor to use for asynchronous execution
454 * @return the new CompletionStage
455 */
456 public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other,
457 Runnable action,
458 Executor executor);
459 /**
460 * Returns a new CompletionStage that, when either this or the
461 * other given stage complete normally, is executed with the
462 * corresponding result as argument to the supplied function.
463 *
464 * See the {@link CompletionStage} documentation for rules
465 * covering exceptional completion.
466 *
467 * @param other the other CompletionStage
468 * @param fn the function to use to compute the value of the
469 * returned CompletionStage
470 * @param <U> the function's return type
471 * @return the new CompletionStage
472 */
473 public <U> CompletionStage<U> applyToEither
474 (CompletionStage<? extends T> other,
475 Function<? super T, U> fn);
476
477 /**
478 * Returns a new CompletionStage that, when either this or the
479 * other given stage complete normally, is executed using this
480 * stage's default asynchronous execution facility, with the
481 * corresponding result as argument to the supplied function.
482 *
483 * See the {@link CompletionStage} documentation for rules
484 * covering exceptional completion.
485 *
486 * @param other the other CompletionStage
487 * @param fn the function to use to compute the value of the
488 * returned CompletionStage
489 * @param <U> the function's return type
490 * @return the new CompletionStage
491 */
492 public <U> CompletionStage<U> applyToEitherAsync
493 (CompletionStage<? extends T> other,
494 Function<? super T, U> fn);
495
496 /**
497 * Returns a new CompletionStage that, when either this or the
498 * other given stage complete normally, is executed using the
499 * supplied executor, with the corresponding result as argument to
500 * the supplied function.
501 *
502 * See the {@link CompletionStage} documentation for rules
503 * covering exceptional completion.
504 *
505 * @param other the other CompletionStage
506 * @param fn the function to use to compute the value of the
507 * returned CompletionStage
508 * @param executor the executor to use for asynchronous execution
509 * @param <U> the function's return type
510 * @return the new CompletionStage
511 */
512 public <U> CompletionStage<U> applyToEitherAsync
513 (CompletionStage<? extends T> other,
514 Function<? super T, U> fn,
515 Executor executor);
516
517 /**
518 * Returns a new CompletionStage that, when either this or the
519 * other given stage complete normally, is executed with the
520 * corresponding result as argument to the supplied action.
521 *
522 * See the {@link CompletionStage} documentation for rules
523 * covering exceptional completion.
524 *
525 * @param other the other CompletionStage
526 * @param action the action to perform before completing the
527 * returned CompletionStage
528 * @return the new CompletionStage
529 */
530 public CompletionStage<Void> acceptEither
531 (CompletionStage<? extends T> other,
532 Consumer<? super T> action);
533
534 /**
535 * Returns a new CompletionStage that, when either this or the
536 * other given stage complete normally, is executed using this
537 * stage's default asynchronous execution facility, with the
538 * corresponding result as argument to the supplied action.
539 *
540 * See the {@link CompletionStage} documentation for rules
541 * covering exceptional completion.
542 *
543 * @param other the other CompletionStage
544 * @param action the action to perform before completing the
545 * returned CompletionStage
546 * @return the new CompletionStage
547 */
548 public CompletionStage<Void> acceptEitherAsync
549 (CompletionStage<? extends T> other,
550 Consumer<? super T> action);
551
552 /**
553 * Returns a new CompletionStage that, when either this or the
554 * other given stage complete normally, is executed using the
555 * supplied executor, with the corresponding result as argument to
556 * the supplied action.
557 *
558 * See the {@link CompletionStage} documentation for rules
559 * covering exceptional completion.
560 *
561 * @param other the other CompletionStage
562 * @param action the action to perform before completing the
563 * returned CompletionStage
564 * @param executor the executor to use for asynchronous execution
565 * @return the new CompletionStage
566 */
567 public CompletionStage<Void> acceptEitherAsync
568 (CompletionStage<? extends T> other,
569 Consumer<? super T> action,
570 Executor executor);
571
572 /**
573 * Returns a new CompletionStage that, when either this or the
574 * other given stage complete normally, executes the given action.
575 *
576 * See the {@link CompletionStage} documentation for rules
577 * covering exceptional completion.
578 *
579 * @param other the other CompletionStage
580 * @param action the action to perform before completing the
581 * returned CompletionStage
582 * @return the new CompletionStage
583 */
584 public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
585 Runnable action);
586
587 /**
588 * Returns a new CompletionStage that, when either this or the
589 * other given stage complete normally, executes the given action
590 * using this stage's default asynchronous execution facility.
591 *
592 * See the {@link CompletionStage} documentation for rules
593 * covering exceptional completion.
594 *
595 * @param other the other CompletionStage
596 * @param action the action to perform before completing the
597 * returned CompletionStage
598 * @return the new CompletionStage
599 */
600 public CompletionStage<Void> runAfterEitherAsync
601 (CompletionStage<?> other,
602 Runnable action);
603
604 /**
605 * Returns a new CompletionStage that, when either this or the
606 * other given stage complete normally, executes the given action
607 * using the supplied executor.
608 *
609 * See the {@link CompletionStage} documentation for rules
610 * covering exceptional completion.
611 *
612 * @param other the other CompletionStage
613 * @param action the action to perform before completing the
614 * returned CompletionStage
615 * @param executor the executor to use for asynchronous execution
616 * @return the new CompletionStage
617 */
618 public CompletionStage<Void> runAfterEitherAsync
619 (CompletionStage<?> other,
620 Runnable action,
621 Executor executor);
622
623 /**
624 * Returns a new CompletionStage that is completed with the same
625 * value as the CompletionStage returned by the given function.
626 *
627 * <p>When this stage completes normally, the given function is
628 * invoked with this stage's result as the argument, returning
629 * another CompletionStage. When that stage completes normally,
630 * the CompletionStage returned by this method is completed with
631 * the same value.
632 *
633 * <p>To ensure progress, the supplied function must arrange
634 * eventual completion of its result.
635 *
636 * <p>This method is analogous to
637 * {@link java.util.Optional#flatMap Optional.flatMap} and
638 * {@link java.util.stream.Stream#flatMap Stream.flatMap}.
639 *
640 * <p>See the {@link CompletionStage} documentation for rules
641 * covering exceptional completion.
642 *
643 * @param fn the function to use to compute another CompletionStage
644 * @param <U> the type of the returned CompletionStage's result
645 * @return the new CompletionStage
646 */
647 public <U> CompletionStage<U> thenCompose
648 (Function<? super T, ? extends CompletionStage<U>> fn);
649
650 /**
651 * Returns a new CompletionStage that is completed with the same
652 * value as the CompletionStage returned by the given function,
653 * executed using this stage's default asynchronous execution
654 * facility.
655 *
656 * <p>When this stage completes normally, the given function is
657 * invoked with this stage's result as the argument, returning
658 * another CompletionStage. When that stage completes normally,
659 * the CompletionStage returned by this method is completed with
660 * the same value.
661 *
662 * <p>To ensure progress, the supplied function must arrange
663 * eventual completion of its result.
664 *
665 * <p>See the {@link CompletionStage} documentation for rules
666 * covering exceptional completion.
667 *
668 * @param fn the function to use to compute another CompletionStage
669 * @param <U> the type of the returned CompletionStage's result
670 * @return the new CompletionStage
671 */
672 public <U> CompletionStage<U> thenComposeAsync
673 (Function<? super T, ? extends CompletionStage<U>> fn);
674
675 /**
676 * Returns a new CompletionStage that is completed with the same
677 * value as the CompletionStage returned by the given function,
678 * executed using the supplied Executor.
679 *
680 * <p>When this stage completes normally, the given function is
681 * invoked with this stage's result as the argument, returning
682 * another CompletionStage. When that stage completes normally,
683 * the CompletionStage returned by this method is completed with
684 * the same value.
685 *
686 * <p>To ensure progress, the supplied function must arrange
687 * eventual completion of its result.
688 *
689 * <p>See the {@link CompletionStage} documentation for rules
690 * covering exceptional completion.
691 *
692 * @param fn the function to use to compute another CompletionStage
693 * @param executor the executor to use for asynchronous execution
694 * @param <U> the type of the returned CompletionStage's result
695 * @return the new CompletionStage
696 */
697 public <U> CompletionStage<U> thenComposeAsync
698 (Function<? super T, ? extends CompletionStage<U>> fn,
699 Executor executor);
700
701 /**
702 * Returns a new CompletionStage that, when this stage completes
703 * either normally or exceptionally, is executed with this stage's
704 * result and exception as arguments to the supplied function.
705 *
706 * <p>When this stage is complete, the given function is invoked
707 * with the result (or {@code null} if none) and the exception (or
708 * {@code null} if none) of this stage as arguments, and the
709 * function's result is used to complete the returned stage.
710 *
711 * @param fn the function to use to compute the value of the
712 * returned CompletionStage
713 * @param <U> the function's return type
714 * @return the new CompletionStage
715 */
716 public <U> CompletionStage<U> handle
717 (BiFunction<? super T, Throwable, ? extends U> fn);
718
719 /**
720 * Returns a new CompletionStage that, when this stage completes
721 * either normally or exceptionally, is executed using this stage's
722 * default asynchronous execution facility, with this stage's
723 * result and exception as arguments to the supplied function.
724 *
725 * <p>When this stage is complete, the given function is invoked
726 * with the result (or {@code null} if none) and the exception (or
727 * {@code null} if none) of this stage as arguments, and the
728 * function's result is used to complete the returned stage.
729 *
730 * @param fn the function to use to compute the value of the
731 * returned CompletionStage
732 * @param <U> the function's return type
733 * @return the new CompletionStage
734 */
735 public <U> CompletionStage<U> handleAsync
736 (BiFunction<? super T, Throwable, ? extends U> fn);
737
738 /**
739 * Returns a new CompletionStage that, when this stage completes
740 * either normally or exceptionally, is executed using the
741 * supplied executor, with this stage's result and exception as
742 * arguments to the supplied function.
743 *
744 * <p>When this stage is complete, the given function is invoked
745 * with the result (or {@code null} if none) and the exception (or
746 * {@code null} if none) of this stage as arguments, and the
747 * function's result is used to complete the returned stage.
748 *
749 * @param fn the function to use to compute the value of the
750 * returned CompletionStage
751 * @param executor the executor to use for asynchronous execution
752 * @param <U> the function's return type
753 * @return the new CompletionStage
754 */
755 public <U> CompletionStage<U> handleAsync
756 (BiFunction<? super T, Throwable, ? extends U> fn,
757 Executor executor);
758
759 /**
760 * Returns a new CompletionStage with the same result or exception as
761 * this stage, that executes the given action when this stage completes.
762 *
763 * <p>When this stage is complete, the given action is invoked
764 * with the result (or {@code null} if none) and the exception (or
765 * {@code null} if none) of this stage as arguments. The returned
766 * stage is completed when the action returns.
767 *
768 * <p>Unlike method {@link #handle handle},
769 * this method is not designed to translate completion outcomes,
770 * so the supplied action should not throw an exception. However,
771 * if it does, the following rules apply: if this stage completed
772 * normally but the supplied action throws an exception, then the
773 * returned stage completes exceptionally with the supplied
774 * action's exception. Or, if this stage completed exceptionally
775 * and the supplied action throws an exception, then the returned
776 * stage completes exceptionally with this stage's exception.
777 *
778 * @param action the action to perform
779 * @return the new CompletionStage
780 */
781 public CompletionStage<T> whenComplete
782 (BiConsumer<? super T, ? super Throwable> action);
783
784 /**
785 * Returns a new CompletionStage with the same result or exception as
786 * this stage, that executes the given action using this stage's
787 * default asynchronous execution facility when this stage completes.
788 *
789 * <p>When this stage is complete, the given action is invoked with the
790 * result (or {@code null} if none) and the exception (or {@code null}
791 * if none) of this stage as arguments. The returned stage is completed
792 * when the action returns.
793 *
794 * <p>Unlike method {@link #handleAsync(BiFunction) handleAsync},
795 * this method is not designed to translate completion outcomes,
796 * so the supplied action should not throw an exception. However,
797 * if it does, the following rules apply: If this stage completed
798 * normally but the supplied action throws an exception, then the
799 * returned stage completes exceptionally with the supplied
800 * action's exception. Or, if this stage completed exceptionally
801 * and the supplied action throws an exception, then the returned
802 * stage completes exceptionally with this stage's exception.
803 *
804 * @param action the action to perform
805 * @return the new CompletionStage
806 */
807 public CompletionStage<T> whenCompleteAsync
808 (BiConsumer<? super T, ? super Throwable> action);
809
810 /**
811 * Returns a new CompletionStage with the same result or exception as
812 * this stage, that executes the given action using the supplied
813 * Executor when this stage completes.
814 *
815 * <p>When this stage is complete, the given action is invoked with the
816 * result (or {@code null} if none) and the exception (or {@code null}
817 * if none) of this stage as arguments. The returned stage is completed
818 * when the action returns.
819 *
820 * <p>Unlike method {@link #handleAsync(BiFunction,Executor) handleAsync},
821 * this method is not designed to translate completion outcomes,
822 * so the supplied action should not throw an exception. However,
823 * if it does, the following rules apply: If this stage completed
824 * normally but the supplied action throws an exception, then the
825 * returned stage completes exceptionally with the supplied
826 * action's exception. Or, if this stage completed exceptionally
827 * and the supplied action throws an exception, then the returned
828 * stage completes exceptionally with this stage's exception.
829 *
830 * @param action the action to perform
831 * @param executor the executor to use for asynchronous execution
832 * @return the new CompletionStage
833 */
834 public CompletionStage<T> whenCompleteAsync
835 (BiConsumer<? super T, ? super Throwable> action,
836 Executor executor);
837
838 /**
839 * Returns a new CompletionStage that, when this stage completes
840 * exceptionally, is executed with this stage's exception as the
841 * argument to the supplied function. Otherwise, if this stage
842 * completes normally, then the returned stage also completes
843 * normally with the same value.
844 *
845 * @param fn the function to use to compute the value of the
846 * returned CompletionStage if this CompletionStage completed
847 * exceptionally
848 * @return the new CompletionStage
849 */
850 public CompletionStage<T> exceptionally
851 (Function<Throwable, ? extends T> fn);
852
853 /**
854 * Returns a new CompletionStage that, when this stage completes
855 * exceptionally, is executed with this stage's exception as the
856 * argument to the supplied function, using this stage's default
857 * asynchronous execution facility. Otherwise, if this stage
858 * completes normally, then the returned stage also completes
859 * normally with the same value.
860 *
861 * @implSpec The default implementation invokes {@link #handle},
862 * relaying to {@link #handleAsync} on exception, then {@link
863 * #thenCompose} for result.
864 *
865 * @param fn the function to use to compute the value of the
866 * returned CompletionStage if this CompletionStage completed
867 * exceptionally
868 * @return the new CompletionStage
869 * @since 12
870 */
871 public default CompletionStage<T> exceptionallyAsync
872 (Function<Throwable, ? extends T> fn) {
873 return handle((r, ex) -> (ex == null)
874 ? this
875 : this.<T>handleAsync((r1, ex1) -> fn.apply(ex1)))
876 .thenCompose(Function.identity());
877 }
878
879 /**
880 * Returns a new CompletionStage that, when this stage completes
881 * exceptionally, is executed with this stage's exception as the
882 * argument to the supplied function, using the supplied Executor.
883 * Otherwise, if this stage completes normally, then the returned
884 * stage also completes normally with the same value.
885 *
886 * @implSpec The default implementation invokes {@link #handle},
887 * relaying to {@link #handleAsync} on exception, then {@link
888 * #thenCompose} for result.
889 *
890 * @param fn the function to use to compute the value of the
891 * returned CompletionStage if this CompletionStage completed
892 * exceptionally
893 * @param executor the executor to use for asynchronous execution
894 * @return the new CompletionStage
895 * @since 12
896 */
897 public default CompletionStage<T> exceptionallyAsync
898 (Function<Throwable, ? extends T> fn, Executor executor) {
899 return handle((r, ex) -> (ex == null)
900 ? this
901 : this.<T>handleAsync((r1, ex1) -> fn.apply(ex1), executor))
902 .thenCompose(Function.identity());
903 }
904
905 /**
906 * Returns a new CompletionStage that, when this stage completes
907 * exceptionally, is composed using the results of the supplied
908 * function applied to this stage's exception.
909 *
910 * @implSpec The default implementation invokes {@link #handle},
911 * invoking the given function on exception, then {@link
912 * #thenCompose} for result.
913 *
914 * @param fn the function to use to compute the returned
915 * CompletionStage if this CompletionStage completed exceptionally
916 * @return the new CompletionStage
917 * @since 12
918 */
919 public default CompletionStage<T> exceptionallyCompose
920 (Function<Throwable, ? extends CompletionStage<T>> fn) {
921 return handle((r, ex) -> (ex == null)
922 ? this
923 : fn.apply(ex))
924 .thenCompose(Function.identity());
925 }
926
927 /**
928 * Returns a new CompletionStage that, when this stage completes
929 * exceptionally, is composed using the results of the supplied
930 * function applied to this stage's exception, using this stage's
931 * default asynchronous execution facility.
932 *
933 * @implSpec The default implementation invokes {@link #handle},
934 * relaying to {@link #handleAsync} on exception, then {@link
935 * #thenCompose} for result.
936 *
937 * @param fn the function to use to compute the returned
938 * CompletionStage if this CompletionStage completed exceptionally
939 * @return the new CompletionStage
940 * @since 12
941 */
942 public default CompletionStage<T> exceptionallyComposeAsync
943 (Function<Throwable, ? extends CompletionStage<T>> fn) {
944 return handle((r, ex) -> (ex == null)
945 ? this
946 : this.handleAsync((r1, ex1) -> fn.apply(ex1))
947 .thenCompose(Function.identity()))
948 .thenCompose(Function.identity());
949 }
950
951 /**
952 * Returns a new CompletionStage that, when this stage completes
953 * exceptionally, is composed using the results of the supplied
954 * function applied to this stage's exception, using the
955 * supplied Executor.
956 *
957 * @implSpec The default implementation invokes {@link #handle},
958 * relaying to {@link #handleAsync} on exception, then {@link
959 * #thenCompose} for result.
960 *
961 * @param fn the function to use to compute the returned
962 * CompletionStage if this CompletionStage completed exceptionally
963 * @param executor the executor to use for asynchronous execution
964 * @return the new CompletionStage
965 * @since 12
966 */
967 public default CompletionStage<T> exceptionallyComposeAsync
968 (Function<Throwable, ? extends CompletionStage<T>> fn,
969 Executor executor) {
970 return handle((r, ex) -> (ex == null)
971 ? this
972 : this.handleAsync((r1, ex1) -> fn.apply(ex1), executor)
973 .thenCompose(Function.identity()))
974 .thenCompose(Function.identity());
975 }
976
977 /**
978 * Returns a {@link CompletableFuture} maintaining the same
979 * completion properties as this stage. If this stage is already a
980 * CompletableFuture, this method may return this stage itself.
981 * Otherwise, invocation of this method may be equivalent in
982 * effect to {@code thenApply(x -> x)}, but returning an instance
983 * of type {@code CompletableFuture}.
984 *
985 * @return the CompletableFuture
986 */
987 public CompletableFuture<T> toCompletableFuture();
988
989 }