Author: remy.maucherat(a)jboss.com Date: 2012-03-16 12:54:57 -0400 (Fri, 16 Mar 2012) New Revision: 2003 Modified: trunk/java/org/jboss/web/upgrade/ProtocolHandler.java trunk/java/org/jboss/web/upgrade/WebConnection.java trunk/webapps/docs/changelog.xml Log: Fix glitches and add javadoc. Modified: trunk/java/org/jboss/web/upgrade/ProtocolHandler.java =================================================================== --- trunk/java/org/jboss/web/upgrade/ProtocolHandler.java 2012-03-14 17:31:01 UTC (rev 2002) +++ trunk/java/org/jboss/web/upgrade/ProtocolHandler.java 2012-03-16 16:54:57 UTC (rev 2003) @@ -22,13 +22,105 @@ package org.jboss.web.upgrade; +/** + * Application can provide implementation of the ProtocolHandler interface to support + * protocol upgrades from HTTP/1.1. This allow access to the raw streams of the underlying + * connection, and full asynchronous IO for maximized scalability. + * + * @author remm + */ public interface ProtocolHandler { + + /** + * Init will be called at the beginning of the processing of the upgraded connection. + * It can be used to initialize any relevant components that will be used for processing. + * 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 WebConnection object instance + * to write data on the open connection. Note that the WebConnection object instance + * methods are not synchronized, so when they are accessed by multiple threads adequate + * synchronization is needed. The WebConnection object will remain associated to the + * same connection for its entire lifecycle until it is destroyed. + * + * @param wc The WebConnection object that will be associated with this connection + */ public void init(WebConnection wc); + + /** + * Destroy may be called to end the processing of the request. Components that have + * been initialized in the init method should be reset. After this event has + * been processed, the WebConnection object will be recycled and used to process + * other connections. In particular, this method will be called when the connection + * is closed asynchronously. + * + * @param wc The WebConnection object that is associated with this connection + */ public void destroy(WebConnection wc); + + /** + * This indicates that input data is available, and that at least one + * read can be made without blocking using the given WebConnection object. + * The isReadReady method of the WebConnection may be used to determine + * if there is a risk of blocking: the Servlet 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 method 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. + * It is not allowed to attempt reading data from the request + * object outside of the processing of this event, unless the suspend() method + * has been used. + * + * @param wc The WebConnection object that is associated with this connection + */ public void inputAvailable(WebConnection wc); + + /** + * Write is called if the Servlet is using the isWriteReady method of the WebConnection. + * This means that the connection is ready to receive data to be written out. This method + * will never be called if the Servlet is not using the isWriteReady() method, or if the + * isWriteReady() method always returns true. + * + * @param wc The WebConnection object that is associated with this connection + */ public void outputReady(WebConnection wc); + + /** + * Resume will be called by the container after the resume() method of the WebConnection + * is called, during which any operations can be performed, including closing the connection + * using the close() method. + * + * @param wc The WebConnection object that is associated with this connection + */ public void resume(WebConnection wc); + + /** + * The connection timed out, but the connection will not be closed unless + * the Servlet uses the close method of the WebConnection. + * + * @param wc The WebConnection object that is associated with this connection + */ public void timeout(WebConnection wc); + + /** + * Error will be called by the container in the case where an IO exception + * or a similar unrecoverable error occurs on the connection. Components that have + * been initialized in the init method should be reset. After this method has + * been called, the WebConnection object will be recycled and used to process + * other requests. + * + * @param wc The WebConnection object that is associated with this connection + */ public void error(WebConnection wc); + + /** + * The end of file of the input has been reached, and no further data is + * available. This event is sent because it can be difficult to detect otherwise. + * Following the processing of this method and the processing of any subsequent + * method, the connection will be suspended. + * + * @param wc The WebConnection object that is associated with this connection + */ public void eof(WebConnection wc); + } Modified: trunk/java/org/jboss/web/upgrade/WebConnection.java =================================================================== --- trunk/java/org/jboss/web/upgrade/WebConnection.java 2012-03-14 17:31:01 UTC (rev 2002) +++ trunk/java/org/jboss/web/upgrade/WebConnection.java 2012-03-16 16:54:57 UTC (rev 2003) @@ -24,14 +24,89 @@ import java.io.IOException; +/** + * The WebConnection object is provided by the web container and is used to allow + * access to the raw streams of the socket following an upgrade from HTTP/1.1. + * + * @author remm + */ public interface WebConnection { + + /** + * Returns true when data may be read from the connection (the flag becomes false if no data + * is available to read). When the flag becomes false, the Servlet can attempt to read additional + * data, but it will block until data is available. If calling this method returns false, it will also + * request notification when the connection has data available for reading again, and the + * Servlet will be called back using the inputAvailable method of the ProtocolHandler. + * + * @return boolean true if data can be read without blocking + */ public boolean isReadReady(); + + /** + * Returns true when data may be written to the connection (the flag becomes false + * when the client is unable to accept data fast enough). When the flag becomes false, + * the Servlet must stop writing data. If there's an attempt to flush additional data + * 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 be called back using the outputReady method of the ProtocolHandler. + * <br> + * Note: If the Servlet is not using isWriteReady, and is writing its output inside the + * container threads (inside the ProtocolHandler.resume() method processing, for example), + * using this method is not mandatory, and writes will block until all bytes are written. + * + * @return boolean true if data can be written without blocking + */ public boolean isWriteReady(); + + /** + * This method sets the timeout in milliseconds of idle time on the connection. + * The timeout is reset every time data is received from the connection. If a timeout occurs, the + * Servlet will be called back using the ProtocolHandler.timeout method which will not result in + * automatically closing the connection (the connection may be closed using the close() method). + * + * @param timeout The timeout in milliseconds for this connection, must be a positive value, larger than 0 + */ public void setTimeout(int timeout); + + /** + * Suspend processing of the connection until the configured timeout occurs, + * or resume() is called. In practice, this means the servlet will no longer + * receive read method callbacks. Reading should always be performed synchronously in + * the web container threads unless the connection has been suspended. + */ public void suspend(); - public void close() throws IOException; + + /** + * Resume will cause the Servlet container to use the ProtocolHandler.resume() + * method to call back 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. + * This method must be called asynchronously. + */ + public void resume(); + + /** + * Close the connection. This will send back to the client a notice that the server + * has no more data to send as part of this request. The ProtocolHandler.close method will + * also be called by the container. This method will actually never perform any operation + * synchronously, it will merely mark the connection for closing. + */ + public void close(); + + /** + * Read data in the given byte array. + */ public int read(byte[] b, int off, int len) throws IOException; + + /** + * Write the given bytes. + */ public void write(byte[] b, int off, int len) throws IOException; + } Modified: trunk/webapps/docs/changelog.xml =================================================================== --- trunk/webapps/docs/changelog.xml 2012-03-14 17:31:01 UTC (rev 2002) +++ trunk/webapps/docs/changelog.xml 2012-03-16 16:54:57 UTC (rev 2003) @@ -25,6 +25,9 @@ <fix> <jira>234</jira>: Fix parameters encoding processing issue introduced when rebasing. (remm) </fix> + <add> + Protocol upgrade API. (remm) + </add> </changelog> </subsection> <subsection name="Jasper">