Debian Codegraph @

spec/src/main/doc/scopescontexts.asciidoc

raw
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