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