- Some javadoc.

git-svn-id: https://svn.apache.org/repos/asf/tomcat/tc6.0.x/trunk@407932 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/java/org/apache/catalina/CometProcessor.java b/java/org/apache/catalina/CometProcessor.java
index bb9d7cf..743889d 100644 (file)
--- a/java/org/apache/catalina/CometProcessor.java
+++ b/java/org/apache/catalina/CometProcessor.java
@@ -23,19 +23,30 @@ import javax.servlet.ServletException;
 import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
 
+/**
+ * This interface should be implemented by servlets which would like to handle
+ * asynchronous IO, recieving events when data is available for reading, and
+ * being able to output data without the need for being invoked by the container.
+ */
 public interface CometProcessor {
 
     /**
      * Begin will be called by the main service method of the servlet at the beginning 
      * of the processing of the connection. It can be used to initialize any relevant 
-     * fields using the request and response objects.
+     * fields using the request and response objects. Between the end of the execution 
+     * of this method, and the beginning of the execution of the end or error methods,
+     * it is possible to use the response object to write data on the open connection.
+     * Note that the response object and depedent OutputStream and Writer are still 
+     * not synchronized, so when they are accessed by multiple threads, 
+     * synchronization is mandatory.
      * 
      * @param request The HTTP servlet request instance, which can be accessed
      *        asynchronously at any time until the end or error methods are called
      * @param response The HTTP servlet response instance, which can be accessed
      *        asynchronously at any time until the end or error methods are called
-     * @throws IOException
-     * @throws ServletException
+     * @throws IOException An IOException may be thrown to indicate an IO error
+     * @throws ServletException An exception has occurred, as specified by the root
+     *         cause
      */
     public void begin(HttpServletRequest request, HttpServletResponse response)
         throws IOException, ServletException;
@@ -46,10 +57,11 @@ public interface CometProcessor {
      * been called, the request and response objects, as well as all their dependent
      * objects will be recycled and used to process other requests.
      * 
-     * @param request
-     * @param response
-     * @throws IOException
-     * @throws ServletException
+     * @param request The HTTP servlet request instance
+     * @param response The HTTP servlet response instance
+     * @throws IOException An IOException may be thrown to indicate an IO error
+     * @throws ServletException An exception has occurred, as specified by the root
+     *         cause
      */
     public void end(HttpServletRequest request, HttpServletResponse response)
         throws IOException, ServletException;
@@ -61,10 +73,11 @@ public interface CometProcessor {
      * been called, the request and response objects, as well as all their dependent
      * objects will be recycled and used to process other requests.
      * 
-     * @param request
-     * @param response
-     * @throws IOException
-     * @throws ServletException
+     * @param request The HTTP servlet request instance
+     * @param response The HTTP servlet response instance
+     * @throws IOException An IOException may be thrown to indicate an IO error
+     * @throws ServletException An exception has occurred, as specified by the root
+     *         cause
      */
     public void error(HttpServletRequest request, HttpServletResponse response)
         throws IOException, ServletException;
@@ -76,13 +89,16 @@ public interface CometProcessor {
      * should read while data is reported available, and can make one additional read
      * without blocking. When encountering a read error or an EOF, the servlet MUST
      * report it by either returning null or throwing an exception such as an 
-     * IOException. 
+     * IOException. This will cause the error method to be invoked, and the connection
+     * will be closed. It is not allowed to attempt reading data from the request object
+     * outside of the execution of this method.
      * 
-     * @param request
-     * @param response
+     * @param request The HTTP servlet request instance
+     * @param response The HTTP servlet response instance
      * @throws IOException An IOException may be thrown to indicate an IO error, 
      *         or that the EOF has been reached on the connection
-     * @throws ServletException
+     * @throws ServletException An exception has occurred, as specified by the root
+     *         cause
      * @return false if the read attempt returned an EOF; alternately, it is also
      *         valid to throw an IOException
      */