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 ({@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  */
122 public 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      */
thenApply(Function<? super T,? extends U> fn)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      */
thenApplyAsync(Function<? super T,? extends U> fn)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      */
thenApplyAsync(Function<? super T,? extends U> fn, Executor executor)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      */
thenAccept(Consumer<? super T> action)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      */
thenAcceptAsync(Consumer<? super T> action)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      */
thenAcceptAsync(Consumer<? super T> action, Executor executor)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      */
thenRun(Runnable action)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      */
thenRunAsync(Runnable action)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      */
thenRunAsync(Runnable action, Executor executor)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      */
thenCombine(CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn)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      */
thenCombineAsync(CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn)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      */
thenCombineAsync(CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn, Executor executor)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      */
thenAcceptBoth(CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action)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      */
thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action)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      */
thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action, Executor executor)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      */
runAfterBoth(CompletionStage<?> other, Runnable action)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      */
runAfterBothAsync(CompletionStage<?> other, Runnable action)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      */
runAfterBothAsync(CompletionStage<?> other, Runnable action, Executor executor)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      */
applyToEither(CompletionStage<? extends T> other, Function<? super T, U> fn)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      */
applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T, U> fn)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      */
applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T, U> fn, Executor executor)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      */
acceptEither(CompletionStage<? extends T> other, Consumer<? super T> action)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      */
acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action)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      */
acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action, Executor executor)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      */
runAfterEither(CompletionStage<?> other, Runnable action)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      */
runAfterEitherAsync(CompletionStage<?> other, Runnable action)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      */
runAfterEitherAsync(CompletionStage<?> other, Runnable action, Executor executor)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      */
thenCompose(Function<? super T, ? extends CompletionStage<U>> fn)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      */
thenComposeAsync(Function<? super T, ? extends CompletionStage<U>> fn)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      */
thenComposeAsync(Function<? super T, ? extends CompletionStage<U>> fn, Executor executor)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      */
handle(BiFunction<? super T, Throwable, ? extends U> fn)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      */
handleAsync(BiFunction<? super T, Throwable, ? extends U> fn)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      */
handleAsync(BiFunction<? super T, Throwable, ? extends U> fn, Executor executor)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      */
whenComplete(BiConsumer<? super T, ? super Throwable> action)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      */
whenCompleteAsync(BiConsumer<? super T, ? super Throwable> action)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      */
whenCompleteAsync(BiConsumer<? super T, ? super Throwable> action, Executor executor)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      */
exceptionally(Function<Throwable, ? extends T> fn)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      */
toCompletableFuture()838     public CompletableFuture<T> toCompletableFuture();
839 
840 }
841