From fcbb88964165fb70bf0d87eb9bbb1c1f4f686e81 Mon Sep 17 00:00:00 2001 From: Simone Bordet Date: Thu, 15 Apr 2010 09:33:12 +0000 Subject: [PATCH] Javadocs for #297104. git-svn-id: svn+ssh://dev.eclipse.org/svnroot/rt/org.eclipse.jetty/jetty/trunk@1515 7e9141cc-0065-0410-87d8-b60c137991c4 --- .../jetty/server/handler/ProxyHandler.java | 83 +++++++++++++++---- 1 file changed, 69 insertions(+), 14 deletions(-) diff --git a/jetty-server/src/main/java/org/eclipse/jetty/server/handler/ProxyHandler.java b/jetty-server/src/main/java/org/eclipse/jetty/server/handler/ProxyHandler.java index 6bb8bfdbf2c..490f00419bd 100644 --- a/jetty-server/src/main/java/org/eclipse/jetty/server/handler/ProxyHandler.java +++ b/jetty-server/src/main/java/org/eclipse/jetty/server/handler/ProxyHandler.java @@ -28,6 +28,12 @@ import org.eclipse.jetty.util.log.Logger; import org.eclipse.jetty.util.thread.ThreadPool; /** + *

Implementation of a tunnelling proxy that supports HTTP CONNECT and transparent proxy.

+ *

To work as CONNECT proxy, objects of this class must be instantiated using the no-arguments + * constructor, since the remote server information will be present in the CONNECT URI.

+ *

To work as transparent proxy, objects of this class must be instantiated using the string + * argument constructor, passing the remote host address and port in the form {@code host:port}.

+ * * @version $Revision$ $Date$ */ public class ProxyHandler extends AbstractHandler @@ -40,31 +46,51 @@ public class ProxyHandler extends AbstractHandler private volatile ThreadPool _threadPool; private volatile ThreadPool _privateThreadPool; + /** + *

Constructor to be used to make this proxy work via HTTP CONNECT.

+ */ public ProxyHandler() { this(null); } + /** + *

Constructor to be used to make this proxy work as transparent proxy.

+ * + * @param serverAddress the address of the remote server in the form {@code host:port} + */ public ProxyHandler(String serverAddress) { _serverAddress = serverAddress; } + /** + * @return the timeout, in milliseconds, to connect to the remote server + */ public int getConnectTimeout() { return _connectTimeout; } + /** + * @param connectTimeout the timeout, in milliseconds, to connect to the remote server + */ public void setConnectTimeout(int connectTimeout) { _connectTimeout = connectTimeout; } + /** + * @return the timeout, in milliseconds, to write data to a peer + */ public int getWriteTimeout() { return _writeTimeout; } + /** + * @param writeTimeout the timeout, in milliseconds, to write data to a peer + */ public void setWriteTimeout(int writeTimeout) { _writeTimeout = writeTimeout; @@ -83,16 +109,16 @@ public class ProxyHandler extends AbstractHandler _threadPool=server.getThreadPool(); } - /** Get the threadPool. - * @return the threadPool + /** + * @return the thread pool */ public ThreadPool getThreadPool() { return _threadPool; } - /** Set the threadPool. - * @param threadPool the threadPool to set + /** + * @param the thread pool */ public void setThreadPool(ThreadPool threadPool) { @@ -160,41 +186,61 @@ public class ProxyHandler extends AbstractHandler } /** - *

Handles a CONNECT request.

+ *

Handles a tunnelling request, either a CONNECT or a transparent request.

*

CONNECT requests may have authentication headers such as Proxy-Authorization * that authenticate the client with the proxy.

+ * * @param request the http request * @param response the http response - * @param connectURI the CONNECT URI + * @param serverAddress the remote server address in the form {@code host:port} * @throws ServletException if an application error occurs * @throws IOException if an I/O error occurs */ - protected void handle(HttpServletRequest request, HttpServletResponse response, String connectURI) throws ServletException, IOException + protected void handle(HttpServletRequest request, HttpServletResponse response, String serverAddress) throws ServletException, IOException { - boolean proceed = handleAuthentication(request, response, connectURI); + boolean proceed = handleAuthentication(request, response, serverAddress); if (!proceed) return; - String host = connectURI; + String host = serverAddress; int port = 80; boolean secure = false; - int colon = connectURI.indexOf(':'); + int colon = serverAddress.indexOf(':'); if (colon > 0) { - host = connectURI.substring(0, colon); - port = Integer.parseInt(connectURI.substring(colon + 1)); + host = serverAddress.substring(0, colon); + port = Integer.parseInt(serverAddress.substring(colon + 1)); secure = isTunnelSecure(host, port); } setupTunnel(request, response, host, port, secure); } + /** + *

Returns whether the given {@code host} and {@code port} identify a SSL communication channel.

+ *

Default implementation returns true if the {@code port} is 443.

+ * + * @param host the host to connect to + * @param port the port to connect to + * @return true if the communication channel is confidential, false otherwise + */ protected boolean isTunnelSecure(String host, int port) { return port == 443; } - protected boolean handleAuthentication(HttpServletRequest request, HttpServletResponse response, String connectURI) throws ServletException, IOException + /** + *

Handles the authentication before setting up the tunnel to the remote server.

+ *

The default implementation returns true.

+ * + * @param request the HTTP request + * @param response the HTTP response + * @param address the address of the remote server in the form {@code host:port}. + * @return true to allow to connect to the remote host, false otherwise + * @throws ServletException to report a server error to the caller + * @throws IOException to report a server error to the caller + */ + protected boolean handleAuthentication(HttpServletRequest request, HttpServletResponse response, String address) throws ServletException, IOException { return true; } @@ -250,6 +296,14 @@ public class ProxyHandler extends AbstractHandler return new ProxyToServerConnection(secure, buffer); } + /** + *

Establishes a connection to the remote server.

+ * @param request the HTTP request that initiated the tunnel + * @param host the host to connect to + * @param port the port to connect to + * @return a {@link SocketChannel} connected to the remote server + * @throws IOException if the connection cannot be established + */ protected SocketChannel connect(HttpServletRequest request, String host, int port) throws IOException { _logger.debug("Establishing connection to {}:{}", host, port); @@ -281,7 +335,8 @@ public class ProxyHandler extends AbstractHandler } /** - * Writes (with blocking semantic) the given buffer of data onto the given endPoint + *

Writes (with blocking semantic) the given buffer of data onto the given endPoint.

+ * * @param endPoint the endPoint to write to * @param buffer the buffer to write * @throws IOException if the buffer cannot be written