svn commit: r407932 - /tomcat/tc6.0.x/trunk/java/org/apache/catalina/CometProcessor.java

[re...@apache.org]

Author: remm
Date: Fri May 19 17:04:08 2006
New Revision: 407932

URL: http://svn.apache.org/viewvc?rev=407932&view=rev
Log:
- Some javadoc.

Modified:
    tomcat/tc6.0.x/trunk/java/org/apache/catalina/CometProcessor.java

Modified: tomcat/tc6.0.x/trunk/java/org/apache/catalina/CometProcessor.java
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/java/org/apache/catalina/CometProcessor.java?rev=407932&r1=407931&r2=407932&view=diff
==============================================================================
--- tomcat/tc6.0.x/trunk/java/org/apache/catalina/CometProcessor.java (original)
+++ tomcat/tc6.0.x/trunk/java/org/apache/catalina/CometProcessor.java Fri May 19 17:04:08 2006
@@ -23,19 +23,30 @@
 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 @@
      * 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 @@
      * 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 @@
      * 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
      */



---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org