org.eclipse.jetty.server.handler

## Class ConnectHandler

- java.lang.Object
- - org.eclipse.jetty.util.component.AbstractLifeCycle
  - - org.eclipse.jetty.util.component.AggregateLifeCycle
    - - org.eclipse.jetty.server.handler.AbstractHandler
      - - org.eclipse.jetty.server.handler.AbstractHandlerContainer
        - - org.eclipse.jetty.server.handler.HandlerWrapper
          - - org.eclipse.jetty.server.handler.ConnectHandler

All Implemented Interfaces:
  Handler, HandlerContainer, Destroyable, Dumpable, LifeCycle

Direct Known Subclasses:
  ProxyHandler

    public class ConnectHandler
    extends HandlerWrapper

Implementation of a tunneling proxy that supports HTTP CONNECT.

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.

### Nested Class Summary

Nested Classes
`class` `ConnectHandler.ClientToProxyConnection`
`class` `ConnectHandler.ProxyToServerConnection`

### Nested classes/interfaces inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

`AbstractLifeCycle.AbstractLifeCycleListener`

### Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.LifeCycle

`LifeCycle.Listener`

### Field Summary

### Fields inherited from class org.eclipse.jetty.server.handler.HandlerWrapper

`_handler`

### Fields inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

`_listeners, FAILED, RUNNING, STARTED, STARTING, STOPPED, STOPPING`

### Constructor Summary

Constructors
Constructor and Description
`ConnectHandler()`
`ConnectHandler(Handler handler)`
`ConnectHandler(Handler handler, String[] white, String[] black)`
`ConnectHandler(String[] white, String[] black)`

### Method Summary

Methods
`void` `addBlack(String entry)` Add a blacklist entry to an existing handler configuration
`void` `addWhite(String entry)` Add a whitelist entry to an existing handler configuration
`protected SocketChannel` `connect(javax.servlet.http.HttpServletRequest request, String host, int port)` Establishes a connection to the remote server.
`protected void` `doStart()` Start the managed lifecycle beans in the order they were added.
`protected void` `doStop()` Stop the joined lifecycle beans in the reverse order they were added.
`void` `dump(Appendable out, String indent)`
`int` `getConnectTimeout()`
`ThreadPool` `getThreadPool()`
`int` `getWriteTimeout()`
`void` `handle(String target, Request baseRequest, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Handle a request.
`protected boolean` `handleAuthentication(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, String address)` Handles the authentication before setting up the tunnel to the remote server.
`protected void` `handleConnect(Request baseRequest, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, String serverAddress)` Handles a CONNECT request.
`protected ConnectHandler.ClientToProxyConnection` `newClientToProxyConnection(ConcurrentMap<String,Object> context, SocketChannel channel, EndPoint endPoint, long timeStamp)`
`protected ConnectHandler.ProxyToServerConnection` `newProxyToServerConnection(ConcurrentMap<String,Object> context, Buffer buffer)`
`protected void` `prepareContext(javax.servlet.http.HttpServletRequest request, ConcurrentMap<String,Object> context)`
`protected int` `read(EndPoint endPoint, Buffer buffer, ConcurrentMap<String,Object> context)` Reads (with non-blocking semantic) into the given `buffer` from the given `endPoint`.
`protected void` `set(String[] entries, HostMap<String> hostMap)` Helper method to process a list of new entries and replace the content of the specified host map
`void` `setBlack(String[] entries)` Re-initialize the blacklist of existing handler object
`void` `setConnectTimeout(int connectTimeout)`
`void` `setServer(Server server)`
`void` `setThreadPool(ThreadPool threadPool)`
`void` `setWhite(String[] entries)` Re-initialize the whitelist of existing handler object
`void` `setWriteTimeout(int writeTimeout)`
`boolean` `validateDestination(String host)` Check the request hostname against white- and blacklist.
`protected int` `write(EndPoint endPoint, Buffer buffer, ConcurrentMap<String,Object> context)` Writes (with blocking semantic) the given buffer of data onto the given endPoint.

### Methods inherited from class org.eclipse.jetty.server.handler.HandlerWrapper

`destroy, expandChildren, getHandler, getHandlers, getNestedHandlerByClass, setHandler`

### Methods inherited from class org.eclipse.jetty.server.handler.AbstractHandlerContainer

`expandHandler, findContainerOf, getChildHandlerByClass, getChildHandlers, getChildHandlersByClass`

### Methods inherited from class org.eclipse.jetty.server.handler.AbstractHandler

`dumpThis, getServer`

### Methods inherited from class org.eclipse.jetty.util.component.AggregateLifeCycle

`addBean, addBean, contains, dump, dump, dump, dump, dumpObject, dumpStdErr, getBean, getBeans, getBeans, isManaged, manage, removeBean, removeBeans, unmanage`

### Methods inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

`addLifeCycleListener, getState, getState, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, removeLifeCycleListener, start, stop`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Methods inherited from interface org.eclipse.jetty.util.component.LifeCycle

`addLifeCycleListener, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, removeLifeCycleListener, start, stop`

### Constructor Detail

#### ConnectHandler

    public ConnectHandler()

#### ConnectHandler

    public ConnectHandler(String[] white,
                  String[] black)

#### ConnectHandler

    public ConnectHandler(Handler handler)

#### ConnectHandler

    public ConnectHandler(Handler handler,
                  String[] white,
                  String[] black)

### Method Detail

#### getConnectTimeout

    public int getConnectTimeout()

Returns:
  the timeout, in milliseconds, to connect to the remote server

#### setConnectTimeout

    public void setConnectTimeout(int connectTimeout)

Parameters:
  `connectTimeout` - the timeout, in milliseconds, to connect to the remote server

#### getWriteTimeout

    public int getWriteTimeout()

Returns:
  the timeout, in milliseconds, to write data to a peer

#### setWriteTimeout

    public void setWriteTimeout(int writeTimeout)

Parameters:
  `writeTimeout` - the timeout, in milliseconds, to write data to a peer

#### setServer

    public void setServer(Server server)

Specified by:
  `setServer` in interface `Handler`
Overrides:
  `setServer` in class `HandlerWrapper`

#### getThreadPool

    public ThreadPool getThreadPool()

Returns:
  the thread pool

#### setThreadPool

    public void setThreadPool(ThreadPool threadPool)

Parameters:
  `threadPool` - the thread pool

#### doStart

    protected void doStart()
                    throws Exception

Description copied from class: `AggregateLifeCycle`
Start the managed lifecycle beans in the order they were added.

Overrides:
  `doStart` in class `HandlerWrapper`
Throws:
  `Exception`
See Also:
  `AbstractLifeCycle.doStart()`

#### doStop

    protected void doStop()
                   throws Exception

Description copied from class: `AggregateLifeCycle`
Stop the joined lifecycle beans in the reverse order they were added.

Overrides:
  `doStop` in class `HandlerWrapper`
Throws:
  `Exception`
See Also:
  `AbstractLifeCycle.doStart()`

#### handle

    public void handle(String target,
              Request baseRequest,
              javax.servlet.http.HttpServletRequest request,
              javax.servlet.http.HttpServletResponse response)
                throws javax.servlet.ServletException,
                       IOException

Description copied from interface: `Handler`
Handle a request.

Specified by:
  `handle` in interface `Handler`
Overrides:
  `handle` in class `HandlerWrapper`
Parameters:
  `target` - The target of the request - either a URI or a name.
  `baseRequest` - The original unwrapped request object.
  `request` - The request either as the `Request` object or a wrapper of that request. The `AbstractHttpConnection.getCurrentConnection()` method can be used access the Request object if required.
  `response` - The response as the `Response` object or a wrapper of that request. The `AbstractHttpConnection.getCurrentConnection()` method can be used access the Response object if required.
Throws:
  `javax.servlet.ServletException`
  `IOException`

#### handleConnect

    protected void handleConnect(Request baseRequest,
                     javax.servlet.http.HttpServletRequest request,
                     javax.servlet.http.HttpServletResponse response,
                     String serverAddress)
                          throws javax.servlet.ServletException,
                                 IOException

Handles a CONNECT request.

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

Parameters:
  `baseRequest` - Jetty-specific http request
  `request` - the http request
  `response` - the http response
  `serverAddress` - the remote server address in the form `host:port`
Throws:
  `javax.servlet.ServletException` - if an application error occurs
  `IOException` - if an I/O error occurs

#### handleAuthentication

    protected boolean handleAuthentication(javax.servlet.http.HttpServletRequest request,
                               javax.servlet.http.HttpServletResponse response,
                               String address)
                                    throws javax.servlet.ServletException,
                                           IOException

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

The default implementation returns true.

Parameters:
  `request` - the HTTP request
  `response` - the HTTP response
  `address` - the address of the remote server in the form `host:port`.
Returns:
  true to allow to connect to the remote host, false otherwise
Throws:
  `javax.servlet.ServletException` - to report a server error to the caller
  `IOException` - to report a server error to the caller

#### newClientToProxyConnection

    protected ConnectHandler.ClientToProxyConnection newClientToProxyConnection(ConcurrentMap<String,Object> context,
                                                                    SocketChannel channel,
                                                                    EndPoint endPoint,
                                                                    long timeStamp)

#### newProxyToServerConnection

    protected ConnectHandler.ProxyToServerConnection newProxyToServerConnection(ConcurrentMap<String,Object> context,
                                                                    Buffer buffer)

#### connect

    protected SocketChannel connect(javax.servlet.http.HttpServletRequest request,
                        String host,
                        int port)
                             throws IOException

Establishes a connection to the remote server.

Parameters:
  `request` - the HTTP request that initiated the tunnel
  `host` - the host to connect to
  `port` - the port to connect to
Returns:
  a `SocketChannel` connected to the remote server
Throws:
  `IOException` - if the connection cannot be established

#### prepareContext

    protected void prepareContext(javax.servlet.http.HttpServletRequest request,
                      ConcurrentMap<String,Object> context)

#### read

    protected int read(EndPoint endPoint,
           Buffer buffer,
           ConcurrentMap<String,Object> context)
                throws IOException

Reads (with non-blocking semantic) into the given `buffer` from the given `endPoint`.

Parameters:
  `endPoint` - the endPoint to read from
  `buffer` - the buffer to read data into
  `context` - the context information related to the connection
Returns:
  the number of bytes read (possibly 0 since the read is non-blocking) or -1 if the channel has been closed remotely
Throws:
  `IOException` - if the endPoint cannot be read

#### write

    protected int write(EndPoint endPoint,
            Buffer buffer,
            ConcurrentMap<String,Object> context)
                 throws IOException

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

Parameters:
  `endPoint` - the endPoint to write to
  `buffer` - the buffer to write
  `context` - the context information related to the connection
Returns:
  the number of bytes written
Throws:
  `IOException` - if the buffer cannot be written

#### addWhite

    public void addWhite(String entry)

Add a whitelist entry to an existing handler configuration

Parameters:
  `entry` - new whitelist entry

#### addBlack

    public void addBlack(String entry)

Add a blacklist entry to an existing handler configuration

Parameters:
  `entry` - new blacklist entry

#### setWhite

    public void setWhite(String[] entries)

Re-initialize the whitelist of existing handler object

Parameters:
  `entries` - array of whitelist entries

#### setBlack

    public void setBlack(String[] entries)

Re-initialize the blacklist of existing handler object

Parameters:
  `entries` - array of blacklist entries

#### set

    protected void set(String[] entries,
           HostMap<String> hostMap)

Helper method to process a list of new entries and replace the content of the specified host map

Parameters:
  `entries` - new entries
  `hostMap` - target host map

#### validateDestination

    public boolean validateDestination(String host)

Check the request hostname against white- and blacklist.

Parameters:
  `host` - hostname to check
Returns:
  true if hostname is allowed to be proxied

#### dump

    public void dump(Appendable out,
            String indent)
              throws IOException

Specified by:
  `dump` in interface `Dumpable`
Overrides:
  `dump` in class `AbstractHandlerContainer`
Throws:
  `IOException`