## org.apache.http.nio.protocol
Class HttpAsyncService

    java.lang.Object
      org.apache.http.nio.protocol.HttpAsyncService

All Implemented Interfaces:
  NHttpServerEventHandler

    @Immutable
    public class HttpAsyncService

extends Object
implements NHttpServerEventHandler

`HttpAsyncService` is a fully asynchronous HTTP server side protocol handler based on the non-blocking (NIO) I/O model. `HttpAsyncServerProtocolHandler` translates individual events fired through the `NHttpServerEventHandler` interface into logically related HTTP message exchanges.

Upon receiving an incoming request `HttpAsyncService` verifies the message for compliance with the server expectations using `HttpAsyncExpectationVerifier`, if provided, and then `HttpAsyncRequestHandlerResolver` is used to resolve the request URI to a particular `HttpAsyncRequestHandler` intended to handle the request with the given URI. The protocol handler uses the selected `HttpAsyncRequestHandler` instance to process the incoming request and to generate an outgoing response.

`HttpAsyncService` relies on `HttpProcessor` to generate mandatory protocol headers for all outgoing messages and apply common, cross-cutting message transformations to all incoming and outgoing messages, whereas individual `HttpAsyncRequestHandler`s are expected to implement application specific content generation and processing.

Individual `HttpAsyncRequestHandler`s do not have to submit a response immediately. They can defer transmission of an HTTP response back to the client without blocking the I/O thread by delegating the process of request handling to another service or a worker thread. HTTP response can be submitted as a later a later point of time once response content becomes available.

The following parameters can be used to customize the behavior of this class:

- `CoreConnectionPNames.SO_TIMEOUT`

Since:
  4.2

Constructor Summary
`HttpAsyncService(HttpProcessor httpProcessor, ConnectionReuseStrategy connStrategy, HttpAsyncRequestHandlerResolver handlerResolver, HttpParams params)` Creates an instance of `HttpAsyncServerProtocolHandler`.
`HttpAsyncService(HttpProcessor httpProcessor, ConnectionReuseStrategy connStrategy, HttpResponseFactory responseFactory, HttpAsyncRequestHandlerResolver handlerResolver, HttpAsyncExpectationVerifier expectationVerifier, HttpParams params)` Creates an instance of `HttpAsyncServerProtocolHandler`.

Method Summary
`void` `closed(NHttpServerConnection conn)` Triggered when the connection is closed.
`void` `connected(NHttpServerConnection conn)` Triggered when a new incoming connection is created.
`void` `endOfInput(NHttpServerConnection conn)` Triggered when the connection is closed by the opposite end point (half-closed).
`void` `exception(NHttpServerConnection conn, Exception cause)` Triggered if an error occurs during the HTTP exchange.
`protected HttpAsyncResponseProducer` `handleException(Exception ex, HttpContext context)`
`void` `inputReady(NHttpServerConnection conn, ContentDecoder decoder)` Triggered when the underlying channel is ready for reading a new portion of the request entity through the corresponding content decoder.
`protected void` `log(Exception ex)` This method can be used to log I/O exception thrown while closing `Closeable` objects (such as `HttpConnection`).
`void` `outputReady(NHttpServerConnection conn, ContentEncoder encoder)` Triggered when the underlying channel is ready for writing a next portion of the response entity through the corresponding content encoder.
`void` `requestReceived(NHttpServerConnection conn)` Triggered when a new HTTP request is received.
`void` `responseReady(NHttpServerConnection conn)` Triggered when the connection is ready to accept a new HTTP response.
`void` `timeout(NHttpServerConnection conn)` Triggered when no input is detected on this connection over the maximum period of inactivity.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### HttpAsyncService

    public HttpAsyncService(HttpProcessor httpProcessor,
                            ConnectionReuseStrategy connStrategy,
                            HttpResponseFactory responseFactory,
                            HttpAsyncRequestHandlerResolver handlerResolver,
                            HttpAsyncExpectationVerifier expectationVerifier,
                            HttpParams params)

  Creates an instance of `HttpAsyncServerProtocolHandler`.

  Parameters:
    `httpProcessor` - HTTP protocol processor (required).
    `connStrategy` - Connection re-use strategy (required).
    `responseFactory` - HTTP response factory (required).
    `handlerResolver` - Request handler resolver.
    `expectationVerifier` - Request expectation verifier (optional).
    `params` - HTTP parameters (required).

### HttpAsyncService

    public HttpAsyncService(HttpProcessor httpProcessor,
                            ConnectionReuseStrategy connStrategy,
                            HttpAsyncRequestHandlerResolver handlerResolver,
                            HttpParams params)

  Creates an instance of `HttpAsyncServerProtocolHandler`.

  Parameters:
    `httpProcessor` - HTTP protocol processor (required).
    `connStrategy` - Connection re-use strategy (required).
    `handlerResolver` - Request handler resolver.
    `params` - HTTP parameters (required).

Method Detail

### connected

    public void connected(NHttpServerConnection conn)

  Description copied from interface: `NHttpServerEventHandler`
  Triggered when a new incoming connection is created.

  Specified by:
    `connected` in interface `NHttpServerEventHandler`
  Parameters:
    `conn` - new incoming connection HTTP connection.

### closed

    public void closed(NHttpServerConnection conn)

  Description copied from interface: `NHttpServerEventHandler`
  Triggered when the connection is closed.

  Specified by:
    `closed` in interface `NHttpServerEventHandler`
  Parameters:
    `conn` - closed HTTP connection.

### exception

    public void exception(NHttpServerConnection conn,
                          Exception cause)

  Description copied from interface: `NHttpServerEventHandler`
  Triggered if an error occurs during the HTTP exchange.

  Specified by:
    `exception` in interface `NHttpServerEventHandler`
  Parameters:
    `conn` - HTTP connection that caused an I/O error
    `cause` - exception

### requestReceived

    public void requestReceived(NHttpServerConnection conn)
                         throws IOException,
                                HttpException

  Description copied from interface: `NHttpServerEventHandler`
  Triggered when a new HTTP request is received. The connection passed as a parameter to this method is guaranteed to return a valid HTTP request object.

  If the request received encloses a request entity this method will be followed a series of `NHttpServerEventHandler.inputReady(NHttpServerConnection, ContentDecoder)` calls to transfer the request content.

  Specified by:
    `requestReceived` in interface `NHttpServerEventHandler`
  Parameters:
    `conn` - HTTP connection that contains a new HTTP request
  Throws:
    `IOException`
    `HttpException`
  See Also:
    `NHttpServerConnection`

### inputReady

    public void inputReady(NHttpServerConnection conn,
                           ContentDecoder decoder)
                    throws IOException,
                           HttpException

  Description copied from interface: `NHttpServerEventHandler`
  Triggered when the underlying channel is ready for reading a new portion of the request entity through the corresponding content decoder.

  If the content consumer is unable to process incoming content, input event notifications can be temporarily suspended using `IOControl` interface (super interface of `NHttpServerConnection`).

  Please note that the `NHttpServerConnection` and `ContentDecoder` objects are not thread-safe and should only be used within the context of this method call. The `IOControl` object can be shared and used on other thread to resume input event notifications when the handler is capable of processing more content.

  Specified by:
    `inputReady` in interface `NHttpServerEventHandler`
  Parameters:
    `conn` - HTTP connection that can produce a new portion of the incoming request content.
    `decoder` - The content decoder to use to read content.
  Throws:
    `IOException`
    `HttpException`
  See Also:
    `NHttpServerConnection`, `ContentDecoder`, `IOControl`

### responseReady

    public void responseReady(NHttpServerConnection conn)
                       throws IOException,
                              HttpException

  Description copied from interface: `NHttpServerEventHandler`
  Triggered when the connection is ready to accept a new HTTP response. The protocol handler does not have to submit a response if it is not ready.

  Specified by:
    `responseReady` in interface `NHttpServerEventHandler`
  Parameters:
    `conn` - HTTP connection that contains an HTTP response
  Throws:
    `IOException`
    `HttpException`
  See Also:
    `NHttpServerConnection`

### outputReady

    public void outputReady(NHttpServerConnection conn,
                            ContentEncoder encoder)
                     throws IOException

  Description copied from interface: `NHttpServerEventHandler`
  Triggered when the underlying channel is ready for writing a next portion of the response entity through the corresponding content encoder.

  If the content producer is unable to generate outgoing content, output event notifications can be temporarily suspended using `IOControl` interface (super interface of `NHttpServerConnection`).

  Please note that the `NHttpServerConnection` and `ContentEncoder` objects are not thread-safe and should only be used within the context of this method call. The `IOControl` object can be shared and used on other thread to resume output event notifications when more content is made available.

  Specified by:
    `outputReady` in interface `NHttpServerEventHandler`
  Parameters:
    `conn` - HTTP connection that can accommodate a new portion of the outgoing response content.
    `encoder` - The content encoder to use to write content.
  Throws:
    `IOException`
  See Also:
    `NHttpServerConnection`, `ContentEncoder`, `IOControl`

### endOfInput

    public void endOfInput(NHttpServerConnection conn)
                    throws IOException

  Description copied from interface: `NHttpServerEventHandler`
  Triggered when the connection is closed by the opposite end point (half-closed).

  Specified by:
    `endOfInput` in interface `NHttpServerEventHandler`
  Parameters:
    `conn` - half-closed HTTP connection.
  Throws:
    `IOException`

### timeout

    public void timeout(NHttpServerConnection conn)
                 throws IOException

  Description copied from interface: `NHttpServerEventHandler`
  Triggered when no input is detected on this connection over the maximum period of inactivity.

  Specified by:
    `timeout` in interface `NHttpServerEventHandler`
  Parameters:
    `conn` - HTTP connection that caused timeout condition.
  Throws:
    `IOException`

### log

    protected void log(Exception ex)

  This method can be used to log I/O exception thrown while closing `Closeable` objects (such as `HttpConnection`).

  Parameters:
    `ex` - I/O exception thrown by `Closeable.close()`

### handleException

    protected HttpAsyncResponseProducer handleException(Exception ex,
                                                        HttpContext context)

Copyright © 2005-2013 The Apache Software Foundation. All Rights Reserved.