[[contexts_ee]]

== Scopes and contexts in Jakarta EE

[[dependent_context_ee]]

=== Dependent pseudo-scope in Jakarta EE

When running in Jakarta EE, the container must extend the rules defined in <<dependent_context>> and must also ensure that if a bean is declared to have `@Dependent` scope:

* 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.

[[dependent_objects_ee]]

==== Dependent objects in Jakarta EE

When running in Jakarta EE, the container must extend the rules defined for bean in <<dependent_objects>> to Jakarta EE component class instance.

[[dependent_destruction_ee]]

==== Destruction of objects with scope `@Dependent` in Jakarta EE

When running in Jakarta EE, the container must extend the rules defined for bean in <<dependent_destruction>> to Jakarta EE component class instance, and must also ensure that :

* 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.

[[dependent_scope_el]]

==== Dependent pseudo-scope and Unified EL

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:

* the bean is instantiated at most once, and
* the resulting instance is reused for every appearance of the bean name, and
* the resulting instance is destroyed when the evaluation completes.


Portable extensions that integrate with the container via Unified EL should also ensure that these rules are enforced.


[[passivating_scope_ee]]

=== Passivation and passivating scopes in Jakarta EE

[[passivation_capable_ee]]

==== Passivation capable beans in Jakarta EE

* As defined by the EJB specification, an EJB stateful session beans is passivation capable if:
** interceptors and decorators of the bean are passivation capable, and,
** the EJB stateful session bean does not have the `passivationCapable` flag set to `false`.
* As defined by the EJB specification, an EJB stateless session bean or an EJB singleton session bean is not passivation capable.

[[passivation_capable_dependency_ee]]

==== Passivation capable dependencies in Jakarta EE

When running in Jakarta EE, the container must extend the rules defined in <<passivation_capable_dependency>>, and must also guarantee that:

* all EJB stateless session beans are passivation capable dependencies,
* all EJB singleton session beans are passivation capable dependencies,
* all passivation capable EJB stateful session beans are passivation capable dependencies, and
* all Jakarta EE resources are passivation capable dependencies.

[[passivation_validation_ee]]

==== Validation of passivation capable beans and dependencies in Jakarta EE

When running in Jakarta EE, the container must extend the rules defined for managed beans in <<passivation_validation>> to EJB session beans.

[[builtin_contexts_ee]]

=== Context management for built-in scopes in Jakarta EE

When running in Jakarta EE, the container must extend the rules defined in <<builtin_contexts>> and is also required to ensure the following rules for built-in context implementation.

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.

[[request_context_ee]]

==== Request context lifecycle in Jakarta EE

When running in Jakarta EE the container must extend the rules defined in <<request_context>> and is also required to implement request context with the following rules.

The request context is active:

* 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`,
* during any Jakarta EE web service invocation,
* 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.


The request context is destroyed:

* at the end of the servlet request, after the `service()` method, all `doFilter()` methods, and all `requestDestroyed()` and `onComplete()` notifications return,
* after the web service invocation completes,
* after the EJB remote method invocation, asynchronous method invocation, timeout or message delivery completes if it did not already exist when the invocation occurred.

The payload of the event fired when the request context is initialized or destroyed is:

* the `ServletRequest` if the context is initialized or destroyed due to a servlet request, or
* the `ServletRequest` if the context is initialized or destroyed due to a web service invocation, or
* any `java.lang.Object` for other types of request.

[[session_context_ee]]

==== Session context lifecycle in Jakarta EE

When running in Jakarta EE the container is required to implement session context with the following rules.

The session scope is active:

* 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`.

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.

An event with qualifier `@Initialized(SessionScoped.class)` is synchronously fired when the session context is initialized.
An event with qualifier `@BeforeDestroyed(SessionScoped.class)` is synchronously fired when the session context is about to be destroyed, i.e. before the actual destruction.
An event with qualifier `@Destroyed(SessionScoped.class)` is synchronously fired when the session context is destroyed, i.e. after the actual destruction.
The event payload is `jakarta.servlet.http.HttpSession`.

[[application_context_ee]]

==== Application context lifecycle in Jakarta EE

When running in Jakarta EE the container must extend the rules defined in <<application_context>> and is also required to implement application context with the following rules.

The application scope is active:

* 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`,
* during any Jakarta EE web service invocation,
* during any asynchronous invocation of an event observer,
* 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,
* when the disposer method or `@PreDestroy` callback of any bean with any normal scope other than `@ApplicationScoped` is called, and
* during `@PostConstruct` callback of any bean.


The application context is shared between all servlet requests, web service invocations, asynchronous invocation of an event observer, 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.

The payload of the event fired when the application context is initialized or destroyed is:

* the `ServletContext` if the application is a web application deployed to a Servlet container, or
* any `java.lang.Object` for other types of application.


[[conversation_context_ee]]

==== Conversation context lifecycle in Jakarta EE

When running in Jakarta EE the container is required to implement conversation context with the following rules.

The conversation scope is active during all Servlet requests.

An event with qualifier `@Initialized(ConversationScoped.class)` is synchronously fired when the conversation context is initialized.
An event with qualifier `@BeforeDestroyed(ConversationScoped.class)` is synchronously fired when the conversation is about to be destroyed, i.e. before the actual destruction.
An event with qualifier `@Destroyed(ConversationScoped.class)` is synchronously fired when the conversation is destroyed, i.e. after the actual destruction.
The event payload is:

* the conversation id if the conversation context is destroyed and is not associated with a current Servlet request, or
* the `ServletRequest` if the application is a web application deployed to a Servlet container, or
* any `java.lang.Object` for other types of application.


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:

* Any Servlet request has exactly one associated conversation.
* 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.
* 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.

Any conversation is in one of two states: _transient_ or _long-running_.

* By default, a conversation is transient
* A transient conversation may be marked long-running by calling `Conversation.begin()`
* A long-running conversation may be marked transient by calling `Conversation.end()`


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.

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.

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.

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:

* 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.
* 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.


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.

All long-running conversations are scoped to a particular HTTP servlet session and may not cross session boundaries.

In the following cases, a propagated long-running conversation cannot be restored and reassociated with the request:

* 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.
* The container is permitted to arbitrarily destroy any long-running conversation that is associated with no current Servlet request, in order to conserve resources.


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.

If the propagated conversation cannot be restored, the container must associate the request with a new transient conversation and throw an exception of type `jakarta.enterprise.context.NonexistentConversationException`.

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 `jakarta.enterprise.context.BusyConversationException`.
