Debian Codegraph @

spec/src/main/doc/spi.asciidoc

raw
1 [[spi]]
2
3 == Portable extensions
4
5 A portable extension may integrate with the container by:
6
7 * Providing its own beans, interceptors and decorators to the container
8 * Injecting dependencies into its own objects using the dependency injection service
9 * Providing a context implementation for a custom scope
10 * Augmenting or overriding the annotation-based metadata with metadata from some other source
11
12
13 [[bean]]
14
15 === The +Bean+ interface
16
17 The +BeanAttributes+ interface exposes the basic attributes of a bean.
18
19 [source, java]
20 ----
21 public interface BeanAttributes<T> {
22 public Set<Type> getTypes();
23 public Set<Annotation> getQualifiers();
24 public Class<? extends Annotation> getScope();
25 public String getName();
26 public Set<Class<? extends Annotation>> getStereotypes();
27 public boolean isAlternative();
28 }
29 ----
30
31 * +getTypes()+, +getQualifiers()+, +getScope()+, +getName()+ and +getStereotypes()+ must return the bean types, qualifiers, scope type, bean name and stereotypes of the bean, as defined in <<concepts>>.
32 * +isAlternative()+ must return +true+ if the bean is an alternative, and +false+ otherwise.
33
34 The interface +javax.enterprise.inject.spi.Bean+ defines everything the container needs to manage instances of a certain bean.
35
36 [source, java]
37 ----
38 public interface Bean<T> extends Contextual<T>, BeanAttributes<T> {
39 public Class<?> getBeanClass();
40 public Set<InjectionPoint> getInjectionPoints();
41 public boolean isNullable();
42 }
43 ----
44
45 * +getBeanClass()+ returns the bean class of the managed bean or session bean or of the bean that declares the producer method or field.
46 * +getInjectionPoints()+ returns a set of +InjectionPoint+ objects, defined in <<injection_point>>, representing injection points of the bean, that will be validated by the container at initialization time.
47 * +isNullable()+ is deprecated in CDI 1.1 and should be ignored by the container.
48
49 Note that implementations of +Bean+ must also implement the inherited operations defined by the +Contextual+ interface defined in <<contextual>>.
50
51 An instance of +Bean+ must exist for every enabled bean.
52
53 A portable extension may add support for new kinds of beans beyond those defined by the this specification (managed beans, session beans, producer methods, producer fields and resources) by implementing +Bean+ and registering beans with the container, using the mechanism defined in <<abd>>.
54
55 Custom implementations of +Bean+ are encouraged to implement +PassivationCapable+ and may be required to in later revisions of this specification.
56
57 [[decorator]]
58
59 ==== The +Decorator+ interface
60
61 The +Bean+ object for a decorator must implement the interface +javax.enterprise.inject.spi.Decorator+.
62
63 [source, java]
64 ----
65 public interface Decorator<T> extends Bean<T> {
66 public Set<Type> getDecoratedTypes();
67 public Type getDelegateType();
68 public Set<Annotation> getDelegateQualifiers();
69 }
70 ----
71
72 * +getDecoratedTypes()+ returns the decorated types of the decorator.
73 * +getDelegateType()+ and +getDelegateQualifiers()+ return the delegate type and qualifiers of the decorator.
74
75
76 An instance of +Decorator+ exists for every enabled decorator.
77
78 [[interceptor]]
79
80 ==== The +Interceptor+ interface
81
82 The +Bean+ object for an interceptor must implement +javax.enterprise.inject.spi.Interceptor+.
83
84 [source, java]
85 ----
86 public interface Interceptor<T> extends Bean<T> {
87 public Set<Annotation> getInterceptorBindings();
88 public boolean intercepts(InterceptionType type);
89 public Object intercept(InterceptionType type, T instance, InvocationContext ctx) throws Exception;
90 }
91 ----
92
93 * +getInterceptorBindings()+ returns the interceptor bindings of the interceptor.
94 * +intercepts()+ returns +true+ if the interceptor intercepts the specified kind of lifecycle callback or method invocation, and +false+ otherwise.
95 * +intercept()+ invokes the specified kind of lifecycle callback or method invocation interception upon the given instance of the interceptor.
96
97
98 An +InterceptionType+ identifies the kind of lifecycle callback, EJB timeout method or business method.
99
100 [source, java]
101 ----
102 public enum InterceptionType {
103 AROUND_INVOKE, AROUND_CONSTRUCT, POST_CONSTRUCT, PRE_DESTROY, PRE_PASSIVATE, POST_ACTIVATE, AROUND_TIMEOUT
104 }
105 ----
106
107 An instance of +Interceptor+ exists for every enabled interceptor.
108
109 [[observer_method]]
110
111 ==== The +ObserverMethod+ interface
112
113 The interface +javax.enterprise.inject.spi.ObserverMethod+ defines everything the container needs to know about an observer method.
114
115 [source, java]
116 ----
117 public interface ObserverMethod<T> {
118 public Class<?> getBeanClass();
119 public Type getObservedType();
120 public Set<Annotation> getObservedQualifiers();
121 public Reception getReception();
122 public TransactionPhase getTransactionPhase();
123 public void notify(T event);
124 }
125 ----
126
127 * +getBeanClass()+ returns the class of the type that declares the observer method.
128 * +getObservedType()+ and +getObservedQualifiers()+ return the observed event type and qualifiers.
129 * +getReception()+ returns +IF_EXISTS+ for a conditional observer and +ALWAYS+ otherwise.
130 * +getTransactionPhase()+ returns the appropriate transaction phase for a transactional observer method or +IN_PROGRESS+ otherwise.
131 * +notify()+ calls the observer method, as defined in <<observer_notification>>.
132
133
134 An instance of +ObserverMethod+ must exist for every observer method of every enabled bean.
135
136 [[injectiontarget]]
137
138 === The +Producer+ and +InjectionTarget+ interfaces
139
140 The interface +javax.enterprise.inject.spi.Producer+ provides a generic operation for producing an instance of a type.
141
142 [source, java]
143 ----
144 public interface Producer<T> {
145 public T produce(CreationalContext<T> ctx);
146 public void dispose(T instance);
147 public Set<InjectionPoint> getInjectionPoints();
148 }
149 ----
150
151 For a +Producer+ that represents a class:
152
153 * +produce()+ calls the constructor annotated +@Inject+ if it exists, or the constructor with no parameters otherwise, as defined in <<instantiation>>, and returns the resulting instance. If the class has interceptors, +produce()+ is responsible for building the interceptors and decorators of the instance. The instance returned by +produce()+ may be a proxy.
154 * +dispose()+ does nothing.
155 * +getInjectionPoints()+ returns the set of +InjectionPoint+ objects representing all injected fields, bean constructor parameters and initializer method parameters.
156
157
158 For a +Producer+ that represents a producer method or field:
159
160 * +produce()+ calls the producer method on, or accesses the producer field of, a contextual instance of the bean that declares the producer method, as defined in <<producer_or_disposer_methods_invocation>>.
161 * +dispose()+ calls the disposer method, if any, on a contextual instance of the bean that declares the disposer method, as defined in <<producer_or_disposer_methods_invocation>>, or performs any additional required cleanup, if any, to destroy state associated with a resource.
162 * +getInjectionPoints()+ returns the set of +InjectionPoint+ objects representing all parameters of the producer method.
163
164
165 The subinterface +javax.enterprise.inject.spi.InjectionTarget+ provides operations for performing dependency injection and lifecycle callbacks on an instance of a type.
166
167 [source, java]
168 ----
169 public interface InjectionTarget<T>
170 extends Producer<T> {
171 public void inject(T instance, CreationalContext<T> ctx);
172 public void postConstruct(T instance);
173 public void preDestroy(T instance);
174 }
175 ----
176
177 * +inject()+ performs dependency injection upon the given object. The container performs Java EE component environment injection, according to the semantics required by the Java EE platform specification, sets the value of all injected fields, and calls all initializer methods, as defined in <<fields_initializer_methods>>.
178 * +postConstruct()+ calls the +@PostConstruct+ callback, if it exists, according to the semantics required by the Java EE platform specification.
179 * +preDestroy()+ calls the +@PreDestroy+ callback, if it exists, according to the semantics required by the Java EE platform specification.
180
181
182 Implementations of +Producer+ and +InjectionTarget+ must ensure that the set of injection points returned by +getInjectionPoints()+ are injected by +produce()+ or +inject()+.
183
184 [[beanmanager]]
185
186 === The +BeanManager+ object
187
188 The interface +javax.enterprise.inject.spi.BeanManager+ provides operations for obtaining contextual references for beans, along with many other operations of use to portable extensions.
189
190 The container provides a built-in bean with bean type +BeanManager+, scope +@Dependent+ and qualifier +@Default+. The built-in implementation must be a passivation capable dependency, as defined in <<passivation_capable_dependency>>. Thus, any bean may obtain an instance of +BeanManager+ by injecting it:
191
192 [source, java]
193 ----
194 @Inject BeanManager manager;
195 ----
196
197
198 Note that, an exception is thrown if the following operations are called before the +AfterBeanDiscovery+ event is fired:
199
200 * +getBeans(String)+,
201 * +getBeans(Type, Annotation...)+,
202 * +getPassivationCapableBean(String)+
203 * +resolve(Set)+,
204 * +resolveDecorators(Set, Annotation...)+,
205 * +resolveInterceptors(InterceptionType, Annotation...)+,
206 * +resolveObserverMethods(Object, Annotation...)+,
207 * +validate(InjectionPoint)+,
208
209 and if the following operations are called before the {@Link AfterDeploymentValidation} event is fired:
210
211 * +getReference(Bean, Type, CreationalContext)+
212 * +getInjectableReference(InjectionPoint, CreationalContext)+.
213
214 All other operations of BeanManager may be called at any time during the execution of the application.
215
216 [[provider]]
217
218 ==== Obtaining a reference to the CDI container
219
220 Portable extensions and other objects sometimes interact directly with the container via programmatic API call. The abstract +javax.enterprise.inject.spi.CDI+ provides access to the +BeanManager+ as well providing lookup of bean instances.
221
222 [source, java]
223 ----
224 public abstract class CDI<T> implements Instance<T> {
225 public static CDI<Object> current() { ... }
226 public static void setCDIProvider(CDIProvider provider);
227 public abstract BeanManager getBeanManager();
228 }
229 ----
230
231 A portable extension or other object may obtain a reference to the current container by calling +CDI.current()+. +CDI.getBeanManager()+ may be called at any time after the container fires the +BeforeBeanDiscovery+ container lifecycle event until the container fires the +BeforeShutdown+ container lifecycle event. Other methods on +CDI+ may be called after the application initialization is completed until the application shutdown starts. If methods on +CDI+ are called at any other time, non-portable behavior results.
232
233 When +CDI.current()+ is called, +getCDI()+ method is called on +javax.enterprise.inject.spi.CDIProvider+.
234
235 The +CDIProvider+ to use may be set by the application or container using the +setCDIProvider()+ method. If the +setCDIProvider()+ has not been called, the first service provider of the service +javax.enterprise.inject.spi.CDIProvider+ declared in META-INF/services is used. If no provider is available an +IllegalStateException+ is thrown.
236
237 [source, java]
238 ----
239 public interface CDIProvider {
240 public CDI<Object> getCDI();
241 }
242 ----
243
244 A Java EE container is required to provide a CDI provider that will allow access to the current container for any Java EE application or Java EE module which contains enabled beans.
245
246 Java EE components may obtain an instance of +BeanManager+ from JNDI by looking up the name +java:comp/BeanManager+.
247
248 [[bm_obtain_contextual_reference]]
249
250 ==== Obtaining a contextual reference for a bean
251
252 The method +BeanManager.getReference()+ returns a contextual reference for a given bean and bean type, as defined in <<contextual_reference>>.
253
254 [source, java]
255 ----
256 public Object getReference(Bean<?> bean, Type beanType, CreationalContext<?> ctx);
257 ----
258
259 The first parameter is the +Bean+ object representing the bean. The second parameter represents a bean type that must be implemented by any client proxy that is returned. The third parameter is an instance of +CreationalContext+ that may be used to destroy any object with scope +@Dependent+ that is created.
260
261 If the given type is not a bean type of the given bean, an +IllegalArgumentException+ is thrown.
262
263 [[bm_obtain_injectable_reference]]
264
265 ==== Obtaining an injectable reference
266
267 The method +BeanManager.getInjectableReference()+ returns an injectable reference for a given injection point, as defined in <<injectable_reference>>.
268
269 [source, java]
270 ----
271 public Object getInjectableReference(InjectionPoint ij, CreationalContext<?> ctx);
272 ----
273
274 The first parameter represents the target injection point. The second parameter is an instance of +CreationalContext+ that may be used to destroy any object with scope +@Dependent+ that is created.
275
276 If the +InjectionPoint+ represents a decorator delegate injection point, +getInjectableReference()+ returns a delegate, as defined in <<delegate_attribute>>.
277
278 If typesafe resolution results in an unsatisfied dependency, the container must throw an +UnsatisfiedResolutionException+. If typesafe resolution results in an unresolvable ambiguous dependency, the container must throw an +AmbiguousResolutionException+.
279
280 Implementations of +Bean+ usually maintain a reference to an instance of +BeanManager+. When the +Bean+ implementation performs dependency injection, it must obtain the contextual instances to inject by calling +BeanManager.getInjectableReference()+, passing an instance of +InjectionPoint+ that represents the injection point and the instance of +CreationalContext+ that was passed to +Bean.create()+.
281
282 [[bm_obtain_unmanaged_instance]]
283
284 ==== Obtaining non-contextual instance
285
286 A non-contextual instance can be obtained and injected from an +InjectionTarget+, however the +InjectionTarget+ interface is designed to work on contextual instances. A helper class, +Unmanaged+ provides a set of methods optimized for working with non-contextual instances.
287
288 For example:
289
290 [source,java]
291 ----
292 Unmanaged<Foo> unmanagedFoo = new Unmanaged<Foo>(Foo.class);
293 UnmanagedInstance<Foo> fooInstance = unmanagedFoo.newInstance();
294 Foo foo = fooInstance.produce().inject().postConstruct().get();
295 ... // Use the foo instance
296 fooInstance.preDestroy().dispose();
297 ----
298
299 [[bm_obtain_creationalcontext]]
300
301 ==== Obtaining a +CreationalContext+
302
303 An instance of +CreationalContext+ for a certain instance of +Contextual+ may be obtained by calling +BeanManager.createCreationalContext()+.
304
305 [source, java]
306 ----
307 public <T> CreationalContext<T> createCreationalContext(Contextual<T> contextual);
308 ----
309
310 An instance of +CreationalContext+ for a non-contextual object may be obtained by passing a null value to +createCreationalContext()+.
311
312 [[bm_obtain_bean_by_type]]
313
314 ==== Obtaining a +Bean+ by type
315
316 The method +BeanManager.getBeans()+ returns the set of beans which have the given required type and qualifiers and are available for injection in the module or library containing the class into which the +BeanManager+ was injected or the Java EE component from whose JNDI environment namespace the +BeanManager+ was obtained, according to the rules for candidates of typesafe resolution defined in <<performing_typesafe_resolution>>.
317
318 [source, java]
319 ----
320 public Set<Bean<?>> getBeans(Type beanType, Annotation... qualifiers);
321 ----
322
323 The first parameter is a required bean type. The remaining parameters are required qualifiers.
324
325 If no qualifiers are passed to +getBeans()+, the default qualifier +@Default+ is assumed.
326
327 If the given type represents a type variable, an +IllegalArgumentException+ is thrown.
328
329 If two instances of the same qualifier type are given, an +IllegalArgumentException+ is thrown.
330
331 If an instance of an annotation that is not a qualifier type is given, an +IllegalArgumentException+ is thrown.
332
333 [[bm_obtain_bean_by_name]]
334
335 ==== Obtaining a +Bean+ by name
336
337 The method +BeanManager.getBeans()+ which accepts a string returns the set of beans which have the given bean name and are available for injection in the module or library containing the class into which the +BeanManager+ was injected or the Java EE component from whose JNDI environment namespace the +BeanManager+ was obtained, according to the rules of name resolution defined in <<name_resolution>>.
338
339 [source, java]
340 ----
341 public Set<Bean<?>> getBeans(String name);
342 ----
343
344 The parameter is a bean name.
345
346 [[bm_obtain_passivation_capable_bean]]
347
348 ==== Obtaining a passivation capable bean by identifier
349
350 The method +BeanManager.getPassivationCapableBean()+ returns the +PassivationCapable+ bean with the given identifier (see <<passivation_capable>>).
351
352 [source, java]
353 ----
354 public Bean<?> getPassivationCapableBean(String id);
355 ----
356
357 [[bm_resolve_ambiguous_dep]]
358
359 ==== Resolving an ambiguous dependency
360
361 The method +BeanManager.resolve()+ applies the ambiguous dependency resolution rules defined in <<unsatisfied_and_ambig_dependencies>> to a set of ++Bean++ s.
362
363 [source, java]
364 ----
365 public <X> Bean<? extends X> resolve(Set<Bean<? extends X>> beans);
366 ----
367
368 If the ambiguous dependency resolution rules fail (as defined in <<unsatisfied_and_ambig_dependencies>>, the container must throw an +AmbiguousResolutionException+.
369
370 +BeanManager.resolve()+ must return null if:
371
372 * null is passed to +resolve()+, or
373 * no beans are passed to +resolve()+.
374
375 [[bm_validate_ip]]
376
377 ==== Validating an injection point
378
379 The +BeanManager.validate()+ operation validates an injection point and throws an +InjectionException+ if there is a deployment problem (for example, an unsatisfied or unresolvable ambiguous dependency) associated with the injection point.
380
381 [source, java]
382 ----
383 public void validate(InjectionPoint injectionPoint);
384 ----
385
386 [[bm_fire_event]]
387
388 ==== Firing an event
389
390 The method +BeanManager.fireEvent()+ fires an event and notifies observers, according to <<observer_notification>>.
391
392 [source, java]
393 ----
394 public void fireEvent(Object event, Annotation... qualifiers);
395 ----
396
397 The first argument is the event object. The remaining parameters are event qualifiers.
398
399 If the runtime type of the event object contains a type variable, an +IllegalArgumentException+ is thrown.
400
401 If two instances of the same qualifier type are given, an +IllegalArgumentException+ is thrown.
402
403 If an instance of an annotation that is not a qualifier type is given, an +IllegalArgumentException+ is thrown.
404
405 If the runtime type of the event object is assignable to the type of a container lifecycle event, an +IllegalArgumentException+ is thrown.
406
407 [[bm_observer_method_resolution]]
408
409 ==== Observer method resolution
410
411 The method +BeanManager.resolveObserverMethods()+ resolves observer methods for an event according to the rules of observer resolution defined in <<observer_resolution>>.
412
413 [source, java]
414 ----
415 public <T> Set<ObserverMethod<? super T>> resolveObserverMethods(T event, Annotation... qualifiers);
416 ----
417
418 The first parameter of +resolveObserverMethods()+ is the event object. The remaining parameters are event qualifiers.
419
420 If the runtime type of the event object contains a type variable, an +IllegalArgumentException+ is thrown.
421
422 If two instances of the same qualifier type are given, an +IllegalArgumentException+ is thrown.
423
424 If an instance of an annotation that is not a qualifier type is given, an +IllegalArgumentException+ is thrown.
425
426 [[bm_decorator_resolution]]
427
428 ==== Decorator resolution
429
430 The method +BeanManager.resolveDecorators()+ returns the ordered list of decorators for a set of bean types and a set of qualifiers and which are enabled in the module or library containing the class into which the +BeanManager+ was injected or the Java EE component from whose JNDI environment namespace the +BeanManager+ was obtained, as defined in <<decorator_resolution>>.
431
432 [source, java]
433 ----
434 List<Decorator<?>> resolveDecorators(Set<Type> types, Annotation... qualifiers);
435 ----
436
437 The first argument is the set of bean types of the decorated bean. The annotations are qualifiers declared by the decorated bean.
438
439 If two instances of the same qualifier type are given, an +IllegalArgumentException+ is thrown.
440
441 If an instance of an annotation that is not a qualifier type is given, an +IllegalArgumentException+ is thrown.
442
443 If the set of bean types is empty, an +IllegalArgumentException+ is thrown.
444
445 [[bm_interceptor_resolution]]
446
447 ==== Interceptor resolution
448
449 The method +BeanManager.resolveInterceptors()+ returns the ordered list of interceptors for a set of interceptor bindings and a type of interception and which are enabled in the module or library containing the class into which the +BeanManager+ was injected or the Java EE component from whose JNDI environment namespace the +BeanManager+ was obtained, as defined in <<interceptor_resolution>>.
450
451 [source, java]
452 ----
453 List<Interceptor<?>> resolveInterceptors(InterceptionType type,
454 Annotation... interceptorBindings);
455 ----
456
457 If two instances of the same interceptor binding type are given, an +IllegalArgumentException+ is thrown.
458
459 If no interceptor binding type instance is given, an +IllegalArgumentException+ is thrown.
460
461 If an instance of an annotation that is not an interceptor binding type is given, an +IllegalArgumentException+ is thrown.
462
463 [[bm_determining_annotation]]
464
465 ==== Determining if an annotation is a qualifier type, scope type, stereotype or interceptor binding type
466
467 A portable extension may test an annotation to determine if it is a qualifier type, scope type, stereotype or interceptor binding type, obtain the set of meta-annotations declared by a stereotype or interceptor binding type, or determine if a scope type is a normal or passivating scope.
468
469 [source, java]
470 ----
471 public boolean isScope(Class<? extends Annotation> annotationType);
472 public boolean isQualifier(Class<? extends Annotation> annotationType);
473 public boolean isInterceptorBinding(Class<? extends Annotation> annotationType);
474 public boolean isStereotype(Class<? extends Annotation> annotationType);
475
476 public boolean isNormalScope(Class<? extends Annotation> scopeType);
477 public boolean isPassivatingScope(Class<? extends Annotation> scopeType);
478 public Set<Annotation> getInterceptorBindingDefinition(Class<? extends Annotation> qualifierType);
479 public Set<Annotation> getStereotypeDefinition(Class<? extends Annotation> stereotype);
480 ----
481
482 [[bm_determining_hash]]
483
484 ==== Determining the hash code and equivalence of qualifiers and interceptor bindings
485
486 A portable extension may determine if two qualifiers or two interceptor bindings are considered equivalent for the purposes of typesafe resolution, as defined in <<performing_typesafe_resolution>>.
487
488 [source, java]
489 ----
490 public boolean areQualifiersEquivalent(Annotation qualifier1, Annotation qualifier2);
491 public boolean areInterceptorBindingsEquivalent(Annotation interceptorBinding1, Annotation interceptorBinding2);
492 ----
493
494 A portable extension may determine the hash code of a qualifier or interceptor binding, ignoring any members annotated with +@Nonbinding+.
495
496 [source, java]
497 ----
498 public int getQualifierHashCode(Annotation qualifier);
499 public int getInterceptorBindingHashCode(Annotation interceptorBinding);
500 ----
501
502 [[bm_obtain_active_context]]
503
504 ==== Obtaining the active +Context+ for a scope
505
506 The method +BeanManager.getContext()+ retrieves an active context object associated with the given scope, as defined in <<active_context>>.
507
508 [source, java]
509 ----
510 public Context getContext(Class<? extends Annotation> scopeType);
511 ----
512
513 [[bm_obtain_elresolver]]
514
515 ==== Obtaining the +ELResolver+
516
517 The method +BeanManager.getELResolver()+ returns the +javax.el.ELResolver+ specified in <<el>>.
518
519 [source, java]
520 ----
521 public ELResolver getELResolver();
522 ----
523
524 [[bm_wrap_expressionfactory]]
525
526 ==== Wrapping a Unified EL +ExpressionFactory+
527
528 The method +BeanManager.wrapExpressionFactory()+ returns a wrapper +javax.el.ExpressionFactory+ that delegates +MethodExpression+ and +ValueExpression+ creation to the given +ExpressionFactory+. When a Unified EL expression is evaluated using a +MethodExpression+ or +ValueExpression+ returned by the wrapper +ExpressionFactory+, the rules defined in <<dependent_scope_el>> are enforced by the container.
529
530 [source, java]
531 ----
532 public ExpressionFactory wrapExpressionFactory(ExpressionFactory expressionFactory);
533 ----
534
535 [[bm_obtain_annotatedtype]]
536
537 ==== Obtaining an +AnnotatedType+ for a class
538
539 The method +BeanManager.createAnnotatedType()+ returns an +AnnotatedType+ that may be used to read the annotations of the given Java class or interface.
540
541 [source, java]
542 ----
543 public <T> AnnotatedType<T> createAnnotatedType(Class<T> type);
544 ----
545
546 [[bm_obtain_injectiontarget]]
547
548 ==== Obtaining an +InjectionTarget+ for a class
549
550 The method +BeanManager.getInjectionTargetFactory()+ returns a factory capable of creating container provided implementations of +InjectionTarget+ for a given +AnnotatedType+ or throws an +IllegalArgumentException+ if there is a definition error associated with any injection point of the type.
551
552 [source, java]
553 ----
554 public <T> InjectionTargetFactory<T> getInjectionTargetFactory(AnnotatedType<T> type);
555 ----
556
557 [source, java]
558 ----
559 public interface InjectionTargetFactory<T> {
560
561 public InjectionTarget<T> createInjectionTarget(Bean<T> bean);
562
563 }
564 ----
565
566 Null should be passed to +InjectionTargetFactory.createInjectionTarget()+ to create a non-contextual injection target. The method +BeanManager.createInjectionTarget()+ is deprecated since version 1.1 of Contexts and Dependency Injection.
567
568 [[bm_obtain_producer]]
569
570 ==== Obtaining a +Producer+ for a field or method
571
572 The method +BeanManager.getProducerFactory()+ returns a factory capable of creating container provided implementations of +Producer+ for a given +AnnotatedMethod+ or +AnnotatedField+, and declaring bean, or throws an +IllegalArgumentException+ if there is a definition error associated with the producer method or field.
573
574 [source, java]
575 ----
576 public <X> ProducerFactory<X> getProducerFactory(AnnotatedField<? super X> field, Bean<X> declaringBean);
577 public <X> ProducerFactory<X> getProducerFactory(AnnotatedMethod<? super X> method, Bean<X> declaringBean);
578 ----
579
580 [source, java]
581 ----
582 public interface ProducerFactory<X> {
583
584 public <T> Producer<T> createProducer(Bean<T> bean);
585
586 }
587 ----
588
589 Null should be passed to +ProducerFactory.createProducer()+ to create a producer of non-contextual objects.
590
591
592 [[bm_obtain_injectionpoint]]
593
594 ==== Obtaining an +InjectionPoint+
595
596 The method +BeanManager.createInjectionPoint()+ returns a container provided implementation of +InjectionPoint+ for a given +AnnotatedField+ or +AnnotatedParameter+ or throws an +IllegalArgumentException+ if there is a definition error associated with the injection point.
597
598 [source, java]
599 ----
600 public InjectionPoint createInjectionPoint(AnnotatedField<?> field);
601 public InjectionPoint createInjectionPoint(AnnotatedParameter<?> parameter);
602 ----
603
604 [[bm_obtain_beanattributes]]
605
606 ==== Obtaining a +BeanAttributes+
607
608 The method +BeanManager.createBeanAttributes()+ returns a container provided implementation of +BeanAttributes+ by reading the annotations of a given +AnnotatedType+ or +AnnotatedMember+, according to the rules defined in <<concepts>>, or throws an +IllegalArgumentException+ if there is a definition error associated with the declared bean attributes.
609
610 [source, java]
611 ----
612 public <T> BeanAttributes<T> createBeanAttributes(AnnotatedType<T> type);
613 public BeanAttributes<?> createBeanAttributes(AnnotatedMember<?> member);
614 ----
615
616 [[bm_obtain_bean]]
617
618 ==== Obtaining a +Bean+
619
620 The method +BeanManager.createBean()+ returns a container provided implementation of +Bean+. The methods accept:
621
622 * a +BeanAttributes+, which determines the bean types, qualifiers, scope, name and stereotypes of the returned +Bean+, and the return values of +isAlternative()+, and
623 * a class, which determines the return value of +Bean.getClass()+.
624 * an +InjectionTargetFactory+, which is used to obtain an +InjectionTarget+. The +InjectionTarget+ is used to create and destroy instances of the bean, to perform dependency injection and lifecycle callbacks, and which determines the return value of +Bean.getInjectionPoints()+.
625
626
627 [source, java]
628 ----
629 public <T> Bean<T> createBean(BeanAttributes<T> attributes, Class<T> beanClass,
630 InjectionTargetFactory<T> injectionTargetFactory);
631 ----
632
633 A second version of the method is provided to create a +Bean+ from a producer. The method accepts:
634
635 * a +BeanAttributes+, which determines the bean types, qualifiers, scope, name and stereotypes of the returned +Bean+, and the return values of +isAlternative()+, and
636 * a class, which determines the return value of +Bean.getClass()+.
637 * a +ProducerFactory+, which is used to obtain a +Producer+. The +Producer+ is used to create and destroy instances of the bean, and which determines the return value of +Bean.getInjectionPoints()+.
638
639
640 [source, java]
641 ----
642 public <T, X> Bean<T> createBean(BeanAttributes<T> attributes, Class<X> beanClass,
643 ProducerFactory<X> producer);
644 ----
645
646 [[bm_obtain_extension]]
647
648 ==== Obtaining the instance of an +Extension+
649
650 The method +BeanManager.getExtension()+ returns the container's instance of an +Extension+ class declared in +META-INF/services+, or throws an +IllegalArgumentException+ if the container has no instance of the given class.
651
652 [source, java]
653 ----
654 public <T extends Extension> T getExtension(Class<T> extensionClass);
655 ----
656
657 [[alternative_metadata_sources]]
658
659 === Alternative metadata sources
660
661 A portable extension may provide an alternative metadata source, such as configuration by XML.
662
663 The interfaces +AnnotatedType+, +AnnotatedField+, +AnnotatedMethod+, +AnnotatedConstructor+ and +AnnotatedParameter+ in the package +javax.enterprise.inject.spi+ allow a portable extension to specify metadata that overrides the annotations that exist on a bean class. The portable extension is responsible for implementing the interfaces, thereby exposing the metadata to the container.
664
665 In general, the behavior is as defined by the Java Language Specification, and only deviations from the Java Language Specification are noted.
666
667 The interface +javax.enterprise.inject.spi.AnnotatedType+ exposes the +Class+ object and members.
668
669 [source, java]
670 ----
671 public interface AnnotatedType<X>
672 extends Annotated {
673 public Class<X> getJavaClass();
674 public Set<AnnotatedConstructor<X>> getConstructors();
675 public Set<AnnotatedMethod<? super X>> getMethods();
676 public Set<AnnotatedField<? super X>> getFields();
677 }
678 ----
679
680 * +getConstructors()+ returns all default-access, public, protected or private constructors declared for the type.
681 * +getMethods()+ returns all default-access, public, protected or private methods declared on the type and those declared on any supertypes. The container should call +AnnotatedMethod.getJavaMember().getDeclaringClass()+ to determine the type in the type hierarchy that declared the method.
682 * +getFields()+ returns all default-access, public, protected or private fields declared on the type and those declared on any supertypes. The container should call +AnnotatedField.getJavaMember().getDeclaringClass()+ to determine the type in the type hierarchy that declared the field.
683
684
685 When determining annotations on a type, the container must only consider the special inheritance rules defined for scope types in <<type_level_inheritance>>.
686
687 The interface +javax.enterprise.inject.spi.AnnotatedField+ exposes the +Field+ object.
688
689 [source, java]
690 ----
691 public interface AnnotatedField<X>
692 extends AnnotatedMember<X> {
693 public Field getJavaMember();
694 }
695 ----
696
697 The interface +javax.enterprise.inject.spi.AnnotatedMethod+ exposes the +Method+ object.
698
699 [source, java]
700 ----
701 public interface AnnotatedMethod<X>
702 extends AnnotatedCallable<X> {
703 public Method getJavaMember();
704 }
705 ----
706
707 The interface +javax.enterprise.inject.spi.AnnotatedConstructor+ exposes the +Constuctor+ object.
708
709 [source, java]
710 ----
711 public interface AnnotatedConstructor<X>
712 extends AnnotatedCallable<X> {
713 public Constructor<X> getJavaMember();
714 }
715 ----
716
717 The interface +javax.enterprise.inject.spi.AnnotatedParameter+ exposes the +position+ of the parameter object and the declaring program element.
718
719 [source, java]
720 ----
721 public interface AnnotatedParameter<X>
722 extends Annotated {
723 public int getPosition();
724 public AnnotatedCallable<X> getDeclaringCallable();
725 }
726 ----
727
728 The interface +javax.enterprise.inject.spi.AnnotatedMemember+ exposes the +Member+ object and the +AnnotatedType+ that defines the member.
729
730 [source, java]
731 ----
732 public interface AnnotatedMember<X>
733 extends Annotated {
734 public Member getJavaMember();
735 public boolean isStatic();
736 public AnnotatedType<X> getDeclaringType();
737 }
738 ----
739
740 The interface +javax.enterprise.inject.spi.AnnotatedCallable+ exposes the parameters of an invokable object.
741
742 Contexts and Dependency Injection for Java EE 1.1 deprecated the method +AnnotatedMember.isStatic()+. The container should instead call +AnnotatedMember.getJavaMember().getModifiers()+ to determine if the member is static.
743
744 [source, java]
745 ----
746 public interface AnnotatedCallable<X>
747 extends AnnotatedMember<X> {
748 public List<AnnotatedParameter<X>> getParameters();
749 }
750 ----
751
752 The interface +javax.enterprise.inject.spi.Annotated+ exposes the overriding annotations and type declarations.
753
754 [source, java]
755 ----
756 public interface Annotated {
757 public Type getBaseType();
758 public Set<Type> getTypeClosure();
759 public <T extends Annotation> T getAnnotation(Class<T> annotationType);
760 public Set<Annotation> getAnnotations();
761 public boolean isAnnotationPresent(Class<? extends Annotation> annotationType);
762 }
763 ----
764
765 * +getBaseType()+ returns the type of the program element.
766 * +getTypeClosure()+ returns all types to which the base type should be considered assignable.
767 * +getAnnotation()+ returns the program element annotation of the given annotation type, or a null value.
768 * +getAnnotations()+ returns all annotations of the program element.
769 * +isAnnotationPresent()+ returns +true+ if the program element has an annotation of the given annotation type, or +false+ otherwise.
770
771
772 The container must use the operations of +Annotated+ and its subinterfaces to discover program element types and annotations. The container must not directly call the Java Reflection API. In particular, the container must:
773
774 * call +Annotated.getBaseType()+ to determine the type of an injection point, event parameter or disposed parameter,
775 * call +Annotated.getTypeClosure()+ to determine the bean types of any kind of bean,
776 * call +Annotated.getAnnotations()+ to determine the scope, qualifiers, stereotypes and interceptor bindings of a bean,
777 * call +Annotated.isAnnotationPresent()+ and +Annotated.getAnnotation()+ to read any bean annotations defined by this specification, and
778 * call +AnnotatedType.getConstructors()+, +AnnotatedType.getMethods()+ and +AnnotatedType.getFields()+ to determine the members of a bean class.
779
780
781 [[init_events]]
782
783 === Container lifecycle events
784
785 During the application initialization process, the container fires a series of events, allowing portable extensions to integrate with the container initialization process defined in <<initialization>>.
786
787 Observer methods of these events must belong to _extensions_. An extension is a service provider of the service +javax.enterprise.inject.spi.Extension+ declared in +META-INF/services+.
788
789 [source, java]
790 ----
791 public interface Extension {}
792 ----
793
794 If any method on the event object is called outside of the observer method invocation, an +IllegalStateException+ is thrown.
795
796 Service providers may have observer methods, which may observe any event, including any container lifecycle event, and obtain an injected +BeanManager+ reference. Any decorators associated with +BeanManager+ will not be applied. If other beans are injected into an extension's observer methods, non-portable behavior results. An extension may use +BeanManager.fireEvent()+ to deliver events to observer methods defined on extensions. The container is not required to deliver events fired during application initialization to observer methods defined on beans.
797
798 The container instantiates a single instance of each extension at the beginning of the application initialization process and maintains a reference to it until the application shuts down. The container delivers event notifications to this instance by calling its observer methods.
799
800 For each service provider, the container must provide a bean of scope +@ApplicationScoped+ and qualifier +@Default+, supporting injection of a reference to the service provider instance. The bean types of this bean include the class of the service provider and all superclasses and interfaces.
801
802 Lifecycle events described below can be grouped in to two categories:
803
804 * Application lifecycle events, that are fired once:
805 ** BeforeBeanDiscovery
806 ** AfterTypeDiscovery
807 ** AfterBeanDiscovery
808 ** AfterDeploymentValidation
809 ** BeforeShutdown
810 * Bean discovery events, that are fired multiple times:
811 ** ProcessAnnotatedType
812 ** ProcessInjectionPoint
813 ** ProcessInjectionTarget
814 ** ProcessBeanAttributes
815 ** ProcessBean
816 ** ProcessProducer
817 ** ProcessObserverMethod
818
819 Note that the chronological order of these events is specified in <<initialization>>.
820
821 [[bbd]]
822
823 ==== +BeforeBeanDiscovery+ event
824
825 The container must fire an event before it begins the type discovery process. The event object must be of type +javax.enterprise.inject.spi.BeforeBeanDiscovery+:
826
827 [source, java]
828 ----
829 public interface BeforeBeanDiscovery {
830 public void addQualifier(Class<? extends Annotation> qualifier);
831 public void addQualifier(AnnotatedType<? extends Annotation> qualifier);
832 public void addScope(Class<? extends Annotation> scopeType, boolean normal, boolean passivating);
833 public void addStereotype(Class<? extends Annotation> stereotype, Annotation... stereotypeDef);
834 public void addInterceptorBinding(Class<? extends Annotation> bindingType, Annotation... bindingTypeDef);
835 public void addInterceptorBinding(AnnotatedType<? extends Annotation> bindingType);
836 public void addAnnotatedType(AnnotatedType<?> type);
837 public void addAnnotatedType(AnnotatedType<?> type, String id);
838 }
839 ----
840
841 * +addQualifier()+ declares an annotation type as a qualifier type.
842 * +addScope()+ declares an annotation type as a scope type.
843 * +addStereotype()+ declares an annotation type as a stereotype, and specifies its meta-annotations.
844 * +addInterceptorBinding()+ declares an annotation type as an interceptor binding type, and specifies its meta-annotations.
845 * +addAnnotatedType()+ adds a given +AnnotatedType+ to the set of types which will be scanned during bean discovery, with an optional identifier. The first version of the method is deprecated since version 1.1 of Contexts and Dependency Injection.
846
847
848 [source, java]
849 ----
850 void beforeBeanDiscovery(@Observes BeforeBeanDiscovery event) { ... }
851 ----
852
853 If any observer method of the +BeforeBeanDiscovery+ event throws an exception, the exception is treated as a definition error by the container.
854
855 If any +BeforeBeanDiscovery+ method is called outside of the observer method invocation, an +IllegalStateException+ is thrown.
856
857 [[atd]]
858
859 ==== +AfterTypeDiscovery+ event
860
861 The container must fire an event when it has fully completed the type discovery process and before it begins the bean discovery process. The event object must be of type +javax.enterprise.inject.spi.AfterTypeDiscovery+.
862
863 [source, java]
864 ----
865 public interface AfterTypeDiscovery {
866 public List<Class<?>> getAlternatives();
867 public List<Class<?>> getInterceptors();
868 public List<Class<?>> getDecorators();
869 public void addAnnotatedType(AnnotatedType<?> type, String id);
870 }
871 ----
872
873 * +getAlternatives()+ returns the ordered list of enabled alternatives for the application. Alternatives enabled for a bean archive are not included in the list.
874 * +getInterceptors()+ returns the ordered list of enabled interceptors for the application. Interceptors enabled for a bean archive are not included in the list.
875 * +getDecorators()+ returns the ordered list of enabled decorators for the application. Decorators enabled for a bean archive are not included in the list.
876 * +addAnnotatedType()+ adds a given +AnnotatedType+ to the set of types which will be scanned during bean discovery, with an identifier.
877
878 If an alternative, interceptor or decorator is added using +AfterTypeDiscovery.addAnnotatedType()+, non-portable behavior results.
879
880 Any observer of this event is permitted to add classes to, or remove classes from, the list of alternatives, list of interceptors or list of decorators. The container must use the final values of these collections, after all observers of +AfterTypeDiscovery+ have been called, to determine the order of the enabled alternatives, interceptors, and decorators for application. The initial values of these collections are defined by the +@Priority+ annotation.
881
882 [source, java]
883 ----
884 void afterTypeDiscovery(@Observes AfterTypeDiscovery event) { ... }
885 ----
886
887
888 If any observer method of a +AfterTypeDiscovery+ event throws an exception, the exception is treated as a definition error by the container.
889
890 If any +AfterTypeDiscovery+ method is called outside of the observer method invocation, an +IllegalStateException+ is thrown.
891
892
893 [[abd]]
894
895 ==== +AfterBeanDiscovery+ event
896
897 The container must fire an event when it has fully completed the bean discovery process, validated that there are no definition errors relating to the discovered beans, and registered +Bean+ and +ObserverMethod+ objects for the discovered beans.
898
899 The event object must be of type +javax.enterprise.inject.spi.AfterBeanDiscovery+:
900
901 [source, java]
902 ----
903 public interface AfterBeanDiscovery {
904 public void addDefinitionError(Throwable t);
905 public void addBean(Bean<?> bean);
906 public void addObserverMethod(ObserverMethod<?> observerMethod);
907 public void addContext(Context context);
908 public <T> AnnotatedType<T> getAnnotatedType(Class<T> type, String id);
909 public <T> Iterable<AnnotatedType<T>> getAnnotatedTypes(Class<T> type);
910 }
911 ----
912
913 * +addDefinitionError()+ registers a definition error with the container, causing the container to abort deployment after all observers have been notified.
914 * +addBean()+ fires an event of type +ProcessBean+ containing the given +Bean+ and then registers the +Bean+ with the container, thereby making it available for injection into other beans. The given +Bean+ may implement +Interceptor+ or +Decorator+.
915 * +addObserverMethod()+ fires an event of type +ProcessObserverMethod+ containing the given +ObserverMethod+ and then registers the +ObserverMethod+ with the container, thereby making it available for event notifications.
916 * +addContext()+ registers a custom +Context+ object with the container.
917 * +getAnnotatedType()+ and +getAnnotatedTypes()+ returns the ++AnnotatedType++ s discovered or added during container initialization. The id of an +AnnotatedType+ added by the container is not defined. If the +id+ passed is null, the container should substitute the container generated id.
918
919
920 A portable extension may take advantage of this event to register beans, interceptors, decorators, observer methods and custom context objects with the container.
921
922 [source, java]
923 ----
924 void afterBeanDiscovery(@Observes AfterBeanDiscovery event, BeanManager manager) { ... }
925 ----
926
927 If any observer method of the +AfterBeanDiscovery+ event throws an exception, the exception is treated as a definition error by the container.
928
929 If any +AfterBeanDiscovery+ method is called outside of the observer method invocation, an +IllegalStateException+ is thrown.
930
931 [[adv]]
932
933 ==== +AfterDeploymentValidation+ event
934
935 The container must fire an event after it has validated that there are no deployment problems and before creating contexts or processing requests.
936
937 The event object must be of type +javax.enterprise.inject.spi.AfterDeploymentValidation+:
938
939 [source, java]
940 ----
941 public interface AfterDeploymentValidation {
942 public void addDeploymentProblem(Throwable t);
943 }
944 ----
945
946 * +addDeploymentProblem()+ registers a deployment problem with the container, causing the container to abort deployment after all observers have been notified.
947
948
949 [source, java]
950 ----
951 void afterDeploymentValidation(@Observes AfterDeploymentValidation event, BeanManager manager) { ... }
952 ----
953
954 If any observer method of the +AfterDeploymentValidation+ event throws an exception, the exception is treated as a deployment problem by the container.
955
956 If any +AfterDeploymentValidation+ method is called outside of the observer method invocation, an +IllegalStateException+ is thrown.
957
958 The container must not allow any request to be processed by the deployment until all observers of this event return.
959
960 [[bs]]
961
962 ==== +BeforeShutdown+ event
963
964 The container must fire a final event after it has finished processing requests and destroyed all contexts.
965
966 The event object must be of type +javax.enterprise.inject.spi.BeforeShutdown+:
967
968 [source, java]
969 ----
970 public interface BeforeShutdown {}
971 ----
972
973 [source, java]
974 ----
975 void beforeShutdown(@Observes BeforeShutdown event, BeanManager manager) { ... }
976 ----
977
978 If any observer method of the +BeforeShutdown+ event throws an exception, the exception is ignored by the container.
979
980 [[pat]]
981
982 ==== +ProcessAnnotatedType+ event
983
984 The container must fire an event, before it processes a type, for every Java class, interface (excluding the special kind of interface declaration _annotation type_) or enum discovered
985
986 as defined in <<type_discovery>>
987
988 An event is not fired for any type annotated with +@Vetoed+, or in a package annotated with +@Vetoed+.
989
990 The event object must be of type +javax.enterprise.inject.spi.ProcessAnnotatedType<X>+, where +X+ is the class, for types discovered in a bean archive, or of type +javax.enterprise.inject.spi.ProcessSyntheticAnnotatedType<X>+ for types added by +BeforeBeanDiscovery.addAnnotatedType()+ or +AfterTypeDiscovery.addAnnotatedType()+.
991
992 The annotation +@WithAnnotations+ may be applied to the event parameter. If the annotation is applied, the container must only deliver +ProcessAnnotatedType+ events for types which contain at least one of the annotations specified. The annotation can appear on the annotated type, or on any member, or any parameter of any member of the annotated type, as defined in <<alternative_metadata_sources>>. The annotation may be applied as a meta-annotation on any annotation considered.
993
994 If the +@WithAnnotations+ annotation is applied to any other event parameter, the container automatically detects the problem and treats it as a definition error.
995
996 [source, java]
997 ----
998 public interface ProcessAnnotatedType<X> {
999 public AnnotatedType<X> getAnnotatedType();
1000 public void setAnnotatedType(AnnotatedType<X> type);
1001 public void veto();
1002 }
1003 ----
1004
1005 [source, java]
1006 ----
1007 interface ProcessSyntheticAnnotatedType<X> extends ProcessAnnotatedType<X> {
1008 public Extension getSource();
1009 }
1010 ----
1011
1012 * +getAnnotatedType()+ returns the +AnnotatedType+ object that will be used by the container to read the declared annotations.
1013 * +setAnnotatedType()+ replaces the +AnnotatedType+.
1014 * +veto()+ forces the container to ignore the type.
1015 * +getSource()+ returns the +Extension+ instance that added the annotated type.
1016
1017
1018 Any observer of this event is permitted to wrap and/or replace the +AnnotatedType+. The container must use the final value of this property, after all observers have been called, as the only source of types and annotations for the program elements.
1019
1020 For example, the following observer decorates the +AnnotatedType+ for every class that is discovered by the container.
1021
1022 [source, java]
1023 ----
1024 <T> void decorateAnnotatedType(@Observes ProcessAnnotatedType<T> pat) {
1025 pat.setAnnotatedType( decorate( pat.getAnnotatedType() ) );
1026 }
1027 ----
1028
1029 If any observer method of a +ProcessAnnotatedType+ event throws an exception, the exception is treated as a definition error by the container.
1030
1031 If any +ProcessAnnotatedType+ method is called outside of the observer method invocation, an +IllegalStateException+ is thrown.
1032
1033 [[pip]]
1034
1035 ==== +ProcessInjectionPoint+ event
1036
1037 The container must fire an event for every injection point of every Java EE component class supporting injection that may be instantiated by the container at runtime, including every managed bean declared using +@ManagedBean+, EJB session or message-driven bean, bean, interceptor or decorator.
1038
1039 The event object must be of type +javax.enterprise.inject.spi.ProcessInjectionPoint<T, X>+ where +T+ is the managed bean class, session bean class or Java EE component class supporting injection, and +X+ is the declared type of the injection point.
1040
1041 [source, java]
1042 ----
1043 public interface ProcessInjectionPoint<T, X> {
1044 public InjectionPoint getInjectionPoint();
1045 public void setInjectionPoint(InjectionPoint injectionPoint);
1046 public void addDefinitionError(Throwable t);
1047 }
1048 ----
1049
1050 * +getInjectionPoint()+ returns the +InjectionPoint+ object that will be used by the container to perform injection.
1051 * +setInjectionPoint()+ replaces the +InjectionPoint+.
1052 * +addDefinitionError()+ registers a definition error with the container, causing the container to abort deployment after bean discovery is complete.
1053
1054
1055 Any observer of this event is permitted to wrap and/or replace the +InjectionPoint+. The container must use the final value of this property, after all observers have been called, whenever it performs injection upon the injection point.
1056
1057 If any observer method of a +ProcessInjectionPoint+ event throws an exception, the exception is treated as a definition error by the container.
1058
1059 If any +ProcessInjectionPoint+ method is called outside of the observer method invocation, an +IllegalStateException+ is thrown.
1060
1061 [[pit]]
1062
1063 ==== +ProcessInjectionTarget+ event
1064
1065 The container must fire an event for every Java EE component class supporting injection that may be instantiated by the container at runtime, including every managed bean declared using +@ManagedBean+, EJB session or message-driven bean, bean, interceptor or decorator.
1066
1067 The event object must be of type +javax.enterprise.inject.spi.ProcessInjectionTarget<X>+, where +X+ is the managed bean class, session bean class or Java EE component class supporting injection.
1068
1069 [source, java]
1070 ----
1071 public interface ProcessInjectionTarget<X> {
1072 public AnnotatedType<X> getAnnotatedType();
1073 public InjectionTarget<X> getInjectionTarget();
1074 public void setInjectionTarget(InjectionTarget<X> injectionTarget);
1075 public void addDefinitionError(Throwable t);
1076 }
1077 ----
1078
1079 * +getAnnotatedType()+ returns the +AnnotatedType+ representing the managed bean class, session bean class or other Java EE component class supporting injection.
1080 * +getInjectionTarget()+ returns the +InjectionTarget+ object that will be used by the container to perform injection.
1081 * +setInjectionTarget()+ replaces the +InjectionTarget+.
1082 * +addDefinitionError()+ registers a definition error with the container, causing the container to abort deployment after bean discovery is complete.
1083
1084
1085 Any observer of this event is permitted to wrap and/or replace the +InjectionTarget+. The container must use the final value of this property, after all observers have been called, whenever it performs injection upon the managed bean, session bean or other Java EE component class supporting injection.
1086
1087 For example, this observer decorates the +InjectionTarget+ for all servlets.
1088
1089 [source, java]
1090 ----
1091 <T extends Servlet> void decorateServlet(@Observes ProcessInjectionTarget<T> pit) {
1092 pit.setInjectionTarget( decorate( pit.getInjectionTarget() ) );
1093 }
1094 ----
1095
1096 If any observer method of a +ProcessInjectionTarget+ event throws an exception, the exception is treated as a definition error by the container.
1097
1098 If any +ProcessInjectionTarget+ method is called outside of the observer method invocation, an +IllegalStateException+ is thrown.
1099
1100 [[pba]]
1101
1102 ==== +ProcessBeanAttributes+ event
1103
1104 The container must fire an event for each bean, interceptor or decorator deployed in a bean archive, before registering the +Bean+ object. No event is fired for any:
1105
1106 * +@New+ qualified bean, defined in <<new>>, or,
1107 * beans added programmatically using +AfterBeanDiscovery.addBean()+, or,
1108 * for any built-in beans.
1109
1110 The event object must be of type +javax.enterprise.inject.spi.ProcessBeanAttributes<T>+ where +T+ is the bean class of the managed bean or session bean, the return type of the producer method, or the type of the producer field.
1111
1112 Resources are considered to be producer fields.
1113
1114 [source, java]
1115 ----
1116 public interface ProcessBeanAttributes<T> {
1117 public Annotated getAnnotated();
1118 public BeanAttributes<T> getBeanAttributes();
1119 public void setBeanAttributes(BeanAttributes<T> beanAttributes);
1120 public void addDefinitionError(Throwable t);
1121 public void veto();
1122 }
1123 ----
1124
1125 * +getAnnotated()+ returns the +AnnotatedType+ representing the managed bean class or session bean class, the +AnnotatedMethod+ representing the producer field, or the +AnnotatedField+ representing the producer field.
1126 * +getBeanAttributes()+ returns the +BeanAttributes+ object that will be used by the container to manage instances of the bean.
1127 * +setBeanAttributes()+ replaces the +BeanAttributes+.
1128 * +addDefinitionError()+ registers a definition error with the container, causing the container to abort deployment after bean discovery is complete.
1129 * +veto()+ forces the container to ignore the bean.
1130
1131
1132 Any observer of this event is permitted to wrap and/or replace the +BeanAttributes+. The container must use the final value of this property, after all observers have been called, to manage instances of the bean. Changes to +BeanAttributes+ are _not_ propagated to the annotated type from which the bean definition was created.
1133
1134 Any bean which has its bean attributes altered must have it's definition validated during deployment validation.
1135
1136 If any observer method of a +ProcessBeanAttributes+ event throws an exception, the exception is treated as a definition error by the container.
1137
1138 If any +ProcessBeanAttributes+ method is called outside of the observer method invocation, an +IllegalStateException+ is thrown.
1139
1140 [[pb]]
1141
1142 ==== +ProcessBean+ event
1143
1144 The container must fire an event for each bean, interceptor or decorator deployed in a bean archive, after firing the +ProcessBeanAttributes+ for the bean and before registering the +Bean+ object. No event is fired for any +@New+ qualified bean, defined in <<new>>.
1145
1146 The event object type in the package +javax.enterprise.inject.spi+ depends upon what kind of bean was discovered:
1147
1148 * For a managed bean with bean class +X+, the container must raise an event of type +ProcessManagedBean<X>+.
1149 * For a session bean with bean class +X+, the container must raise an event of type +ProcessSessionBean<X>+.
1150 * For a producer method with method return type +X+ of a bean with bean class +T+, the container must raise an event of type +ProcessProducerMethod<T, X>+.
1151 * For a producer field with field type +X+ of a bean with bean class +T+, the container must raise an event of type +ProcessProducerField<T, X>+.
1152
1153
1154 Resources are considered to be producer fields.
1155
1156 The interface +javax.enterprise.inject.spi.ProcessBean+ is a supertype of all these event types:
1157
1158 [source, java]
1159 ----
1160 public interface ProcessBean<X> {
1161 public Annotated getAnnotated();
1162 public Bean<X> getBean();
1163 public void addDefinitionError(Throwable t);
1164 }
1165 ----
1166
1167 * +getAnnotated()+ returns the +AnnotatedType+ representing the bean class, the +AnnotatedMethod+ representing the producer method, or the +AnnotatedField+ representing the producer field.
1168 * +getBean()+ returns the +Bean+ object that is about to be registered. The +Bean+ may implement +Interceptor+ or +Decorator+.
1169 * +addDefinitionError()+ registers a definition error with the container, causing the container to abort deployment after bean discovery is complete.
1170
1171
1172 [source, java]
1173 ----
1174 public interface ProcessSessionBean<X>
1175 extends ProcessManagedBean<Object> {
1176 public String getEjbName();
1177 public SessionBeanType getSessionBeanType();
1178 }
1179 ----
1180
1181 * +getEjbName()+ returns the EJB name of the session bean.
1182 * +getSessionBeanType()+ returns a +javax.enterprise.inject.spi.SessionBeanType+ representing the kind of session bean.
1183
1184
1185 [source, java]
1186 ----
1187 public enum SessionBeanType { STATELESS, STATEFUL, SINGLETON }
1188 ----
1189
1190 [source, java]
1191 ----
1192 public interface ProcessManagedBean<X>
1193 extends ProcessBean<X> {
1194 public AnnotatedType<X> getAnnotatedBeanClass();
1195 }
1196 ----
1197
1198 [source, java]
1199 ----
1200 public interface ProcessProducerMethod<T, X>
1201 extends ProcessBean<X> {
1202 public AnnotatedMethod<T> getAnnotatedProducerMethod();
1203 public AnnotatedParameter<T> getAnnotatedDisposedParameter();
1204 }
1205 ----
1206
1207 [source, java]
1208 ----
1209 public interface ProcessProducerField<T, X>
1210 extends ProcessBean<X> {
1211 public AnnotatedField<T> getAnnotatedProducerField();
1212 public AnnotatedParameter<T> getAnnotatedDisposedParameter();
1213 }
1214 ----
1215
1216 If any observer method of a +ProcessBean+ event throws an exception, the exception is treated as a definition error by the container.
1217
1218 If any +ProcessBean+ method is called outside of the observer method invocation, an +IllegalStateException+ is thrown.
1219
1220 [[pp]]
1221
1222 ==== +ProcessProducer+ event
1223
1224 The container must fire an event for each producer method or field of each bean, including resources.
1225
1226 The event object must be of type +javax.enterprise.inject.spi.ProcessProducer<T, X>+, where +T+ is the bean class of the bean that declares the producer method or field and +X+ is the return type of the producer method or the type of the producer field.
1227
1228 [source, java]
1229 ----
1230 public interface ProcessProducer<T, X> {
1231 public AnnotatedMember<T> getAnnotatedMember();
1232 public Producer<X> getProducer();
1233 public void setProducer(Producer<X> producer);
1234 public void addDefinitionError(Throwable t);
1235 }
1236 ----
1237
1238 * +getAnnotatedMember()+ returns the +AnnotatedField+ representing the producer field or the +AnnotatedMethod+ representing the producer method.
1239 * +getProducer()+ returns the +Producer+ object that will be used by the container to call the producer method or read the producer field.
1240 * +setProducer()+ replaces the +Producer+.
1241 * +addDefinitionError()+ registers a definition error with the container, causing the container to abort deployment after bean discovery is complete.
1242
1243
1244 Any observer of this event is permitted to wrap and/or replace the +Producer+. The container must use the final value of this property, after all observers have been called, whenever it calls the producer or disposer.
1245
1246 For example, this observer decorates the +Producer+ for all producer methods and fields of type +EntityManager+.
1247
1248 [source, java]
1249 ----
1250 void decorateEntityManager(@Observes ProcessProducer<?, EntityManager> pp) {
1251 pit.setProducer( decorate( pp.getProducer() ) );
1252 }
1253 ----
1254
1255 If any observer method of a +ProcessProducer+ event throws an exception, the exception is treated as a definition error by the container.
1256
1257 If any +ProcessProducer+ method is called outside of the observer method invocation, an +IllegalStateException+ is thrown.
1258
1259 [[pom]]
1260
1261 ==== +ProcessObserverMethod+ event
1262
1263 The container must fire an event for each observer method of each bean, before registering the +ObserverMethod+ object.
1264
1265 The event object must be of type +javax.enterprise.inject.spi.ProcessObserverMethod<T, X>+, where +T+ is the observed event type of the observer method and +X+ is the bean class of the bean that declares the observer method.
1266
1267 [source, java]
1268 ----
1269 public interface ProcessObserverMethod<T, X> {
1270 public AnnotatedMethod<X> getAnnotatedMethod();
1271 public ObserverMethod<T> getObserverMethod();
1272 public void addDefinitionError(Throwable t);
1273 }
1274 ----
1275
1276 * +getAnnotatedMethod()+ returns the +AnnotatedMethod+ representing the observer method.
1277 * +getObserverMethod()+ returns the +ObserverMethod+ object that will be used by the container to call the observer method.
1278 * +addDefinitionError()+ registers a definition error with the container, causing the container to abort deployment after bean discovery is complete.
1279
1280
1281 If any observer method of a +ProcessObserverMethod+ event throws an exception, the exception is treated as a definition error by the container.
1282
1283 If any +ProcessObserverMethod+ method is called outside of the observer method invocation, an +IllegalStateException+ is thrown.
1284