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