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: <ul> |
21 |
* |
22 |
* <li>The computation performed by a stage may be expressed as a |
23 |
* Function, Consumer, or Runnable (using methods with names including |
24 |
* <em>apply</em>, <em>accept</em>, or <em>run</em>, respectively) |
25 |
* depending on whether it requires arguments and/or produces results. |
26 |
* For example, {@code stage.thenApply(x -> square(x)).thenAccept(x -> |
27 |
* System.out.print(x)).thenRun(() -> System.out.println())}. An |
28 |
* additional form (<em>compose</em>) applies functions of stages |
29 |
* themselves, rather than their results. </li> |
30 |
* |
31 |
* <li> One stage's execution may be triggered by completion of a |
32 |
* single stage, or both of two stages, or either of two stages. |
33 |
* Dependencies on a single stage are arranged using methods with |
34 |
* prefix <em>then</em>. Those triggered by completion of |
35 |
* <em>both</em> of two stages may <em>combine</em> their results or |
36 |
* effects, using correspondingly named methods. Those triggered by |
37 |
* <em>either</em> of two stages make no guarantees about which of the |
38 |
* results or effects are used for the dependent stage's |
39 |
* computation.</li> |
40 |
* |
41 |
* <li> Dependencies among stages control the triggering of |
42 |
* computations, but do not otherwise guarantee any particular |
43 |
* ordering. Additionally, execution of a new stage's computations may |
44 |
* be arranged in any of three ways: default execution, default |
45 |
* asynchronous execution (using methods with suffix <em>async</em> |
46 |
* that employ the stage's default asynchronous execution facility), |
47 |
* or custom (via a supplied {@link Executor}). The execution |
48 |
* properties of default and async modes are specified by |
49 |
* CompletionStage implementations, not this interface. Methods with |
50 |
* explicit Executor arguments may have arbitrary execution |
51 |
* properties, and might not even support concurrent execution, but |
52 |
* are arranged for processing in a way that accommodates asynchrony. |
53 |
* |
54 |
* <li> Two method forms support processing whether the triggering |
55 |
* stage completed normally or exceptionally: Method {@link |
56 |
* #whenComplete whenComplete} allows injection of an action |
57 |
* regardless of outcome, otherwise preserving the outcome in its |
58 |
* completion. Method {@link #handle handle} additionally allows the |
59 |
* stage to compute a replacement result that may enable further |
60 |
* processing by other dependent stages. In all other cases, if a |
61 |
* stage's computation terminates abruptly with an (unchecked) |
62 |
* exception or error, then all dependent stages requiring its |
63 |
* completion complete exceptionally as well, with a {@link |
64 |
* CompletionException} holding the exception as its cause. If a |
65 |
* stage is dependent on <em>both</em> of two stages, and both |
66 |
* complete exceptionally, then the CompletionException may correspond |
67 |
* to either one of these exceptions. If a stage is dependent on |
68 |
* <em>either</em> of two others, and only one of them completes |
69 |
* exceptionally, no guarantees are made about whether the dependent |
70 |
* stage completes normally or exceptionally. In the case of method |
71 |
* {@code whenComplete}, when the supplied action itself encounters an |
72 |
* exception, then the stage exceptionally completes with this |
73 |
* exception if not already completed exceptionally.</li> |
74 |
* |
75 |
* </ul> |
76 |
* |
77 |
* <p>All methods adhere to the above triggering, execution, and |
78 |
* exceptional completion specifications (which are not repeated in |
79 |
* individual method specifications). Additionally, while arguments |
80 |
* used to pass a completion result (that is, for parameters of type |
81 |
* {@code T}) for methods accepting them may be null, passing a null |
82 |
* value for any other parameter will result in a {@link |
83 |
* NullPointerException} being thrown. |
84 |
* |
85 |
* <p>This interface does not define methods for initially creating, |
86 |
* forcibly completing normally or exceptionally, probing completion |
87 |
* status or results, or awaiting completion of a stage. |
88 |
* Implementations of CompletionStage may provide means of achieving |
89 |
* such effects, as appropriate. Method {@link #toCompletableFuture} |
90 |
* enables interoperability among different implementations of this |
91 |
* interface by providing a common conversion type. |
92 |
* |
93 |
* @author Doug Lea |
94 |
* @since 1.8 |
95 |
*/ |
96 |
public interface CompletionStage<T> { |
97 |
|
98 |
/** |
99 |
* Returns a new CompletionStage that, when this stage completes |
100 |
* normally, is executed with this stage's result as the argument |
101 |
* to the supplied function. |
102 |
* |
103 |
* See the {@link CompletionStage} documentation for rules |
104 |
* covering exceptional completion. |
105 |
* |
106 |
* @param fn the function to use to compute the value of |
107 |
* the returned CompletionStage |
108 |
* @param <U> the function's return type |
109 |
* @return the new CompletionStage |
110 |
*/ |
111 |
public <U> CompletionStage<U> thenApply(Function<? super T,? extends U> fn); |
112 |
|
113 |
/** |
114 |
* Returns a new CompletionStage that, when this stage completes |
115 |
* normally, is executed using this stage's default asynchronous |
116 |
* execution facility, with this stage's result as the argument to |
117 |
* the supplied function. |
118 |
* |
119 |
* See the {@link CompletionStage} documentation for rules |
120 |
* covering exceptional completion. |
121 |
* |
122 |
* @param fn the function to use to compute the value of |
123 |
* the returned CompletionStage |
124 |
* @param <U> the function's return type |
125 |
* @return the new CompletionStage |
126 |
*/ |
127 |
public <U> CompletionStage<U> thenApplyAsync |
128 |
(Function<? super T,? extends U> fn); |
129 |
|
130 |
/** |
131 |
* Returns a new CompletionStage that, when this stage completes |
132 |
* normally, is executed using the supplied Executor, with this |
133 |
* stage's result as the argument to the supplied function. |
134 |
* |
135 |
* See the {@link CompletionStage} documentation for rules |
136 |
* covering exceptional completion. |
137 |
* |
138 |
* @param fn the function to use to compute the value of |
139 |
* the returned CompletionStage |
140 |
* @param executor the executor to use for asynchronous execution |
141 |
* @param <U> the function's return type |
142 |
* @return the new CompletionStage |
143 |
*/ |
144 |
public <U> CompletionStage<U> thenApplyAsync |
145 |
(Function<? super T,? extends U> fn, |
146 |
Executor executor); |
147 |
|
148 |
/** |
149 |
* Returns a new CompletionStage that, when this stage completes |
150 |
* normally, is executed with this stage's result as the argument |
151 |
* to the supplied action. |
152 |
* |
153 |
* See the {@link CompletionStage} documentation for rules |
154 |
* covering exceptional completion. |
155 |
* |
156 |
* @param action the action to perform before completing the |
157 |
* returned CompletionStage |
158 |
* @return the new CompletionStage |
159 |
*/ |
160 |
public CompletionStage<Void> thenAccept(Consumer<? super T> action); |
161 |
|
162 |
/** |
163 |
* Returns a new CompletionStage that, when this stage completes |
164 |
* normally, is executed using this stage's default asynchronous |
165 |
* execution facility, with this stage's result as the argument to |
166 |
* the supplied action. |
167 |
* |
168 |
* See the {@link CompletionStage} documentation for rules |
169 |
* covering exceptional completion. |
170 |
* |
171 |
* @param action the action to perform before completing the |
172 |
* returned CompletionStage |
173 |
* @return the new CompletionStage |
174 |
*/ |
175 |
public CompletionStage<Void> thenAcceptAsync(Consumer<? super T> action); |
176 |
|
177 |
/** |
178 |
* Returns a new CompletionStage that, when this stage completes |
179 |
* normally, is executed using the supplied Executor, with this |
180 |
* stage's result as the argument to the supplied action. |
181 |
* |
182 |
* See the {@link CompletionStage} documentation for rules |
183 |
* covering exceptional completion. |
184 |
* |
185 |
* @param action the action to perform before completing the |
186 |
* returned CompletionStage |
187 |
* @param executor the executor to use for asynchronous execution |
188 |
* @return the new CompletionStage |
189 |
*/ |
190 |
public CompletionStage<Void> thenAcceptAsync(Consumer<? super T> action, |
191 |
Executor executor); |
192 |
/** |
193 |
* Returns a new CompletionStage that, when this stage completes |
194 |
* normally, executes the given action. |
195 |
* |
196 |
* See the {@link CompletionStage} documentation for rules |
197 |
* covering exceptional completion. |
198 |
* |
199 |
* @param action the action to perform before completing the |
200 |
* returned CompletionStage |
201 |
* @return the new CompletionStage |
202 |
*/ |
203 |
public CompletionStage<Void> thenRun(Runnable action); |
204 |
|
205 |
/** |
206 |
* Returns a new CompletionStage that, when this stage completes |
207 |
* normally, executes the given action using this stage's default |
208 |
* asynchronous execution facility. |
209 |
* |
210 |
* See the {@link CompletionStage} documentation for rules |
211 |
* covering exceptional completion. |
212 |
* |
213 |
* @param action the action to perform before completing the |
214 |
* returned CompletionStage |
215 |
* @return the new CompletionStage |
216 |
*/ |
217 |
public CompletionStage<Void> thenRunAsync(Runnable action); |
218 |
|
219 |
/** |
220 |
* Returns a new CompletionStage that, when this stage completes |
221 |
* normally, executes the given action using the supplied Executor. |
222 |
* |
223 |
* See the {@link CompletionStage} documentation for rules |
224 |
* covering exceptional completion. |
225 |
* |
226 |
* @param action the action to perform before completing the |
227 |
* returned CompletionStage |
228 |
* @param executor the executor to use for asynchronous execution |
229 |
* @return the new CompletionStage |
230 |
*/ |
231 |
public CompletionStage<Void> thenRunAsync(Runnable action, |
232 |
Executor executor); |
233 |
|
234 |
/** |
235 |
* Returns a new CompletionStage that, when this and the other |
236 |
* given stage both complete normally, is executed with the two |
237 |
* results as arguments to the supplied function. |
238 |
* |
239 |
* See the {@link CompletionStage} documentation for rules |
240 |
* covering exceptional completion. |
241 |
* |
242 |
* @param other the other CompletionStage |
243 |
* @param fn the function to use to compute the value of |
244 |
* the returned CompletionStage |
245 |
* @param <U> the type of the other CompletionStage's result |
246 |
* @param <V> the function's return type |
247 |
* @return the new CompletionStage |
248 |
*/ |
249 |
public <U,V> CompletionStage<V> thenCombine |
250 |
(CompletionStage<? extends U> other, |
251 |
BiFunction<? super T,? super U,? extends V> fn); |
252 |
|
253 |
/** |
254 |
* Returns a new CompletionStage that, when this and the other |
255 |
* given stage complete normally, is executed using this stage's |
256 |
* default asynchronous execution facility, with the two results |
257 |
* as arguments to the supplied function. |
258 |
* |
259 |
* See the {@link CompletionStage} documentation for rules |
260 |
* covering exceptional completion. |
261 |
* |
262 |
* @param other the other CompletionStage |
263 |
* @param fn the function to use to compute the value of |
264 |
* the returned CompletionStage |
265 |
* @param <U> the type of the other CompletionStage's result |
266 |
* @param <V> the function's return type |
267 |
* @return the new CompletionStage |
268 |
*/ |
269 |
public <U,V> CompletionStage<V> thenCombineAsync |
270 |
(CompletionStage<? extends U> other, |
271 |
BiFunction<? super T,? super U,? extends V> fn); |
272 |
|
273 |
/** |
274 |
* Returns a new CompletionStage that, when this and the other |
275 |
* given stage complete normally, is executed using the supplied |
276 |
* executor, with the two results as arguments to the supplied |
277 |
* function. |
278 |
* |
279 |
* See the {@link CompletionStage} documentation for rules |
280 |
* covering exceptional completion. |
281 |
* |
282 |
* @param other the other CompletionStage |
283 |
* @param fn the function to use to compute the value of |
284 |
* the returned CompletionStage |
285 |
* @param executor the executor to use for asynchronous execution |
286 |
* @param <U> the type of the other CompletionStage's result |
287 |
* @param <V> the function's return type |
288 |
* @return the new CompletionStage |
289 |
*/ |
290 |
public <U,V> CompletionStage<V> thenCombineAsync |
291 |
(CompletionStage<? extends U> other, |
292 |
BiFunction<? super T,? super U,? extends V> fn, |
293 |
Executor executor); |
294 |
|
295 |
/** |
296 |
* Returns a new CompletionStage that, when this and the other |
297 |
* given stage both complete normally, is executed with the two |
298 |
* results as arguments to the supplied action. |
299 |
* |
300 |
* See the {@link CompletionStage} documentation for rules |
301 |
* covering exceptional completion. |
302 |
* |
303 |
* @param other the other CompletionStage |
304 |
* @param action the action to perform before completing the |
305 |
* returned CompletionStage |
306 |
* @param <U> the type of the other CompletionStage's result |
307 |
* @return the new CompletionStage |
308 |
*/ |
309 |
public <U> CompletionStage<Void> thenAcceptBoth |
310 |
(CompletionStage<? extends U> other, |
311 |
BiConsumer<? super T, ? super U> action); |
312 |
|
313 |
/** |
314 |
* Returns a new CompletionStage that, when this and the other |
315 |
* given stage complete normally, is executed using this stage's |
316 |
* default asynchronous execution facility, with the two results |
317 |
* as arguments to the supplied action. |
318 |
* |
319 |
* @param other the other CompletionStage |
320 |
* @param action the action to perform before completing the |
321 |
* returned CompletionStage |
322 |
* @param <U> the type of the other CompletionStage's result |
323 |
* @return the new CompletionStage |
324 |
*/ |
325 |
public <U> CompletionStage<Void> thenAcceptBothAsync |
326 |
(CompletionStage<? extends U> other, |
327 |
BiConsumer<? super T, ? super U> action); |
328 |
|
329 |
/** |
330 |
* Returns a new CompletionStage that, when this and the other |
331 |
* given stage complete normally, is executed using the supplied |
332 |
* executor, with the two results as arguments to the supplied |
333 |
* function. |
334 |
* |
335 |
* @param other the other CompletionStage |
336 |
* @param action the action to perform before completing the |
337 |
* returned CompletionStage |
338 |
* @param executor the executor to use for asynchronous execution |
339 |
* @param <U> the type of the other CompletionStage's result |
340 |
* @return the new CompletionStage |
341 |
*/ |
342 |
public <U> CompletionStage<Void> thenAcceptBothAsync |
343 |
(CompletionStage<? extends U> other, |
344 |
BiConsumer<? super T, ? super U> action, |
345 |
Executor executor); |
346 |
|
347 |
/** |
348 |
* Returns a new CompletionStage that, when this and the other |
349 |
* given stage both complete normally, executes the given action. |
350 |
* |
351 |
* See the {@link CompletionStage} documentation for rules |
352 |
* covering exceptional completion. |
353 |
* |
354 |
* @param other the other CompletionStage |
355 |
* @param action the action to perform before completing the |
356 |
* returned CompletionStage |
357 |
* @return the new CompletionStage |
358 |
*/ |
359 |
public CompletionStage<Void> runAfterBoth(CompletionStage<?> other, |
360 |
Runnable action); |
361 |
/** |
362 |
* Returns a new CompletionStage that, when this and the other |
363 |
* given stage complete normally, executes the given action using |
364 |
* this stage's default asynchronous execution facility. |
365 |
* |
366 |
* See the {@link CompletionStage} documentation for rules |
367 |
* covering exceptional completion. |
368 |
* |
369 |
* @param other the other CompletionStage |
370 |
* @param action the action to perform before completing the |
371 |
* returned CompletionStage |
372 |
* @return the new CompletionStage |
373 |
*/ |
374 |
public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other, |
375 |
Runnable action); |
376 |
|
377 |
/** |
378 |
* Returns a new CompletionStage that, when this and the other |
379 |
* given stage complete normally, executes the given action using |
380 |
* the supplied executor. |
381 |
* |
382 |
* See the {@link CompletionStage} documentation for rules |
383 |
* covering exceptional completion. |
384 |
* |
385 |
* @param other the other CompletionStage |
386 |
* @param action the action to perform before completing the |
387 |
* returned CompletionStage |
388 |
* @param executor the executor to use for asynchronous execution |
389 |
* @return the new CompletionStage |
390 |
*/ |
391 |
public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other, |
392 |
Runnable action, |
393 |
Executor executor); |
394 |
/** |
395 |
* Returns a new CompletionStage that, when either this or the |
396 |
* other given stage complete normally, is executed with the |
397 |
* corresponding result as argument to the supplied function. |
398 |
* |
399 |
* See the {@link CompletionStage} documentation for rules |
400 |
* covering exceptional completion. |
401 |
* |
402 |
* @param other the other CompletionStage |
403 |
* @param fn the function to use to compute the value of |
404 |
* the returned CompletionStage |
405 |
* @param <U> the function's return type |
406 |
* @return the new CompletionStage |
407 |
*/ |
408 |
public <U> CompletionStage<U> applyToEither |
409 |
(CompletionStage<? extends T> other, |
410 |
Function<? super T, U> fn); |
411 |
|
412 |
/** |
413 |
* Returns a new CompletionStage that, when either this or the |
414 |
* other given stage complete normally, is executed using this |
415 |
* stage's default asynchronous execution facility, with the |
416 |
* corresponding result as argument to the supplied function. |
417 |
* |
418 |
* See the {@link CompletionStage} documentation for rules |
419 |
* covering exceptional completion. |
420 |
* |
421 |
* @param other the other CompletionStage |
422 |
* @param fn the function to use to compute the value of |
423 |
* the returned CompletionStage |
424 |
* @param <U> the function's return type |
425 |
* @return the new CompletionStage |
426 |
*/ |
427 |
public <U> CompletionStage<U> applyToEitherAsync |
428 |
(CompletionStage<? extends T> other, |
429 |
Function<? super T, U> fn); |
430 |
|
431 |
/** |
432 |
* Returns a new CompletionStage that, when either this or the |
433 |
* other given stage complete normally, is executed using the |
434 |
* supplied executor, with the corresponding result as argument to |
435 |
* the supplied function. |
436 |
* |
437 |
* See the {@link CompletionStage} documentation for rules |
438 |
* covering exceptional completion. |
439 |
* |
440 |
* @param other the other CompletionStage |
441 |
* @param fn the function to use to compute the value of |
442 |
* the returned CompletionStage |
443 |
* @param executor the executor to use for asynchronous execution |
444 |
* @param <U> the function's return type |
445 |
* @return the new CompletionStage |
446 |
*/ |
447 |
public <U> CompletionStage<U> applyToEitherAsync |
448 |
(CompletionStage<? extends T> other, |
449 |
Function<? super T, U> fn, |
450 |
Executor executor); |
451 |
|
452 |
/** |
453 |
* Returns a new CompletionStage that, when either this or the |
454 |
* other given stage complete normally, is executed with the |
455 |
* corresponding result as argument to the supplied action. |
456 |
* |
457 |
* See the {@link CompletionStage} documentation for rules |
458 |
* covering exceptional completion. |
459 |
* |
460 |
* @param other the other CompletionStage |
461 |
* @param action the action to perform before completing the |
462 |
* returned CompletionStage |
463 |
* @return the new CompletionStage |
464 |
*/ |
465 |
public CompletionStage<Void> acceptEither |
466 |
(CompletionStage<? extends T> other, |
467 |
Consumer<? super T> action); |
468 |
|
469 |
/** |
470 |
* Returns a new CompletionStage that, when either this or the |
471 |
* other given stage complete normally, is executed using this |
472 |
* stage's default asynchronous execution facility, with the |
473 |
* corresponding result as argument to the supplied action. |
474 |
* |
475 |
* See the {@link CompletionStage} documentation for rules |
476 |
* covering exceptional completion. |
477 |
* |
478 |
* @param other the other CompletionStage |
479 |
* @param action the action to perform before completing the |
480 |
* returned CompletionStage |
481 |
* @return the new CompletionStage |
482 |
*/ |
483 |
public CompletionStage<Void> acceptEitherAsync |
484 |
(CompletionStage<? extends T> other, |
485 |
Consumer<? super T> action); |
486 |
|
487 |
/** |
488 |
* Returns a new CompletionStage that, when either this or the |
489 |
* other given stage complete normally, is executed using the |
490 |
* supplied executor, with the corresponding result as argument to |
491 |
* the supplied function. |
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 |
* @param executor the executor to use for asynchronous execution |
500 |
* @return the new CompletionStage |
501 |
*/ |
502 |
public CompletionStage<Void> acceptEitherAsync |
503 |
(CompletionStage<? extends T> other, |
504 |
Consumer<? super T> action, |
505 |
Executor executor); |
506 |
|
507 |
/** |
508 |
* Returns a new CompletionStage that, when either this or the |
509 |
* other given stage complete normally, executes the given 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> runAfterEither(CompletionStage<?> other, |
520 |
Runnable action); |
521 |
|
522 |
/** |
523 |
* Returns a new CompletionStage that, when either this or the |
524 |
* other given stage complete normally, executes the given action |
525 |
* using this stage's default asynchronous execution facility. |
526 |
* |
527 |
* See the {@link CompletionStage} documentation for rules |
528 |
* covering exceptional completion. |
529 |
* |
530 |
* @param other the other CompletionStage |
531 |
* @param action the action to perform before completing the |
532 |
* returned CompletionStage |
533 |
* @return the new CompletionStage |
534 |
*/ |
535 |
public CompletionStage<Void> runAfterEitherAsync |
536 |
(CompletionStage<?> other, |
537 |
Runnable action); |
538 |
|
539 |
/** |
540 |
* Returns a new CompletionStage that, when either this or the |
541 |
* other given stage complete normally, executes the given action |
542 |
* using the supplied executor. |
543 |
* |
544 |
* See the {@link CompletionStage} documentation for rules |
545 |
* covering exceptional completion. |
546 |
* |
547 |
* @param other the other CompletionStage |
548 |
* @param action the action to perform before completing the |
549 |
* returned CompletionStage |
550 |
* @param executor the executor to use for asynchronous execution |
551 |
* @return the new CompletionStage |
552 |
*/ |
553 |
public CompletionStage<Void> runAfterEitherAsync |
554 |
(CompletionStage<?> other, |
555 |
Runnable action, |
556 |
Executor executor); |
557 |
|
558 |
/** |
559 |
* Returns a new CompletionStage that, when this stage completes |
560 |
* normally, is executed with this stage's result as the argument |
561 |
* to the supplied function. |
562 |
* |
563 |
* See the {@link CompletionStage} documentation for rules |
564 |
* covering exceptional completion. |
565 |
* |
566 |
* @param fn the function returning a new CompletionStage |
567 |
* @param <U> the type of the returned CompletionStage's result |
568 |
* @return the CompletionStage |
569 |
*/ |
570 |
public <U> CompletionStage<U> thenCompose |
571 |
(Function<? super T, ? extends CompletionStage<U>> fn); |
572 |
|
573 |
/** |
574 |
* Returns a new CompletionStage that, when this stage completes |
575 |
* normally, is executed using this stage's default asynchronous |
576 |
* execution facility, with this stage's result as the argument to the |
577 |
* supplied function. |
578 |
* |
579 |
* See the {@link CompletionStage} documentation for rules |
580 |
* covering exceptional completion. |
581 |
* |
582 |
* @param fn the function returning a new CompletionStage |
583 |
* @param <U> the type of the returned CompletionStage's result |
584 |
* @return the CompletionStage |
585 |
*/ |
586 |
public <U> CompletionStage<U> thenComposeAsync |
587 |
(Function<? super T, ? extends CompletionStage<U>> fn); |
588 |
|
589 |
/** |
590 |
* Returns a new CompletionStage that, when this stage completes |
591 |
* normally, is executed using the supplied Executor, with this |
592 |
* stage's result as the argument to the supplied function. |
593 |
* |
594 |
* See the {@link CompletionStage} documentation for rules |
595 |
* covering exceptional completion. |
596 |
* |
597 |
* @param fn the function returning a new CompletionStage |
598 |
* @param executor the executor to use for asynchronous execution |
599 |
* @param <U> the type of the returned CompletionStage's result |
600 |
* @return the CompletionStage |
601 |
*/ |
602 |
public <U> CompletionStage<U> thenComposeAsync |
603 |
(Function<? super T, ? extends CompletionStage<U>> fn, |
604 |
Executor executor); |
605 |
|
606 |
/** |
607 |
* Returns a new CompletionStage that, when this stage completes |
608 |
* exceptionally, is executed with this stage's exception as the |
609 |
* argument to the supplied function. Otherwise, if this stage |
610 |
* completes normally, then the returned stage also completes |
611 |
* normally with the same value. |
612 |
* |
613 |
* @param fn the function to use to compute the value of the |
614 |
* returned CompletionStage if this CompletionStage completed |
615 |
* exceptionally |
616 |
* @return the new CompletionStage |
617 |
*/ |
618 |
public CompletionStage<T> exceptionally |
619 |
(Function<Throwable, ? extends T> fn); |
620 |
|
621 |
/** |
622 |
* Returns a new CompletionStage with the same result or exception as |
623 |
* this stage, that executes the given action when this stage completes. |
624 |
* |
625 |
* <p>When this stage is complete, the given action is invoked |
626 |
* with the result (or {@code null} if none) and the exception (or |
627 |
* {@code null} if none) of this stage as arguments. The returned |
628 |
* stage is completed when the action returns. If the supplied |
629 |
* action itself encounters an exception, then the returned stage |
630 |
* exceptionally completes with this exception unless this stage |
631 |
* also completed exceptionally (in which case, the returned stage |
632 |
* exceptionally completes with the original exception). |
633 |
* |
634 |
* @param action the action to perform |
635 |
* @return the new CompletionStage |
636 |
*/ |
637 |
public CompletionStage<T> whenComplete |
638 |
(BiConsumer<? super T, ? super Throwable> action); |
639 |
|
640 |
/** |
641 |
* Returns a new CompletionStage with the same result or exception as |
642 |
* this stage, that executes the given action using this stage's |
643 |
* default asynchronous execution facility when this stage completes. |
644 |
* |
645 |
* <p>When this stage is complete, the given action is invoked with the |
646 |
* result (or {@code null} if none) and the exception (or {@code null} |
647 |
* if none) of this stage as arguments. The returned stage is completed |
648 |
* when the action returns. If the supplied action itself encounters an |
649 |
* exception, then the returned stage exceptionally completes with this |
650 |
* exception unless this stage also completed exceptionally. |
651 |
* |
652 |
* @param action the action to perform |
653 |
* @return the new CompletionStage |
654 |
*/ |
655 |
public CompletionStage<T> whenCompleteAsync |
656 |
(BiConsumer<? super T, ? super Throwable> action); |
657 |
|
658 |
/** |
659 |
* Returns a new CompletionStage with the same result or exception as |
660 |
* this stage, that executes the given action using the supplied |
661 |
* Executor when this stage completes. |
662 |
* |
663 |
* <p>When this stage is complete, the given action is invoked with the |
664 |
* result (or {@code null} if none) and the exception (or {@code null} |
665 |
* if none) of this stage as arguments. The returned stage is completed |
666 |
* when the action returns. If the supplied action itself encounters an |
667 |
* exception, then the returned stage exceptionally completes with this |
668 |
* exception unless this stage also completed exceptionally. |
669 |
* |
670 |
* @param action the action to perform |
671 |
* @param executor the executor to use for asynchronous execution |
672 |
* @return the new CompletionStage |
673 |
*/ |
674 |
public CompletionStage<T> whenCompleteAsync |
675 |
(BiConsumer<? super T, ? super Throwable> action, |
676 |
Executor executor); |
677 |
|
678 |
/** |
679 |
* Returns a new CompletionStage that, when this stage completes |
680 |
* either normally or exceptionally, is executed with this stage's |
681 |
* result and exception as arguments to the supplied function. |
682 |
* |
683 |
* <p>When this stage is complete, the given function is invoked |
684 |
* with the result (or {@code null} if none) and the exception (or |
685 |
* {@code null} if none) of this stage as arguments, and the |
686 |
* function's result is used to complete the returned stage. |
687 |
* |
688 |
* @param fn the function to use to compute the value of the |
689 |
* returned CompletionStage |
690 |
* @param <U> the function's return type |
691 |
* @return the new CompletionStage |
692 |
*/ |
693 |
public <U> CompletionStage<U> handle |
694 |
(BiFunction<? super T, Throwable, ? extends U> fn); |
695 |
|
696 |
/** |
697 |
* Returns a new CompletionStage that, when this stage completes |
698 |
* either normally or exceptionally, is executed using this stage's |
699 |
* default asynchronous execution facility, with this stage's |
700 |
* result and exception as arguments to the supplied function. |
701 |
* |
702 |
* <p>When this stage is complete, the given function is invoked |
703 |
* with the result (or {@code null} if none) and the exception (or |
704 |
* {@code null} if none) of this stage as arguments, and the |
705 |
* function's result is used to complete the returned stage. |
706 |
* |
707 |
* @param fn the function to use to compute the value of the |
708 |
* returned CompletionStage |
709 |
* @param <U> the function's return type |
710 |
* @return the new CompletionStage |
711 |
*/ |
712 |
public <U> CompletionStage<U> handleAsync |
713 |
(BiFunction<? super T, Throwable, ? extends U> fn); |
714 |
|
715 |
/** |
716 |
* Returns a new CompletionStage that, when this stage completes |
717 |
* either normally or exceptionally, is executed using the |
718 |
* supplied executor, with this stage's result and exception as |
719 |
* arguments to the supplied function. |
720 |
* |
721 |
* <p>When this stage is complete, the given function is invoked |
722 |
* with the result (or {@code null} if none) and the exception (or |
723 |
* {@code null} if none) of this stage as arguments, and the |
724 |
* function's result is used to complete the returned stage. |
725 |
* |
726 |
* @param fn the function to use to compute the value of the |
727 |
* returned CompletionStage |
728 |
* @param executor the executor to use for asynchronous execution |
729 |
* @param <U> the function's return type |
730 |
* @return the new CompletionStage |
731 |
*/ |
732 |
public <U> CompletionStage<U> handleAsync |
733 |
(BiFunction<? super T, Throwable, ? extends U> fn, |
734 |
Executor executor); |
735 |
|
736 |
/** |
737 |
* Returns a {@link CompletableFuture} maintaining the same |
738 |
* completion properties as this stage. If this stage is already a |
739 |
* CompletableFuture, this method may return this stage itself. |
740 |
* Otherwise, invocation of this method may be equivalent in |
741 |
* effect to {@code thenApply(x -> x)}, but returning an instance |
742 |
* of type {@code CompletableFuture}. A CompletionStage |
743 |
* implementation that does not choose to interoperate with others |
744 |
* may throw {@code UnsupportedOperationException}. |
745 |
* |
746 |
* @return the CompletableFuture |
747 |
* @throws UnsupportedOperationException if this implementation |
748 |
* does not interoperate with CompletableFuture |
749 |
*/ |
750 |
public CompletableFuture<T> toCompletableFuture(); |
751 |
|
752 |
} |