Author: fhanik
Date: Mon Jun 11 04:53:47 2007
New Revision: 546108
URL: http://svn.apache.org/viewvc?view=rev&rev=546108
Log:
Added some doco
Modified:
tomcat/trunk/java/org/apache/catalina/CometEvent.java
tomcat/trunk/java/org/apache/catalina/CometProcessor.java
Modified: tomcat/trunk/java/org/apache/catalina/CometEvent.java
URL:
http://svn.apache.org/viewvc/tomcat/trunk/java/org/apache/catalina/CometEvent.java?view=diff&rev=546108&r1=546107&r2=546108
==============================================================================
--- tomcat/trunk/java/org/apache/catalina/CometEvent.java (original)
+++ tomcat/trunk/java/org/apache/catalina/CometEvent.java Mon Jun 11 04:53:47
2007
@@ -26,7 +26,8 @@
/**
* 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 @@
* 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 @@
* 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 @@
* 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<br/>
* Option bit set for allowing non blocking IO
* when reading from the request or writing to the response<br/>
@@ -201,11 +211,13 @@
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 @@
/**
* 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
*/
Modified: tomcat/trunk/java/org/apache/catalina/CometProcessor.java
URL:
http://svn.apache.org/viewvc/tomcat/trunk/java/org/apache/catalina/CometProcessor.java?view=diff&rev=546108&r1=546107&r2=546108
==============================================================================
--- tomcat/trunk/java/org/apache/catalina/CometProcessor.java (original)
+++ tomcat/trunk/java/org/apache/catalina/CometProcessor.java Mon Jun 11
04:53:47 2007
@@ -49,6 +49,8 @@
* @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;
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
