jakarta.enterprise.context

Annotation Type ConversationScoped

@Target(value={TYPE,METHOD,FIELD})
 @Retention(value=RUNTIME)
 @Documented
 @NormalScope(passivating=true)
 @Inherited
public @interface ConversationScoped

Specifies that a bean is conversation scoped.

While ConversationScoped must be associated with the built-in conversation context required by the specification, third-party extensions are allowed to also associate it with their own context. Behavior described below is only related to the built-in conversation context.

The conversation scope is active:

• during all Servlet requests.

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:

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

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 re-associated 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.

Author:

Gavin King, Pete Muir, Antoine Sabot-Durand

See Also:

Conversation, NonexistentConversationException, BusyConversationException