tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From r...@apache.org
Subject svn commit: r550649 - /tomcat/sandbox/comet/java/org/apache/comet/CometEvent.java
Date Tue, 26 Jun 2007 00:57:55 GMT
Author: remm
Date: Mon Jun 25 17:57:54 2007
New Revision: 550649

URL: http://svn.apache.org/viewvc?view=rev&rev=550649
Log:
- More javadocs cleanups.

Modified:
    tomcat/sandbox/comet/java/org/apache/comet/CometEvent.java

Modified: tomcat/sandbox/comet/java/org/apache/comet/CometEvent.java
URL: http://svn.apache.org/viewvc/tomcat/sandbox/comet/java/org/apache/comet/CometEvent.java?view=diff&rev=550649&r1=550648&r2=550649
==============================================================================
--- tomcat/sandbox/comet/java/org/apache/comet/CometEvent.java (original)
+++ tomcat/sandbox/comet/java/org/apache/comet/CometEvent.java Mon Jun 25 17:57:54 2007
@@ -40,21 +40,22 @@
      *  fields using the request and response objects. Between the end of the processing

      *  of this event, and the beginning of the processing of the end or error events,
      *  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. After processing the initial event, the request 
+     *  Note that the response object and depedent OutputStream and Writer are  
+     *  not synchronized, so when they are accessed by multiple threads adequate
+     *  synchronization is needed. After processing the initial event, the request 
      *  is considered to be committed.</li>
-     * <li>READ - This indicates that input data is available, and that one read can
be made
-     *  without blocking. The available and ready methods of the InputStream or
+     * <li>READ - This indicates that input data is available, and that at least one

+     *  read can be made 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. When encountering a read error, 
+     *  must continue reading while data is reported available. When encountering a read
error, 
      *  the servlet should report it by propagating the exception properly. Throwing 
      *  an exception will cause the error event to be invoked, and the connection 
      *  will be closed. 
      *  Alternately, it is also possible to catch any exception, perform clean up
      *  on any data structure the servlet may be using, and using the close method
      *  of the event. It is not allowed to attempt reading data from the request 
-     *  object outside of the execution of this method.</li>
+     *  object outside of the processing of this event, unless the suspend() method
+     *  has been used.</li>
      * <li>END - End may be called to end the processing of the request. Fields that
have
      *  been initialized in the begin method should be reset. After this event has
      *  been processed, the request and response objects, as well as all their dependent
@@ -64,26 +65,33 @@
      *  been initialized in the begin method should be reset. After this event has
      *  been processed, the request and response objects, as well as all their dependent
      *  objects will be recycled and used to process other requests.</li>
-     * <li>EVENT - Event will be called by the container after the resume() method
is called.
-     *  This allows you get an event instantly, and you can perform IO actions
-     *  or close the Comet connection.</li>
+     * <li>EVENT - Event will be called by the container after the resume() method
is called,
+     *  during which any operations can be performed, including closing the Comet connection
+     *  using the close() method.</li>
      * <li>WRITE - Write is sent if the servlet is using the ready method. This means
that 
-     *  the connection is ready to receive data to be written out.</li>
+     *  the connection is ready to receive data to be written out. This event will never
+     *  be recieved if the Servlet is not using the ready() method, or if the ready() 
+     *  method always returns true.</li>
      * </ul>
      */
     public enum EventType {BEGIN, READ, END, ERROR, WRITE, EVENT}
     
     
     /**
-     * Event details:
+     * Enumeration containing event sub categories.
+     * <br>
+     * END events sub types:
      * <ul>
-     * <li>TIMEOUT - the connection timed out (sub type of ERROR); note that this ERROR
type is not fatal, and
+     * <li>WEBAPP_RELOAD - the webapplication is being reloaded</li>
+     * <li>SERVER_SHUTDOWN - the server is shutting down</li>
+     * <li>SESSION_END - the servlet ended the session</li>
+     * </ul>
+     * ERROR events sub types:
+     * <ul>
+     * <li>TIMEOUT - the connection timed out; note that this ERROR type is not fatal,
and
      *   the connection will not be closed unless the servlet uses the close method of the
event</li>
-     * <li>CLIENT_DISCONNECT - the client connection was closed (sub type of ERROR)</li>
-     * <li>IOEXCEPTION - an IO exception occurred, such as invalid content, for example,
an invalid chunk block (sub type of ERROR)</li>
-     * <li>WEBAPP_RELOAD - the webapplication is being reloaded (sub type of END)</li>
-     * <li>SERVER_SHUTDOWN - the server is shutting down (sub type of END)</li>
-     * <li>SESSION_END - the servlet ended the session (sub type of END)</li>
+     * <li>CLIENT_DISCONNECT - the client connection was closed</li>
+     * <li>IOEXCEPTION - an IO exception occurred, such as invalid content, for example,
an invalid chunk block</li>
      * </ul>
      */
     public enum EventSubType { TIMEOUT, CLIENT_DISCONNECT, IOEXCEPTION, WEBAPP_RELOAD, SERVER_SHUTDOWN,
SESSION_END }
@@ -120,11 +128,13 @@
     public EventSubType getEventSubType();
 
     /**
-     * Ends the Comet session. This signals to the container that 
-     * the container wants to end the comet session. This will send back to the
-     * client a notice that the server has no more data to send as part of this
-     * request. The servlet should perform any needed cleanup as if it had recieved
-     * an END or ERROR event. 
+     * Ends the request, which marks the end of the comet session. This will send 
+     * back to the client a notice that the server has no more data to send 
+     * as part of this request. If this method is called from a Tomcat provided thread
+     * (during the processing of an event), the container will not call an END event.
+     * If this method is called asynchronously, an END event will be sent to the 
+     * servlet (note that this event will be sent whenever another event would have
+     * been sent, such as a READ or ERROR/TIMEOUT event).
      * 
      * @throws IOException if an IO exception occurs
      */
@@ -148,28 +158,31 @@
      * to the client and data still cannot be written immediately, an IOException will be

      * thrown. If calling this method returns false, it will also 
      * request notification when the connection becomes available for writing again, and
the  
-     * servlet will recieve a write event.<br/>
-     * 
+     * servlet will recieve a write event.
+     * <br>
      * Note: If the servlet is not using ready, and is writing its output inside the
      * container threads, using this method is not mandatory, but any incomplete writes will
be
      * performed again in blocking mode.
      * 
-     * @return boolean true if you can write to the response 
+     * @return boolean true if data can be written 
      */
     public boolean ready();
 
     /**
-     * Suspend processing of the connection until the configured timeout occurs, or resume()
is called. In
-     * parctice, this means the servlet will no longer recieve read events. Reading should
always be
-     * performed synchronously in the Tomcat threads unless the connection has been suspended.
+     * Suspend processing of the connection until the configured timeout occurs, 
+     * or resume() is called. In parctice, this means the servlet will no longer 
+     * recieve read events. Reading should always be performed synchronously in 
+     * the Tomcat threads unless the connection has been suspended.
      */
     public void suspend();
 
     /**
-     * Will ask the servlet container to send a generic event to the servlet, where the request
can be processed
-     * synchronously (for example, it is possible to use this to complete the request after
some asynchronous
-     * processing is done). This also resumes read events if they had been disabled using
suspend (it is possible
-     * to call suspend again). It is possible to call resume without calling suspend before.
+     * Resume will cause the servlet container to send a generic event 
+     * to the servlet, where the request can be processed synchronously 
+     * (for example, it is possible to use this to complete the request after 
+     * some asynchronous processing is done). This also resumes read events 
+     * if they have been disabled using suspend. It is then possible to call suspend 
+     * again later. It is also possible to call resume without calling suspend before.
      */
     public void resume();
 



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


Mime
View raw message