ConnectHandler (Jetty :: Aggregate :: All core Jetty 7.6.8.v20121106 API)
Date: 2012-11-06

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
    Modifier and Type | Class and Description
    --- | ---
    `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
    Modifier and Type | Method and Description
    --- | ---
    `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`

Copyright © 1995-2012 Mort Bay Consulting. All Rights Reserved.