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 import java.util.function.Supplier;
38 import java.util.function.Consumer;
39 import java.util.function.BiConsumer;
40 import java.util.function.Function;
41 import java.util.function.BiFunction;
42 import java.util.concurrent.Executor;
43 
44 /**
45  * A stage of a possibly asynchronous computation, that performs an
46  * action or computes a value when another CompletionStage completes.
47  * A stage completes upon termination of its computation, but this may
48  * in turn trigger other dependent stages.  The functionality defined
49  * in this interface takes only a few basic forms, which expand out to
50  * a larger set of methods to capture a range of usage styles: <ul>
51  *
52  * <li>The computation performed by a stage may be expressed as a
53  * Function, Consumer, or Runnable (using methods with names including
54  * <em>apply</em>, <em>accept</em>, or <em>run</em>, respectively)
55  * depending on whether it requires arguments and/or produces results.
56  * For example, {@code stage.thenApply(x -> square(x)).thenAccept(x ->
57  * System.out.print(x)).thenRun(() -> System.out.println())}. An
58  * additional form (<em>compose</em>) applies functions of stages
59  * themselves, rather than their results. </li>
60  *
61  * <li> One stage's execution may be triggered by completion of a
62  * single stage, or both of two stages, or either of two stages.
63  * Dependencies on a single stage are arranged using methods with
64  * prefix <em>then</em>. Those triggered by completion of
65  * <em>both</em> of two stages may <em>combine</em> their results or
66  * effects, using correspondingly named methods. Those triggered by
67  * <em>either</em> of two stages make no guarantees about which of the
68  * results or effects are used for the dependent stage's
69  * computation.</li>
70  *
71  * <li> Dependencies among stages control the triggering of
72  * computations, but do not otherwise guarantee any particular
73  * ordering. Additionally, execution of a new stage's computations may
74  * be arranged in any of three ways: default execution, default
75  * asynchronous execution (using methods with suffix <em>async</em>
76  * that employ the stage's default asynchronous execution facility),
77  * or custom (via a supplied {@link Executor}).  The execution
78  * properties of default and async modes are specified by
79  * CompletionStage implementations, not this interface. Methods with
80  * explicit Executor arguments may have arbitrary execution
81  * properties, and might not even support concurrent execution, but
82  * are arranged for processing in a way that accommodates asynchrony.
83  *
84  * <li> Two method forms support processing whether the triggering
85  * stage completed normally or exceptionally: Method {@link
86  * #whenComplete whenComplete} allows injection of an action
87  * regardless of outcome, otherwise preserving the outcome in its
88  * completion. Method {@link #handle handle} additionally allows the
89  * stage to compute a replacement result that may enable further
90  * processing by other dependent stages.  In all other cases, if a
91  * stage's computation terminates abruptly with an (unchecked)
92  * exception or error, then all dependent stages requiring its
93  * completion complete exceptionally as well, with a {@link
94  * CompletionException} holding the exception as its cause.  If a
95  * stage is dependent on <em>both</em> of two stages, and both
96  * complete exceptionally, then the CompletionException may correspond
97  * to either one of these exceptions.  If a stage is dependent on
98  * <em>either</em> of two others, and only one of them completes
99  * exceptionally, no guarantees are made about whether the dependent
100  * stage completes normally or exceptionally. In the case of method
101  * {@code whenComplete}, when the supplied action itself encounters an
102  * exception, then the stage exceptionally completes with this
103  * exception if not already completed exceptionally.</li>
104  *
105  * </ul>
106  *
107  * <p>All methods adhere to the above triggering, execution, and
108  * exceptional completion specifications (which are not repeated in
109  * individual method specifications). Additionally, while arguments
110  * used to pass a completion result (that is, for parameters of type
111  * {@code T}) for methods accepting them may be null, passing a null
112  * value for any other parameter will result in a {@link
113  * NullPointerException} being thrown.
114  *
115  * <p>This interface does not define methods for initially creating,
116  * forcibly completing normally or exceptionally, probing completion
117  * status or results, or awaiting completion of a stage.
118  * Implementations of CompletionStage may provide means of achieving
119  * such effects, as appropriate.  Method {@link #toCompletableFuture}
120  * enables interoperability among different implementations of this
121  * interface by providing a common conversion type.
122  *
123  * @author Doug Lea
124  * @since 1.8
125  */
126 public interface CompletionStage<T> {
127 
128     /**
129      * Returns a new CompletionStage that, when this stage completes
130      * normally, is executed with this stage's result as the argument
131      * to the supplied function.
132      *
133      * See the {@link CompletionStage} documentation for rules
134      * covering exceptional completion.
135      *
136      * @param fn the function to use to compute the value of
137      * the 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
153      * the 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
169      * the 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
274      * the 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 complete normally, is executed using this stage's
286      * default asynchronous execution facility, with the two results
287      * 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
294      * the 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 complete normally, is executed using the supplied
306      * executor, with the two results as arguments to the supplied
307      * 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
314      * the 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 complete normally, is executed using this stage's
346      * default asynchronous execution facility, with the two results
347      * as arguments to the supplied action.
348      *
349      * @param other the other CompletionStage
350      * @param action the action to perform before completing the
351      * returned CompletionStage
352      * @param <U> the type of the other CompletionStage's result
353      * @return the new CompletionStage
354      */
thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action)355     public <U> CompletionStage<Void> thenAcceptBothAsync
356         (CompletionStage<? extends U> other,
357          BiConsumer<? super T, ? super U> action);
358 
359     /**
360      * Returns a new CompletionStage that, when this and the other
361      * given stage complete normally, is executed using the supplied
362      * executor, with the two results as arguments to the supplied
363      * function.
364      *
365      * @param other the other CompletionStage
366      * @param action the action to perform before completing the
367      * returned CompletionStage
368      * @param executor the executor to use for asynchronous execution
369      * @param <U> the type of the other CompletionStage's result
370      * @return the new CompletionStage
371      */
thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action, Executor executor)372     public <U> CompletionStage<Void> thenAcceptBothAsync
373         (CompletionStage<? extends U> other,
374          BiConsumer<? super T, ? super U> action,
375          Executor executor);
376 
377     /**
378      * Returns a new CompletionStage that, when this and the other
379      * given stage both complete normally, executes the given action.
380      *
381      * See the {@link CompletionStage} documentation for rules
382      * covering exceptional completion.
383      *
384      * @param other the other CompletionStage
385      * @param action the action to perform before completing the
386      * returned CompletionStage
387      * @return the new CompletionStage
388      */
runAfterBoth(CompletionStage<?> other, Runnable action)389     public CompletionStage<Void> runAfterBoth(CompletionStage<?> other,
390                                               Runnable action);
391     /**
392      * Returns a new CompletionStage that, when this and the other
393      * given stage complete normally, executes the given action using
394      * this stage's default asynchronous execution facility.
395      *
396      * See the {@link CompletionStage} documentation for rules
397      * covering exceptional completion.
398      *
399      * @param other the other CompletionStage
400      * @param action the action to perform before completing the
401      * returned CompletionStage
402      * @return the new CompletionStage
403      */
runAfterBothAsync(CompletionStage<?> other, Runnable action)404     public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other,
405                                                    Runnable action);
406 
407     /**
408      * Returns a new CompletionStage that, when this and the other
409      * given stage complete normally, executes the given action using
410      * the supplied executor.
411      *
412      * See the {@link CompletionStage} documentation for rules
413      * covering exceptional completion.
414      *
415      * @param other the other CompletionStage
416      * @param action the action to perform before completing the
417      * returned CompletionStage
418      * @param executor the executor to use for asynchronous execution
419      * @return the new CompletionStage
420      */
runAfterBothAsync(CompletionStage<?> other, Runnable action, Executor executor)421     public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other,
422                                                    Runnable action,
423                                                    Executor executor);
424     /**
425      * Returns a new CompletionStage that, when either this or the
426      * other given stage complete normally, is executed with the
427      * corresponding result as argument to the supplied function.
428      *
429      * See the {@link CompletionStage} documentation for rules
430      * covering exceptional completion.
431      *
432      * @param other the other CompletionStage
433      * @param fn the function to use to compute the value of
434      * the returned CompletionStage
435      * @param <U> the function's return type
436      * @return the new CompletionStage
437      */
applyToEither(CompletionStage<? extends T> other, Function<? super T, U> fn)438     public <U> CompletionStage<U> applyToEither
439         (CompletionStage<? extends T> other,
440          Function<? super T, U> fn);
441 
442     /**
443      * Returns a new CompletionStage that, when either this or the
444      * other given stage complete normally, is executed using this
445      * stage's default asynchronous execution facility, with the
446      * corresponding result as argument to the supplied function.
447      *
448      * See the {@link CompletionStage} documentation for rules
449      * covering exceptional completion.
450      *
451      * @param other the other CompletionStage
452      * @param fn the function to use to compute the value of
453      * the returned CompletionStage
454      * @param <U> the function's return type
455      * @return the new CompletionStage
456      */
applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T, U> fn)457     public <U> CompletionStage<U> applyToEitherAsync
458         (CompletionStage<? extends T> other,
459          Function<? super T, U> fn);
460 
461     /**
462      * Returns a new CompletionStage that, when either this or the
463      * other given stage complete normally, is executed using the
464      * supplied executor, with the corresponding result as argument to
465      * the supplied function.
466      *
467      * See the {@link CompletionStage} documentation for rules
468      * covering exceptional completion.
469      *
470      * @param other the other CompletionStage
471      * @param fn the function to use to compute the value of
472      * the returned CompletionStage
473      * @param executor the executor to use for asynchronous execution
474      * @param <U> the function's return type
475      * @return the new CompletionStage
476      */
applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T, U> fn, Executor executor)477     public <U> CompletionStage<U> applyToEitherAsync
478         (CompletionStage<? extends T> other,
479          Function<? super T, U> fn,
480          Executor executor);
481 
482     /**
483      * Returns a new CompletionStage that, when either this or the
484      * other given stage complete normally, is executed with the
485      * corresponding result as argument to the supplied action.
486      *
487      * See the {@link CompletionStage} documentation for rules
488      * covering exceptional completion.
489      *
490      * @param other the other CompletionStage
491      * @param action the action to perform before completing the
492      * returned CompletionStage
493      * @return the new CompletionStage
494      */
acceptEither(CompletionStage<? extends T> other, Consumer<? super T> action)495     public CompletionStage<Void> acceptEither
496         (CompletionStage<? extends T> other,
497          Consumer<? super T> action);
498 
499     /**
500      * Returns a new CompletionStage that, when either this or the
501      * other given stage complete normally, is executed using this
502      * stage's default asynchronous execution facility, with the
503      * corresponding result as argument to the supplied action.
504      *
505      * See the {@link CompletionStage} documentation for rules
506      * covering exceptional completion.
507      *
508      * @param other the other CompletionStage
509      * @param action the action to perform before completing the
510      * returned CompletionStage
511      * @return the new CompletionStage
512      */
acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action)513     public CompletionStage<Void> acceptEitherAsync
514         (CompletionStage<? extends T> other,
515          Consumer<? super T> action);
516 
517     /**
518      * Returns a new CompletionStage that, when either this or the
519      * other given stage complete normally, is executed using the
520      * supplied executor, with the corresponding result as argument to
521      * the supplied function.
522      *
523      * See the {@link CompletionStage} documentation for rules
524      * covering exceptional completion.
525      *
526      * @param other the other CompletionStage
527      * @param action the action to perform before completing the
528      * returned CompletionStage
529      * @param executor the executor to use for asynchronous execution
530      * @return the new CompletionStage
531      */
acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action, Executor executor)532     public CompletionStage<Void> acceptEitherAsync
533         (CompletionStage<? extends T> other,
534          Consumer<? super T> action,
535          Executor executor);
536 
537     /**
538      * Returns a new CompletionStage that, when either this or the
539      * other given stage complete normally, executes the given action.
540      *
541      * See the {@link CompletionStage} documentation for rules
542      * covering exceptional completion.
543      *
544      * @param other the other CompletionStage
545      * @param action the action to perform before completing the
546      * returned CompletionStage
547      * @return the new CompletionStage
548      */
runAfterEither(CompletionStage<?> other, Runnable action)549     public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
550                                                 Runnable action);
551 
552     /**
553      * Returns a new CompletionStage that, when either this or the
554      * other given stage complete normally, executes the given action
555      * using this stage's default asynchronous execution facility.
556      *
557      * See the {@link CompletionStage} documentation for rules
558      * covering exceptional completion.
559      *
560      * @param other the other CompletionStage
561      * @param action the action to perform before completing the
562      * returned CompletionStage
563      * @return the new CompletionStage
564      */
runAfterEitherAsync(CompletionStage<?> other, Runnable action)565     public CompletionStage<Void> runAfterEitherAsync
566         (CompletionStage<?> other,
567          Runnable action);
568 
569     /**
570      * Returns a new CompletionStage that, when either this or the
571      * other given stage complete normally, executes the given action
572      * using the supplied executor.
573      *
574      * See the {@link CompletionStage} documentation for rules
575      * covering exceptional completion.
576      *
577      * @param other the other CompletionStage
578      * @param action the action to perform before completing the
579      * returned CompletionStage
580      * @param executor the executor to use for asynchronous execution
581      * @return the new CompletionStage
582      */
runAfterEitherAsync(CompletionStage<?> other, Runnable action, Executor executor)583     public CompletionStage<Void> runAfterEitherAsync
584         (CompletionStage<?> other,
585          Runnable action,
586          Executor executor);
587 
588     /**
589      * Returns a new CompletionStage that, when this stage completes
590      * normally, is executed with this stage as the argument
591      * to the supplied function.
592      *
593      * See the {@link CompletionStage} documentation for rules
594      * covering exceptional completion.
595      *
596      * @param fn the function returning a new CompletionStage
597      * @param <U> the type of the returned CompletionStage's result
598      * @return the CompletionStage
599      */
thenCompose(Function<? super T, ? extends CompletionStage<U>> fn)600     public <U> CompletionStage<U> thenCompose
601         (Function<? super T, ? extends CompletionStage<U>> fn);
602 
603     /**
604      * Returns a new CompletionStage that, when this stage completes
605      * normally, is executed using this stage's default asynchronous
606      * execution facility, with this stage as the argument to the
607      * supplied function.
608      *
609      * See the {@link CompletionStage} documentation for rules
610      * covering exceptional completion.
611      *
612      * @param fn the function returning a new CompletionStage
613      * @param <U> the type of the returned CompletionStage's result
614      * @return the CompletionStage
615      */
thenComposeAsync(Function<? super T, ? extends CompletionStage<U>> fn)616     public <U> CompletionStage<U> thenComposeAsync
617         (Function<? super T, ? extends CompletionStage<U>> fn);
618 
619     /**
620      * Returns a new CompletionStage that, when this stage completes
621      * normally, is executed using the supplied Executor, with this
622      * stage's result as the argument to the supplied function.
623      *
624      * See the {@link CompletionStage} documentation for rules
625      * covering exceptional completion.
626      *
627      * @param fn the function returning a new CompletionStage
628      * @param executor the executor to use for asynchronous execution
629      * @param <U> the type of the returned CompletionStage's result
630      * @return the CompletionStage
631      */
thenComposeAsync(Function<? super T, ? extends CompletionStage<U>> fn, Executor executor)632     public <U> CompletionStage<U> thenComposeAsync
633         (Function<? super T, ? extends CompletionStage<U>> fn,
634          Executor executor);
635 
636     /**
637      * Returns a new CompletionStage that, when this stage completes
638      * exceptionally, is executed with this stage's exception as the
639      * argument to the supplied function.  Otherwise, if this stage
640      * completes normally, then the returned stage also completes
641      * normally with the same value.
642      *
643      * @param fn the function to use to compute the value of the
644      * returned CompletionStage if this CompletionStage completed
645      * exceptionally
646      * @return the new CompletionStage
647      */
exceptionally(Function<Throwable, ? extends T> fn)648     public CompletionStage<T> exceptionally
649         (Function<Throwable, ? extends T> fn);
650 
651     /**
652      * Returns a new CompletionStage with the same result or exception as
653      * this stage, that executes the given action when this stage completes.
654      *
655      * <p>When this stage is complete, the given action is invoked with the
656      * result (or {@code null} if none) and the exception (or {@code null}
657      * if none) of this stage as arguments.  The returned stage is completed
658      * when the action returns.  If the supplied action itself encounters an
659      * exception, then the returned stage exceptionally completes with this
660      * exception unless this stage also completed exceptionally.
661      *
662      * @param action the action to perform
663      * @return the new CompletionStage
664      */
whenComplete(BiConsumer<? super T, ? super Throwable> action)665     public CompletionStage<T> whenComplete
666         (BiConsumer<? super T, ? super Throwable> action);
667 
668     /**
669      * Returns a new CompletionStage with the same result or exception as
670      * this stage, that executes the given action using this stage's
671      * default asynchronous execution facility when this stage completes.
672      *
673      * <p>When this stage is complete, the given action is invoked with the
674      * result (or {@code null} if none) and the exception (or {@code null}
675      * if none) of this stage as arguments.  The returned stage is completed
676      * when the action returns.  If the supplied action itself encounters an
677      * exception, then the returned stage exceptionally completes with this
678      * exception unless this stage also completed exceptionally.
679      *
680      * @param action the action to perform
681      * @return the new CompletionStage
682      */
whenCompleteAsync(BiConsumer<? super T, ? super Throwable> action)683     public CompletionStage<T> whenCompleteAsync
684         (BiConsumer<? super T, ? super Throwable> action);
685 
686     /**
687      * Returns a new CompletionStage with the same result or exception as
688      * this stage, that executes the given action using the supplied
689      * Executor when this stage completes.
690      *
691      * <p>When this stage is complete, the given action is invoked with the
692      * result (or {@code null} if none) and the exception (or {@code null}
693      * if none) of this stage as arguments.  The returned stage is completed
694      * when the action returns.  If the supplied action itself encounters an
695      * exception, then the returned stage exceptionally completes with this
696      * exception unless this stage also completed exceptionally.
697      *
698      * @param action the action to perform
699      * @param executor the executor to use for asynchronous execution
700      * @return the new CompletionStage
701      */
whenCompleteAsync(BiConsumer<? super T, ? super Throwable> action, Executor executor)702     public CompletionStage<T> whenCompleteAsync
703         (BiConsumer<? super T, ? super Throwable> action,
704          Executor executor);
705 
706     /**
707      * Returns a new CompletionStage that, when this stage completes
708      * either normally or exceptionally, is executed with this stage's
709      * result and exception as arguments to the supplied function.
710      *
711      * <p>When this stage is complete, the given function is invoked
712      * with the result (or {@code null} if none) and the exception (or
713      * {@code null} if none) of this stage as arguments, and the
714      * function's result is used to complete the returned stage.
715      *
716      * @param fn the function to use to compute the value of the
717      * returned CompletionStage
718      * @param <U> the function's return type
719      * @return the new CompletionStage
720      */
handle(BiFunction<? super T, Throwable, ? extends U> fn)721     public <U> CompletionStage<U> handle
722         (BiFunction<? super T, Throwable, ? extends U> fn);
723 
724     /**
725      * Returns a new CompletionStage that, when this stage completes
726      * either normally or exceptionally, is executed using this stage's
727      * default asynchronous execution facility, with this stage's
728      * result and exception as arguments to the supplied function.
729      *
730      * <p>When this stage is complete, the given function is invoked
731      * with the result (or {@code null} if none) and the exception (or
732      * {@code null} if none) of this stage as arguments, and the
733      * function's result is used to complete the returned stage.
734      *
735      * @param fn the function to use to compute the value of the
736      * returned CompletionStage
737      * @param <U> the function's return type
738      * @return the new CompletionStage
739      */
handleAsync(BiFunction<? super T, Throwable, ? extends U> fn)740     public <U> CompletionStage<U> handleAsync
741         (BiFunction<? super T, Throwable, ? extends U> fn);
742 
743     /**
744      * Returns a new CompletionStage that, when this stage completes
745      * either normally or exceptionally, is executed using the
746      * supplied executor, with this stage's result and exception as
747      * arguments to the supplied function.
748      *
749      * <p>When this stage is complete, the given function is invoked
750      * with the result (or {@code null} if none) and the exception (or
751      * {@code null} if none) of this stage as arguments, and the
752      * function's result is used to complete the returned stage.
753      *
754      * @param fn the function to use to compute the value of the
755      * returned CompletionStage
756      * @param executor the executor to use for asynchronous execution
757      * @param <U> the function's return type
758      * @return the new CompletionStage
759      */
handleAsync(BiFunction<? super T, Throwable, ? extends U> fn, Executor executor)760     public <U> CompletionStage<U> handleAsync
761         (BiFunction<? super T, Throwable, ? extends U> fn,
762          Executor executor);
763 
764     /**
765      * Returns a {@link CompletableFuture} maintaining the same
766      * completion properties as this stage. If this stage is already a
767      * CompletableFuture, this method may return this stage itself.
768      * Otherwise, invocation of this method may be equivalent in
769      * effect to {@code thenApply(x -> x)}, but returning an instance
770      * of type {@code CompletableFuture}. A CompletionStage
771      * implementation that does not choose to interoperate with others
772      * may throw {@code UnsupportedOperationException}.
773      *
774      * @return the CompletableFuture
775      * @throws UnsupportedOperationException if this implementation
776      * does not interoperate with CompletableFuture
777      */
toCompletableFuture()778     public CompletableFuture<T> toCompletableFuture();
779 
780 }
781