From: fhanik Date: Mon, 11 Jun 2007 11:53:47 +0000 (+0000) Subject: Added some doco X-Git-Url: https://git.internetallee.de/?a=commitdiff_plain;h=87faffb5e626e5622dec16bf140aa4f84d5be0d1;p=tomcat7.0 Added some doco git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@546108 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/java/org/apache/catalina/CometEvent.java b/java/org/apache/catalina/CometEvent.java index e296be7a8..25c64682b 100644 --- a/java/org/apache/catalina/CometEvent.java +++ b/java/org/apache/catalina/CometEvent.java @@ -26,7 +26,8 @@ import javax.servlet.http.HttpServletResponse; /** * The CometEvent interface. - * A comet event is the contract between the servlet container and the servlet implementation(CometProcessor) for handling comet connections. + * A comet event is the contract between the servlet container and the servlet + * implementation(CometProcessor) for handling comet connections. * * @see CometProcessor * @author Filip Hanik @@ -68,6 +69,7 @@ public interface CometEvent { * 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. + * When an error event is invoked, the close() method on the CometEvent object. * CALLBACK - Callback will be called by the container after the comet processor * has registered for the OP_CALLBACK operation. * This allows you get an event instantly, and you can perform IO actions @@ -128,10 +130,18 @@ public interface CometEvent { * 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. + * Invoking this method during a event, will cause the session to close + * immediately after the event method has finished. + * Invoking this method asynchrously will not cause the session to close + * until another event occurred, most likely a timeout. + * If you wish to signal to the container + * that the session should end sooner rather than later when this method is invoked + * asycnhronously, then issue a + * register(OP_CALLBACK) immediately after this method has been invoked. * - * @throws IOException if an IO exception occurs + * @see #register(CometOperation) */ - public void close() throws IOException; + public void close(); /** * Sets the timeout for this Comet connection. Please NOTE, that the implementation @@ -145,19 +155,19 @@ public interface CometEvent { * This method should not be called asynchronously, as that will have no effect. * * @param timeout The timeout in milliseconds for this connection, must be a positive value, larger than 0 - * @throws IOException An IOException may be thrown to indicate an IO error, - * or that the EOF has been reached on the connection * @throws ServletException An exception has occurred, as specified by the root * cause * @throws UnsupportedOperationException if per connection timeout is not supported, either at all or at this phase * of the invocation. */ public void setTimeout(int timeout) - throws IOException, ServletException, UnsupportedOperationException; + throws ServletException, UnsupportedOperationException; /** + * Enumeration for a comet connection state. + * A comet session can be blocking or non blocking. * COMET_NON_BLOCKING
* Option bit set for allowing non blocking IO * when reading from the request or writing to the response
@@ -201,11 +211,13 @@ public interface CometEvent { public enum CometOperation {OP_CALLBACK, OP_READ, OP_WRITE}; /** - * Registers the Comet connection with the container for IO notifications. - * These could be notifications + * Registers the Comet connection with the container for IO and event notifications. + * The different notifications are defined by the * @param operations * @throws IllegalStateException - if you are trying to register with a socket that already is registered * or if the operation you are trying to register is invalid. + * @see #EventType + * @see #CometOperation */ public void register(CometOperation... operations) throws IllegalStateException; @@ -226,13 +238,23 @@ public interface CometEvent { /** * Returns true if the Comet connection is blocking or non blocking and you can write - * without blocking data to the response + * without blocking data to the response. The amount of data you can write is often related to + * the size of the sockets network buffer. + * This method returns true if the last write attempted was able to write the entire data set. + * This method is not useful when using blocking writes, as it will always return true * @return boolean - true if you can write to the response */ public boolean isWriteable(); /** * Returns true if the Comet connection is blocking or non blocking and data is available to be read + * The logic for isReadable is as follows: + * First we check the inputstream/reader and see if there is data available to the comet processor. + * If that returns false, we check to see if the underlying tomcat buffer is holding any data, and + * if that returns false, we issue a quick non blocking read on the socket, to see if + * there is data in the network buffer. + * The operation can be summarized as: + * available()>0 || tomcat-buffer.size>0 || socket.read>0 * @see javax.servlet.ServletRequest#getInputStream()#available()>0 * @return boolean */ diff --git a/java/org/apache/catalina/CometProcessor.java b/java/org/apache/catalina/CometProcessor.java index 9a3498d6e..57c972890 100644 --- a/java/org/apache/catalina/CometProcessor.java +++ b/java/org/apache/catalina/CometProcessor.java @@ -49,6 +49,8 @@ public interface CometProcessor extends Servlet * @param event The Comet event that will be processed * @throws IOException * @throws ServletException + * @see CometEvent + * @see CometEvent#EventType */ public void event(CometEvent event) throws IOException, ServletException;