javadoc

git-svn-id: svn+ssh://dev.eclipse.org/svnroot/rt/org.eclipse.jetty/jetty/trunk@337 7e9141cc-0065-0410-87d8-b60c137991c4

jetty-continuation/src/main/java/org/eclipse/jetty/continuation/ContinuationListener.java

@@ -3,9 +3,37 @@ package org.eclipse.jetty.continuation;
 
 import java.util.EventListener;
 
+import javax.servlet.ServletRequest;
+import javax.servlet.ServletRequestListener;
 
+
+
+/* ------------------------------------------------------------ */
+/** A Continuation Listener
+ * <p>
+ * A ContinuationListener may be registered with a call to
+ * {@link Continuation#addContinuationListener(ContinuationListener)}.
+ * 
+ */
 public interface ContinuationListener extends EventListener 
 {    
+    /* ------------------------------------------------------------ */
+    /**
+     * Called when a continuation life cycle is complete and prior
+     * to any calls to {@link ServletRequestListener#requestDestroyed(javax.servlet.ServletRequestEvent)}
+     * The response may still be written to during the call.
+     * 
+     * @param continuation
+     */
     public void onComplete(Continuation continuation);
+    
+    /* ------------------------------------------------------------ */
+    /**
+     * Called when a suspended continuation has timed out.
+     * The response may be written to and the methods 
+     * {@link Continuation#resume()} or {@link Continuation#complete()} 
+     * may be called by a onTimeout implementation,
+     * @param continuation
+     */
     public void onTimeout(Continuation continuation);
 }

jetty-continuation/src/main/java/org/eclipse/jetty/continuation/ContinuationSupport.java

@@ -79,7 +79,13 @@ public class ContinuationSupport
 
     /* ------------------------------------------------------------ */
     /**
-     * @param request
+     * Get a Continuation.  The type of the Continuation returned may
+     * vary depending on the container in which the application is 
+     * deployed. It may be an implementation native to the container (eg
+     * org.eclipse.jetty.server.AsyncContinuation) or one of the utility
+     * implementations provided such as {@link FauxContinuation} or 
+     * {@link Servlet3Continuation}.
+     * @param request The request 
      * @return a Continuation instance
      */
     public static Continuation getContinuation(ServletRequest request)

jetty-continuation/src/main/java/org/eclipse/jetty/continuation/FauxContinuation.java

@@ -20,6 +20,13 @@ import javax.servlet.ServletRequest;
 import javax.servlet.ServletResponse;
 import javax.servlet.ServletResponseWrapper;
 
+
+/* ------------------------------------------------------------ */
+/**
+ * A blocking implementation of Continuation.
+ * This implementation of Continuation is used by the {@link ContinuationFilter}
+ * when there are is no native or asynchronous continuation type available. 
+ */
 class FauxContinuation implements Continuation
 {
     private final static ContinuationThrowable __exception = new ContinuationThrowable();

jetty-continuation/src/main/java/org/eclipse/jetty/continuation/Jetty6Continuation.java

@@ -7,6 +7,13 @@ import javax.servlet.ServletResponse;
 import javax.servlet.ServletResponseWrapper;
 
 
+
+/* ------------------------------------------------------------ */
+/**
+ * This implementation of Continuation is used by {@link ContinuationSupport}
+ * when it detects that the application is deployed in a jetty-6 server.
+ * This continuation requires the {@link ContinuationFilter} to be deployed.
+ */
 public class Jetty6Continuation implements ContinuationFilter.PartialContinuation
 {
     private final ServletRequest _request;

jetty-continuation/src/main/java/org/eclipse/jetty/continuation/Servlet3Continuation.java

@@ -11,6 +11,13 @@ import javax.servlet.ServletResponse;
 import javax.servlet.ServletResponseWrapper;
 
 
+
+/* ------------------------------------------------------------ */
+/**
+ * This implementation of Continuation is used by {@link ContinuationSupport}
+ * when it detects that the application has been deployed in a non-jetty Servlet 3 
+ * server.
+ */
 public class Servlet3Continuation implements Continuation
 {
     private final static ContinuationThrowable __exception = new ContinuationThrowable();