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

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.