1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
/*
* Copyright (c) OSGi Alliance (2014, 2017). All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.osgi.util.promise;
import static java.util.Objects.requireNonNull;
import java.util.concurrent.Executor;
import java.util.concurrent.ScheduledExecutorService;
/**
* A Deferred Promise resolution.
*
* <p>
* Instances of this class can be used to create a {@link Promise} that can be
* resolved in the future. The {@link #getPromise() associated} Promise can be
* successfully resolved with {@link #resolve(Object)} or resolved with a
* failure with {@link #fail(Throwable)}. It can also be resolved with the
* resolution of another promise using {@link #resolveWith(Promise)}.
*
* <p>
* The associated Promise can be provided to any one, but the Deferred object
* should be made available only to the party that will responsible for
* resolving the Promise.
*
* @param <T> The value type associated with the created Promise.
*
* @Immutable
* @author $Id$
*/
public class Deferred<T> {
private final PromiseImpl<T> promise;
/**
* Create a new Deferred.
* <p>
* The default callback executor and default scheduled executor will be
* used.
*/
public Deferred() {
this(null, null);
}
/**
* Create a new Deferred with the specified callback executor.
* <p>
* The default scheduled executor will be used.
*
* @param callbackExecutor The executor to use for callbacks. {@code null}
* can be specified for the default callback executor.
* @since 1.1
*/
public Deferred(Executor callbackExecutor) {
this(callbackExecutor, null);
}
/**
* Create a new Deferred with the specified callback and scheduled
* executors.
*
* @param callbackExecutor The executor to use for callbacks. {@code null}
* can be specified for the default callback executor.
* @param scheduledExecutor The scheduled executor for use for scheduled
* operations. {@code null} can be specified for the default
* scheduled executor.
* @since 1.1
*/
public Deferred(Executor callbackExecutor,
ScheduledExecutorService scheduledExecutor) {
promise = new PromiseImpl<>(callbackExecutor, scheduledExecutor);
}
/**
* Returns the Promise associated with this Deferred.
* <p>
* All Promise objects created by the associated Promise will use the
* executors of the associated Promise.
*
* @return The Promise associated with this Deferred.
*/
public Promise<T> getPromise() {
return promise;
}
/**
* Successfully resolve the Promise associated with this Deferred.
*
* <p>
* After the associated Promise is resolved with the specified value, all
* registered {@link Promise#onResolve(Runnable) callbacks} are called and
* any {@link Promise#then(Success, Failure) chained} Promises are resolved.
* This may occur asynchronously to this method.
* <p>
* Resolving the associated Promise <i>happens-before</i> any registered
* callback is called. That is, in a registered callback,
* {@link Promise#isDone()} must return {@code true} and
* {@link Promise#getValue()} and {@link Promise#getFailure()} must not
* block.
*
* @param value The value of the resolved Promise.
* @throws IllegalStateException If the associated Promise was already
* resolved.
*/
public void resolve(T value) {
promise.resolve(value, null);
}
/**
* Fail the Promise associated with this Deferred.
*
* <p>
* After the associated Promise is resolved with the specified failure, all
* registered {@link Promise#onResolve(Runnable) callbacks} are called and
* any {@link Promise#then(Success, Failure) chained} Promises are resolved.
* This may occur asynchronously to this method.
* <p>
* Resolving the associated Promise <i>happens-before</i> any registered
* callback is called. That is, in a registered callback,
* {@link Promise#isDone()} must return {@code true} and
* {@link Promise#getValue()} and {@link Promise#getFailure()} must not
* block.
*
* @param failure The failure of the resolved Promise. Must not be
* {@code null}.
* @throws IllegalStateException If the associated Promise was already
* resolved.
*/
public void fail(Throwable failure) {
promise.resolve(null, requireNonNull(failure));
}
/**
* Resolve the Promise associated with this Deferred with the specified
* Promise.
*
* <p>
* If the specified Promise is successfully resolved, the associated Promise
* is resolved with the value of the specified Promise. If the specified
* Promise is resolved with a failure, the associated Promise is resolved
* with the failure of the specified Promise.
*
* <p>
* After the associated Promise is resolved with the specified Promise, all
* registered {@link Promise#onResolve(Runnable) callbacks} are called and
* any {@link Promise#then(Success, Failure) chained} Promises are resolved.
* This may occur asynchronously to this method.
* <p>
* Resolving the associated Promise <i>happens-before</i> any registered
* callback is called. That is, in a registered callback,
* {@link Promise#isDone()} must return {@code true} and
* {@link Promise#getValue()} and {@link Promise#getFailure()} must not
* block.
*
* @param with A Promise whose value or failure must be used to resolve the
* associated Promise. Must not be {@code null}.
* @return A Promise that is resolved only when the associated Promise is
* resolved by the specified Promise. The returned Promise must be
* successfully resolved with the value {@code null}, if the
* associated Promise was resolved by the specified Promise. The
* returned Promise must be resolved with a failure of
* {@link IllegalStateException}, if the associated Promise was
* already resolved when the specified Promise was resolved.
*/
public Promise<Void> resolveWith(Promise<? extends T> with) {
return promise.resolveWith(with);
}
/**
* Returns a string representation of the associated Promise.
*
* @return A string representation of the associated Promise.
* @since 1.1
*/
@Override
public String toString() {
return promise.toString();
}
}
|
