Debian Codegraph @

spec/src/main/doc/lifecycle.asciidoc

raw
1 [[lifecycle]]
2
3 == Lifecycle of contextual instances
4
5 The lifecycle of a contextual instance of a bean is managed by the context object for the bean's scope, as defined in <<contexts>>.
6
7 Every bean in the system is represented by an instance of the +Bean+ interface defined in <<bean>>. This interface is a subtype of +Contextual+. To create and destroy contextual instances, the context object calls the +create()+ and +destroy()+ operations defined by the interface +Contextual+, as defined in <<contextual>>.
8
9 [[bean_instantiation_restriction]]
10
11 === Restriction upon bean instantiation
12
13 The managed bean and EJB specifications place very few programming restrictions upon the bean class of a bean. In particular, the class is a concrete class and is not required to implement any special interface or extend any special superclass. Therefore, bean classes are easy to instantiate and unit test.
14
15 However, if the application directly instantiates a bean class, instead of letting the container perform instantiation, the resulting instance is not managed by the container and is not a contextual instance as defined by <<contextual_instance>>. Furthermore, the capabilities listed in <<capabilities>> will not be available to that particular instance. In a deployed application, it is the container that is responsible for instantiating beans and initializing their dependencies.
16
17 If the application requires more control over instantiation of a contextual instance, a producer method or field may be used. Any Java object may be returned by a producer method or field. It is not required that the returned object be a contextual reference for a bean. However, if the object is not a contextual reference for another bean, the object will be contextual instance of the producer method bean, and therefore available for injection into other objects and use in EL expressions, but the other capabilities listed in <<capabilities>> will not be available to the object.
18
19 In the following example, a producer method returns instances of other beans:
20
21 [source, java]
22 ----
23 @SessionScoped
24 public class PaymentStrategyProducer implements Serializable {
25
26 private PaymentStrategyType paymentStrategyType;
27
28 public void setPaymentStrategyType(PaymentStrategyType type) {
29 paymentStrategyType = type;
30 }
31
32 @Produces PaymentStrategy getPaymentStrategy(@CreditCard PaymentStrategy creditCard,
33 @Cheque PaymentStrategy cheque,
34 @Online PaymentStrategy online) {
35 switch (paymentStrategyType) {
36 case CREDIT_CARD: return creditCard;
37 case CHEQUE: return cheque;
38 case ONLINE: return online;
39 default: throw new IllegalStateException();
40 }
41 }
42
43 }
44 ----
45
46 In this case, any object returned by the producer method has already had its dependencies injected, receives lifecycle callbacks and event notifications and may have interceptors.
47
48 But in this example, the returned objects are not contextual instances:
49
50 [source, java]
51 ----
52 @SessionScoped
53 public class PaymentStrategyProducer implements Serializable {
54
55 private PaymentStrategyType paymentStrategyType;
56
57 public void setPaymentStrategyType(PaymentStrategyType type) {
58 paymentStrategyType = type;
59 }
60
61 @Produces PaymentStrategy getPaymentStrategy() {
62 switch (paymentStrategyType) {
63 case CREDIT_CARD: return new CreditCardPaymentStrategy();
64 case CHEQUE: return new ChequePaymentStrategy();
65 case ONLINE: return new OnlinePaymentStrategy();
66 default: throw new IllegalStateException();
67 }
68 }
69
70 }
71 ----
72
73 In this case, any object returned by the producer method will not have any dependencies injected by the container, receives no lifecycle callbacks or event notifications and does not have interceptors or decorators.
74
75 [[biz_method]]
76
77 === Container invocations and interception
78
79 When the application invokes:
80
81 * a method of a bean via a contextual reference to the bean, as defined in <<contextual_reference>>, or
82 * a method of a bean via a non-contextual reference to the bean, if the instance was created by the container (e.g. using +InjectionTarget.produce()+ or +UnmanagedInstance.produce()+), or
83 * a business method of a session bean via an EJB remote or local reference,
84
85
86 the invocation is treated as a _business method invocation_.
87
88 When the container invokes a method of a bean, the invocation may or may not be treated as a business method invocation:
89
90 * Invocations of initializer methods by the container are not business method invocations.
91 * Invocations of producer, disposer and observer methods by the container are business method invocations and are intercepted by method interceptors and decorators.
92 * Invocation of lifecycle callbacks by the container are not business method invocations, but are intercepted by interceptors for lifecycle callbacks.
93 * Invocation of EJB timer service timeouts by the container are not business method invocations, but are intercepted by interceptors for EJB timeouts.
94 * Invocations of interceptors and decorator methods during method or lifecycle callback interception are not business method invocations, and therefore no recursive interception occurs.
95 * Invocations of methods declared by java.lang.Object are not business method invocations.
96
97
98 If, and only if, an invocation is a business method invocation:
99
100 * it passes through method interceptors and decorators, and
101 * in the case of a session bean, it is subject to EJB services such as declarative transaction management, concurrency, security and asynchronicity, as defined by the EJB specification.
102
103 Additionally, invocations of message listener methods of message-driven beans during message delivery are passed through method interceptors.
104
105 Otherwise, the invocation is treated as a normal Java method call and is not intercepted by the container.
106
107 [[contextual_instance_lifecycle]]
108
109 === Lifecycle of contextual instances
110
111 The actual mechanics of bean creation and destruction varies according to what kind of bean is being created or destroyed.
112
113 [[managedbeanlifecycle]]
114
115 [[managed_bean_lifecycle]]
116
117 ==== Lifecycle of managed beans
118
119 When the +create()+ method of the +Bean+ object that represents a managed bean is called, the container obtains an instance of the bean, as defined by the Managed Beans specification, calling the bean constructor as defined by <<instantiation>>, and performing dependency injection as defined in <<fields_initializer_methods>>.
120
121 When the +destroy()+ method is called, the container destroys the instance, as defined by the Managed Beans specification, and any dependent objects, as defined in <<dependent_objects_destruction>>.
122
123 [[stateful_lifecycle]]
124
125 ==== Lifecycle of stateful session beans
126
127 When the +create()+ method of a +Bean+ object that represents a stateful session bean that is called, the container creates and returns a container-specific internal local reference to a new session bean instance. The reference must be passivation capable. This reference is not directly exposed to the application.
128
129 Before injecting or returning a contextual instance to the application, the container transforms its internal reference into an object that implements the bean types expected by the application and delegates method invocations to the underlying stateful session bean instance. This object must be passivation capable.
130
131 When the +destroy()+ method is called, and if the underlying EJB was not already removed by direct invocation of a remove method by the application, the container removes the stateful session bean. The +@PreDestroy+ callback must be invoked by the container.
132
133 Note that the container performs additional work when the underlying EJB is created and removed, as defined in <<injection>>
134
135 [[stateless_lifecycle]]
136
137 ==== Lifecycle of stateless and singleton session beans
138
139 When the +create()+ method of a +Bean+ object that represents a stateless session or singleton session bean is called, the container creates and returns a container-specific internal local reference to the session bean. This reference is not directly exposed to the application.
140
141 Before injecting or returning a contextual instance to the application, the container transforms its internal reference into an object that implements the bean types expected by the application and delegates method invocations to the underlying session bean. This object must be passivation capable.
142
143 When the +destroy()+ method is called, the container simply discards this internal reference.
144
145 Note that the container performs additional work when the underlying EJB is created and removed, as defined in <<injection>>
146
147 [[producer_method_lifecycle]]
148
149 ==== Lifecycle of producer methods
150
151 When the +create()+ method of a +Bean+ object that represents a producer method is called, the container must invoke the producer method as defined by <<producer_or_disposer_methods_invocation>>. The return value of the producer method, after method interception completes, is the new contextual instance to be returned by +Bean.create()+.
152
153 If the producer method returns a null value and the producer method bean has the scope +@Dependent+, the +create()+ method returns a null value.
154
155 Otherwise, if the producer method returns a null value, and the scope of the producer method is not +@Dependent+, the +create()+ method throws an +IllegalProductException+.
156
157 When the +destroy()+ method is called, and if there is a disposer method for this producer method, the container must invoke the disposer method as defined by <<producer_or_disposer_methods_invocation>>, passing the instance given to +destroy()+ to the disposed parameter. Finally, the container destroys dependent objects, as defined in <<dependent_objects_destruction>>.
158
159 [[producer_field_lifecycle]]
160
161 ==== Lifecycle of producer fields
162
163 When the +create()+ method of a +Bean+ object that represents a producer field is called, the container must access the producer field as defined by <<producer_fields_access>> to obtain the current value of the field. The value of the producer field is the new contextual instance to be returned by +Bean.create()+.
164
165 If the producer field contains a null value and the producer field bean has the scope +@Dependent+, the +create()+ method returns a null value.
166
167 Otherwise, if the producer field contains a null value, and the scope of the producer field is not +@Dependent+, the +create()+ method throws an +IllegalProductException+.
168
169 When the +destroy()+ method is called, and if there is a disposer method for this producer field, the container must invoke the disposer method as defined by <<producer_or_disposer_methods_invocation>>, passing the instance given to +destroy()+ to the disposed parameter.
170
171 [[resource_lifecycle]]
172
173 ==== Lifecycle of resources
174
175 When the +create()+ method of a +Bean+ object that represents a resource is called, the container creates and returns a container-specific internal reference to the Java EE component environment resource, entity manager, entity manager factory, remote EJB instance or web service reference. This reference is not directly exposed to the application.
176
177 Before injecting or returning a contextual instance to the application, the container transforms its internal reference into an object that implements the bean types expected by the application and delegates method invocations to the underlying resource, entity manager, entity manager factory, remote EJB instance or web service reference. This object must be passivation capable.
178
179 The container must perform ordinary Java EE component environment injection upon any non-static field that functions as a resource declaration, as defined by the Java EE platform and Common Annotations for the Java platform specifications. The container is not required to perform Java EE component environment injection upon a static field. Portable applications should not rely upon the value of a static field that functions as a resource declaration.
180
181 References to EJBs and web services are always dependent scoped and a new instance must be obtained for every injection performed.
182
183 For an entity manager associated with a resource definition, it must behave as though it were injected directly using +@PersistencContext+.
184
185 When the +destroy()+ method of a bean which represents a remote stateful EJB reference is called, the container will _not_ automatically destroy the EJB reference. The application must explicitly call the method annotated +@Remove+. This behavior differs to that specified in <<stateful_lifecycle>> for beans which represent a local stateful EJB reference
186