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