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