From 49de22ea48aef9307520b1ffb3d178b1b6514426 Mon Sep 17 00:00:00 2001 From: Greg Wilkins Date: Thu, 15 Nov 2012 17:31:28 +1100 Subject: [PATCH] jetty-9 improved javadoc --- .../jetty/server/ConnectionFactory.java | 19 +++++- .../server/ForwardedRequestCustomizer.java | 19 ++++++ .../jetty/server/HttpConfiguration.java | 65 +++++++++++++++++++ 3 files changed, 102 insertions(+), 1 deletion(-) diff --git a/jetty-server/src/main/java/org/eclipse/jetty/server/ConnectionFactory.java b/jetty-server/src/main/java/org/eclipse/jetty/server/ConnectionFactory.java index b129baf62f9..6fd2369c37b 100644 --- a/jetty-server/src/main/java/org/eclipse/jetty/server/ConnectionFactory.java +++ b/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; /** - *

Factory for {@link Connection}s.

+ *

A Factory to create {@link Connection} instances for {@link Connector}s.

+ *

A Connection factory is responsible for instantiating and configuring a {@link Connection} instance + * to handle an {@link EndPoint} accepted by a {@link Connector}.

+ *

+ * A ConnectionFactory has a protocol name that represents the protocol of the Connections + * created. Example of protocol names include:

+ *
http
Creates a HTTP connection that can handle multiple versions of HTTP from 0.9 to 1.1
+ *
spdy/2
Creates a HTTP connection that handles a specific version of the SPDY protocol
+ *
SSL-XYZ
Create an SSL connection chained to a connection obtained from a connection factory + * with a protocol "XYZ".
+ *
SSL-http
Create an SSL connection chained to a HTTP connection (aka https)
+ *
SSL-npn
Create an SSL connection chained to a NPN connection, that uses a negotiation with + * the client to determine the next protocol.
+ *
*/ public interface ConnectionFactory { + /* ------------------------------------------------------------ */ + /** + * @return A string representing the protocol name. + */ public String getProtocol(); /** diff --git a/jetty-server/src/main/java/org/eclipse/jetty/server/ForwardedRequestCustomizer.java b/jetty-server/src/main/java/org/eclipse/jetty/server/ForwardedRequestCustomizer.java index a36f4f86165..8614c3e9759 100644 --- a/jetty-server/src/main/java/org/eclipse/jetty/server/ForwardedRequestCustomizer.java +++ b/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. + *

+ * This customizer looks at at HTTP request for headers that indicate + * it has been forwarded by one or more proxies. Specifically handled are: + *

+ *

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

+ *

Headers can also be defined so that forwarded SSL Session IDs and Cipher + * suites may be customised

+ * @see http://en.wikipedia.org/wiki/X-Forwarded-For + */ public class ForwardedRequestCustomizer implements Customizer { private String _hostHeader; diff --git a/jetty-server/src/main/java/org/eclipse/jetty/server/HttpConfiguration.java b/jetty-server/src/main/java/org/eclipse/jetty/server/HttpConfiguration.java index 89dcdb07722..86f1dbe483c 100644 --- a/jetty-server/src/main/java/org/eclipse/jetty/server/HttpConfiguration.java +++ b/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. + *

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).

+ *

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. + *

+ */ @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; } + /* ------------------------------------------------------------ */ + /** + *

Add a {@link Customizer} that is invoked for every + * request received.

+ *

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 getCustomizers() { return _customizers; @@ -107,32 +132,72 @@ public class HttpConfiguration return _secureScheme; } + /* ------------------------------------------------------------ */ + /** + *

Set the {@link Customizer}s that are invoked for every + * request received.

+ *

Customisers are often used to interpret optional headers (eg {@link ForwardedRequestCustomizer}) or + * optional protocol semantics (eg {@link SecureRequestCustomizer}). + * @param customizers + */ public void setCustomizers(List 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. + *

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.

+ * @param requestHeaderSize Max header size in bytes + */ public void setRequestHeaderSize(int requestHeaderSize) { _requestHeaderSize = requestHeaderSize; } + /* ------------------------------------------------------------ */ + /** Set the maximum size of a response header. + * + *

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.

+ * @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;