Debian Codegraph @

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/SyntheticObserverBuilder.java

raw
1 /*
2 * Copyright (c) 2021 Red Hat and others
3 *
4 * This program and the accompanying materials are made available under the
5 * Apache Software License 2.0 which is available at:
6 * https://www.apache.org/licenses/LICENSE-2.0.
7 *
8 * SPDX-License-Identifier: Apache-2.0
9 */
10
11 package jakarta.enterprise.inject.build.compatible.spi;
12
13 import jakarta.enterprise.event.TransactionPhase;
14 import jakarta.enterprise.lang.model.AnnotationInfo;
15 import jakarta.enterprise.lang.model.declarations.ClassInfo;
16 import jakarta.enterprise.lang.model.types.Type;
17
18 import java.lang.annotation.Annotation;
19
20 /**
21 * Builder for synthetic observers.
22 * Instances are not reusable. For each synthetic observer, new instance
23 * must be created by {@link SyntheticComponents#addObserver(Class)}
24 * or {@link SyntheticComponents#addObserver(Type)}.
25 *
26 * @param <T> the observed event type of this synthetic observer
27 * @since 4.0
28 */
29 public interface SyntheticObserverBuilder<T> {
30 /**
31 * Sets the bean class that "declares" this synthetic observer.
32 * <p>
33 * If not called, the class declaring the extension which creates this synthetic observer is used.
34 *
35 * @param declaringClass bean class that "declares" this synthetic observer, must not be {@code null}
36 * @return this {@code SyntheticObserverBuilder}
37 * @throws IllegalStateException if this method is called multiple times
38 */
39 SyntheticObserverBuilder<T> declaringClass(Class<?> declaringClass);
40
41 /**
42 * Sets the bean class that "declares" this synthetic observer.
43 * <p>
44 * If not called, the class declaring the extension which creates this synthetic observer is used.
45 *
46 * @param declaringClass bean class that "declares" this synthetic observer, must not be {@code null}
47 * @return this {@code SyntheticObserverBuilder}
48 * @throws IllegalStateException if this method is called multiple times
49 */
50 SyntheticObserverBuilder<T> declaringClass(ClassInfo declaringClass);
51
52 /**
53 * Adds a marker annotation of given type to the set of qualifiers of this synthetic observer.
54 * This method may be called multiple times to add multiple qualifiers.
55 * <p>
56 * If not called, this synthetic observer will have no qualifier.
57 *
58 * @param annotationType the type of the marker annotation, must not be {@code null}
59 * @return this {@code SyntheticObserverBuilder}
60 */
61 SyntheticObserverBuilder<T> qualifier(Class<? extends Annotation> annotationType);
62
63 /**
64 * Adds given annotation to the set of qualifiers of this synthetic observer.
65 * This method may be called multiple times to add multiple qualifiers.
66 * <p>
67 * If not called, this synthetic observer will have no qualifier.
68 *
69 * @param qualifierAnnotation the annotation, must not be {@code null}
70 * @return this {@code SyntheticObserverBuilder}
71 */
72 SyntheticObserverBuilder<T> qualifier(AnnotationInfo qualifierAnnotation);
73
74 /**
75 * Adds given annotation to the set of qualifiers of this synthetic observer.
76 * This method may be called multiple times to add multiple qualifiers.
77 * <p>
78 * If not called, this synthetic observer will have no qualifier.
79 *
80 * @param qualifierAnnotation the annotation, must not be {@code null}
81 * @return this {@code SyntheticObserverBuilder}
82 */
83 SyntheticObserverBuilder<T> qualifier(Annotation qualifierAnnotation);
84
85 /**
86 * Sets a priority of this synthetic observer.
87 * <p>
88 * If not called, this synthetic observer will have a default priority
89 * of {@link jakarta.interceptor.Interceptor.Priority#APPLICATION Priority.APPLICATION} + 500.
90 *
91 * @param priority the priority of this synthetic observer
92 * @return this {@code SyntheticObserverBuilder}
93 * @throws IllegalStateException if this method is called multiple times
94 */
95 SyntheticObserverBuilder<T> priority(int priority);
96
97 /**
98 * Marks this synthetic observer as asynchronous if desired.
99 * <p>
100 * If not called, this synthetic observer will not be asynchronous.
101 *
102 * @param isAsync whether this synthetic observer should be asynchronous
103 * @return this {@code SyntheticObserverBuilder}
104 * @throws IllegalStateException if this method is called multiple times
105 */
106 SyntheticObserverBuilder<T> async(boolean isAsync);
107
108 /**
109 * Sets the {@link TransactionPhase} during which this synthetic observer should be notified.
110 * If anything else than {@link TransactionPhase#IN_PROGRESS} is passed, this synthetic observer
111 * will be a transactional observer.
112 * <p>
113 * If not called, this synthetic observer will not be a transactional observer.
114 * In other words, the default is {@link TransactionPhase#IN_PROGRESS}.
115 * <p>
116 * Note that transactional observers cannot be asynchronous. If this synthetic observer
117 * is configured to be both transactional and asynchronous, its registration will fail.
118 *
119 * @param transactionPhase the {@link TransactionPhase}, must not be {@code null}
120 * @return this {@code SyntheticObserverBuilder}
121 * @throws IllegalStateException if this method is called multiple times
122 */
123 SyntheticObserverBuilder<T> transactionPhase(TransactionPhase transactionPhase);
124
125 /**
126 * Adds a {@code boolean}-valued parameter to the parameter map. The parameter map is passed
127 * to the {@linkplain SyntheticObserver event notification} function when the event is fired.
128 *
129 * @param key the parameter key, must not be {@code null}
130 * @param value the parameter value
131 * @return this {@code SyntheticObserverBuilder}
132 */
133 SyntheticObserverBuilder<T> withParam(String key, boolean value);
134
135 /**
136 * Adds a {@code boolean} array-valued parameter to the parameter map. The parameter map is passed
137 * to the {@linkplain SyntheticObserver event notification} function when the event is fired.
138 *
139 * @param key the parameter key, must not be {@code null}
140 * @param value the parameter value
141 * @return this {@code SyntheticObserverBuilder}
142 */
143 SyntheticObserverBuilder<T> withParam(String key, boolean[] value);
144
145 /**
146 * Adds an {@code int}-valued parameter to the parameter map. The parameter map is passed
147 * to the {@linkplain SyntheticObserver event notification} function when the event is fired.
148 *
149 * @param key the parameter key, must not be {@code null}
150 * @param value the parameter value
151 * @return this {@code SyntheticObserverBuilder}
152 */
153 SyntheticObserverBuilder<T> withParam(String key, int value);
154
155 /**
156 * Adds an {@code int} array-valued parameter to the parameter map. The parameter map is passed
157 * to the {@linkplain SyntheticObserver event notification} function when the event is fired.
158 *
159 * @param key the parameter key, must not be {@code null}
160 * @param value the parameter value
161 * @return this {@code SyntheticObserverBuilder}
162 */
163 SyntheticObserverBuilder<T> withParam(String key, int[] value);
164
165 /**
166 * Adds a {@code long}-valued parameter to the parameter map. The parameter map is passed
167 * to the {@linkplain SyntheticObserver event notification} function when the event is fired.
168 *
169 * @param key the parameter key, must not be {@code null}
170 * @param value the parameter value
171 * @return this {@code SyntheticObserverBuilder}
172 */
173 SyntheticObserverBuilder<T> withParam(String key, long value);
174
175 /**
176 * Adds a {@code long} array-valued parameter to the parameter map. The parameter map is passed
177 * to the {@linkplain SyntheticObserver event notification} function when the event is fired.
178 *
179 * @param key the parameter key, must not be {@code null}
180 * @param value the parameter value
181 * @return this {@code SyntheticObserverBuilder}
182 */
183 SyntheticObserverBuilder<T> withParam(String key, long[] value);
184
185 /**
186 * Adds a {@code double}-valued parameter to the parameter map. The parameter map is passed
187 * to the {@linkplain SyntheticObserver event notification} function when the event is fired.
188 *
189 * @param key the parameter key, must not be {@code null}
190 * @param value the parameter value
191 * @return this {@code SyntheticObserverBuilder}
192 */
193 SyntheticObserverBuilder<T> withParam(String key, double value);
194
195 /**
196 * Adds a {@code double} array-valued parameter to the parameter map. The parameter map is passed
197 * to the {@linkplain SyntheticObserver event notification} function when the event is fired.
198 *
199 * @param key the parameter key, must not be {@code null}
200 * @param value the parameter value
201 * @return this {@code SyntheticObserverBuilder}
202 */
203 SyntheticObserverBuilder<T> withParam(String key, double[] value);
204
205 /**
206 * Adds a {@code String}-valued parameter to the parameter map. The parameter map is passed
207 * to the {@linkplain SyntheticObserver event notification} function when the event is fired.
208 *
209 * @param key the parameter key, must not be {@code null}
210 * @param value the parameter value
211 * @return this {@code SyntheticObserverBuilder}
212 */
213 SyntheticObserverBuilder<T> withParam(String key, String value);
214
215 /**
216 * Adds a {@code String} array-valued parameter to the parameter map. The parameter map is passed
217 * to the {@linkplain SyntheticObserver event notification} function when the event is fired.
218 *
219 * @param key the parameter key, must not be {@code null}
220 * @param value the parameter value
221 * @return this {@code SyntheticObserverBuilder}
222 */
223 SyntheticObserverBuilder<T> withParam(String key, String[] value);
224
225 /**
226 * Adds an enum-valued parameter to the parameter map. The parameter map is passed
227 * to the {@linkplain SyntheticObserver event notification} function when the event is fired.
228 *
229 * @param key the parameter key, must not be {@code null}
230 * @param value the parameter value
231 * @return this {@code SyntheticObserverBuilder}
232 */
233 SyntheticObserverBuilder<T> withParam(String key, Enum<?> value);
234
235 /**
236 * Adds an enum array-valued parameter to the parameter map. The parameter map is passed
237 * to the {@linkplain SyntheticObserver event notification} function when the event is fired.
238 *
239 * @param key the parameter key, must not be {@code null}
240 * @param value the parameter value
241 * @return this {@code SyntheticObserverBuilder}
242 */
243 SyntheticObserverBuilder<T> withParam(String key, Enum<?>[] value);
244
245 /**
246 * Adds a {@code Class}-valued parameter to the parameter map. The parameter map is passed
247 * to the {@linkplain SyntheticObserver event notification} function when the event is fired.
248 *
249 * @param key the parameter key, must not be {@code null}
250 * @param value the parameter value
251 * @return this {@code SyntheticObserverBuilder}
252 */
253 SyntheticObserverBuilder<T> withParam(String key, Class<?> value);
254
255 /**
256 * Adds a {@code Class}-valued parameter to the parameter map. The parameter map is passed
257 * to the {@linkplain SyntheticObserver event notification} function when the event is fired.
258 * <p>
259 * When looked up from the parameter map in the event notification function, the value will be
260 * an instance of {@link Class}, <em>not</em> a {@code ClassInfo}.
261 *
262 * @param key the parameter key, must not be {@code null}
263 * @param value the parameter value
264 * @return this {@code SyntheticObserverBuilder}
265 */
266 SyntheticObserverBuilder<T> withParam(String key, ClassInfo value);
267
268 /**
269 * Adds a {@code Class} array-valued parameter to the parameter map. The parameter map is passed
270 * to the {@linkplain SyntheticObserver event notification} function when the event is fired.
271 *
272 * @param key the parameter key, must not be {@code null}
273 * @param value the parameter value
274 * @return this {@code SyntheticObserverBuilder}
275 */
276 SyntheticObserverBuilder<T> withParam(String key, Class<?>[] value);
277
278 /**
279 * Adds a {@code Class} array-valued parameter to the parameter map. The parameter map is passed
280 * to the {@linkplain SyntheticObserver event notification} function when the event is fired.
281 * <p>
282 * When looked up from the parameter map in the event notification function, the values will be
283 * instances of {@link Class}, <em>not</em> {@code ClassInfo}.
284 *
285 * @param key the parameter key, must not be {@code null}
286 * @param value the parameter value
287 * @return this {@code SyntheticObserverBuilder}
288 */
289 SyntheticObserverBuilder<T> withParam(String key, ClassInfo[] value);
290
291 /**
292 * Adds an annotation-valued parameter to the parameter map. The parameter map is passed
293 * to the {@linkplain SyntheticObserver event notification} function when the event is fired.
294 * <p>
295 * When looked up from the parameter map in the event notification function, the value will be
296 * an instance of the annotation type, <em>not</em> an {@code AnnotationInfo}.
297 *
298 * @param key the parameter key, must not be {@code null}
299 * @param value the parameter value
300 * @return this {@code SyntheticObserverBuilder}
301 */
302 SyntheticObserverBuilder<T> withParam(String key, AnnotationInfo value);
303
304 /**
305 * Adds an annotation-valued parameter to the parameter map. The parameter map is passed
306 * to the {@linkplain SyntheticObserver event notification} function when the event is fired.
307 *
308 * @param key the parameter key, must not be {@code null}
309 * @param value the parameter value
310 * @return this {@code SyntheticObserverBuilder}
311 */
312 SyntheticObserverBuilder<T> withParam(String key, Annotation value);
313
314 /**
315 * Adds an annotation array-valued parameter to the parameter map. The parameter map is passed
316 * to the {@linkplain SyntheticObserver event notification} function when the event is fired.
317 * <p>
318 * When looked up from the parameter map in the event notification function, the values will be
319 * instances of the corresponding annotation types, <em>not</em> {@code AnnotationInfo}.
320 *
321 * @param key the parameter key, must not be {@code null}
322 * @param value the parameter value
323 * @return this {@code SyntheticObserverBuilder}
324 */
325 SyntheticObserverBuilder<T> withParam(String key, AnnotationInfo[] value);
326
327 /**
328 * Adds an annotation array-valued parameter to the parameter map. The parameter map is passed
329 * to the {@linkplain SyntheticObserver event notification} function when the event is fired.
330 *
331 * @param key the parameter key, must not be {@code null}
332 * @param value the parameter value
333 * @return this {@code SyntheticObserverBuilder}
334 */
335 SyntheticObserverBuilder<T> withParam(String key, Annotation[] value);
336
337 /**
338 * Sets the class of the synthetic observer {@linkplain SyntheticObserver event notification} function.
339 * CDI container will create an instance of the event notification function every time when it needs
340 * to notify the synthetic observer. The class must be {@code public} and have a {@code public}
341 * zero-parameter constructor; it must not be a bean.
342 * <p>
343 * If not called, the synthetic observer registration will fail.
344 *
345 * @param observerClass the {@linkplain SyntheticObserver event notification} function class, must not be {@code null}
346 * @return this {@code SyntheticObserverBuilder}
347 * @throws IllegalStateException if this method is called multiple times
348 */
349 SyntheticObserverBuilder<T> observeWith(Class<? extends SyntheticObserver<T>> observerClass);
350 }