jetty-9 improved javadoc

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

@@ -23,10 +23,27 @@ import org.eclipse.jetty.io.Connection;
 import org.eclipse.jetty.io.EndPoint;
 
 /**
- * <p>Factory for {@link Connection}s.</p>
+ * <p>A Factory to create {@link Connection} instances for {@link Connector}s.</p>
+ * <p>A Connection factory is responsible for instantiating and configuring a {@link Connection} instance
+ * to handle an {@link EndPoint} accepted by a {@link Connector}.</p>
+ * <p>
+ * A ConnectionFactory has a protocol name that represents the protocol of the Connections
+ * created.  Example of protocol names include:<dl>
+ * <dt>http</dt><dd>Creates a HTTP connection that can handle multiple versions of HTTP from 0.9 to 1.1</dd>
+ * <dt>spdy/2</dt><dd>Creates a HTTP connection that handles a specific version of the SPDY protocol</dd>
+ * <dt>SSL-XYZ</dt><dd>Create an SSL connection chained to a connection obtained from a connection factory 
+ * with a protocol "XYZ".</dd>
+ * <dt>SSL-http</dt><dd>Create an SSL connection chained to a HTTP connection (aka https)</dd>
+ * <dt>SSL-npn</dt><dd>Create an SSL connection chained to a NPN connection, that uses a negotiation with
+ * the client to determine the next protocol.</dd>
+ * </dl>
  */
 public interface ConnectionFactory
 {
+    /* ------------------------------------------------------------ */
+    /**
+     * @return A string representing the protocol name.
+     */
     public String getProtocol();
     
     /**

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

@@ -27,6 +27,25 @@ import org.eclipse.jetty.http.HttpHeader;
 import org.eclipse.jetty.http.HttpScheme;
 import org.eclipse.jetty.server.HttpConfiguration.Customizer;
 
+
+/* ------------------------------------------------------------ */
+/** Customize Requests for Proxy Forwarding.
+ * <p>
+ * This customizer looks at at HTTP request for headers that indicate
+ * it has been forwarded by one or more proxies.  Specifically handled are:
+ * <ul>
+ * <li>X-Forwarded-Host</li>
+ * <li>X-Forwarded-Server</li>
+ * <li>X-Forwarded-For</li>
+ * <li>X-Forwarded-Proto</li>
+ * </ul>
+ * <p>If these headers are present, then the {@link Request} object is updated
+ * so that the proxy is not seen as the other end point of the connection on which
+ * the request came</p>
+ * <p>Headers can also be defined so that forwarded SSL Session IDs and Cipher
+ * suites may be customised</p> 
+ * @see http://en.wikipedia.org/wiki/X-Forwarded-For
+ */
 public class ForwardedRequestCustomizer implements Customizer
 {
     private String _hostHeader;

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

@@ -25,6 +25,18 @@ import org.eclipse.jetty.http.HttpScheme;
 import org.eclipse.jetty.util.annotation.ManagedAttribute;
 import org.eclipse.jetty.util.annotation.ManagedObject;
 
+
+/* ------------------------------------------------------------ */
+/** HTTP Configuration.
+ * <p>This class is a holder of HTTP configuration for use by the 
+ * {@link HttpChannel} class.  Typically a HTTPConfiguration instance
+ * is instantiated and passed to a {@link ConnectionFactory} that can 
+ * create HTTP channels (eg HTTP, AJP or SPDY).</p>
+ * <p>The configuration held by this class is not for the wire protocol,
+ * but for the interpretation and handling of HTTP requests that could
+ * be transported by a variety of protocols.
+ * </p>
+ */
 @ManagedObject("HTTP Configuration")
 public class HttpConfiguration
 {
@@ -49,6 +61,10 @@ public class HttpConfiguration
     {
     }
     
+    /* ------------------------------------------------------------ */
+    /** Create a configuration from another.
+     * @param config The configuration to copy.
+     */
     public HttpConfiguration(HttpConfiguration config)
     {
         _customizers.addAll(config._customizers);
@@ -59,11 +75,20 @@ public class HttpConfiguration
         _secureScheme=config._secureScheme;
     }
     
+    /* ------------------------------------------------------------ */
+    /** 
+     * <p>Add a {@link Customizer} that is invoked for every 
+     * request received.</p>
+     * <p>Customiser are often used to interpret optional headers (eg {@link ForwardedRequestCustomizer}) or 
+     * optional protocol semantics (eg {@link SecureRequestCustomizer}). 
+     * @param customizer A request customizer
+     */
     public void addCustomizer(Customizer customizer)
     {
         _customizers.add(customizer);
     }
     
+    /* ------------------------------------------------------------ */
     public List<Customizer> getCustomizers()
     {
         return _customizers;
@@ -107,32 +132,72 @@ public class HttpConfiguration
         return _secureScheme;
     }
     
+    /* ------------------------------------------------------------ */
+    /**
+     * <p>Set the {@link Customizer}s that are invoked for every 
+     * request received.</p>
+     * <p>Customisers are often used to interpret optional headers (eg {@link ForwardedRequestCustomizer}) or 
+     * optional protocol semantics (eg {@link SecureRequestCustomizer}). 
+     * @param customizers
+     */
     public void setCustomizers(List<Customizer> customizers)
     {
         _customizers.clear();
         _customizers.addAll(customizers);
     }
 
+    /* ------------------------------------------------------------ */
+    /**
+     * Set the size of the buffer into which response content is aggregated
+     * before being sent to the client.  A larger buffer can improve performance by allowing
+     * a content producer to run without blocking, however larger buffers consume more memory and
+     * may induce some latency before a client starts processing the content.
+     * @param responseBufferSize buffer size in bytes.
+     */
     public void setOutputBufferSize(int responseBufferSize)
     {
         _outputBufferSize = responseBufferSize;
     }
     
+    /* ------------------------------------------------------------ */
+    /** Set the maximum size of a request header.
+     * <p>Larger headers will allow for more and/or larger cookies plus larger form content encoded 
+     * in a URL. However, larger headers consume more memory and can make a server more vulnerable to denial of service
+     * attacks.</p>
+     * @param requestHeaderSize Max header size in bytes
+     */
     public void setRequestHeaderSize(int requestHeaderSize)
     {
         _requestHeaderSize = requestHeaderSize;
     }
 
+    /* ------------------------------------------------------------ */
+    /** Set the maximum size of a response header.
+     * 
+     * <p>Larger headers will allow for more and/or larger cookies and longer HTTP headers (eg for redirection). 
+     * However, larger headers will also consume more memory.</p>
+     * @param responseHeaderSize Response header size in bytes.
+     */
     public void setResponseHeaderSize(int responseHeaderSize)
     {
         _responseHeaderSize = responseHeaderSize;
     }
 
+    /* ------------------------------------------------------------ */
+    /** Set the TCP/IP port used for CONFIDENTIAL and INTEGRAL 
+     * redirections.
+     * @param confidentialPort
+     */
     public void setSecurePort(int confidentialPort)
     {
         _securePort = confidentialPort;
     }
 
+    /* ------------------------------------------------------------ */
+    /** Set the  URI scheme used for CONFIDENTIAL and INTEGRAL 
+     * redirections.
+     * @param confidentialScheme A string like"https"
+     */
     public void setSecureScheme(String confidentialScheme)
     {
         _secureScheme = confidentialScheme;