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 `HttpAsyncRequestHandlerMapper` is used to map the request 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.

Since:
  4.2

### Constructor Summary

Constructors
Constructor and Description
`HttpAsyncService(HttpProcessor httpProcessor, ConnectionReuseStrategy connStrategy, HttpAsyncRequestHandlerResolver handlerResolver, HttpParams params)` Deprecated. (4.3) use `HttpAsyncService(HttpProcessor, ConnectionReuseStrategy, HttpResponseFactory, HttpAsyncRequestHandlerMapper, HttpAsyncExpectationVerifier)`
`HttpAsyncService(HttpProcessor httpProcessor, ConnectionReuseStrategy connStrategy, HttpResponseFactory responseFactory, HttpAsyncRequestHandlerMapper handlerMapper, HttpAsyncExpectationVerifier expectationVerifier)` Creates new instance of `HttpAsyncServerProtocolHandler`.

`HttpAsyncService(HttpProcessor httpProcessor, ConnectionReuseStrategy connStrategy, HttpResponseFactory responseFactory, HttpAsyncRequestHandlerResolver handlerResolver, HttpAsyncExpectationVerifier expectationVerifier, HttpParams params)`
Deprecated.
(4.3) use `HttpAsyncService(HttpProcessor, ConnectionReuseStrategy, HttpResponseFactory, HttpAsyncRequestHandlerMapper, HttpAsyncExpectationVerifier)`

`HttpAsyncService(HttpProcessor httpProcessor, HttpAsyncRequestHandlerMapper handlerMapper)` Creates new instance of `HttpAsyncServerProtocolHandler`.

### Method Summary

Methods
`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

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

Deprecated. (4.3) use `HttpAsyncService(HttpProcessor, ConnectionReuseStrategy, HttpResponseFactory, HttpAsyncRequestHandlerMapper, HttpAsyncExpectationVerifier)`
Creates new 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

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

Deprecated. (4.3) use `HttpAsyncService(HttpProcessor, ConnectionReuseStrategy, HttpResponseFactory, HttpAsyncRequestHandlerMapper, HttpAsyncExpectationVerifier)`
Creates new instance of `HttpAsyncServerProtocolHandler`.

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

#### HttpAsyncService

    public HttpAsyncService(HttpProcessor httpProcessor,
                    ConnectionReuseStrategy connStrategy,
                    HttpResponseFactory responseFactory,
                    HttpAsyncRequestHandlerMapper handlerMapper,
                    HttpAsyncExpectationVerifier expectationVerifier)

Creates new instance of `HttpAsyncServerProtocolHandler`.

Parameters:
  `httpProcessor` - HTTP protocol processor.
  `connStrategy` - Connection re-use strategy. If `null` `DefaultConnectionReuseStrategy.INSTANCE` will be used.
  `responseFactory` - HTTP response factory. If `null` `DefaultHttpResponseFactory.INSTANCE` will be used.
  `handlerMapper` - Request handler mapper.
  `expectationVerifier` - Request expectation verifier. May be `null`.
Since:
  4.3

#### HttpAsyncService

    public HttpAsyncService(HttpProcessor httpProcessor,
                    HttpAsyncRequestHandlerMapper handlerMapper)

Creates new instance of `HttpAsyncServerProtocolHandler`.

Parameters:
  `httpProcessor` - HTTP protocol processor.
  `handlerMapper` - Request handler mapper.
Since:
  4.3

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