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 |
*/ |
141 |
public <U> CompletionStage<U> thenApply(Function<? super T,? extends U> fn); |
142 |
|
143 |
/** |
144 |
* Returns a new CompletionStage that, when this stage completes |
145 |
* normally, is executed using this stage's default asynchronous |
146 |
* execution facility, with this stage's result as the argument to |
147 |
* the supplied function. |
148 |
* |
149 |
* See the {@link CompletionStage} documentation for rules |
150 |
* covering exceptional completion. |
151 |
* |
152 |
* @param fn the function to use to compute the value of the |
153 |
* returned CompletionStage |
154 |
* @param <U> the function's return type |
155 |
* @return the new CompletionStage |
156 |
*/ |
157 |
public <U> CompletionStage<U> thenApplyAsync |
158 |
(Function<? super T,? extends U> fn); |
159 |
|
160 |
/** |
161 |
* Returns a new CompletionStage that, when this stage completes |
162 |
* normally, is executed using the supplied Executor, with this |
163 |
* stage's result as the argument to the supplied function. |
164 |
* |
165 |
* See the {@link CompletionStage} documentation for rules |
166 |
* covering exceptional completion. |
167 |
* |
168 |
* @param fn the function to use to compute the value of the |
169 |
* returned CompletionStage |
170 |
* @param executor the executor to use for asynchronous execution |
171 |
* @param <U> the function's return type |
172 |
* @return the new CompletionStage |
173 |
*/ |
174 |
public <U> CompletionStage<U> thenApplyAsync |
175 |
(Function<? super T,? extends U> fn, |
176 |
Executor executor); |
177 |
|
178 |
/** |
179 |
* Returns a new CompletionStage that, when this stage completes |
180 |
* normally, is executed with this stage's result as the argument |
181 |
* to the supplied action. |
182 |
* |
183 |
* See the {@link CompletionStage} documentation for rules |
184 |
* covering exceptional completion. |
185 |
* |
186 |
* @param action the action to perform before completing the |
187 |
* returned CompletionStage |
188 |
* @return the new CompletionStage |
189 |
*/ |
190 |
public CompletionStage<Void> thenAccept(Consumer<? super T> action); |
191 |
|
192 |
/** |
193 |
* Returns a new CompletionStage that, when this stage completes |
194 |
* normally, is executed using this stage's default asynchronous |
195 |
* execution facility, with this stage's result as the argument to |
196 |
* the supplied action. |
197 |
* |
198 |
* See the {@link CompletionStage} documentation for rules |
199 |
* covering exceptional completion. |
200 |
* |
201 |
* @param action the action to perform before completing the |
202 |
* returned CompletionStage |
203 |
* @return the new CompletionStage |
204 |
*/ |
205 |
public CompletionStage<Void> thenAcceptAsync(Consumer<? super T> action); |
206 |
|
207 |
/** |
208 |
* Returns a new CompletionStage that, when this stage completes |
209 |
* normally, is executed using the supplied Executor, with this |
210 |
* stage's result as the argument to the supplied action. |
211 |
* |
212 |
* See the {@link CompletionStage} documentation for rules |
213 |
* covering exceptional completion. |
214 |
* |
215 |
* @param action the action to perform before completing the |
216 |
* returned CompletionStage |
217 |
* @param executor the executor to use for asynchronous execution |
218 |
* @return the new CompletionStage |
219 |
*/ |
220 |
public CompletionStage<Void> thenAcceptAsync(Consumer<? super T> action, |
221 |
Executor executor); |
222 |
/** |
223 |
* Returns a new CompletionStage that, when this stage completes |
224 |
* normally, executes the given action. |
225 |
* |
226 |
* See the {@link CompletionStage} documentation for rules |
227 |
* covering exceptional completion. |
228 |
* |
229 |
* @param action the action to perform before completing the |
230 |
* returned CompletionStage |
231 |
* @return the new CompletionStage |
232 |
*/ |
233 |
public CompletionStage<Void> thenRun(Runnable action); |
234 |
|
235 |
/** |
236 |
* Returns a new CompletionStage that, when this stage completes |
237 |
* normally, executes the given action using this stage's default |
238 |
* asynchronous execution facility. |
239 |
* |
240 |
* See the {@link CompletionStage} documentation for rules |
241 |
* covering exceptional completion. |
242 |
* |
243 |
* @param action the action to perform before completing the |
244 |
* returned CompletionStage |
245 |
* @return the new CompletionStage |
246 |
*/ |
247 |
public CompletionStage<Void> thenRunAsync(Runnable action); |
248 |
|
249 |
/** |
250 |
* Returns a new CompletionStage that, when this stage completes |
251 |
* normally, executes the given action using the supplied Executor. |
252 |
* |
253 |
* See the {@link CompletionStage} documentation for rules |
254 |
* covering exceptional completion. |
255 |
* |
256 |
* @param action the action to perform before completing the |
257 |
* returned CompletionStage |
258 |
* @param executor the executor to use for asynchronous execution |
259 |
* @return the new CompletionStage |
260 |
*/ |
261 |
public CompletionStage<Void> thenRunAsync(Runnable action, |
262 |
Executor executor); |
263 |
|
264 |
/** |
265 |
* Returns a new CompletionStage that, when this and the other |
266 |
* given stage both complete normally, is executed with the two |
267 |
* results as arguments to the supplied function. |
268 |
* |
269 |
* See the {@link CompletionStage} documentation for rules |
270 |
* covering exceptional completion. |
271 |
* |
272 |
* @param other the other CompletionStage |
273 |
* @param fn the function to use to compute the value of the |
274 |
* returned CompletionStage |
275 |
* @param <U> the type of the other CompletionStage's result |
276 |
* @param <V> the function's return type |
277 |
* @return the new CompletionStage |
278 |
*/ |
279 |
public <U,V> CompletionStage<V> thenCombine |
280 |
(CompletionStage<? extends U> other, |
281 |
BiFunction<? super T,? super U,? extends V> fn); |
282 |
|
283 |
/** |
284 |
* Returns a new CompletionStage that, when this and the other |
285 |
* given stage both complete normally, is executed using this |
286 |
* stage's default asynchronous execution facility, with the two |
287 |
* results as arguments to the supplied function. |
288 |
* |
289 |
* See the {@link CompletionStage} documentation for rules |
290 |
* covering exceptional completion. |
291 |
* |
292 |
* @param other the other CompletionStage |
293 |
* @param fn the function to use to compute the value of the |
294 |
* returned CompletionStage |
295 |
* @param <U> the type of the other CompletionStage's result |
296 |
* @param <V> the function's return type |
297 |
* @return the new CompletionStage |
298 |
*/ |
299 |
public <U,V> CompletionStage<V> thenCombineAsync |
300 |
(CompletionStage<? extends U> other, |
301 |
BiFunction<? super T,? super U,? extends V> fn); |
302 |
|
303 |
/** |
304 |
* Returns a new CompletionStage that, when this and the other |
305 |
* given stage both complete normally, is executed using the |
306 |
* supplied executor, with the two results as arguments to the |
307 |
* supplied function. |
308 |
* |
309 |
* See the {@link CompletionStage} documentation for rules |
310 |
* covering exceptional completion. |
311 |
* |
312 |
* @param other the other CompletionStage |
313 |
* @param fn the function to use to compute the value of the |
314 |
* returned CompletionStage |
315 |
* @param executor the executor to use for asynchronous execution |
316 |
* @param <U> the type of the other CompletionStage's result |
317 |
* @param <V> the function's return type |
318 |
* @return the new CompletionStage |
319 |
*/ |
320 |
public <U,V> CompletionStage<V> thenCombineAsync |
321 |
(CompletionStage<? extends U> other, |
322 |
BiFunction<? super T,? super U,? extends V> fn, |
323 |
Executor executor); |
324 |
|
325 |
/** |
326 |
* Returns a new CompletionStage that, when this and the other |
327 |
* given stage both complete normally, is executed with the two |
328 |
* results as arguments to the supplied action. |
329 |
* |
330 |
* See the {@link CompletionStage} documentation for rules |
331 |
* covering exceptional completion. |
332 |
* |
333 |
* @param other the other CompletionStage |
334 |
* @param action the action to perform before completing the |
335 |
* returned CompletionStage |
336 |
* @param <U> the type of the other CompletionStage's result |
337 |
* @return the new CompletionStage |
338 |
*/ |
339 |
public <U> CompletionStage<Void> thenAcceptBoth |
340 |
(CompletionStage<? extends U> other, |
341 |
BiConsumer<? super T, ? super U> action); |
342 |
|
343 |
/** |
344 |
* Returns a new CompletionStage that, when this and the other |
345 |
* given stage both complete normally, is executed using this |
346 |
* stage's default asynchronous execution facility, with the two |
347 |
* results as arguments to the supplied action. |
348 |
* |
349 |
* See the {@link CompletionStage} documentation for rules |
350 |
* covering exceptional completion. |
351 |
* |
352 |
* @param other the other CompletionStage |
353 |
* @param action the action to perform before completing the |
354 |
* returned CompletionStage |
355 |
* @param <U> the type of the other CompletionStage's result |
356 |
* @return the new CompletionStage |
357 |
*/ |
358 |
public <U> CompletionStage<Void> thenAcceptBothAsync |
359 |
(CompletionStage<? extends U> other, |
360 |
BiConsumer<? super T, ? super U> action); |
361 |
|
362 |
/** |
363 |
* Returns a new CompletionStage that, when this and the other |
364 |
* given stage both complete normally, is executed using the |
365 |
* supplied executor, with the two results as arguments to the |
366 |
* supplied action. |
367 |
* |
368 |
* See the {@link CompletionStage} documentation for rules |
369 |
* covering exceptional completion. |
370 |
* |
371 |
* @param other the other CompletionStage |
372 |
* @param action the action to perform before completing the |
373 |
* returned CompletionStage |
374 |
* @param executor the executor to use for asynchronous execution |
375 |
* @param <U> the type of the other CompletionStage's result |
376 |
* @return the new CompletionStage |
377 |
*/ |
378 |
public <U> CompletionStage<Void> thenAcceptBothAsync |
379 |
(CompletionStage<? extends U> other, |
380 |
BiConsumer<? super T, ? super U> action, |
381 |
Executor executor); |
382 |
|
383 |
/** |
384 |
* Returns a new CompletionStage that, when this and the other |
385 |
* given stage both complete normally, executes the given action. |
386 |
* |
387 |
* See the {@link CompletionStage} documentation for rules |
388 |
* covering exceptional completion. |
389 |
* |
390 |
* @param other the other CompletionStage |
391 |
* @param action the action to perform before completing the |
392 |
* returned CompletionStage |
393 |
* @return the new CompletionStage |
394 |
*/ |
395 |
public CompletionStage<Void> runAfterBoth(CompletionStage<?> other, |
396 |
Runnable action); |
397 |
/** |
398 |
* Returns a new CompletionStage that, when this and the other |
399 |
* given stage both complete normally, executes the given action |
400 |
* using this stage's default asynchronous execution facility. |
401 |
* |
402 |
* See the {@link CompletionStage} documentation for rules |
403 |
* covering exceptional completion. |
404 |
* |
405 |
* @param other the other CompletionStage |
406 |
* @param action the action to perform before completing the |
407 |
* returned CompletionStage |
408 |
* @return the new CompletionStage |
409 |
*/ |
410 |
public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other, |
411 |
Runnable action); |
412 |
|
413 |
/** |
414 |
* Returns a new CompletionStage that, when this and the other |
415 |
* given stage both complete normally, executes the given action |
416 |
* using the supplied executor. |
417 |
* |
418 |
* See the {@link CompletionStage} documentation for rules |
419 |
* covering exceptional completion. |
420 |
* |
421 |
* @param other the other CompletionStage |
422 |
* @param action the action to perform before completing the |
423 |
* returned CompletionStage |
424 |
* @param executor the executor to use for asynchronous execution |
425 |
* @return the new CompletionStage |
426 |
*/ |
427 |
public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other, |
428 |
Runnable action, |
429 |
Executor executor); |
430 |
/** |
431 |
* Returns a new CompletionStage that, when either this or the |
432 |
* other given stage complete normally, is executed with the |
433 |
* corresponding result as argument to the supplied function. |
434 |
* |
435 |
* See the {@link CompletionStage} documentation for rules |
436 |
* covering exceptional completion. |
437 |
* |
438 |
* @param other the other CompletionStage |
439 |
* @param fn the function to use to compute the value of the |
440 |
* returned CompletionStage |
441 |
* @param <U> the function's return type |
442 |
* @return the new CompletionStage |
443 |
*/ |
444 |
public <U> CompletionStage<U> applyToEither |
445 |
(CompletionStage<? extends T> other, |
446 |
Function<? super T, U> fn); |
447 |
|
448 |
/** |
449 |
* Returns a new CompletionStage that, when either this or the |
450 |
* other given stage complete normally, is executed using this |
451 |
* stage's default asynchronous execution facility, with the |
452 |
* corresponding result as argument to the supplied function. |
453 |
* |
454 |
* See the {@link CompletionStage} documentation for rules |
455 |
* covering exceptional completion. |
456 |
* |
457 |
* @param other the other CompletionStage |
458 |
* @param fn the function to use to compute the value of the |
459 |
* returned CompletionStage |
460 |
* @param <U> the function's return type |
461 |
* @return the new CompletionStage |
462 |
*/ |
463 |
public <U> CompletionStage<U> applyToEitherAsync |
464 |
(CompletionStage<? extends T> other, |
465 |
Function<? super T, U> fn); |
466 |
|
467 |
/** |
468 |
* Returns a new CompletionStage that, when either this or the |
469 |
* other given stage complete normally, is executed using the |
470 |
* supplied executor, with the corresponding result as argument to |
471 |
* the supplied function. |
472 |
* |
473 |
* See the {@link CompletionStage} documentation for rules |
474 |
* covering exceptional completion. |
475 |
* |
476 |
* @param other the other CompletionStage |
477 |
* @param fn the function to use to compute the value of the |
478 |
* returned CompletionStage |
479 |
* @param executor the executor to use for asynchronous execution |
480 |
* @param <U> the function's return type |
481 |
* @return the new CompletionStage |
482 |
*/ |
483 |
public <U> CompletionStage<U> applyToEitherAsync |
484 |
(CompletionStage<? extends T> other, |
485 |
Function<? super T, U> fn, |
486 |
Executor executor); |
487 |
|
488 |
/** |
489 |
* Returns a new CompletionStage that, when either this or the |
490 |
* other given stage complete normally, is executed with the |
491 |
* corresponding result as argument to the supplied action. |
492 |
* |
493 |
* See the {@link CompletionStage} documentation for rules |
494 |
* covering exceptional completion. |
495 |
* |
496 |
* @param other the other CompletionStage |
497 |
* @param action the action to perform before completing the |
498 |
* returned CompletionStage |
499 |
* @return the new CompletionStage |
500 |
*/ |
501 |
public CompletionStage<Void> acceptEither |
502 |
(CompletionStage<? extends T> other, |
503 |
Consumer<? super T> action); |
504 |
|
505 |
/** |
506 |
* Returns a new CompletionStage that, when either this or the |
507 |
* other given stage complete normally, is executed using this |
508 |
* stage's default asynchronous execution facility, with the |
509 |
* corresponding result as argument to the supplied action. |
510 |
* |
511 |
* See the {@link CompletionStage} documentation for rules |
512 |
* covering exceptional completion. |
513 |
* |
514 |
* @param other the other CompletionStage |
515 |
* @param action the action to perform before completing the |
516 |
* returned CompletionStage |
517 |
* @return the new CompletionStage |
518 |
*/ |
519 |
public CompletionStage<Void> acceptEitherAsync |
520 |
(CompletionStage<? extends T> other, |
521 |
Consumer<? super T> action); |
522 |
|
523 |
/** |
524 |
* Returns a new CompletionStage that, when either this or the |
525 |
* other given stage complete normally, is executed using the |
526 |
* supplied executor, with the corresponding result as argument to |
527 |
* the supplied action. |
528 |
* |
529 |
* See the {@link CompletionStage} documentation for rules |
530 |
* covering exceptional completion. |
531 |
* |
532 |
* @param other the other CompletionStage |
533 |
* @param action the action to perform before completing the |
534 |
* returned CompletionStage |
535 |
* @param executor the executor to use for asynchronous execution |
536 |
* @return the new CompletionStage |
537 |
*/ |
538 |
public CompletionStage<Void> acceptEitherAsync |
539 |
(CompletionStage<? extends T> other, |
540 |
Consumer<? super T> action, |
541 |
Executor executor); |
542 |
|
543 |
/** |
544 |
* Returns a new CompletionStage that, when either this or the |
545 |
* other given stage complete normally, executes the given action. |
546 |
* |
547 |
* See the {@link CompletionStage} documentation for rules |
548 |
* covering exceptional completion. |
549 |
* |
550 |
* @param other the other CompletionStage |
551 |
* @param action the action to perform before completing the |
552 |
* returned CompletionStage |
553 |
* @return the new CompletionStage |
554 |
*/ |
555 |
public CompletionStage<Void> runAfterEither(CompletionStage<?> other, |
556 |
Runnable action); |
557 |
|
558 |
/** |
559 |
* Returns a new CompletionStage that, when either this or the |
560 |
* other given stage complete normally, executes the given action |
561 |
* using this stage's default asynchronous execution facility. |
562 |
* |
563 |
* See the {@link CompletionStage} documentation for rules |
564 |
* covering exceptional completion. |
565 |
* |
566 |
* @param other the other CompletionStage |
567 |
* @param action the action to perform before completing the |
568 |
* returned CompletionStage |
569 |
* @return the new CompletionStage |
570 |
*/ |
571 |
public CompletionStage<Void> runAfterEitherAsync |
572 |
(CompletionStage<?> other, |
573 |
Runnable action); |
574 |
|
575 |
/** |
576 |
* Returns a new CompletionStage that, when either this or the |
577 |
* other given stage complete normally, executes the given action |
578 |
* using the supplied executor. |
579 |
* |
580 |
* See the {@link CompletionStage} documentation for rules |
581 |
* covering exceptional completion. |
582 |
* |
583 |
* @param other the other CompletionStage |
584 |
* @param action the action to perform before completing the |
585 |
* returned CompletionStage |
586 |
* @param executor the executor to use for asynchronous execution |
587 |
* @return the new CompletionStage |
588 |
*/ |
589 |
public CompletionStage<Void> runAfterEitherAsync |
590 |
(CompletionStage<?> other, |
591 |
Runnable action, |
592 |
Executor executor); |
593 |
|
594 |
/** |
595 |
* Returns a new CompletionStage that is completed with the same |
596 |
* value as the CompletionStage returned by the given function. |
597 |
* |
598 |
* <p>When this stage completes normally, the given function is |
599 |
* invoked with this stage's result as the argument, returning |
600 |
* another CompletionStage. When that stage completes normally, |
601 |
* the CompletionStage returned by this method is completed with |
602 |
* the same value. |
603 |
* |
604 |
* <p>To ensure progress, the supplied function must arrange |
605 |
* eventual completion of its result. |
606 |
* |
607 |
* <p>This method is analogous to |
608 |
* {@link java.util.Optional#flatMap Optional.flatMap} and |
609 |
* {@link java.util.stream.Stream#flatMap Stream.flatMap}. |
610 |
* |
611 |
* <p>See the {@link CompletionStage} documentation for rules |
612 |
* covering exceptional completion. |
613 |
* |
614 |
* @param fn the function to use to compute another CompletionStage |
615 |
* @param <U> the type of the returned CompletionStage's result |
616 |
* @return the new CompletionStage |
617 |
*/ |
618 |
public <U> CompletionStage<U> thenCompose |
619 |
(Function<? super T, ? extends CompletionStage<U>> fn); |
620 |
|
621 |
/** |
622 |
* Returns a new CompletionStage that is completed with the same |
623 |
* value as the CompletionStage returned by the given function, |
624 |
* executed using this stage's default asynchronous execution |
625 |
* facility. |
626 |
* |
627 |
* <p>When this stage completes normally, the given function is |
628 |
* invoked with this stage's result as the argument, returning |
629 |
* another CompletionStage. When that stage completes normally, |
630 |
* the CompletionStage returned by this method is completed with |
631 |
* the same value. |
632 |
* |
633 |
* <p>To ensure progress, the supplied function must arrange |
634 |
* eventual completion of its result. |
635 |
* |
636 |
* <p>See the {@link CompletionStage} documentation for rules |
637 |
* covering exceptional completion. |
638 |
* |
639 |
* @param fn the function to use to compute another CompletionStage |
640 |
* @param <U> the type of the returned CompletionStage's result |
641 |
* @return the new CompletionStage |
642 |
*/ |
643 |
public <U> CompletionStage<U> thenComposeAsync |
644 |
(Function<? super T, ? extends CompletionStage<U>> fn); |
645 |
|
646 |
/** |
647 |
* Returns a new CompletionStage that is completed with the same |
648 |
* value as the CompletionStage returned by the given function, |
649 |
* executed using the supplied Executor. |
650 |
* |
651 |
* <p>When this stage completes normally, the given function is |
652 |
* invoked with this stage's result as the argument, returning |
653 |
* another CompletionStage. When that stage completes normally, |
654 |
* the CompletionStage returned by this method is completed with |
655 |
* the same value. |
656 |
* |
657 |
* <p>To ensure progress, the supplied function must arrange |
658 |
* eventual completion of its result. |
659 |
* |
660 |
* <p>See the {@link CompletionStage} documentation for rules |
661 |
* covering exceptional completion. |
662 |
* |
663 |
* @param fn the function to use to compute another CompletionStage |
664 |
* @param executor the executor to use for asynchronous execution |
665 |
* @param <U> the type of the returned CompletionStage's result |
666 |
* @return the new CompletionStage |
667 |
*/ |
668 |
public <U> CompletionStage<U> thenComposeAsync |
669 |
(Function<? super T, ? extends CompletionStage<U>> fn, |
670 |
Executor executor); |
671 |
|
672 |
/** |
673 |
* Returns a new CompletionStage that, when this stage completes |
674 |
* either normally or exceptionally, is executed with this stage's |
675 |
* result and exception as arguments to the supplied function. |
676 |
* |
677 |
* <p>When this stage is complete, the given function is invoked |
678 |
* with the result (or {@code null} if none) and the exception (or |
679 |
* {@code null} if none) of this stage as arguments, and the |
680 |
* function's result is used to complete the returned stage. |
681 |
* |
682 |
* @param fn the function to use to compute the value of the |
683 |
* returned CompletionStage |
684 |
* @param <U> the function's return type |
685 |
* @return the new CompletionStage |
686 |
*/ |
687 |
public <U> CompletionStage<U> handle |
688 |
(BiFunction<? super T, Throwable, ? extends U> fn); |
689 |
|
690 |
/** |
691 |
* Returns a new CompletionStage that, when this stage completes |
692 |
* either normally or exceptionally, is executed using this stage's |
693 |
* default asynchronous execution facility, with this stage's |
694 |
* result and exception as arguments to the supplied function. |
695 |
* |
696 |
* <p>When this stage is complete, the given function is invoked |
697 |
* with the result (or {@code null} if none) and the exception (or |
698 |
* {@code null} if none) of this stage as arguments, and the |
699 |
* function's result is used to complete the returned stage. |
700 |
* |
701 |
* @param fn the function to use to compute the value of the |
702 |
* returned CompletionStage |
703 |
* @param <U> the function's return type |
704 |
* @return the new CompletionStage |
705 |
*/ |
706 |
public <U> CompletionStage<U> handleAsync |
707 |
(BiFunction<? super T, Throwable, ? extends U> fn); |
708 |
|
709 |
/** |
710 |
* Returns a new CompletionStage that, when this stage completes |
711 |
* either normally or exceptionally, is executed using the |
712 |
* supplied executor, with this stage's result and exception as |
713 |
* arguments to the supplied function. |
714 |
* |
715 |
* <p>When this stage is complete, the given function is invoked |
716 |
* with the result (or {@code null} if none) and the exception (or |
717 |
* {@code null} if none) of this stage as arguments, and the |
718 |
* function's result is used to complete the returned stage. |
719 |
* |
720 |
* @param fn the function to use to compute the value of the |
721 |
* returned CompletionStage |
722 |
* @param executor the executor to use for asynchronous execution |
723 |
* @param <U> the function's return type |
724 |
* @return the new CompletionStage |
725 |
*/ |
726 |
public <U> CompletionStage<U> handleAsync |
727 |
(BiFunction<? super T, Throwable, ? extends U> fn, |
728 |
Executor executor); |
729 |
|
730 |
/** |
731 |
* Returns a new CompletionStage with the same result or exception as |
732 |
* this stage, that executes the given action when this stage completes. |
733 |
* |
734 |
* <p>When this stage is complete, the given action is invoked |
735 |
* with the result (or {@code null} if none) and the exception (or |
736 |
* {@code null} if none) of this stage as arguments. The returned |
737 |
* stage is completed when the action returns. |
738 |
* |
739 |
* <p>Unlike method {@link #handle handle}, |
740 |
* this method is not designed to translate completion outcomes, |
741 |
* so the supplied action should not throw an exception. However, |
742 |
* if it does, the following rules apply: if this stage completed |
743 |
* normally but the supplied action throws an exception, then the |
744 |
* returned stage completes exceptionally with the supplied |
745 |
* action's exception. Or, if this stage completed exceptionally |
746 |
* and the supplied action throws an exception, then the returned |
747 |
* stage completes exceptionally with this stage's exception. |
748 |
* |
749 |
* @param action the action to perform |
750 |
* @return the new CompletionStage |
751 |
*/ |
752 |
public CompletionStage<T> whenComplete |
753 |
(BiConsumer<? super T, ? super Throwable> action); |
754 |
|
755 |
/** |
756 |
* Returns a new CompletionStage with the same result or exception as |
757 |
* this stage, that executes the given action using this stage's |
758 |
* default asynchronous execution facility when this stage completes. |
759 |
* |
760 |
* <p>When this stage is complete, the given action is invoked with the |
761 |
* result (or {@code null} if none) and the exception (or {@code null} |
762 |
* if none) of this stage as arguments. The returned stage is completed |
763 |
* when the action returns. |
764 |
* |
765 |
* <p>Unlike method {@link #handleAsync(BiFunction) handleAsync}, |
766 |
* this method is not designed to translate completion outcomes, |
767 |
* so the supplied action should not throw an exception. However, |
768 |
* if it does, the following rules apply: If this stage completed |
769 |
* normally but the supplied action throws an exception, then the |
770 |
* returned stage completes exceptionally with the supplied |
771 |
* action's exception. Or, if this stage completed exceptionally |
772 |
* and the supplied action throws an exception, then the returned |
773 |
* stage completes exceptionally with this stage's exception. |
774 |
* |
775 |
* @param action the action to perform |
776 |
* @return the new CompletionStage |
777 |
*/ |
778 |
public CompletionStage<T> whenCompleteAsync |
779 |
(BiConsumer<? super T, ? super Throwable> action); |
780 |
|
781 |
/** |
782 |
* Returns a new CompletionStage with the same result or exception as |
783 |
* this stage, that executes the given action using the supplied |
784 |
* Executor when this stage completes. |
785 |
* |
786 |
* <p>When this stage is complete, the given action is invoked with the |
787 |
* result (or {@code null} if none) and the exception (or {@code null} |
788 |
* if none) of this stage as arguments. The returned stage is completed |
789 |
* when the action returns. |
790 |
* |
791 |
* <p>Unlike method {@link #handleAsync(BiFunction,Executor) handleAsync}, |
792 |
* this method is not designed to translate completion outcomes, |
793 |
* so the supplied action should not throw an exception. However, |
794 |
* if it does, the following rules apply: If this stage completed |
795 |
* normally but the supplied action throws an exception, then the |
796 |
* returned stage completes exceptionally with the supplied |
797 |
* action's exception. Or, if this stage completed exceptionally |
798 |
* and the supplied action throws an exception, then the returned |
799 |
* stage completes exceptionally with this stage's exception. |
800 |
* |
801 |
* @param action the action to perform |
802 |
* @param executor the executor to use for asynchronous execution |
803 |
* @return the new CompletionStage |
804 |
*/ |
805 |
public CompletionStage<T> whenCompleteAsync |
806 |
(BiConsumer<? super T, ? super Throwable> action, |
807 |
Executor executor); |
808 |
|
809 |
/** |
810 |
* Returns a new CompletionStage that, when this stage completes |
811 |
* exceptionally, is executed with this stage's exception as the |
812 |
* argument to the supplied function. Otherwise, if this stage |
813 |
* completes normally, then the returned stage also completes |
814 |
* normally with the same value. |
815 |
* |
816 |
* @param fn the function to use to compute the value of the |
817 |
* returned CompletionStage if this CompletionStage completed |
818 |
* exceptionally |
819 |
* @return the new CompletionStage |
820 |
*/ |
821 |
public CompletionStage<T> exceptionally |
822 |
(Function<Throwable, ? extends T> fn); |
823 |
|
824 |
/** |
825 |
* Returns a new CompletionStage that, when this stage completes |
826 |
* exceptionally, is executed with this stage's exception as the |
827 |
* argument to the supplied function, using this stage's default |
828 |
* asynchronous execution facility. Otherwise, if this stage |
829 |
* completes normally, then the returned stage also completes |
830 |
* normally with the same value. |
831 |
* |
832 |
* @implSpec The default implementation invokes {@link #handle}, |
833 |
* relaying to {@link #handleAsync} on exception, then {@link |
834 |
* #thenCompose} for result. |
835 |
* |
836 |
* @param fn the function to use to compute the value of the |
837 |
* returned CompletionStage if this CompletionStage completed |
838 |
* exceptionally |
839 |
* @return the new CompletionStage |
840 |
* @since 12 |
841 |
*/ |
842 |
public default CompletionStage<T> exceptionallyAsync |
843 |
(Function<Throwable, ? extends T> fn) { |
844 |
return handle((r, ex) -> (ex == null) |
845 |
? this |
846 |
: this.<T>handleAsync((r1, ex1) -> fn.apply(ex1))) |
847 |
.thenCompose(Function.identity()); |
848 |
} |
849 |
|
850 |
/** |
851 |
* Returns a new CompletionStage that, when this stage completes |
852 |
* exceptionally, is executed with this stage's exception as the |
853 |
* argument to the supplied function, using the supplied Executor. |
854 |
* Otherwise, if this stage completes normally, then the returned |
855 |
* stage also completes normally with the same value. |
856 |
* |
857 |
* @implSpec The default implementation invokes {@link #handle}, |
858 |
* relaying to {@link #handleAsync} on exception, then {@link |
859 |
* #thenCompose} for result. |
860 |
* |
861 |
* @param fn the function to use to compute the value of the |
862 |
* returned CompletionStage if this CompletionStage completed |
863 |
* exceptionally |
864 |
* @param executor the executor to use for asynchronous execution |
865 |
* @return the new CompletionStage |
866 |
* @since 12 |
867 |
*/ |
868 |
public default CompletionStage<T> exceptionallyAsync |
869 |
(Function<Throwable, ? extends T> fn, Executor executor) { |
870 |
return handle((r, ex) -> (ex == null) |
871 |
? this |
872 |
: this.<T>handleAsync((r1, ex1) -> fn.apply(ex1), executor)) |
873 |
.thenCompose(Function.identity()); |
874 |
} |
875 |
|
876 |
/** |
877 |
* Returns a new CompletionStage that, when this stage completes |
878 |
* exceptionally, is composed using the results of the supplied |
879 |
* function applied to this stage's exception. |
880 |
* |
881 |
* @implSpec The default implementation invokes {@link #handle}, |
882 |
* invoking the given function on exception, then {@link |
883 |
* #thenCompose} for result. |
884 |
* |
885 |
* @param fn the function to use to compute the returned |
886 |
* CompletionStage if this CompletionStage completed exceptionally |
887 |
* @return the new CompletionStage |
888 |
* @since 12 |
889 |
*/ |
890 |
public default CompletionStage<T> exceptionallyCompose |
891 |
(Function<Throwable, ? extends CompletionStage<T>> fn) { |
892 |
return handle((r, ex) -> (ex == null) |
893 |
? this |
894 |
: fn.apply(ex)) |
895 |
.thenCompose(Function.identity()); |
896 |
} |
897 |
|
898 |
/** |
899 |
* Returns a new CompletionStage that, when this stage completes |
900 |
* exceptionally, is composed using the results of the supplied |
901 |
* function applied to this stage's exception, using this stage's |
902 |
* default asynchronous execution facility. |
903 |
* |
904 |
* @implSpec The default implementation invokes {@link #handle}, |
905 |
* relaying to {@link #handleAsync} on exception, then {@link |
906 |
* #thenCompose} for result. |
907 |
* |
908 |
* @param fn the function to use to compute the returned |
909 |
* CompletionStage if this CompletionStage completed exceptionally |
910 |
* @return the new CompletionStage |
911 |
* @since 12 |
912 |
*/ |
913 |
public default CompletionStage<T> exceptionallyComposeAsync |
914 |
(Function<Throwable, ? extends CompletionStage<T>> fn) { |
915 |
return handle((r, ex) -> (ex == null) |
916 |
? this |
917 |
: this.handleAsync((r1, ex1) -> fn.apply(ex1)) |
918 |
.thenCompose(Function.identity())) |
919 |
.thenCompose(Function.identity()); |
920 |
} |
921 |
|
922 |
/** |
923 |
* Returns a new CompletionStage that, when this stage completes |
924 |
* exceptionally, is composed using the results of the supplied |
925 |
* function applied to this stage's exception, using the |
926 |
* supplied Executor. |
927 |
* |
928 |
* @implSpec The default implementation invokes {@link #handle}, |
929 |
* relaying to {@link #handleAsync} on exception, then {@link |
930 |
* #thenCompose} for result. |
931 |
* |
932 |
* @param fn the function to use to compute the returned |
933 |
* CompletionStage if this CompletionStage completed exceptionally |
934 |
* @param executor the executor to use for asynchronous execution |
935 |
* @return the new CompletionStage |
936 |
* @since 12 |
937 |
*/ |
938 |
public default CompletionStage<T> exceptionallyComposeAsync |
939 |
(Function<Throwable, ? extends CompletionStage<T>> fn, |
940 |
Executor executor) { |
941 |
return handle((r, ex) -> (ex == null) |
942 |
? this |
943 |
: this.handleAsync((r1, ex1) -> fn.apply(ex1), executor) |
944 |
.thenCompose(Function.identity())) |
945 |
.thenCompose(Function.identity()); |
946 |
} |
947 |
|
948 |
/** |
949 |
* Returns a {@link CompletableFuture} maintaining the same |
950 |
* completion properties as this stage. If this stage is already a |
951 |
* CompletableFuture, this method may return this stage itself. |
952 |
* Otherwise, invocation of this method may be equivalent in |
953 |
* effect to {@code thenApply(x -> x)}, but returning an instance |
954 |
* of type {@code CompletableFuture}. |
955 |
* |
956 |
* @return the CompletableFuture |
957 |
*/ |
958 |
public CompletableFuture<T> toCompletableFuture(); |
959 |
|
960 |
} |