434536 Improved Customizer javadoc

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

@@ -54,6 +54,23 @@ public class HttpConfiguration
     private boolean _sendXPoweredBy = false; //send X-Powered-By: header
     private boolean _sendDateHeader = true; //send Date: header
 
+    
+    /* ------------------------------------------------------------ */
+    /** 
+     * <p>An interface that allows a request object to be customized 
+     * for a particular HTTP connector configuration.  Unlike Filters, customiser are
+     * applied before a is submitted for request processing and can be specific to the 
+     * connector on which the request was received.
+     * 
+     * <p>Typically Customizers perform tasks such as: <ul>
+     *  <li>process header fields that may be injected by a proxy or load balancer.
+     *  <li>setup attributes that may come from the connection/connector such as SSL Session IDs
+     *  <li>Allow a request to be marked as secure or authenticated if those have been offloaded
+     *  and communicated by header, cookie or other out-of-band mechansism
+     *  <li>Set request attributes/fields that are determined by the connector on which the
+     *  request was received
+     *  </ul>
+     */
     public interface Customizer
     {
         public void customize(Connector connector, HttpConfiguration channelConfig, Request request);
@@ -104,6 +121,7 @@ public class HttpConfiguration
         return _customizers;
     }
 
+    /* ------------------------------------------------------------ */
     public <T> T getCustomizer(Class<T> type)
     {
         for (Customizer c : _customizers)

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

@@ -20,8 +20,10 @@ package org.eclipse.jetty.server;
 
 import java.security.cert.X509Certificate;
 
+import javax.net.ssl.SSLContext;
 import javax.net.ssl.SSLEngine;
 import javax.net.ssl.SSLSession;
+import javax.servlet.ServletRequest;
 
 import org.eclipse.jetty.http.HttpScheme;
 import org.eclipse.jetty.io.ssl.SslConnection;
@@ -31,6 +33,12 @@ import org.eclipse.jetty.util.log.Log;
 import org.eclipse.jetty.util.log.Logger;
 import org.eclipse.jetty.util.ssl.SslContextFactory;
 
+
+/* ------------------------------------------------------------ */
+/** Customizer that extracts the attribute from an {@link SSLContext}
+ * and sets them on the request with {@link ServletRequest#setAttribute(String, Object)}
+ * according to Servlet Specification Requirements.
+ */
 public class SecureRequestCustomizer implements HttpConfiguration.Customizer
 {
     private static final Logger LOG = Log.getLogger(SecureRequestCustomizer.class);
@@ -40,7 +48,6 @@ public class SecureRequestCustomizer implements HttpConfiguration.Customizer
      */
     public static final String CACHED_INFO_ATTR = CachedInfo.class.getName();
 
-
     @Override
     public void customize(Connector connector, HttpConfiguration channelConfig, Request request)
     {
@@ -53,14 +60,11 @@ public class SecureRequestCustomizer implements HttpConfiguration.Customizer
             SSLEngine sslEngine=sslConnection.getSSLEngine();
             customize(sslEngine,request);
         }
-
     }
 
     /* ------------------------------------------------------------ */
     /*
-     * Allow the Listener a chance to customise the request. before the server
+     * Customise the request attributes to be set for SSL requests. <br>
-     * does its stuff. <br>
-     * This allows the required attributes to be set for SSL requests. <br>
      * The requirements of the Servlet specs are:
      * <ul>
      * <li> an attribute named "javax.servlet.request.ssl_session_id" of type