scopescontext_ee.asciidoc

Scopes and contexts in Jakarta 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 Jakarta Server Faces 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 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.

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 Jakarta Server Faces page are destroyed when the evaluation completes.

Dependent pseudo-scope and Unified EL

Suppose a Unified EL expression in a Jakarta Server Faces 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.

Passivation and passivating scopes in Jakarta EE

Passivation capable beans in Jakarta EE

• As defined by the Jakarta Eneterprise Bean specification, an Jakarta Eneterprise Bean stateful session beans is passivation capable if:

  • interceptors and decorators of the bean are passivation capable, and,

  • the Jakarta Eneterprise Bean stateful session bean does not have the passivationCapable flag set to false.

• As defined by the Jakarta Eneterprise Bean specification, an Jakarta Eneterprise Bean stateless session bean or an Jakarta Eneterprise Bean singleton session bean is not passivation capable.

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 Jakarta Eneterprise Bean stateless session beans are passivation capable dependencies,

• all Jakarta Eneterprise Bean singleton session beans are passivation capable dependencies,

• all passivation capable Jakarta Eneterprise Bean stateful session beans are passivation capable dependencies, and

• all Jakarta EE resources are passivation capable dependencies.

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 Jakarta Eneterprise Bean session beans.

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 Jakarta Eneterprise Bean invocations, and the built in session and request context objects are active during servlet and web service invocations.

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 Jakarta Eneterprise Bean, during any asynchronous method invocation of any Jakarta Eneterprise Bean, during any call to an Jakarta Eneterprise Bean timeout method and during message delivery to any Jakarta Eneterprise Bean 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 Jakarta Eneterprise Bean 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 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 javax.servlet.http.HttpSession.

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 Jakarta Eneterprise Bean, during any asynchronous method invocation of any Jakarta Eneterprise Bean, during any call to an Jakarta Eneterprise Bean timeout method and during message delivery to any Jakarta Eneterprise Bean 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, Jakarta Eneterprise Bean remote method invocations, Jakarta Eneterprise Bean asynchronous method invocations, Jakarta Eneterprise Bean 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 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 Jakarta Server Faces 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 Jakarta Server Faces view is automatically propagated to any faces request (Jakarta Server Faces form submission) that originates from that rendered page.

• The long-running conversation context associated with a request that results in a Jakarta Server Faces redirect (a redirect resulting from a navigation rule or Jakarta Server Faces 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 javax.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 javax.enterprise.context.BusyConversationException.