Debian Codegraph @

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/SyntheticBeanBuilder.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.lang.model.AnnotationInfo;
14 import jakarta.enterprise.lang.model.declarations.ClassInfo;
15 import jakarta.enterprise.lang.model.types.Type;
16
17 import java.lang.annotation.Annotation;
18
19 /**
20 * Builder for synthetic beans.
21 * Instances are not reusable. For each synthetic bean, new instance
22 * must be created by {@link SyntheticComponents#addBean(Class)}.
23 *
24 * @param <T> the bean class of this synthetic bean
25 * @since 4.0
26 */
27 public interface SyntheticBeanBuilder<T> {
28 /**
29 * Adds {@code type} to the set of bean types of this synthetic bean. This method may be called
30 * multiple times to add multiple bean types.
31 * <p>
32 * If not called, the set of bean types of this synthetic bean will be a singleton set
33 * containing {@code java.lang.Object}.
34 *
35 * @param type the bean type, must not be {@code null}
36 * @return this {@code SyntheticBeanBuilder}
37 */
38 SyntheticBeanBuilder<T> type(Class<?> type);
39
40 /**
41 * Adds {@code type} to the set of bean types of this synthetic bean. This method may be called
42 * multiple times to add multiple bean types.
43 * <p>
44 * If not called, the set of bean types of this synthetic bean will be a singleton set
45 * containing {@code java.lang.Object}.
46 *
47 * @param type the bean type, must not be {@code null}
48 * @return this {@code SyntheticBeanBuilder}
49 */
50 SyntheticBeanBuilder<T> type(ClassInfo type);
51
52 /**
53 * Adds {@code type} to the set of bean types of this synthetic bean. This method may be called
54 * multiple times to add multiple bean types.
55 * <p>
56 * If not called, the set of bean types of this synthetic bean will be a singleton set
57 * containing {@code java.lang.Object}.
58 *
59 * @param type the bean type, must not be {@code null}
60 * @return this {@code SyntheticBeanBuilder}
61 */
62 SyntheticBeanBuilder<T> type(Type type);
63
64 /**
65 * Adds a marker annotation of given type to the set of qualifiers of this synthetic bean.
66 * This method may be called multiple times to add multiple qualifiers.
67 * <p>
68 * If not called, this synthetic bean will have the {@code @Default} qualifier
69 * (and the {@code @Any} qualifier that all beans have).
70 *
71 * @param annotationType the type of the marker annotation, must not be {@code null}
72 * @return this {@code SyntheticBeanBuilder}
73 */
74 SyntheticBeanBuilder<T> qualifier(Class<? extends Annotation> annotationType);
75
76 /**
77 * Adds given annotation to the set of qualifiers of this synthetic bean.
78 * This method may be called multiple times to add multiple qualifiers.
79 * <p>
80 * If not called, this synthetic bean will have the {@code @Default} qualifier
81 * (and the {@code @Any} qualifier that all beans have).
82 *
83 * @param qualifierAnnotation the annotation, must not be {@code null}
84 * @return this {@code SyntheticBeanBuilder}
85 */
86 SyntheticBeanBuilder<T> qualifier(AnnotationInfo qualifierAnnotation);
87
88 /**
89 * Adds given annotation to the set of qualifiers of this synthetic bean.
90 * This method may be called multiple times to add multiple qualifiers.
91 * <p>
92 * If not called, this synthetic bean will have the {@code @Default} qualifier
93 * (and the {@code @Any} qualifier that all beans have).
94 *
95 * @param qualifierAnnotation the annotation, must not be {@code null}
96 * @return this {@code SyntheticBeanBuilder}
97 */
98 SyntheticBeanBuilder<T> qualifier(Annotation qualifierAnnotation);
99
100 /**
101 * Sets the scope of this synthetic bean to given scope type.
102 * <p>
103 * If not called, this synthetic bean will be {@code @Dependent}.
104 *
105 * @param scopeAnnotation the scope type, must not be {@code null}
106 * @return this {@code SyntheticBeanBuilder}
107 * @throws IllegalStateException if this method is called multiple times
108 */
109 SyntheticBeanBuilder<T> scope(Class<? extends Annotation> scopeAnnotation);
110
111 /**
112 * Marks this synthetic bean as an alternative if desired. To make this synthetic bean
113 * an enabled alternative, call both {@code alternative(true)} and {@code priority(some priority)}.
114 * <p>
115 * If this synthetic bean is an alternative, not setting a priority means
116 * that it is not enabled, which is equivalent to not registering it at all.
117 * <p>
118 * If not called, this synthetic bean will not be an alternative.
119 *
120 * @param isAlternative whether this synthetic bean should be an alternative
121 * @return this {@code SyntheticBeanBuilder}
122 * @throws IllegalStateException if this method is called multiple times
123 */
124 SyntheticBeanBuilder<T> alternative(boolean isAlternative);
125
126 /**
127 * Sets a priority of this synthetic bean. To make this synthetic bean an enabled alternative,
128 * call both {@code alternative(true)} and {@code priority(some priority)}.
129 * <p>
130 * If this synthetic bean is an alternative, not setting a priority means
131 * that it is not enabled, which is equivalent to not registering it at all.
132 * <p>
133 * If not called, this synthetic bean will not have a priority.
134 * If this synthetic bean is not an alternative, the priority is ignored.
135 *
136 * @param priority the priority of this synthetic bean
137 * @return this {@code SyntheticBeanBuilder}
138 * @throws IllegalStateException if this method is called multiple times
139 */
140 SyntheticBeanBuilder<T> priority(int priority);
141
142 /**
143 * Sets the bean name of this synthetic bean. If {@code beanName} is {@code null},
144 * this synthetic bean will not have a name.
145 * <p>
146 * If not called, this synthetic bean will not have a name.
147 *
148 * @param beanName the bean name of this synthetic bean
149 * @return this {@code SyntheticBeanBuilder}
150 * @throws IllegalStateException if this method is called multiple times
151 */
152 SyntheticBeanBuilder<T> name(String beanName);
153
154 /**
155 * Adds {@code stereotypeAnnotation} to the set of stereotypes of this synthetic bean.
156 * This method may be called multiple times to add multiple stereotypes.
157 * <p>
158 * If not called, this synthetic bean will have no stereotype.
159 *
160 * @param stereotypeAnnotation the stereotype, must not be {@code null}
161 * @return this {@code SyntheticBeanBuilder}
162 */
163 SyntheticBeanBuilder<T> stereotype(Class<? extends Annotation> stereotypeAnnotation);
164
165 /**
166 * Adds {@code stereotypeAnnotation} to the set of stereotypes of this synthetic bean.
167 * This method may be called multiple times to add multiple stereotypes.
168 * <p>
169 * If not called, this synthetic bean will have no stereotype.
170 *
171 * @param stereotypeAnnotation the stereotype, must not be {@code null}
172 * @return this {@code SyntheticBeanBuilder}
173 */
174 SyntheticBeanBuilder<T> stereotype(ClassInfo stereotypeAnnotation);
175
176 /**
177 * Adds a {@code boolean}-valued parameter to the parameter map. The parameter map is passed
178 * to the {@linkplain SyntheticBeanCreator creation} and {@linkplain SyntheticBeanDisposer destruction}
179 * functions when a bean instance is created/destroyed.
180 *
181 * @param key the parameter key, must not be {@code null}
182 * @param value the parameter value
183 * @return this {@code SyntheticBeanBuilder}
184 */
185 SyntheticBeanBuilder<T> withParam(String key, boolean value);
186
187 /**
188 * Adds a {@code boolean} array-valued parameter to the parameter map. The parameter map is passed
189 * to the {@linkplain SyntheticBeanCreator creation} and {@linkplain SyntheticBeanDisposer destruction}
190 * functions when a bean instance is created/destroyed.
191 *
192 * @param key the parameter key, must not be {@code null}
193 * @param value the parameter value
194 * @return this {@code SyntheticBeanBuilder}
195 */
196 SyntheticBeanBuilder<T> withParam(String key, boolean[] value);
197
198 /**
199 * Adds an {@code int}-valued parameter to the parameter map. The parameter map is passed
200 * to the {@linkplain SyntheticBeanCreator creation} and {@linkplain SyntheticBeanDisposer destruction}
201 * functions when a bean instance is created/destroyed.
202 *
203 * @param key the parameter key, must not be {@code null}
204 * @param value the parameter value
205 * @return this {@code SyntheticBeanBuilder}
206 */
207 SyntheticBeanBuilder<T> withParam(String key, int value);
208
209 /**
210 * Adds an {@code int} array-valued parameter to the parameter map. The parameter map is passed
211 * to the {@linkplain SyntheticBeanCreator creation} and {@linkplain SyntheticBeanDisposer destruction}
212 * functions when a bean instance is created/destroyed.
213 *
214 * @param key the parameter key, must not be {@code null}
215 * @param value the parameter value
216 * @return this {@code SyntheticBeanBuilder}
217 */
218 SyntheticBeanBuilder<T> withParam(String key, int[] value);
219
220 /**
221 * Adds a {@code long}-valued parameter to the parameter map. The parameter map is passed
222 * to the {@linkplain SyntheticBeanCreator creation} and {@linkplain SyntheticBeanDisposer destruction}
223 * functions when a bean instance is created/destroyed.
224 *
225 * @param key the parameter key, must not be {@code null}
226 * @param value the parameter value
227 * @return this {@code SyntheticBeanBuilder}
228 */
229 SyntheticBeanBuilder<T> withParam(String key, long value);
230
231 /**
232 * Adds a {@code long} array-valued parameter to the parameter map. The parameter map is passed
233 * to the {@linkplain SyntheticBeanCreator creation} and {@linkplain SyntheticBeanDisposer destruction}
234 * functions when a bean instance is created/destroyed.
235 *
236 * @param key the parameter key, must not be {@code null}
237 * @param value the parameter value
238 * @return this {@code SyntheticBeanBuilder}
239 */
240 SyntheticBeanBuilder<T> withParam(String key, long[] value);
241
242 /**
243 * Adds a {@code double}-valued parameter to the parameter map. The parameter map is passed
244 * to the {@linkplain SyntheticBeanCreator creation} and {@linkplain SyntheticBeanDisposer destruction}
245 * functions when a bean instance is created/destroyed.
246 *
247 * @param key the parameter key, must not be {@code null}
248 * @param value the parameter value
249 * @return this {@code SyntheticBeanBuilder}
250 */
251 SyntheticBeanBuilder<T> withParam(String key, double value);
252
253 /**
254 * Adds a {@code double} array-valued parameter to the parameter map. The parameter map is passed
255 * to the {@linkplain SyntheticBeanCreator creation} and {@linkplain SyntheticBeanDisposer destruction}
256 * functions when a bean instance is created/destroyed.
257 *
258 * @param key the parameter key, must not be {@code null}
259 * @param value the parameter value
260 * @return this {@code SyntheticBeanBuilder}
261 */
262 SyntheticBeanBuilder<T> withParam(String key, double[] value);
263
264 /**
265 * Adds a {@code String}-valued parameter to the parameter map. The parameter map is passed
266 * to the {@linkplain SyntheticBeanCreator creation} and {@linkplain SyntheticBeanDisposer destruction}
267 * functions when a bean instance is created/destroyed.
268 *
269 * @param key the parameter key, must not be {@code null}
270 * @param value the parameter value
271 * @return this {@code SyntheticBeanBuilder}
272 */
273 SyntheticBeanBuilder<T> withParam(String key, String value);
274
275 /**
276 * Adds a {@code String} array-valued parameter to the parameter map. The parameter map is passed
277 * to the {@linkplain SyntheticBeanCreator creation} and {@linkplain SyntheticBeanDisposer destruction}
278 * functions when a bean instance is created/destroyed.
279 *
280 * @param key the parameter key, must not be {@code null}
281 * @param value the parameter value
282 * @return this {@code SyntheticBeanBuilder}
283 */
284 SyntheticBeanBuilder<T> withParam(String key, String[] value);
285
286 /**
287 * Adds an enum-valued parameter to the parameter map. The parameter map is passed
288 * to the {@linkplain SyntheticBeanCreator creation} and {@linkplain SyntheticBeanDisposer destruction}
289 * functions when a bean instance is created/destroyed.
290 *
291 * @param key the parameter key, must not be {@code null}
292 * @param value the parameter value
293 * @return this {@code SyntheticBeanBuilder}
294 */
295 SyntheticBeanBuilder<T> withParam(String key, Enum<?> value);
296
297 /**
298 * Adds an enum array-valued parameter to the parameter map. The parameter map is passed
299 * to the {@linkplain SyntheticBeanCreator creation} and {@linkplain SyntheticBeanDisposer destruction}
300 * functions when a bean instance is created/destroyed.
301 *
302 * @param key the parameter key, must not be {@code null}
303 * @param value the parameter value
304 * @return this {@code SyntheticBeanBuilder}
305 */
306 SyntheticBeanBuilder<T> withParam(String key, Enum<?>[] value);
307
308 /**
309 * Adds a {@code Class}-valued parameter to the parameter map. The parameter map is passed
310 * to the {@linkplain SyntheticBeanCreator creation} and {@linkplain SyntheticBeanDisposer destruction}
311 * functions when a bean instance is created/destroyed.
312 *
313 * @param key the parameter key, must not be {@code null}
314 * @param value the parameter value
315 * @return this {@code SyntheticBeanBuilder}
316 */
317 SyntheticBeanBuilder<T> withParam(String key, Class<?> value);
318
319 /**
320 * Adds a {@code Class}-valued parameter to the parameter map. The parameter map is passed
321 * to the {@linkplain SyntheticBeanCreator creation} and {@linkplain SyntheticBeanDisposer destruction}
322 * functions when a bean instance is created/destroyed.
323 * <p>
324 * When looked up from the parameter map in the creation/destruction function, the value will be
325 * an instance of {@link Class}, <em>not</em> a {@code ClassInfo}.
326 *
327 * @param key the parameter key, must not be {@code null}
328 * @param value the parameter value
329 * @return this {@code SyntheticBeanBuilder}
330 */
331 SyntheticBeanBuilder<T> withParam(String key, ClassInfo value);
332
333 /**
334 * Adds a {@code Class} array-valued parameter to the parameter map. The parameter map is passed
335 * to the {@linkplain SyntheticBeanCreator creation} and {@linkplain SyntheticBeanDisposer destruction}
336 * functions when a bean instance is created/destroyed.
337 *
338 * @param key the parameter key, must not be {@code null}
339 * @param value the parameter value
340 * @return this {@code SyntheticBeanBuilder}
341 */
342 SyntheticBeanBuilder<T> withParam(String key, Class<?>[] value);
343
344 /**
345 * Adds a {@code Class} array-valued parameter to the parameter map. The parameter map is passed
346 * to the {@linkplain SyntheticBeanCreator creation} and {@linkplain SyntheticBeanDisposer destruction}
347 * functions when a bean instance is created/destroyed.
348 * <p>
349 * When looked up from the parameter map in the creation/destruction function, the values will be
350 * instances of {@link Class}, <em>not</em> {@code ClassInfo}.
351 *
352 * @param key the parameter key, must not be {@code null}
353 * @param value the parameter value
354 * @return this {@code SyntheticBeanBuilder}
355 */
356 SyntheticBeanBuilder<T> withParam(String key, ClassInfo[] value);
357
358 /**
359 * Adds an annotation-valued parameter to the parameter map. The parameter map is passed
360 * to the {@linkplain SyntheticBeanCreator creation} and {@linkplain SyntheticBeanDisposer destruction}
361 * functions when a bean instance is created/destroyed.
362 * <p>
363 * When looked up from the parameter map in the creation/destruction function, the value will be
364 * an instance of the annotation type, <em>not</em> an {@code AnnotationInfo}.
365 *
366 * @param key the parameter key, must not be {@code null}
367 * @param value the parameter value
368 * @return this {@code SyntheticBeanBuilder}
369 */
370 SyntheticBeanBuilder<T> withParam(String key, AnnotationInfo value);
371
372 /**
373 * Adds an annotation-valued parameter to the parameter map. The parameter map is passed
374 * to the {@linkplain SyntheticBeanCreator creation} and {@linkplain SyntheticBeanDisposer destruction}
375 * functions when a bean instance is created/destroyed.
376 *
377 * @param key the parameter key, must not be {@code null}
378 * @param value the parameter value
379 * @return this {@code SyntheticBeanBuilder}
380 */
381 SyntheticBeanBuilder<T> withParam(String key, Annotation value);
382
383 /**
384 * Adds an annotation array-valued parameter to the parameter map. The parameter map is passed
385 * to the {@linkplain SyntheticBeanCreator creation} and {@linkplain SyntheticBeanDisposer destruction}
386 * functions when a bean instance is created/destroyed.
387 * <p>
388 * When looked up from the parameter map in the creation/destruction function, the values will be
389 * instances of the corresponding annotation types, <em>not</em> {@code AnnotationInfo}.
390 *
391 * @param key the parameter key, must not be {@code null}
392 * @param value the parameter value
393 * @return this {@code SyntheticBeanBuilder}
394 */
395 SyntheticBeanBuilder<T> withParam(String key, AnnotationInfo[] value);
396
397 /**
398 * Adds an annotation array-valued parameter to the parameter map. The parameter map is passed
399 * to the {@linkplain SyntheticBeanCreator creation} and {@linkplain SyntheticBeanDisposer destruction}
400 * functions when a bean instance is created/destroyed.
401 *
402 * @param key the parameter key, must not be {@code null}
403 * @param value the parameter value
404 * @return this {@code SyntheticBeanBuilder}
405 */
406 SyntheticBeanBuilder<T> withParam(String key, Annotation[] value);
407
408 /**
409 * Sets the class of the synthetic bean {@linkplain SyntheticBeanCreator creation} function.
410 * CDI container will create an instance of the creation function every time when it needs
411 * to obtain an instance of the synthetic bean. The class must be {@code public} and have
412 * a {@code public} zero-parameter constructor; it must not be a bean.
413 * <p>
414 * If not called, the synthetic bean registration will fail.
415 *
416 * @param creatorClass the {@linkplain SyntheticBeanCreator creation} function class, must not be {@code null}
417 * @return this {@code SyntheticBeanBuilder}
418 * @throws IllegalStateException if this method is called multiple times
419 */
420 SyntheticBeanBuilder<T> createWith(Class<? extends SyntheticBeanCreator<T>> creatorClass);
421
422 /**
423 * Sets the class of the synthetic bean {@linkplain SyntheticBeanDisposer destruction} function.
424 * CDI container will create an instance of the destruction function every time when it needs
425 * to destruction an instance of the synthetic bean. The class must be {@code public} and have
426 * a {@code public} zero-parameter constructor; it must not be a bean.
427 * <p>
428 * If not called, a noop destruction function will be used.
429 *
430 * @param disposerClass the {@linkplain SyntheticBeanDisposer destruction} function class, must not be {@code null}
431 * @return this {@code SyntheticBeanBuilder}
432 * @throws IllegalStateException if this method is called multiple times
433 */
434 SyntheticBeanBuilder<T> disposeWith(Class<? extends SyntheticBeanDisposer<T>> disposerClass);
435 }