From 0b522aee32b797b7053144147e2ada3a9d0bbeab Mon Sep 17 00:00:00 2001
From: Greg Wilkins <greg@webtide.com>
Date: Fri, 19 Feb 2010 03:31:40 +0000
Subject: [PATCH] javadoc

git-svn-id: svn+ssh://dev.eclipse.org/svnroot/rt/org.eclipse.jetty/jetty/trunk@1278 7e9141cc-0065-0410-87d8-b60c137991c4
---
 .../java/org/eclipse/jetty/io/Connection.java     | 15 ++++++++++++++-
 .../org/eclipse/jetty/server/HttpConnection.java  | 14 +++++++++++++-
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/jetty-io/src/main/java/org/eclipse/jetty/io/Connection.java b/jetty-io/src/main/java/org/eclipse/jetty/io/Connection.java
index 66381cb67dd..42f58a0e864 100644
--- a/jetty-io/src/main/java/org/eclipse/jetty/io/Connection.java
+++ b/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;
diff --git a/jetty-server/src/main/java/org/eclipse/jetty/server/HttpConnection.java b/jetty-server/src/main/java/org/eclipse/jetty/server/HttpConnection.java
index bf126f29452..420eb3d9d9b 100644
--- a/jetty-server/src/main/java/org/eclipse/jetty/server/HttpConnection.java
+++ b/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