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