Debian Codegraph @

api/src/main/java/jakarta/enterprise/inject/spi/configurator/BeanConfigurator.java

raw
1 /*
2 * JBoss, Home of Professional Open Source
3 * Copyright 2015, Red Hat, Inc., and individual contributors
4 * by the @authors tag. See the copyright.txt in the distribution for a
5 * full listing of individual contributors.
6 *
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
10 * http://www.apache.org/licenses/LICENSE-2.0
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package jakarta.enterprise.inject.spi.configurator;
18
19 import java.lang.annotation.Annotation;
20 import java.lang.reflect.Type;
21 import java.util.Set;
22 import java.util.function.BiConsumer;
23 import java.util.function.Function;
24
25 import jakarta.enterprise.context.spi.Contextual;
26 import jakarta.enterprise.context.spi.CreationalContext;
27 import jakarta.enterprise.inject.Instance;
28 import jakarta.enterprise.inject.spi.AfterBeanDiscovery;
29 import jakarta.enterprise.inject.spi.AnnotatedType;
30 import jakarta.enterprise.inject.spi.Bean;
31 import jakarta.enterprise.inject.spi.BeanAttributes;
32 import jakarta.enterprise.inject.spi.InjectionPoint;
33 import jakarta.enterprise.inject.spi.PassivationCapable;
34 import jakarta.enterprise.util.TypeLiteral;
35
36 /**
37 * This API is an helper to configure a new {@link Bean} instance.
38 * CDI container must provides an implementation of this interface.
39 *
40 * This builder is not thread safe and shall not be used concurrently.
41 *
42 * <p>CDI Lite implementations are not required to provide support for Portable Extensions.</p>
43 *
44 * @see AfterBeanDiscovery#addBean()
45 * @author Martin Kouba
46 * @author Antoine Sabot-Durand
47 * @param <T> the class of the bean instance
48 * @since 2.0
49 */
50 public interface BeanConfigurator<T> {
51
52 /**
53 * Set the class of the configured Bean.
54 * If not set, the extension class is used.
55 *
56 * @param beanClass class of the configured bean
57 * @return self
58 */
59 BeanConfigurator<T> beanClass(Class<?> beanClass);
60
61 /**
62 * Add an InjectionPoint to the configured bean
63 *
64 * @param injectionPoint the injectionPoint to add
65 * @return self
66 */
67 BeanConfigurator<T> addInjectionPoint(InjectionPoint injectionPoint);
68
69 /**
70 * Add InjectionPoints to the configured bean
71 *
72 * @param injectionPoints the injectionPoints to add
73 * @return self
74 */
75 BeanConfigurator<T> addInjectionPoints(InjectionPoint... injectionPoints);
76
77 /**
78 * Add InjectionPoints to the configured bean
79 *
80 * @param injectionPoints the injectionPoints to add
81 * @return self
82 */
83 BeanConfigurator<T> addInjectionPoints(Set<InjectionPoint> injectionPoints);
84
85 /**
86 * Replace InjectionPoints for the configured bean
87 *
88 * @param injectionPoints the injectionPoints for the configured bean
89 * @return self
90 */
91 BeanConfigurator<T> injectionPoints(InjectionPoint... injectionPoints);
92
93 /**
94 * Replace InjectionPoints for the configured bean
95 *
96 * @param injectionPoints the injectionPoints for the configured bean
97 * @return self
98 */
99 BeanConfigurator<T> injectionPoints(Set<InjectionPoint> injectionPoints);
100
101 /**
102 * Make the configured bean implements {@link PassivationCapable} and its Id for passivation.
103 *
104 *
105 * @param id for
106 * @see PassivationCapable#getId()
107 * @return self
108 */
109 BeanConfigurator<T> id(String id);
110
111 /**
112 * Set a callback to create a bean instance.
113 *
114 * @param <U> instance type
115 * @param callback the callback to create the instance
116 * @return self
117 * @see Contextual#create(CreationalContext)
118 */
119 <U extends T> BeanConfigurator<U> createWith(Function<CreationalContext<U>, U> callback);
120
121 /**
122 * Set a callback to create a bean instance.
123 * <p>
124 * The {@link Instance} argument might be used to simulate producer method parameter injection. However, dependent scoped
125 * bean instances obtained from {@link Instance} during the callback execution remain managed until the produced bean
126 * instance is destroyed. Therefore, applications are encouraged to always destroy unneeded dependent scoped bean instances
127 * obtained from {@link Instance}.
128 *
129 * @param <U> instance type
130 * @param callback the callback to create the instance
131 * @return self
132 */
133 <U extends T> BeanConfigurator<U> produceWith(Function<Instance<Object>, U> callback);
134
135 /**
136 * Set a callback to destroy a bean instance.
137 * <p>
138 * If no destroy callback is specified, a NOOP callback is automatically set.
139 *
140 * @param callback the callback to destroy the instance
141 * @return self
142 */
143 BeanConfigurator<T> destroyWith(BiConsumer<T, CreationalContext<T>> callback);
144
145 /**
146 * Set a callback to destroy a bean instance.
147 * <p>
148 * If no dispose callback is specified, a NOOP callback is automatically set.
149 * <p>
150 * The {@link Instance} argument might be used to simulate disposer method parameter injection. All dependent scoped bean
151 * instances obtained from {@link Instance} during the callback execution are destroyed when the execution completes.
152 *
153 * @param callback the callback to dispose the instance
154 * @return self
155 */
156 BeanConfigurator<T> disposeWith(BiConsumer<T, Instance<Object>> callback);
157
158 /**
159 * Read the information from the given annotated type. All relevant information is overwritten.
160 *
161 * @param <U> instance type
162 * @param type class to read information from
163 * @return self
164 */
165 <U extends T> BeanConfigurator<U> read(AnnotatedType<U> type);
166
167 /**
168 * Read the information from the given bean attributes. All relevant information is overwritten.
169 *
170 * @param beanAttributes beanAttributes to read information from
171 * @return self
172 */
173 BeanConfigurator<T> read(BeanAttributes<?> beanAttributes);
174
175 /**
176 * Add a type to the bean types
177 *
178 * @param type the type to add
179 * @return self
180 */
181 BeanConfigurator<T> addType(Type type);
182
183 /**
184 * Add a type to the bean types
185 *
186 * @param typeLiteral the type to add
187 * @return self
188 */
189 BeanConfigurator<T> addType(TypeLiteral<?> typeLiteral);
190
191 /**
192 * Add types to the bean types
193 *
194 * @param types types to add
195 * @return self
196 */
197 BeanConfigurator<T> addTypes(Type... types);
198
199 /**
200 * Add types to the bean types
201 *
202 * @param types types to add
203 * @return self
204 */
205 BeanConfigurator<T> addTypes(Set<Type> types);
206
207 /**
208 * Adds an unrestricted set of bean types for the given type as if it represented a bean class of a managed bean.
209 * Illegal bean types are omitted.
210 *
211 * @param type to build the closure from
212 * @return self
213 */
214 BeanConfigurator<T> addTransitiveTypeClosure(Type type);
215
216 /**
217 * Replace bean types
218 *
219 * @param types the types of the configured bean
220 * @return self
221 */
222 BeanConfigurator<T> types(Type... types);
223
224 /**
225 * Replace bean types
226 *
227 * @param types the types of the configured bean
228 * @return self
229 */
230 BeanConfigurator<T> types(Set<Type> types);
231
232 /**
233 * Replace Bean scope
234 *
235 * @param scope new scope for the configured bean
236 * @return self
237 */
238 BeanConfigurator<T> scope(Class<? extends Annotation> scope);
239
240 /**
241 * Add a qualifier to the configured bean
242 *
243 * @param qualifier qualifier to add
244 * @return self
245 */
246 BeanConfigurator<T> addQualifier(Annotation qualifier);
247
248 /**
249 * Add qualifiers to the bean.
250 *
251 * @param qualifiers qualifiers to add
252 * @return self
253 */
254 BeanConfigurator<T> addQualifiers(Annotation... qualifiers);
255
256 /**
257 * Add qualifiers to the bean.
258 *
259 * @param qualifiers qualifiers to add
260 * @return self
261 */
262 BeanConfigurator<T> addQualifiers(Set<Annotation> qualifiers);
263
264 /**
265 * Replace all qualifiers.
266 *
267 * @param qualifiers qualifiers for the build bean
268 * @return self
269 */
270 BeanConfigurator<T> qualifiers(Annotation... qualifiers);
271
272 /**
273 * Replace all qualifiers.
274 *
275 * @param qualifiers for the configured bean
276 * @return self
277 */
278 BeanConfigurator<T> qualifiers(Set<Annotation> qualifiers);
279
280 /**
281 * Add a stereotype to the configured bean
282 *
283 * @param stereotype stereotype to add
284 * @return self
285 */
286 BeanConfigurator<T> addStereotype(Class<? extends Annotation> stereotype);
287
288 /**
289 * Add stereotypes to the configured bean
290 *
291 * @param stereotypes stereotypes to add
292 * @return self
293 */
294 BeanConfigurator<T> addStereotypes(Set<Class<? extends Annotation>> stereotypes);
295
296 /**
297 * Replace stereotypes on the configured bean
298 *
299 * @param stereotypes for the configured bean
300 * @return self
301 */
302 BeanConfigurator<T> stereotypes(Set<Class<? extends Annotation>> stereotypes);
303
304 /**
305 * Set the name of the configured bean
306 *
307 * @param name name for the configured bean
308 * @return self
309 */
310 BeanConfigurator<T> name(String name);
311
312 /**
313 * Change the alternative status of the configured bean.
314 * By default the configured bean is not an alternative.
315 *
316 * @param value value for alternative property
317 * @return self
318 */
319 BeanConfigurator<T> alternative(boolean value);
320
321 /**
322 * Set the priority of the configured bean.
323 * By default, the configured bean does not have a priority.
324 * <p>
325 * This is equivalent to putting the {@link jakarta.annotation.Priority Priority}
326 * annotation to an actual bean class or making a custom
327 * {@link jakarta.enterprise.inject.spi.Bean Bean} class implement
328 * {@link jakarta.enterprise.inject.spi.Prioritized Prioritized}.
329 * <p>
330 * This method has no effect if the configured bean is not an alternative.
331 *
332 * @param priority the priority value
333 * @return self
334 */
335 BeanConfigurator<T> priority(int priority);
336
337 }