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