[weld-commits] Weld SVN: r4314 - api/trunk/cdi/src/main/java/javax/enterprise/context.
weld-commits at lists.jboss.org
weld-commits at lists.jboss.org
Sun Oct 25 19:12:33 EDT 2009
Author: gavin.king at 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>
+ * @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
*/
More information about the weld-commits
mailing list