-
@Target({TYPE,METHOD,FIELD}) @Retention(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 anyweb.xml
in the application, the conversation associated with a Servlet request is determined at the beginning of the request before calling anyservice()
method of any servlet in the web application, calling thedoFilter()
method of any servlet filter in the web application and before the container calls anyServletRequestListener
orAsyncListener
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 namedcid
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 valuenone
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.
CDI Lite implementations are not required to provide support for conversations.
- Author:
- Gavin King, Pete Muir, Antoine Sabot-Durand
- See Also:
Conversation
,NonexistentConversationException
,BusyConversationException