/**
* 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
* 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
* 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
* 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/>
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;
/**
* 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
*/
projects / tomcat7.0 / commitdiff