- Add example read method.

- Return value for read errors (as an option compared with throwing an exception).
- Add some javadocs.

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

diff --git a/java/org/apache/catalina/CometProcessor.java b/java/org/apache/catalina/CometProcessor.java
index ded67f9..bb9d7cf 100644 (file)
--- a/java/org/apache/catalina/CometProcessor.java
+++ b/java/org/apache/catalina/CometProcessor.java
@@ -30,8 +30,10 @@ public interface CometProcessor {
      * of the processing of the connection. It can be used to initialize any relevant 
      * fields using the request and response objects.
      * 
-     * @param request
-     * @param response
+     * @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
      */
@@ -40,7 +42,9 @@ public interface CometProcessor {
 
     /**
      * End may be called to end the processing of the request. Fields that have
-     * been initialized in the begin method should be reset.
+     * been initialized in the begin method should be reset. After this method has
+     * 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
@@ -53,7 +57,9 @@ public interface CometProcessor {
     /**
      * Error will be called by the container in the case where an IO exception
      * or a similar unrecoverable error occurs on the connection. Fields that have
-     * been initialized in the begin method should be reset.
+     * been initialized in the begin method should be reset. After this method has
+     * 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
@@ -68,14 +74,19 @@ public interface CometProcessor {
      * without blocking. The available and ready methods of the InputStream or
      * Reader may be used to determine if there is a risk of blocking: the servlet
      * should read while data is reported available, and can make one additional read
-     * without blocking.
+     * 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. 
      * 
      * @param request
      * @param response
-     * @throws IOException
+     * @throws IOException An IOException may be thrown to indicate an IO error, 
+     *         or that the EOF has been reached on the connection
      * @throws ServletException
+     * @return false if the read attempt returned an EOF; alternately, it is also
+     *         valid to throw an IOException
      */
-    public void read(HttpServletRequest request, HttpServletResponse response)
+    public boolean read(HttpServletRequest request, HttpServletResponse response)
         throws IOException, ServletException;
 
 }

diff --git a/java/org/apache/catalina/connector/CoyoteAdapter.java b/java/org/apache/catalina/connector/CoyoteAdapter.java
index 85779f7..7faa471 100644 (file)
--- a/java/org/apache/catalina/connector/CoyoteAdapter.java
+++ b/java/org/apache/catalina/connector/CoyoteAdapter.java
@@ -128,7 +128,15 @@ public class CoyoteAdapter
                 if (error) {\r
                     servlet.error(request.getRequest(), response.getResponse());\r
                 } else {\r
-                    servlet.read(request.getRequest(), response.getResponse());\r
+                    if (!servlet.read(request.getRequest(), response.getResponse())) {\r
+                        error = true;\r
+                        request.removeAttribute("org.apache.tomcat.comet");\r
+                        try {\r
+                            servlet.error(request.getRequest(), response.getResponse());\r
+                        } catch (Throwable th) {\r
+                            log.error(sm.getString("coyoteAdapter.service"), th);\r
+                        }\r
+                    }\r
                 }\r
                 return (!error);\r
             } catch (Throwable t) {\r

diff --git a/java/org/apache/catalina/servlets/CometServlet.java b/java/org/apache/catalina/servlets/CometServlet.java
index 7536977..623c85f 100644 (file)
--- a/java/org/apache/catalina/servlets/CometServlet.java
+++ b/java/org/apache/catalina/servlets/CometServlet.java
@@ -19,6 +19,7 @@ package org.apache.catalina.servlets;
 
 
 import java.io.IOException;
+import java.io.InputStream;
 
 import javax.servlet.ServletException;
 import javax.servlet.http.HttpServlet;
@@ -49,8 +50,20 @@ public abstract class CometServlet
         end(request, response);
     }
     
-    public abstract void read(HttpServletRequest request, HttpServletResponse response)
-        throws IOException, ServletException;
+    public boolean read(HttpServletRequest request, HttpServletResponse response)
+        throws IOException, ServletException {
+        InputStream is = request.getInputStream();
+        byte[] buf = new byte[512];
+        do {
+            int n = is.read(buf);
+            if (n > 0) {
+                // Do something with the data
+            } else if (n < 0) {
+                return false;
+            }
+        } while (is.available() > 0);
+        return true;
+    }
 
     protected void service(HttpServletRequest request, HttpServletResponse response)
         throws IOException, ServletException {