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 import java.util.function.Supplier; 38 import java.util.function.Consumer; 39 import java.util.function.BiConsumer; 40 import java.util.function.Function; 41 import java.util.function.BiFunction; 42 import java.util.concurrent.Executor; 43 44 /** 45 * A stage of a possibly asynchronous computation, that performs an 46 * action or computes a value when another CompletionStage completes. 47 * A stage completes upon termination of its computation, but this may 48 * in turn trigger other dependent stages. The functionality defined 49 * in this interface takes only a few basic forms, which expand out to 50 * a larger set of methods to capture a range of usage styles: <ul> 51 * 52 * <li>The computation performed by a stage may be expressed as a 53 * Function, Consumer, or Runnable (using methods with names including 54 * <em>apply</em>, <em>accept</em>, or <em>run</em>, respectively) 55 * depending on whether it requires arguments and/or produces results. 56 * For example, {@code stage.thenApply(x -> square(x)).thenAccept(x -> 57 * System.out.print(x)).thenRun(() -> System.out.println())}. An 58 * additional form (<em>compose</em>) applies functions of stages 59 * themselves, rather than their results. </li> 60 * 61 * <li> One stage's execution may be triggered by completion of a 62 * single stage, or both of two stages, or either of two stages. 63 * Dependencies on a single stage are arranged using methods with 64 * prefix <em>then</em>. Those triggered by completion of 65 * <em>both</em> of two stages may <em>combine</em> their results or 66 * effects, using correspondingly named methods. Those triggered by 67 * <em>either</em> of two stages make no guarantees about which of the 68 * results or effects are used for the dependent stage's 69 * computation.</li> 70 * 71 * <li> Dependencies among stages control the triggering of 72 * computations, but do not otherwise guarantee any particular 73 * ordering. Additionally, execution of a new stage's computations may 74 * be arranged in any of three ways: default execution, default 75 * asynchronous execution (using methods with suffix <em>async</em> 76 * that employ the stage's default asynchronous execution facility), 77 * or custom (via a supplied {@link Executor}). The execution 78 * properties of default and async modes are specified by 79 * CompletionStage implementations, not this interface. Methods with 80 * explicit Executor arguments may have arbitrary execution 81 * properties, and might not even support concurrent execution, but 82 * are arranged for processing in a way that accommodates asynchrony. 83 * 84 * <li> Two method forms support processing whether the triggering 85 * stage completed normally or exceptionally: Method {@link 86 * #whenComplete whenComplete} allows injection of an action 87 * regardless of outcome, otherwise preserving the outcome in its 88 * completion. Method {@link #handle handle} additionally allows the 89 * stage to compute a replacement result that may enable further 90 * processing by other dependent stages. In all other cases, if a 91 * stage's computation terminates abruptly with an (unchecked) 92 * exception or error, then all dependent stages requiring its 93 * completion complete exceptionally as well, with a {@link 94 * CompletionException} holding the exception as its cause. If a 95 * stage is dependent on <em>both</em> of two stages, and both 96 * complete exceptionally, then the CompletionException may correspond 97 * to either one of these exceptions. If a stage is dependent on 98 * <em>either</em> of two others, and only one of them completes 99 * exceptionally, no guarantees are made about whether the dependent 100 * stage completes normally or exceptionally. In the case of method 101 * {@code whenComplete}, when the supplied action itself encounters an 102 * exception, then the stage exceptionally completes with this 103 * exception if not already completed exceptionally.</li> 104 * 105 * </ul> 106 * 107 * <p>All methods adhere to the above triggering, execution, and 108 * exceptional completion specifications (which are not repeated in 109 * individual method specifications). Additionally, while arguments 110 * used to pass a completion result (that is, for parameters of type 111 * {@code T}) for methods accepting them may be null, passing a null 112 * value for any other parameter will result in a {@link 113 * NullPointerException} being thrown. 114 * 115 * <p>This interface does not define methods for initially creating, 116 * forcibly completing normally or exceptionally, probing completion 117 * status or results, or awaiting completion of a stage. 118 * Implementations of CompletionStage may provide means of achieving 119 * such effects, as appropriate. Method {@link #toCompletableFuture} 120 * enables interoperability among different implementations of this 121 * interface by providing a common conversion type. 122 * 123 * @author Doug Lea 124 * @since 1.8 125 */ 126 public interface CompletionStage<T> { 127 128 /** 129 * Returns a new CompletionStage that, when this stage completes 130 * normally, is executed with this stage's result as the argument 131 * to the supplied function. 132 * 133 * See the {@link CompletionStage} documentation for rules 134 * covering exceptional completion. 135 * 136 * @param fn the function to use to compute the value of 137 * the 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 153 * the 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 169 * the 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 274 * the 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 complete normally, is executed using this stage's 286 * default asynchronous execution facility, with the two results 287 * 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 294 * the 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 complete normally, is executed using the supplied 306 * executor, with the two results as arguments to the supplied 307 * 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 314 * the 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 complete normally, is executed using this stage's 346 * default asynchronous execution facility, with the two results 347 * as arguments to the supplied action. 348 * 349 * @param other the other CompletionStage 350 * @param action the action to perform before completing the 351 * returned CompletionStage 352 * @param <U> the type of the other CompletionStage's result 353 * @return the new CompletionStage 354 */ thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action)355 public <U> CompletionStage<Void> thenAcceptBothAsync 356 (CompletionStage<? extends U> other, 357 BiConsumer<? super T, ? super U> action); 358 359 /** 360 * Returns a new CompletionStage that, when this and the other 361 * given stage complete normally, is executed using the supplied 362 * executor, with the two results as arguments to the supplied 363 * function. 364 * 365 * @param other the other CompletionStage 366 * @param action the action to perform before completing the 367 * returned CompletionStage 368 * @param executor the executor to use for asynchronous execution 369 * @param <U> the type of the other CompletionStage's result 370 * @return the new CompletionStage 371 */ thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action, Executor executor)372 public <U> CompletionStage<Void> thenAcceptBothAsync 373 (CompletionStage<? extends U> other, 374 BiConsumer<? super T, ? super U> action, 375 Executor executor); 376 377 /** 378 * Returns a new CompletionStage that, when this and the other 379 * given stage both complete normally, executes the given action. 380 * 381 * See the {@link CompletionStage} documentation for rules 382 * covering exceptional completion. 383 * 384 * @param other the other CompletionStage 385 * @param action the action to perform before completing the 386 * returned CompletionStage 387 * @return the new CompletionStage 388 */ runAfterBoth(CompletionStage<?> other, Runnable action)389 public CompletionStage<Void> runAfterBoth(CompletionStage<?> other, 390 Runnable action); 391 /** 392 * Returns a new CompletionStage that, when this and the other 393 * given stage complete normally, executes the given action using 394 * this stage's default asynchronous execution facility. 395 * 396 * See the {@link CompletionStage} documentation for rules 397 * covering exceptional completion. 398 * 399 * @param other the other CompletionStage 400 * @param action the action to perform before completing the 401 * returned CompletionStage 402 * @return the new CompletionStage 403 */ runAfterBothAsync(CompletionStage<?> other, Runnable action)404 public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other, 405 Runnable action); 406 407 /** 408 * Returns a new CompletionStage that, when this and the other 409 * given stage complete normally, executes the given action using 410 * the supplied executor. 411 * 412 * See the {@link CompletionStage} documentation for rules 413 * covering exceptional completion. 414 * 415 * @param other the other CompletionStage 416 * @param action the action to perform before completing the 417 * returned CompletionStage 418 * @param executor the executor to use for asynchronous execution 419 * @return the new CompletionStage 420 */ runAfterBothAsync(CompletionStage<?> other, Runnable action, Executor executor)421 public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other, 422 Runnable action, 423 Executor executor); 424 /** 425 * Returns a new CompletionStage that, when either this or the 426 * other given stage complete normally, is executed with the 427 * corresponding result as argument to the supplied function. 428 * 429 * See the {@link CompletionStage} documentation for rules 430 * covering exceptional completion. 431 * 432 * @param other the other CompletionStage 433 * @param fn the function to use to compute the value of 434 * the returned CompletionStage 435 * @param <U> the function's return type 436 * @return the new CompletionStage 437 */ applyToEither(CompletionStage<? extends T> other, Function<? super T, U> fn)438 public <U> CompletionStage<U> applyToEither 439 (CompletionStage<? extends T> other, 440 Function<? super T, U> fn); 441 442 /** 443 * Returns a new CompletionStage that, when either this or the 444 * other given stage complete normally, is executed using this 445 * stage's default asynchronous execution facility, with the 446 * corresponding result as argument to the supplied function. 447 * 448 * See the {@link CompletionStage} documentation for rules 449 * covering exceptional completion. 450 * 451 * @param other the other CompletionStage 452 * @param fn the function to use to compute the value of 453 * the returned CompletionStage 454 * @param <U> the function's return type 455 * @return the new CompletionStage 456 */ applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T, U> fn)457 public <U> CompletionStage<U> applyToEitherAsync 458 (CompletionStage<? extends T> other, 459 Function<? super T, U> fn); 460 461 /** 462 * Returns a new CompletionStage that, when either this or the 463 * other given stage complete normally, is executed using the 464 * supplied executor, with the corresponding result as argument to 465 * the supplied function. 466 * 467 * See the {@link CompletionStage} documentation for rules 468 * covering exceptional completion. 469 * 470 * @param other the other CompletionStage 471 * @param fn the function to use to compute the value of 472 * the returned CompletionStage 473 * @param executor the executor to use for asynchronous execution 474 * @param <U> the function's return type 475 * @return the new CompletionStage 476 */ applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T, U> fn, Executor executor)477 public <U> CompletionStage<U> applyToEitherAsync 478 (CompletionStage<? extends T> other, 479 Function<? super T, U> fn, 480 Executor executor); 481 482 /** 483 * Returns a new CompletionStage that, when either this or the 484 * other given stage complete normally, is executed with the 485 * corresponding result as argument to the supplied action. 486 * 487 * See the {@link CompletionStage} documentation for rules 488 * covering exceptional completion. 489 * 490 * @param other the other CompletionStage 491 * @param action the action to perform before completing the 492 * returned CompletionStage 493 * @return the new CompletionStage 494 */ acceptEither(CompletionStage<? extends T> other, Consumer<? super T> action)495 public CompletionStage<Void> acceptEither 496 (CompletionStage<? extends T> other, 497 Consumer<? super T> action); 498 499 /** 500 * Returns a new CompletionStage that, when either this or the 501 * other given stage complete normally, is executed using this 502 * stage's default asynchronous execution facility, with the 503 * corresponding result as argument to the supplied action. 504 * 505 * See the {@link CompletionStage} documentation for rules 506 * covering exceptional completion. 507 * 508 * @param other the other CompletionStage 509 * @param action the action to perform before completing the 510 * returned CompletionStage 511 * @return the new CompletionStage 512 */ acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action)513 public CompletionStage<Void> acceptEitherAsync 514 (CompletionStage<? extends T> other, 515 Consumer<? super T> action); 516 517 /** 518 * Returns a new CompletionStage that, when either this or the 519 * other given stage complete normally, is executed using the 520 * supplied executor, with the corresponding result as argument to 521 * the supplied function. 522 * 523 * See the {@link CompletionStage} documentation for rules 524 * covering exceptional completion. 525 * 526 * @param other the other CompletionStage 527 * @param action the action to perform before completing the 528 * returned CompletionStage 529 * @param executor the executor to use for asynchronous execution 530 * @return the new CompletionStage 531 */ acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action, Executor executor)532 public CompletionStage<Void> acceptEitherAsync 533 (CompletionStage<? extends T> other, 534 Consumer<? super T> action, 535 Executor executor); 536 537 /** 538 * Returns a new CompletionStage that, when either this or the 539 * other given stage complete normally, executes the given action. 540 * 541 * See the {@link CompletionStage} documentation for rules 542 * covering exceptional completion. 543 * 544 * @param other the other CompletionStage 545 * @param action the action to perform before completing the 546 * returned CompletionStage 547 * @return the new CompletionStage 548 */ runAfterEither(CompletionStage<?> other, Runnable action)549 public CompletionStage<Void> runAfterEither(CompletionStage<?> other, 550 Runnable action); 551 552 /** 553 * Returns a new CompletionStage that, when either this or the 554 * other given stage complete normally, executes the given action 555 * using this stage's default asynchronous execution facility. 556 * 557 * See the {@link CompletionStage} documentation for rules 558 * covering exceptional completion. 559 * 560 * @param other the other CompletionStage 561 * @param action the action to perform before completing the 562 * returned CompletionStage 563 * @return the new CompletionStage 564 */ runAfterEitherAsync(CompletionStage<?> other, Runnable action)565 public CompletionStage<Void> runAfterEitherAsync 566 (CompletionStage<?> other, 567 Runnable action); 568 569 /** 570 * Returns a new CompletionStage that, when either this or the 571 * other given stage complete normally, executes the given action 572 * using the supplied executor. 573 * 574 * See the {@link CompletionStage} documentation for rules 575 * covering exceptional completion. 576 * 577 * @param other the other CompletionStage 578 * @param action the action to perform before completing the 579 * returned CompletionStage 580 * @param executor the executor to use for asynchronous execution 581 * @return the new CompletionStage 582 */ runAfterEitherAsync(CompletionStage<?> other, Runnable action, Executor executor)583 public CompletionStage<Void> runAfterEitherAsync 584 (CompletionStage<?> other, 585 Runnable action, 586 Executor executor); 587 588 /** 589 * Returns a new CompletionStage that, when this stage completes 590 * normally, is executed with this stage as the argument 591 * to the supplied function. 592 * 593 * See the {@link CompletionStage} documentation for rules 594 * covering exceptional completion. 595 * 596 * @param fn the function returning a new CompletionStage 597 * @param <U> the type of the returned CompletionStage's result 598 * @return the CompletionStage 599 */ thenCompose(Function<? super T, ? extends CompletionStage<U>> fn)600 public <U> CompletionStage<U> thenCompose 601 (Function<? super T, ? extends CompletionStage<U>> fn); 602 603 /** 604 * Returns a new CompletionStage that, when this stage completes 605 * normally, is executed using this stage's default asynchronous 606 * execution facility, with this stage as the argument to the 607 * supplied function. 608 * 609 * See the {@link CompletionStage} documentation for rules 610 * covering exceptional completion. 611 * 612 * @param fn the function returning a new CompletionStage 613 * @param <U> the type of the returned CompletionStage's result 614 * @return the CompletionStage 615 */ thenComposeAsync(Function<? super T, ? extends CompletionStage<U>> fn)616 public <U> CompletionStage<U> thenComposeAsync 617 (Function<? super T, ? extends CompletionStage<U>> fn); 618 619 /** 620 * Returns a new CompletionStage that, when this stage completes 621 * normally, is executed using the supplied Executor, with this 622 * stage's result as the argument to the supplied function. 623 * 624 * See the {@link CompletionStage} documentation for rules 625 * covering exceptional completion. 626 * 627 * @param fn the function returning a new CompletionStage 628 * @param executor the executor to use for asynchronous execution 629 * @param <U> the type of the returned CompletionStage's result 630 * @return the CompletionStage 631 */ thenComposeAsync(Function<? super T, ? extends CompletionStage<U>> fn, Executor executor)632 public <U> CompletionStage<U> thenComposeAsync 633 (Function<? super T, ? extends CompletionStage<U>> fn, 634 Executor executor); 635 636 /** 637 * Returns a new CompletionStage that, when this stage completes 638 * exceptionally, is executed with this stage's exception as the 639 * argument to the supplied function. Otherwise, if this stage 640 * completes normally, then the returned stage also completes 641 * normally with the same value. 642 * 643 * @param fn the function to use to compute the value of the 644 * returned CompletionStage if this CompletionStage completed 645 * exceptionally 646 * @return the new CompletionStage 647 */ exceptionally(Function<Throwable, ? extends T> fn)648 public CompletionStage<T> exceptionally 649 (Function<Throwable, ? extends T> fn); 650 651 /** 652 * Returns a new CompletionStage with the same result or exception as 653 * this stage, that executes the given action when this stage completes. 654 * 655 * <p>When this stage is complete, the given action is invoked with the 656 * result (or {@code null} if none) and the exception (or {@code null} 657 * if none) of this stage as arguments. The returned stage is completed 658 * when the action returns. If the supplied action itself encounters an 659 * exception, then the returned stage exceptionally completes with this 660 * exception unless this stage also completed exceptionally. 661 * 662 * @param action the action to perform 663 * @return the new CompletionStage 664 */ whenComplete(BiConsumer<? super T, ? super Throwable> action)665 public CompletionStage<T> whenComplete 666 (BiConsumer<? super T, ? super Throwable> action); 667 668 /** 669 * Returns a new CompletionStage with the same result or exception as 670 * this stage, that executes the given action using this stage's 671 * default asynchronous execution facility when this stage completes. 672 * 673 * <p>When this stage is complete, the given action is invoked with the 674 * result (or {@code null} if none) and the exception (or {@code null} 675 * if none) of this stage as arguments. The returned stage is completed 676 * when the action returns. If the supplied action itself encounters an 677 * exception, then the returned stage exceptionally completes with this 678 * exception unless this stage also completed exceptionally. 679 * 680 * @param action the action to perform 681 * @return the new CompletionStage 682 */ whenCompleteAsync(BiConsumer<? super T, ? super Throwable> action)683 public CompletionStage<T> whenCompleteAsync 684 (BiConsumer<? super T, ? super Throwable> action); 685 686 /** 687 * Returns a new CompletionStage with the same result or exception as 688 * this stage, that executes the given action using the supplied 689 * Executor when this stage completes. 690 * 691 * <p>When this stage is complete, the given action is invoked with the 692 * result (or {@code null} if none) and the exception (or {@code null} 693 * if none) of this stage as arguments. The returned stage is completed 694 * when the action returns. If the supplied action itself encounters an 695 * exception, then the returned stage exceptionally completes with this 696 * exception unless this stage also completed exceptionally. 697 * 698 * @param action the action to perform 699 * @param executor the executor to use for asynchronous execution 700 * @return the new CompletionStage 701 */ whenCompleteAsync(BiConsumer<? super T, ? super Throwable> action, Executor executor)702 public CompletionStage<T> whenCompleteAsync 703 (BiConsumer<? super T, ? super Throwable> action, 704 Executor executor); 705 706 /** 707 * Returns a new CompletionStage that, when this stage completes 708 * either normally or exceptionally, is executed with this stage's 709 * result and exception as arguments to the supplied function. 710 * 711 * <p>When this stage is complete, the given function is invoked 712 * with the result (or {@code null} if none) and the exception (or 713 * {@code null} if none) of this stage as arguments, and the 714 * function's result is used to complete the returned stage. 715 * 716 * @param fn the function to use to compute the value of the 717 * returned CompletionStage 718 * @param <U> the function's return type 719 * @return the new CompletionStage 720 */ handle(BiFunction<? super T, Throwable, ? extends U> fn)721 public <U> CompletionStage<U> handle 722 (BiFunction<? super T, Throwable, ? extends U> fn); 723 724 /** 725 * Returns a new CompletionStage that, when this stage completes 726 * either normally or exceptionally, is executed using this stage's 727 * default asynchronous execution facility, with this stage's 728 * result and exception as arguments to the supplied function. 729 * 730 * <p>When this stage is complete, the given function is invoked 731 * with the result (or {@code null} if none) and the exception (or 732 * {@code null} if none) of this stage as arguments, and the 733 * function's result is used to complete the returned stage. 734 * 735 * @param fn the function to use to compute the value of the 736 * returned CompletionStage 737 * @param <U> the function's return type 738 * @return the new CompletionStage 739 */ handleAsync(BiFunction<? super T, Throwable, ? extends U> fn)740 public <U> CompletionStage<U> handleAsync 741 (BiFunction<? super T, Throwable, ? extends U> fn); 742 743 /** 744 * Returns a new CompletionStage that, when this stage completes 745 * either normally or exceptionally, is executed using the 746 * supplied executor, with this stage's result and exception as 747 * arguments to the supplied function. 748 * 749 * <p>When this stage is complete, the given function is invoked 750 * with the result (or {@code null} if none) and the exception (or 751 * {@code null} if none) of this stage as arguments, and the 752 * function's result is used to complete the returned stage. 753 * 754 * @param fn the function to use to compute the value of the 755 * returned CompletionStage 756 * @param executor the executor to use for asynchronous execution 757 * @param <U> the function's return type 758 * @return the new CompletionStage 759 */ handleAsync(BiFunction<? super T, Throwable, ? extends U> fn, Executor executor)760 public <U> CompletionStage<U> handleAsync 761 (BiFunction<? super T, Throwable, ? extends U> fn, 762 Executor executor); 763 764 /** 765 * Returns a {@link CompletableFuture} maintaining the same 766 * completion properties as this stage. If this stage is already a 767 * CompletableFuture, this method may return this stage itself. 768 * Otherwise, invocation of this method may be equivalent in 769 * effect to {@code thenApply(x -> x)}, but returning an instance 770 * of type {@code CompletableFuture}. A CompletionStage 771 * implementation that does not choose to interoperate with others 772 * may throw {@code UnsupportedOperationException}. 773 * 774 * @return the CompletableFuture 775 * @throws UnsupportedOperationException if this implementation 776 * does not interoperate with CompletableFuture 777 */ toCompletableFuture()778 public CompletableFuture<T> toCompletableFuture(); 779 780 } 781