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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
