| 1 |
[[contexts]] |
| 2 |
|
| 3 |
== Scopes and contexts |
| 4 |
|
| 5 |
Associated with every scope type is a _context object_. The context object determines the lifecycle and visibility of instances of all beans with that scope. In particular, the context object defines: |
| 6 |
|
| 7 |
* When a new instance of any bean with that scope is created |
| 8 |
* When an existing instance of any bean with that scope is destroyed |
| 9 |
* Which injected references refer to any instance of a bean with that scope |
| 10 |
|
| 11 |
|
| 12 |
The context implementation collaborates with the container via the +Context+ and +Contextual+ interfaces to create and destroy contextual instances. |
| 13 |
|
| 14 |
[[contextual]] |
| 15 |
|
| 16 |
=== The +Contextual+ interface |
| 17 |
|
| 18 |
The interface +javax.enterprise.context.spi.Contextual+ defines operations to create and destroy contextual instances of a certain type. Any implementation of +Contextual+ is called a _contextual type_. In particular, the +Bean+ interface defined in <<bean>> extends +Contextual+, so all beans are contextual types. |
| 19 |
|
| 20 |
[source, java] |
| 21 |
---- |
| 22 |
public interface Contextual<T> { |
| 23 |
public T create(CreationalContext<T> creationalContext); |
| 24 |
public void destroy(T instance, CreationalContext<T> creationalContext); |
| 25 |
} |
| 26 |
---- |
| 27 |
|
| 28 |
* +create()+ is responsible for creating new contextual instances of the type. |
| 29 |
* +destroy()+ is responsible for destroying instances of the type. In particular, it is responsible for destroying all dependent objects of an instance. |
| 30 |
|
| 31 |
|
| 32 |
If an exception occurs while creating an instance, the exception is rethrown by the +create()+ method. If the exception is a checked exception, it must be wrapped and rethrown as an (unchecked) +CreationException+. |
| 33 |
|
| 34 |
If an exception occurs while destroying an instance, the exception must be caught by the +destroy()+ method. |
| 35 |
|
| 36 |
If the application invokes a contextual instance after it has been destroyed, the behavior is undefined. |
| 37 |
|
| 38 |
The container and portable extensions may define implementations of the +Contextual+ interface that do not extend +Bean+, but it is not recommended that applications directly implement +Contextual+. |
| 39 |
|
| 40 |
[[creational_context]] |
| 41 |
|
| 42 |
==== The +CreationalContext+ interface |
| 43 |
|
| 44 |
The interface +javax.enterprise.context.spi.CreationalContext+ provides operations that are used by the +Contextual+ implementation during instance creation and destruction. |
| 45 |
|
| 46 |
[source, java] |
| 47 |
---- |
| 48 |
public interface CreationalContext<T> { |
| 49 |
public void push(T incompleteInstance); |
| 50 |
public void release(); |
| 51 |
} |
| 52 |
---- |
| 53 |
|
| 54 |
* +push()+ registers an _incompletely initialized_ contextual instance the with the container. A contextual instance is considered incompletely initialized until it is returned by the +create()+ method. |
| 55 |
* +release()+ destroys all dependent objects, as defined in <<dependent_objects>>, of the instance which is being destroyed, by passing each dependent object to the +destroy()+ method of its +Contextual+ object. |
| 56 |
|
| 57 |
|
| 58 |
The implementation of +Contextual+ is not required to call +push()+. However, for certain bean scopes, invocation of +push()+ between instantiation and injection helps the container minimize the use of client proxy objects (which would otherwise be required to allow circular dependencies). |
| 59 |
|
| 60 |
If +Contextual.create()+ calls +push()+, it must also return the instance passed to +push()+. |
| 61 |
|
| 62 |
+Contextual.create()+ should use the given +CreationalContext+ when obtaining contextual references to inject, as defined in <<contextual_reference>>, in order to ensure that any dependent objects are associated with the contextual instance that is being created. |
| 63 |
|
| 64 |
+Contextual.destroy()+ should call +release()+ to allow the container to destroy dependent objects of the contextual instance. |
| 65 |
|
| 66 |
[[context]] |
| 67 |
|
| 68 |
=== The +Context+ interface |
| 69 |
|
| 70 |
The +javax.enterprise.context.spi.Context+ interface provides an operation for obtaining contextual instances with a particular scope of any contextual type. Any instance of +Context+ is called a context object. |
| 71 |
|
| 72 |
The context object is responsible for creating and destroying contextual instances by calling operations of the +Contextual+ interface. |
| 73 |
|
| 74 |
The +Context+ interface is called by the container and may be called by portable extensions. It should not be called directly by the application. |
| 75 |
|
| 76 |
[source, java] |
| 77 |
---- |
| 78 |
public interface Context { |
| 79 |
public Class<? extends Annotation> getScope(); |
| 80 |
boolean isActive(); |
| 81 |
public <T> T get(Contextual<T> bean); |
| 82 |
public <T> T get(Contextual<T> bean, CreationalContext<T> creationalContext); |
| 83 |
} |
| 84 |
---- |
| 85 |
|
| 86 |
[source, java] |
| 87 |
---- |
| 88 |
public interface AlterableContext extends Context { |
| 89 |
public void destroy(Contextual<?> contextual); |
| 90 |
} |
| 91 |
---- |
| 92 |
|
| 93 |
The method +getScope()+ returns the scope type of the context object. |
| 94 |
|
| 95 |
A context object may be defined for any of the built-in scopes and registered with the container using the `AfterBeanDiscovery` event as described in <<abd>>. |
| 96 |
|
| 97 |
At a particular point in the execution of the program a context object may be _active_ with respect to the current thread. When a context object is active the +isActive()+ method returns +true+. Otherwise, we say that the context object is _inactive_ and the +isActive()+ method returns +false+. |
| 98 |
|
| 99 |
The +get()+ method obtains contextual instances of the contextual type represented by the given instance of +Contextual+. The +get()+ method may either: |
| 100 |
|
| 101 |
* return an existing instance of the given contextual type, or |
| 102 |
* if no +CreationalContext+ is given, return a null value, or |
| 103 |
* if a +CreationalContext+ is given, create a new instance of the given contextual type by calling +Contextual.create()+, passing the given +CreationalContext+, and return the new instance. |
| 104 |
|
| 105 |
|
| 106 |
The +get()+ method may not return a null value unless no +CreationalContext+ is given, or +Contextual.create()+ returns a null value. |
| 107 |
|
| 108 |
The +get()+ method may not create a new instance of the given contextual type unless a +CreationalContext+ is given. |
| 109 |
|
| 110 |
The +destroy()+ method destroys an existing contextual instance, removing it from the context instance. |
| 111 |
|
| 112 |
The +AlterableContext+ interface was introduced in Contexts and Dependency Injection for Java EE 1.1 to allow bean instances to be destroyed by the application. Extensions providing context implementations for normal scopes should implement +AlterableContext+ instead of +Context+. |
| 113 |
|
| 114 |
If the context object is inactive, the +get()+ and +destroy()+ methods must throw a +ContextNotActiveException+. |
| 115 |
|
| 116 |
When the container calls +get()+ or +destroy()+ for a context that is associated with a passivating scope it must ensure that the given instance of +Contextual+ and the instance of +CreationalContext+, if given, are serializable. |
| 117 |
|
| 118 |
The context object is responsible for destroying any contextual instance it creates by passing the instance to the +destroy()+ method of the +Contextual+ object representing the contextual type. A destroyed instance must not subsequently be returned by the +get()+ method. |
| 119 |
|
| 120 |
The context object must pass the same instance of +CreationalContext+ to +Contextual.destroy()+ that it passed to +Contextual.create()+ when it created the instance. |
| 121 |
|
| 122 |
[[normal_scope]] |
| 123 |
|
| 124 |
=== Normal scopes and pseudo-scopes |
| 125 |
|
| 126 |
Most scopes are _normal scopes_. The context object for a normal scope type is a mapping from each contextual type with that scope to an instance of that contextual type. There may be no more than one mapped instance per contextual type per thread. The set of all mapped instances of contextual types with a certain scope for a certain thread is called the _context_ for that scope associated with that thread. |
| 127 |
|
| 128 |
A context may be associated with one or more threads. A context with a certain scope is said to _propagate_ from one point in the execution of the program to another when the set of mapped instances of contextual types with that scope is preserved. |
| 129 |
|
| 130 |
The context associated with the current thread is called the _current context_ for the scope. The mapped instance of a contextual type associated with a current context is called the _current instance_ of the contextual type. |
| 131 |
|
| 132 |
The +get()+ operation of the context object for an active normal scope returns the current instance of the given contextual type. |
| 133 |
|
| 134 |
At certain points in the execution of the program a context may be _destroyed_. When a context is destroyed, all mapped instances belonging to that context are destroyed by passing them to the +Contextual.destroy()+ method. |
| 135 |
|
| 136 |
Contexts with normal scopes must obey the following rule: |
| 137 |
|
| 138 |
_Suppose beans A, B and Z all have normal scopes. Suppose A has an injection point x, and B has an injection point y. Suppose further that both x and y resolve to bean Z according to the rules of typesafe resolution. If a is the current instance of A, and b is the current instance of B, then both a.x and b.y refer to the same instance of Z. This instance is the current instance of Z._ |
| 139 |
|
| 140 |
Any scope that is not a normal scope is called a _pseudo-scope_. The concept of a current instance is not well-defined in the case of a pseudo-scope. |
| 141 |
|
| 142 |
All normal scopes must be explicitly declared +@NormalScope+, to indicate to the container that a client proxy is required. |
| 143 |
|
| 144 |
All pseudo-scopes must be explicitly declared +@Scope+, to indicate to the container that no client proxy is required. |
| 145 |
|
| 146 |
All scopes defined by this specification, except for the +@Dependent+ pseudo-scope, are normal scopes. |
| 147 |
|
| 148 |
[[dependent_context]] |
| 149 |
|
| 150 |
=== Dependent pseudo-scope |
| 151 |
|
| 152 |
The +@Dependent+ scope type is a pseudo-scope. Beans declared with scope type +@Dependent+ behave differently to beans with other built-in scope types. |
| 153 |
|
| 154 |
When a bean is declared to have +@Dependent+ scope: |
| 155 |
|
| 156 |
* No injected instance of the bean is ever shared between multiple injection points. |
| 157 |
* Any instance of the bean injected into an object that is being created by the container is bound to the lifecycle of the newly created object. |
| 158 |
* When a Unified EL expression in a JSF or JSP page that refers to the bean by its bean name is evaluated, at most one instance of the bean is instantiated. This instance exists to service just a single evaluation of the EL expression. It is reused if the bean name appears multiple times in the EL expression, but is never reused when the EL expression is evaluated again, or when another EL expression is evaluated. |
| 159 |
* Any instance of the bean that receives a producer method, producer field, disposer method or observer method invocation exists to service that invocation only. |
| 160 |
* Any instance of the bean injected into method parameters of a disposer method or observer method exists to service the method invocation only (except for observer methods of container lifecycle events). |
| 161 |
|
| 162 |
|
| 163 |
Every invocation of the +get()+ operation of the +Context+ object for the +@Dependent+ scope with a +CreationalContext+ returns a new instance of the given bean. |
| 164 |
|
| 165 |
Every invocation of the +get()+ operation of the +Context+ object for the +@Dependent+ scope with no +CreationalContext+ returns a null value. |
| 166 |
|
| 167 |
The +@Dependent+ scope is always active. |
| 168 |
|
| 169 |
[[dependent_objects]] |
| 170 |
|
| 171 |
==== Dependent objects |
| 172 |
|
| 173 |
Many instances of beans with scope +@Dependent+ belong to some other bean or Java EE component class instance and are called _dependent objects_. |
| 174 |
|
| 175 |
* Instances of decorators and interceptors are dependent objects of the bean instance they decorate. |
| 176 |
* An instance of a bean with scope +@Dependent+ injected into a field, bean constructor or initializer method is a dependent object of the bean or Java EE component class instance into which it was injected. |
| 177 |
* An instance of a bean with scope +@Dependent+ injected into a producer method is a dependent object of the producer method bean instance that is being produced. |
| 178 |
* An instance of a bean with scope +@Dependent+ obtained by direct invocation of an +Instance+ is a dependent object of the instance of +Instance+. |
| 179 |
|
| 180 |
|
| 181 |
[[dependent_destruction]] |
| 182 |
|
| 183 |
==== Destruction of objects with scope +@Dependent+ |
| 184 |
|
| 185 |
Dependent objects of a contextual instance are destroyed when +Contextual.destroy()+ calls +CreationalContext.release()+, as defined in <<creational_context>>. |
| 186 |
|
| 187 |
Additionally, the container must ensure that: |
| 188 |
|
| 189 |
* all dependent objects of a non-contextual instance of a bean or other Java EE component class are destroyed when the instance is destroyed by the container, |
| 190 |
* all +@Dependent+ scoped contextual instances injected into method parameters of a disposer method or an observer method are destroyed when the invocation completes, |
| 191 |
* all +@Dependent+ scoped contextual instances injected into method or constructor parameters that are annotated with +@TransientReference+ are destroyed when the invocation completes, |
| 192 |
* any +@Dependent+ scoped contextual instance created to receive a producer method, producer field, disposer method or observer method invocation is destroyed when the invocation completes, and |
| 193 |
* all +@Dependent+ scoped contextual instances created during evaluation of a Unified EL expression in a JSP or JSF page are destroyed when the evaluation completes. |
| 194 |
|
| 195 |
|
| 196 |
Finally, the container is permitted to destroy any +@Dependent+ scoped contextual instance at any time if the instance is no longer referenced by the application (excluding weak, soft and phantom references). |
| 197 |
|
| 198 |
[[dependent_scope_el]] |
| 199 |
|
| 200 |
==== Dependent pseudo-scope and Unified EL |
| 201 |
|
| 202 |
Suppose a Unified EL expression in a JSF or JSP page refers to a bean with scope +@Dependent+ by its bean name. Each time the EL expression is evaluated: |
| 203 |
|
| 204 |
* the bean is instantiated at most once, and |
| 205 |
* the resulting instance is reused for every appearance of the bean name, and |
| 206 |
* the resulting instance is destroyed when the evaluation completes. |
| 207 |
|
| 208 |
|
| 209 |
Portable extensions that integrate with the container via Unified EL should also ensure that these rules are enforced. |
| 210 |
|
| 211 |
[[contextual_instances_and_references]] |
| 212 |
|
| 213 |
=== Contextual instances and contextual references |
| 214 |
|
| 215 |
The +Context+ object is the ultimate source of the contextual instances that underly contextual references. |
| 216 |
|
| 217 |
[[active_context]] |
| 218 |
|
| 219 |
==== The active context object for a scope |
| 220 |
|
| 221 |
From time to time, the container must obtain an _active context object_ for a certain scope type. The container must search for an active instance of +Context+ associated with the scope type. |
| 222 |
|
| 223 |
* If no active context object exists for the scope type, the container throws a +ContextNotActiveException+. |
| 224 |
* If more than one active context object exists for the given scope type, the container must throw an +IllegalStateException+. |
| 225 |
|
| 226 |
|
| 227 |
If there is exactly one active instance of +Context+ associated with the scope type, we say that the scope is _active_. |
| 228 |
|
| 229 |
[[contextual_instance]] |
| 230 |
|
| 231 |
==== Contextual instance of a bean |
| 232 |
|
| 233 |
From time to time, the container must obtain a _contextual instance_ of a bean. The container must: |
| 234 |
|
| 235 |
* obtain the active context object for the bean scope, then |
| 236 |
* obtain an instance of the bean by calling +Context.get()+, passing the +Bean+ instance representing the bean and an instance of +CreationalContext+. |
| 237 |
|
| 238 |
|
| 239 |
From time to time, the container attempts to obtain a _contextual instance of a bean that already exists_, without creating a new contextual instance. The container must determine if the scope of the bean is active and if it is: |
| 240 |
|
| 241 |
* obtain the active context object for the bean scope, then |
| 242 |
* attempt to obtain an existing instance of the bean by calling +Context.get()+, passing the +Bean+ instance representing the bean without passing any instance of +CreationalContext+. |
| 243 |
|
| 244 |
|
| 245 |
If the scope is not active, or if +Context.get()+ returns a null value, there is no contextual instance that already exists. |
| 246 |
|
| 247 |
A contextual instance of any of the built-in kinds of bean defined in <<implementation>> is considered an internal container construct, and it is therefore not strictly required that a contextual instance of a built-in kind of bean directly implement the bean types of the bean. However, in this case, the container is required to transform its internal representation to an object that does implement the bean types expected by the application before injecting or returning a contextual instance to the application. |
| 248 |
|
| 249 |
For a custom implementation of the +Bean+ interface defined in <<bean>>, the container calls +getScope()+ to determine the bean scope. |
| 250 |
|
| 251 |
[[contextual_reference]] |
| 252 |
|
| 253 |
==== Contextual reference for a bean |
| 254 |
|
| 255 |
From time to time, the container must obtain a _contextual reference_ for a bean and a given bean type of the bean. A contextual reference implements the given bean type and all bean types of the bean which are Java interfaces. A contextual reference is not, in general, required to implement all concrete bean types of the bean. |
| 256 |
|
| 257 |
Contextual references must be obtained with a given +CreationalContext+, allowing any instance of scope +@Dependent+ that is created to be later destroyed. |
| 258 |
|
| 259 |
* If the bean has a normal scope and the given bean type cannot be proxied by the container, as defined in <<unproxyable>>, the container throws an +UnproxyableResolutionException+. |
| 260 |
* If the bean has a normal scope, then the contextual reference for the bean is a client proxy, as defined in <<client_proxies>>, created by the container, that implements the given bean type and all bean types of the bean which are Java interfaces. |
| 261 |
* Otherwise, if the bean has a pseudo-scope, the container must obtain a contextual instance of the bean. If the bean has scope +@Dependent+, the container must associate it with the +CreationalContext+. |
| 262 |
|
| 263 |
|
| 264 |
The container must ensure that every injection point of type +InjectionPoint+ and qualifier +@Default+ of any dependent object instantiated during this process receives: |
| 265 |
|
| 266 |
* an instance of +InjectionPoint+ representing the injection point into which the dependent object will be injected, or |
| 267 |
* a null value if it is not being injected into any injection point. |
| 268 |
|
| 269 |
[[contextual_reference_validity]] |
| 270 |
|
| 271 |
==== Contextual reference validity |
| 272 |
|
| 273 |
A contextual reference for a bean is _valid_ only for a certain period of time. The application should not invoke a method of an invalid reference. |
| 274 |
|
| 275 |
The validity of a contextual reference for a bean depends upon whether the scope of the bean is a normal scope or a pseudo-scope. |
| 276 |
|
| 277 |
* Any reference to a bean with a normal scope is valid as long as the application maintains a hard reference to it. However, it may only be invoked when the context associated with the normal scope is active. If it is invoked when the context is inactive, a +ContextNotActiveException+ is thrown by the container. |
| 278 |
* Any reference to a bean with a pseudo-scope (such as +@Dependent+) is valid until the bean instance to which it refers is destroyed. It may be invoked even if the context associated with the pseudo-scope is not active. If the application invokes a method of a reference to an instance that has already been destroyed, the behavior is undefined. |
| 279 |
|
| 280 |
|
| 281 |
[[injectable_reference]] |
| 282 |
|
| 283 |
==== Injectable references |
| 284 |
|
| 285 |
From time to time, the container must obtain an _injectable reference_ for an injection point. The container must: |
| 286 |
|
| 287 |
* Identify a bean according to the rules defined in <<typesafe_resolution>> and resolving ambiguities according to <<unsatisfied_and_ambig_dependencies>>. |
| 288 |
* Obtain a contextual reference for this bean and the type of the injection point according to <<contextual_reference>>. |
| 289 |
|
| 290 |
|
| 291 |
For certain combinations of scopes, the container is permitted to optimize the above procedure: |
| 292 |
|
| 293 |
* The container is permitted to directly inject a contextual instance of the bean, as defined in <<contextual_instance>>. |
| 294 |
* If an incompletely initialized instance of the bean is registered with the current +CreationalContext+, as defined in <<contextual>>, the container is permitted to directly inject this instance. |
| 295 |
|
| 296 |
|
| 297 |
However, in performing these optimizations, the container must respect the rules of _injectable reference validity_. |
| 298 |
|
| 299 |
[[injectable_reference_validity]] |
| 300 |
|
| 301 |
==== Injectable reference validity |
| 302 |
|
| 303 |
Injectable references to a bean must respect the rules of contextual reference validity, with the following exceptions: |
| 304 |
|
| 305 |
* A reference to a bean injected into a field, bean constructor or initializer method is only valid until the object into which it was injected is destroyed. |
| 306 |
* A reference to a bean injected into a producer method is only valid until the producer method bean instance that is being produced is destroyed. |
| 307 |
* A reference to a bean injected into a disposer method or observer method is only valid until the invocation of the method completes. |
| 308 |
|
| 309 |
|
| 310 |
The application should not invoke a method of an invalid injected reference. If the application invokes a method of an invalid injected reference, the behavior is undefined. |
| 311 |
|
| 312 |
[[passivating_scope]] |
| 313 |
|
| 314 |
=== Passivation and passivating scopes |
| 315 |
|
| 316 |
The temporary transfer of the state of an idle object held in memory to some form of secondary storage is called _passivation_. The transfer of the passivated state back into memory is called _activation_. |
| 317 |
|
| 318 |
[[passivation_capable]] |
| 319 |
|
| 320 |
==== Passivation capable beans |
| 321 |
|
| 322 |
A bean is called _passivation capable_ if the container is able to temporarily transfer the state of any idle instance to secondary storage. |
| 323 |
|
| 324 |
* As defined by the EJB specification, a stateful session beans is passivation capable if: |
| 325 |
** interceptors and decorators of the bean are passivation capable, and, |
| 326 |
** the stateful session bean does not have the +passivationCapable+ flag set to +false+. |
| 327 |
* As defined by the EJB specification, a stateless session bean or a singleton session bean is not passivation capable. |
| 328 |
* A managed bean is passivation capable if and only if the bean class is serializable and all interceptors and decorators of the bean are passivation capable. |
| 329 |
* A producer method is passivation capable if and only if it never returns a value which is not passivation capable at runtime. |
| 330 |
* A producer field is passivation capable if and only if it never refers to a value which is not passivation capable at runtime. |
| 331 |
|
| 332 |
|
| 333 |
A custom implementation of +Bean+ is passivation capable if it implements the interface +PassivationCapable+. An implementation of +Contextual+ that is not a bean is passivation capable if it implements both +PassivationCapable+ and +Serializable+. |
| 334 |
|
| 335 |
[source, java] |
| 336 |
---- |
| 337 |
public interface PassivationCapable { |
| 338 |
public String getId(); |
| 339 |
} |
| 340 |
---- |
| 341 |
|
| 342 |
The +getId()+ method must return a value that uniquely identifies the instance of +Bean+ or +Contextual+. It is recommended that the string contain the package name of the class that implements +Bean+ or +Contextual+. |
| 343 |
|
| 344 |
[[passivation_capable_injection_points]] |
| 345 |
|
| 346 |
==== Passivation capable injection points |
| 347 |
|
| 348 |
We call an injection point of a bean _passivation capable_ if the injection point is: |
| 349 |
|
| 350 |
* a transient field, or |
| 351 |
* a non-transient field which resolves to a bean that is a passivation capable dependency, or |
| 352 |
* a bean constructor parameter which is annotated with +@TransientReference+, or |
| 353 |
* a bean constructor parameter which resolves to a bean that is a passivation capable dependency, or |
| 354 |
* a method parameter which is annotated with +@TransientReference+, or |
| 355 |
* a method parameter which resolves to a bean that is a passivation capable dependency. |
| 356 |
|
| 357 |
[[passivation_capable_dependency]] |
| 358 |
|
| 359 |
==== Passivation capable dependencies |
| 360 |
|
| 361 |
A bean is called a _passivation capable dependency_ if any contextual reference for that bean is preserved when the object holding the reference is passivated and then activated. |
| 362 |
|
| 363 |
The container must guarantee that: |
| 364 |
|
| 365 |
* all beans with normal scope are passivation capable dependencies, |
| 366 |
* all passivation capable beans with scope +@Dependent+ are passivation capable dependencies, |
| 367 |
* all stateless session beans are passivation capable dependencies, |
| 368 |
* all singleton session beans are passivation capable dependencies, |
| 369 |
* all passivation capable stateful session beans are passivation capable dependencies, |
| 370 |
* all resources are passivation capable dependencies, and |
| 371 |
* the built-in beans of type +Instance+, +Event+, +InjectionPoint+ and +BeanManager+ are passivation capable dependencies. |
| 372 |
|
| 373 |
|
| 374 |
A custom implementation of +Bean+ is a passivation capable dependency if it implements +PassivationCapable+. |
| 375 |
|
| 376 |
[[passivating_scopes]] |
| 377 |
|
| 378 |
==== Passivating scopes |
| 379 |
|
| 380 |
A _passivating scope_ requires that: |
| 381 |
|
| 382 |
* beans with the scope are passivation capable, and |
| 383 |
* implementations of +Contextual+ passed to any context object for the scope are passivation capable. |
| 384 |
|
| 385 |
|
| 386 |
Passivating scopes must be explicitly declared +@NormalScope(passivating=true)+. |
| 387 |
|
| 388 |
For example, the built-in session and conversation scopes defined in <<builtin_contexts>> are passivating scopes. No other built-in scopes are passivating scopes. |
| 389 |
|
| 390 |
[[passivation_validation]] |
| 391 |
|
| 392 |
==== Validation of passivation capable beans and dependencies |
| 393 |
|
| 394 |
For every bean which declares a passivating scope, the container must validate that the bean truly is passivation capable and that, in addition, its dependencies are passivation capable. |
| 395 |
|
| 396 |
If a managed bean which declares a passivating scope, a stateful session bean which declares a passivating scope, or a built-in bean: |
| 397 |
|
| 398 |
* is not passivation capable, |
| 399 |
* has an injection point that is not passivation capable, |
| 400 |
* has an interceptor or decorator that is not passivation capable |
| 401 |
* has an interceptor or decorator with an injection point that is not passivation capable |
| 402 |
|
| 403 |
then the container automatically detects the problem and treats it as a deployment problem. |
| 404 |
|
| 405 |
If a producer method declares a passivating scope and: |
| 406 |
|
| 407 |
* has a return type that is declared final and does not implement or extend +Serializable+, or, |
| 408 |
* has an injection point that is not passivation capable |
| 409 |
|
| 410 |
then the container automatically detects the problem and treats it as a deployment problem. |
| 411 |
|
| 412 |
If a producer method declares a passivating scope and doesn't only return +Serializable+ types at runtime, then the container must throw an +IllegalProductException+. |
| 413 |
|
| 414 |
If a producer field declares a passivating scope and has a type that is declared final and does not implement or extend +Serializable+ then the container automatically detects the problem and treats it as a deployment problem. |
| 415 |
|
| 416 |
If a producer field declares a passivating scope and doesn't only contain +Serializable+ values at runtime then the container must throw an +IllegalProductException+. |
| 417 |
|
| 418 |
If a producer method or field of scope +@Dependent+ returns an unserializable object for injection into an injection point that requires a passivation capable dependency, the container must throw an +IllegalProductException+ |
| 419 |
|
| 420 |
For a custom implementation of +Bean+, the container calls +getInjectionPoints()+ to determine the injection points, and +InjectionPoint.isTransient()+ to determine whether the injection point is a transient field. |
| 421 |
|
| 422 |
If a managed bean or a stateful session bean which declares a passivating scope type, has a decorator or interceptor which is not a passivation capable dependency, the container automatically detects the problem and treats it as a deployment problem. |
| 423 |
|
| 424 |
[[builtin_contexts]] |
| 425 |
|
| 426 |
=== Context management for built-in scopes |
| 427 |
|
| 428 |
The container provides an implementation of the +Context+ interface for each of the built-in scopes. |
| 429 |
|
| 430 |
The built-in request and application context objects are active during servlet, web service and EJB invocations, and the built in session and request context objects are active during servlet and web service invocations. For other kinds of invocations, a portable extension may define a custom context object for any or all of the built-in scopes. For example, a remoting framework might provide a request context object for the built-in request scope. |
| 431 |
|
| 432 |
The context associated with a built-in normal scope propagates across local, synchronous Java method calls, including invocation of EJB local business methods. The context does not propagate across remote method invocations or to asynchronous processes such as JMS message listeners or EJB timer service timeouts. |
| 433 |
|
| 434 |
Portable extensions are encouraged to fire an event with qualifier +@Initialized(X.class)+ when a custom context is initialized, and an event with qualifier +@Destroyed(X.class)+ when a custom context is destroyed, where X is the scope type associated with the context. A suitable event payload should be chosen. |
| 435 |
|
| 436 |
[[request_context]] |
| 437 |
|
| 438 |
==== Request context lifecycle |
| 439 |
|
| 440 |
The _request context_ is provided by a built-in context object for the built-in scope type +@RequestScoped+. The request scope is active: |
| 441 |
|
| 442 |
* during the +service()+ method of any servlet in the web application, during the +doFilter()+ method of any servlet filter and when the container calls any +ServletRequestListener+ or +AsyncListener+, |
| 443 |
* during any Java EE web service invocation, |
| 444 |
* during any remote method invocation of any EJB, during any asynchronous method invocation of any EJB, during any call to an EJB timeout method and during message delivery to any EJB message-driven bean, and |
| 445 |
* during +@PostConstruct+ callback of any bean. |
| 446 |
|
| 447 |
|
| 448 |
The request context is destroyed: |
| 449 |
|
| 450 |
* at the end of the servlet request, after the +service()+ method, all +doFilter()+ methods, and all +requestDestroyed()+ and +onComplete()+ notifications return, |
| 451 |
* after the web service invocation completes, |
| 452 |
* after the EJB remote method invocation, asynchronous method invocation, timeout or message delivery completes if it did not already exist when the invocation occurred, or |
| 453 |
* after the +@PostConstruct+ callback completes, if it did not already exist when the +@PostConstruct+ callback occurred. |
| 454 |
|
| 455 |
|
| 456 |
An event with qualifier +@Initialized(RequestScoped.class)+ is fired when the request context is initialized and an event with qualifier +@Destroyed(RequestScoped.class)+ when the request context is destroyed. The event payload is: |
| 457 |
|
| 458 |
* the +ServletRequest+ if the context is initialized or destroyed due to a servlet request, or |
| 459 |
* the +ServletRequest+ if the context is initialized or destroyed due to a web service invocation, or |
| 460 |
* any +java.lang.Object+ for other types of request. |
| 461 |
|
| 462 |
|
| 463 |
[[session_context]] |
| 464 |
|
| 465 |
==== Session context lifecycle |
| 466 |
|
| 467 |
The _session context_ is provided by a built-in context object for the built-in passivating scope type +@SessionScoped+. The session scope is active: |
| 468 |
|
| 469 |
* during the +service()+ method of any servlet in the web application, during the +doFilter()+ method of any servlet filter and when the container calls any +HttpSessionListener+, +AsyncListener+ or +ServletRequestListener+. |
| 470 |
|
| 471 |
|
| 472 |
The session context is shared between all servlet requests that occur in the same HTTP session. The session context is destroyed when the +HTTPSession+ times out, after all ++HttpSessionListener++ s have been called, and at the very end of any request in which +invalidate()+ was called, after all filters and ++ServletRequestListener++ s have been called. |
| 473 |
|
| 474 |
An event with the +HttpSession+ as payload and with qualifier +@Initialized(SessionScoped.class)+ is fired when the session context is initialized and an event with qualifier +@Destroyed(SessionScoped.class)+ when the session context is destroyed. |
| 475 |
|
| 476 |
[[application_context]] |
| 477 |
|
| 478 |
==== Application context lifecycle |
| 479 |
|
| 480 |
The _application context_ is provided by a built-in context object for the built-in scope type +@ApplicationScoped+. The application scope is active: |
| 481 |
|
| 482 |
* during the +service()+ method of any servlet in the web application, during the +doFilter()+ method of any servlet filter and when the container calls any +ServletContextListener+, +HttpSessionListener+, +AsyncListener+ or +ServletRequestListener+, |
| 483 |
* during any Java EE web service invocation, |
| 484 |
* during any remote method invocation of any EJB, during any asynchronous method invocation of any EJB, during any call to an EJB timeout method and during message delivery to any EJB message-driven bean, |
| 485 |
* when the disposer method or +@PreDestroy+ callback of any bean with any normal scope other than +@ApplicationScoped+ is called, and |
| 486 |
* during +@PostConstruct+ callback of any bean. |
| 487 |
|
| 488 |
|
| 489 |
The application context is shared between all servlet requests, web service invocations, EJB remote method invocations, EJB asynchronous method invocations, EJB timeouts and message deliveries to message-driven beans that execute within the same application. The application context is destroyed when the application is shut down. |
| 490 |
|
| 491 |
An event with qualifier +@Initialized(ApplicationScoped.class)+ is fired when the application context is initialized and an event with qualifier +@Destroyed(ApplicationScoped.class)+ is fired when the application is destroyed. The event payload is: |
| 492 |
|
| 493 |
* the +ServletContext+ if the application is a web application deployed to a Servlet container, or |
| 494 |
* any +java.lang.Object+ for other types of application. |
| 495 |
|
| 496 |
|
| 497 |
[[conversation_context]] |
| 498 |
|
| 499 |
==== Conversation context lifecycle |
| 500 |
|
| 501 |
The _conversation context_ is provided by a built-in context object for the built-in passivating scope type +@ConversationScoped+. The conversation scope is active during all Servlet requests. |
| 502 |
|
| 503 |
An event with qualifier +@Initialized(ConversationScoped.class)+ is fired when the conversation context is initialized and an event with qualifier +@Destroyed(ConversationScoped.class)+ is fired when the conversation is destroyed. The event payload is: |
| 504 |
|
| 505 |
* the conversation id if the conversation context is destroyed and is not associated with a current Servlet request, or |
| 506 |
* the +ServletRequest+ if the application is a web application deployed to a Servlet container, or |
| 507 |
* any +java.lang.Object+ for other types of application. |
| 508 |
|
| 509 |
|
| 510 |
The conversation context provides access to state associated with a particular _conversation_. Every Servlet request has an associated conversation. This association is managed automatically by the container according to the following rules: |
| 511 |
|
| 512 |
* Any Servlet request has exactly one associated conversation. |
| 513 |
* The container provides a filter with the name "CDI Conversation Filter", which may be mapped in +web.xml+, allowing the user alter when the conversation is associated with the servlet request. If this filter is not mapped in any +web.xml+ in the application, the conversation associated with a Servlet request is determined at the beginning of the request before calling any +service()+ method of any servlet in the web application, calling the +doFilter()+ method of any servlet filter in the web application and before the container calls any +ServletRequestListener+ or +AsyncListener+ in the web application. |
| 514 |
* The implementation should determine the conversation associated with the Servlet request in a way that does not prevent other filters or servlet from setting the request character encoding or parsing the request body themselves. |
| 515 |
|
| 516 |
Any conversation is in one of two states: _transient_ or _long-running_. |
| 517 |
|
| 518 |
* By default, a conversation is transient |
| 519 |
* A transient conversation may be marked long-running by calling +Conversation.begin()+ |
| 520 |
* A long-running conversation may be marked transient by calling +Conversation.end()+ |
| 521 |
|
| 522 |
|
| 523 |
All long-running conversations have a string-valued unique identifier, which may be set by the application when the conversation is marked long-running, or generated by the container. |
| 524 |
|
| 525 |
If the conversation associated with the current Servlet request is in the _transient_ state at the end of a Servlet request, it is destroyed, and the conversation context is also destroyed. |
| 526 |
|
| 527 |
If the conversation associated with the current Servlet request is in the _long-running_ state at the end of a Servlet request, it is not destroyed. The long-running conversation associated with a request may be propagated to any Servlet request via use of a request parameter named +cid+ containing the unique identifier of the conversation. In this case, the application must manage this request parameter. |
| 528 |
|
| 529 |
If the current Servlet request is a JSF request, and the conversation is in _long-running_ state, it is propagated according to the following rules: |
| 530 |
|
| 531 |
* The long-running conversation context associated with a request that renders a JSF view is automatically propagated to any faces request (JSF form submission) that originates from that rendered page. |
| 532 |
* The long-running conversation context associated with a request that results in a JSF redirect (a redirect resulting from a navigation rule or JSF +NavigationHandler+) is automatically propagated to the resulting non-faces request, and to any other subsequent request to the same URL. This is accomplished via use of a request parameter named +cid+ containing the unique identifier of the conversation. |
| 533 |
|
| 534 |
|
| 535 |
When no conversation is propagated to a Servlet request, or if a request parameter named +conversationPropagation+ has the value +none+ the request is associated with a new transient conversation. |
| 536 |
|
| 537 |
All long-running conversations are scoped to a particular HTTP servlet session and may not cross session boundaries. |
| 538 |
|
| 539 |
In the following cases, a propagated long-running conversation cannot be restored and reassociated with the request: |
| 540 |
|
| 541 |
* When the HTTP servlet session is invalidated, all long-running conversation contexts created during the current session are destroyed, after the servlet +service()+ method completes. |
| 542 |
* The container is permitted to arbitrarily destroy any long-running conversation that is associated with no current Servlet request, in order to conserve resources. |
| 543 |
|
| 544 |
|
| 545 |
The _conversation timeout_, which may be specified by calling +Conversation.setTimeout()+ is a hint to the container that a conversation should not be destroyed if it has been active within the last given interval in milliseconds. |
| 546 |
|
| 547 |
If the propagated conversation cannot be restored, the container must associate the request with a new transient conversation and throw an exception of type +javax.enterprise.context.NonexistentConversationException+. |
| 548 |
|
| 549 |
The container ensures that a long-running conversation may be associated with at most one request at a time, by blocking or rejecting concurrent requests. If the container rejects a request, it must associate the request with a new transient conversation and throw an exception of type +javax.enterprise.context.BusyConversationException+. |
| 550 |
|
| 551 |
[[conversation]] |
| 552 |
|
| 553 |
==== The +Conversation+ interface |
| 554 |
|
| 555 |
The container provides a built-in bean with bean type +Conversation+, scope +@RequestScoped+, and qualifier +@Default+, named +javax.enterprise.context.conversation+. |
| 556 |
|
| 557 |
[source, java] |
| 558 |
---- |
| 559 |
public interface Conversation { |
| 560 |
public void begin(); |
| 561 |
public void begin(String id); |
| 562 |
public void end(); |
| 563 |
public String getId(); |
| 564 |
public long getTimeout(); |
| 565 |
public void setTimeout(long milliseconds); |
| 566 |
public boolean isTransient(); |
| 567 |
} |
| 568 |
---- |
| 569 |
|
| 570 |
* +begin()+ marks the current transient conversation long-running. A conversation identifier may, optionally, be specified. If no conversation identifier is specified, an identifier is generated by the container. |
| 571 |
* +end()+ marks the current long-running conversation transient. |
| 572 |
* +getId()+ returns the identifier of the current long-running conversation, or a null value if the current conversation is transient. |
| 573 |
* +getTimeout()+ returns the timeout, in milliseconds, of the current conversation. |
| 574 |
* +setTimeout()+ sets the timeout of the current conversation. |
| 575 |
* +isTransient()+ returns +true+ if the conversation is marked transient, or +false+ if it is marked long-running. |
| 576 |
|
| 577 |
|
| 578 |
If any method of +Conversation+ is called when the conversation scope is not active, a +ContextNotActiveException+ is thrown. |
| 579 |
|
| 580 |
If +end()+ is called, and the current conversation is marked transient, an +IllegalStateException+ is thrown. |
| 581 |
|
| 582 |
If +begin()+ is called, and the current conversation is already marked long-running, an +IllegalStateException+ is thrown. |
| 583 |
|
| 584 |
If +begin()+ is called with an explicit conversation identifier, and a long-running conversation with that identifier already exists, an +IllegalArgumentException+ is thrown. |
| 585 |
|