Author: gavin.king(a)jboss.com Date: 2009-10-25 19:12:33 -0400 (Sun, 25 Oct 2009) New Revision: 4314 Modified: api/trunk/cdi/src/main/java/javax/enterprise/context/ApplicationScoped.java api/trunk/cdi/src/main/java/javax/enterprise/context/BusyConversationException.java api/trunk/cdi/src/main/java/javax/enterprise/context/Conversation.java api/trunk/cdi/src/main/java/javax/enterprise/context/ConversationScoped.java api/trunk/cdi/src/main/java/javax/enterprise/context/NonexistentConversationException.java api/trunk/cdi/src/main/java/javax/enterprise/context/NormalScope.java api/trunk/cdi/src/main/java/javax/enterprise/context/RequestScoped.java api/trunk/cdi/src/main/java/javax/enterprise/context/SessionScoped.java Log: javadoc for rest of context pkg Modified: api/trunk/cdi/src/main/java/javax/enterprise/context/ApplicationScoped.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/context/ApplicationScoped.java 2009-10-25 23:07:53 UTC (rev 4313) +++ api/trunk/cdi/src/main/java/javax/enterprise/context/ApplicationScoped.java 2009-10-25 23:12:33 UTC (rev 4314) @@ -29,8 +29,38 @@ /** - * Specifies that a bean is application scoped. + * <p>Specifies that a bean is application scoped.</p> * + * <p>The application scope is active:</p> + * + * <ul> + * <li>during the <tt>service()</tt> method of any servlet in + * the web application, during the <tt>doFilter()</tt> method of + * any servlet filter and when the container calls any + * <tt>ServletContextListener</tt>, <tt>HttpSessionListener</tt>, + * <tt>AsyncListener</tt> or <tt>ServletRequestListener</tt>,</li> + * <li>during any Java EE web service invocation,</li> + * <li>during any asynchronous observer method notification,</li> + * <li>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,</li> + * <li>during any message delivery to a <tt>MessageListener</tt> + * for a JMS topic or queue obtained from the Java EE component + * environment, and</li> + * <li>when the disposer method or <tt>@PreDestroy</tt> callback of + * any bean with any normal scope other than <tt>@ApplicationScoped</tt> + * is called.</li> + * </ul> + * + * <p>The application context is shared between all servlet + * requests, asynchronous observer method notifications, web + * service invocations, 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.</p> + * * @author Gavin King * @author Pete Muir */ Modified: api/trunk/cdi/src/main/java/javax/enterprise/context/BusyConversationException.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/context/BusyConversationException.java 2009-10-25 23:07:53 UTC (rev 4313) +++ api/trunk/cdi/src/main/java/javax/enterprise/context/BusyConversationException.java 2009-10-25 23:12:33 UTC (rev 4314) @@ -18,15 +18,20 @@ package javax.enterprise.context; /** - * The container ensures that a long-running conversation may be associated with + * <p>Indicates that the container has rejected a request because a concurrent + * request is associated with the same conversation context.</p> + * + * <p>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 - * {@link BusyConversationException} from the restore view phase of the JSF - * lifecycle. + * <tt>BusyConversationException</tt> from the restore view phase of the JSF + * lifecycle.</p> * + * @see javax.enterprise.context.ConversationScoped * * @author Pete Muir + * @author Gavin King */ public class BusyConversationException extends ContextException Modified: api/trunk/cdi/src/main/java/javax/enterprise/context/Conversation.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/context/Conversation.java 2009-10-25 23:07:53 UTC (rev 4313) +++ api/trunk/cdi/src/main/java/javax/enterprise/context/Conversation.java 2009-10-25 23:12:33 UTC (rev 4314) @@ -17,70 +17,82 @@ package javax.enterprise.context; /** - * Provides conversation management operations + * <p>Allows the application to manage the conversation context + * by marking the current conversation as transient or long-running, + * specifying a conversation identifier, or setting the conversation + * timeout.</p> * + * <p>An instance may be injected:</p> + * + * <pre> + * &#064;Inject Conversation conversation; + * </pre> + * + * <p>The conversation timeout 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.</p> + * * @author Pete Muir + * @author Gavin King * */ public interface Conversation { /** - * Mark a transient conversation long running. The container will generate an - * id + * <p>Mark the current transient conversation long-running. A + * conversation identifier is generated by the container.</p> * - * @throws IllegalStateException if the current conversation is marked long - * running + * @throws IllegalStateException if the current conversation + * is already marked long-running. */ public void begin(); /** - * Mark a transient conversation long running. + * <p>Mark the current transient conversation long-running, + * with a specified identifier.</p> * - * @param id the id of the conversation - * @throws IllegalStateException if the current conversation is marked long - * running - * @throws IllegalArgumentException if a long running conversation with id - * already exists + * @throws IllegalStateException if the current conversation + * is already marked long-running. + * @throws IllegalArgumentException if a conversation with + * the specified identifier already exists. */ public void begin(String id); /** - * Mark a long running conversation transient + * <p>Marks the current long-running conversation transient.</p> * - * @throws IllegalStateException if the current conversation is marked - * transient + * @throws IllegalStateException if the current conversation + * is already marked transient. */ public void end(); /** - * Get the id associated with the current long running conversation + * <p>Get the identifier of the current long-running conversation.</p> * - * @return the id of the current long running conversation + * @return the identifier of the current long-running conversation, + * or a null value if the current conversation is transient. */ public String getId(); /** - * Get the timeout for the current long running conversation. + * <p>Get the timeout of the current conversation.</p> * - * The conversation will destroy the conversation if it has not been accessed - * within this time period. - * - * @return the current timeout in milliseconds + * @return the current timeout in milliseconds. */ public long getTimeout(); /** - * Set the timeout for the current long running conversation + * <p>Set the timeout of the current conversation.</p> * - * @param milliseconds the new timeout in milliseconds + * @param milliseconds the new timeout in milliseconds. */ public void setTimeout(long milliseconds); /** - * @return true if the conversation is marked transient, or false if it is - * marked long-running. + * @return <tt>true</tt> if the conversation is marked transient, + * or <tt>false</tt>if it is marked long-running. */ public boolean isTransient(); } \ No newline at end of file Modified: api/trunk/cdi/src/main/java/javax/enterprise/context/ConversationScoped.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/context/ConversationScoped.java 2009-10-25 23:07:53 UTC (rev 4313) +++ api/trunk/cdi/src/main/java/javax/enterprise/context/ConversationScoped.java 2009-10-25 23:12:33 UTC (rev 4314) @@ -27,8 +27,92 @@ import java.lang.annotation.Target; /** - * Specifies that a bean is conversation scoped. + * <p>Specifies that a bean is conversation scoped.</p> * + * <p>The conversation scope is active:</p> + * + * <ul> + * <li>during all standard lifecycle phases of any JSF faces or + * non-faces request.</li> + * </ul> + * + * <p>The conversation context provides access to state associated + * with a particular conversation. Every JSF request has an + * associated conversation. This association is managed + * automatically by the container according to the following + * rules:</p> + * + * <ul> + * <li>Any JSF request has exactly one associated conversation.</li> + * <li>The conversation associated with a JSF request is determined + * at the beginning of the restore view phase and does not change + * during the request.</li> + * </ul> + * + * <p>Any conversation is in one of two states: <em>transient</em> + * or <em>long-running</em>.</p> + * + * <ul> + * <li>By default, a conversation is transient</li> + * <li>A transient conversation may be marked long-running by calling + * {@link javax.enterprise.context.Conversation#begin()}</li> + * <li>A long-running conversation may be marked transient by calling + * {@link javax.enterprise.context.Conversation#end()}</li> + * </ul> + * + * <p>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.</p> + * + * <p>If the conversation associated with the current JSF request + * is in the transient state at the end of a JSF request, it is + * destroyed, and the conversation context is also destroyed.</p> + * + * <p>If the conversation associated with the current JSF request + * is in the long-running state at the end of a JSF request, it is + * not destroyed. Instead, it may be propagated to other requests + * according to the following rules:</p> + * + * <ul> + * <li>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.</li> + * <li>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 GET request parameter named <tt>cid</tt> + * containing the unique identifier of the conversation.</li> + * <li>The long-running conversation associated with a request + * may be propagated to any non-faces request via use of a GET + * request parameter named <tt>cid</tt> containing the unique identifier + * of the conversation. In this case, the application must manage + * this request parameter.</li> + * </ul> + * + * <p>When no conversation is propagated to a JSF request, 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:</p> + * + * <ul> + * <li>When the HTTP servlet session is invalidated, all + * long-running conversation contexts created during the current + * session are destroyed, after the servlet <tt>service()</tt> + * method completes.</li> + * <li>The container is permitted to arbitrarily destroy any + * long-running conversation that is associated with no current + * JSF request, in order to conserve resources.</li> + * </ul> + * + * @see javax.enterprise.context.Conversation + * @see javax.enterprise.context.NonexistentConversationException + * @see javax.enterprise.context.BusyConversationException + * * @author Gavin King * @author Pete Muir */ Modified: api/trunk/cdi/src/main/java/javax/enterprise/context/NonexistentConversationException.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/context/NonexistentConversationException.java 2009-10-25 23:07:53 UTC (rev 4313) +++ api/trunk/cdi/src/main/java/javax/enterprise/context/NonexistentConversationException.java 2009-10-25 23:12:33 UTC (rev 4314) @@ -18,15 +18,17 @@ package javax.enterprise.context; /** - * If the propagated conversation cannot be restored, the container must + * <p>Indicates that the conversation context could not be restored.</p> + * + * <p>If the propagated conversation cannot be restored, the container must * associate the request with a new transient conversation and throw an - * exception of type {@link NonexistentConversationException} from the - * restore view phase of the JSF lifecycle. The application may handle this - * exception using the JSF ExceptionHandler. + * exception of type <tt>NonexistentConversationException</tt> from the + * restore view phase of the JSF lifecycle.</p> * + * @see javax.enterprise.context.ConversationScoped * - * * @author Pete Muir + * @author Gavin King */ public class NonexistentConversationException extends ContextException Modified: api/trunk/cdi/src/main/java/javax/enterprise/context/NormalScope.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/context/NormalScope.java 2009-10-25 23:07:53 UTC (rev 4313) +++ api/trunk/cdi/src/main/java/javax/enterprise/context/NormalScope.java 2009-10-25 23:12:33 UTC (rev 4314) @@ -25,7 +25,7 @@ import java.lang.annotation.Target; /** - * Specifies that an annotation type is a scope type. + * <tt>Specifies that an annotation type is a normal scope type.</tt> * * @author Gavin King * @author Pete Muir Modified: api/trunk/cdi/src/main/java/javax/enterprise/context/RequestScoped.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/context/RequestScoped.java 2009-10-25 23:07:53 UTC (rev 4313) +++ api/trunk/cdi/src/main/java/javax/enterprise/context/RequestScoped.java 2009-10-25 23:12:33 UTC (rev 4314) @@ -28,8 +28,40 @@ import java.lang.annotation.Target; /** - * Specifies that a bean is request scoped. + * <p>Specifies that a bean is request scoped.</p> * + * <p>The request scope is active:</p> + * + * <ul> + * <li>during the <tt>service()</tt> method of any servlet in the web + * application, during the <tt>doFilter()</tt> method of any servlet + * filter and when the container calls any <tt>ServletRequestListener</tt> + * or <tt>AsyncListener</tt>,</li> + * <li>during any Java EE web service invocation,</li> + * <li>during any asynchronous observer method notification,</li> + * <li>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, and</li> + * <li>during any message delivery to a MessageListener for + * a JMS topic or queue obtained from the Java EE component + * environment.</li> + * </ul> + * + * <p>The request context is destroyed:</p> + * + * <ul> + * <li>at the end of the servlet request, after the <tt>service()</tt> + * method, all <tt>doFilter()</tt> methods, and all <tt>requestDestroyed()</tt> + * and <tt>onComplete()</tt> notifications return,</li> + * <li>after the web service invocation completes,</li> + * <li>after the asynchronous observer notification completes,</li> + * <li>after the EJB remote method invocation, asynchronous + * method invocation, timeout or message delivery completes, or</li> + * <li>after the message delivery to the <tt>MessageListener</tt> + * completes.</li> + * </ul> + * * @author Gavin King * @author Pete Muir */ Modified: api/trunk/cdi/src/main/java/javax/enterprise/context/SessionScoped.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/context/SessionScoped.java 2009-10-25 23:07:53 UTC (rev 4313) +++ api/trunk/cdi/src/main/java/javax/enterprise/context/SessionScoped.java 2009-10-25 23:12:33 UTC (rev 4314) @@ -28,8 +28,26 @@ import java.lang.annotation.Target; /** - * Specifies that a bean is session scoped. + * <p>Specifies that a bean is session scoped.</p> * + * <p>The session scope is active:</p> + * + * <ul> + * <li>during the <tt>service()</tt> method of any servlet + * in the web application, during the doFilter() method of + * any servlet filter and when the container calls any + * <tt>HttpSessionListener</tt>, <tt>AsyncListener</tt> or + * <tt>ServletRequestListener</tt>.</li> + * </ul> + * + * <p>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 <tt>HttpSessionListeners</tt> have been called, + * and at the very end of any request in which + * <tt>invalidate()</tt> was called, after all filters and + * <tt>ServletRequestListeners</tt> have been called.</p> + * * @author Gavin King * @author Pete Muir */