javadoc

git-svn-id: svn+ssh://dev.eclipse.org/svnroot/rt/org.eclipse.jetty/jetty/trunk@1278 7e9141cc-0065-0410-87d8-b60c137991c4

jetty-io/src/main/java/org/eclipse/jetty/io/Connection.java

@@ -15,12 +15,25 @@ package org.eclipse.jetty.io;
 
 import java.io.IOException;
 
+/* ------------------------------------------------------------ */
+/** Abstract Connection used by Jetty Connectors.
+ * <p>
+ * Jetty will call the handle method of a connection when there is work 
+ * to be done on the connection.  For blocking connections, this is soon 
+ * as the connection is open and handle will keep being called until the 
+ * connection is closed.   For non-blocking connections, handle will only
+ * be called if there are bytes to be read or the connection becomes writable
+ * after being write blocked.
+ * 
+ * @see org.eclipse.jetty.io.nio.SelectorManager
+ */
 public interface Connection
 {
     /* ------------------------------------------------------------ */
     /**
      * Handle the connection.
-     * @return The Connection to use for the next handling of the connection. This allows protocol upgrades.
+     * @return The Connection to use for the next handling of the connection. 
+     * This allows protocol upgrades and support for CONNECT.
      * @throws IOException
      */
     Connection handle() throws IOException;

jetty-server/src/main/java/org/eclipse/jetty/server/HttpConnection.java

@@ -70,7 +70,19 @@ import org.eclipse.jetty.util.thread.Timeout;
  * The connection state is held by 3 separate state machines: The request state, the 
  * response state and the continuation state.  All three state machines must be driven
  * to completion for every request, and all three can complete in any order.
- * 
+ * </p>
+ * <p>
+ * The HttpConnection support protocol upgrade.  If on completion of a request, the
+ * response code is 101 (switch protocols), then the org.eclipse.jetty.io.Connection
+ * request attribute is checked to see if there is a new Connection instance. If so,
+ * the new connection is returned from {@link #handle()} and is used for future 
+ * handling of the underlying connection.   Note that for switching protocols that
+ * don't use 101 responses (eg CONNECT), the response should be sent and then the
+ * status code changed to 101 before returning from the handler.  Implementors 
+ * of new Connection types should be careful to extract any buffered data from
+ * (HttpParser)http.getParser()).getHeaderBuffer() and 
+ * (HttpParser)http.getParser()).getBodyBuffer() to initialise their new connection.
+ * </p>
  *
  */
 public class HttpConnection implements Connection