org.apache.http.nio.protocol
Class HttpAsyncService

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

All Implemented Interfaces:

NHttpServerEventHandler

@Contract(threading=IMMUTABLE_CONDITIONAL)
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 HttpAsyncRequestHandlers are expected to implement application specific content generation and processing.

Individual HttpAsyncRequestHandlers 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

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, HttpAsyncRequestHandlerMapper handlerMapper, HttpAsyncExpectationVerifier expectationVerifier, ExceptionLogger exceptionLogger)
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.

HttpAsyncService(HttpProcessor httpProcessor, HttpAsyncRequestHandlerMapper handlerMapper, ExceptionLogger exceptionLogger)
Creates new 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.
protected HttpResponse	createHttpResponse(int status, HttpContext context)
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.
ConnectionReuseStrategy	getConnectionStrategy() Gets the ConnectionReuseStrategy for this service.
ExceptionLogger	getExceptionLogger() Gets the ExceptionLogger for this service.
HttpAsyncExpectationVerifier	getExpectationVerifier() Gets the HttpAsyncExpectationVerifier for this service.
HttpAsyncRequestHandlerMapper	getHandlerMapper() Gets the HttpAsyncRequestHandlerMapper for this service.
HttpProcessor	getHttpProcessor() Gets the HttpProcessor for this service.
HttpResponseFactory	getResponseFactory() Gets the HttpResponseFactory for this service.
protected void	handleAlreadySubmittedResponse(Cancellable cancellable, HttpContext context) This method can be used to handle callback set up happened after response submission.
protected void	handleAlreadySubmittedResponse(HttpAsyncResponseProducer responseProducer, HttpContext context) This method can be used to handle double response submission.
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.
protected int	toStatusCode(Exception ex, HttpContext context)

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,
                        ConnectionReuseStrategy connStrategy,
                        HttpResponseFactory responseFactory,
                        HttpAsyncRequestHandlerMapper handlerMapper,
                        HttpAsyncExpectationVerifier expectationVerifier,
                        ExceptionLogger exceptionLogger)

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.

exceptionLogger - Exception logger. If null ExceptionLogger.NO_OP will be used. Please note that the exception logger will be only used to log I/O exception thrown while closing Closeable objects (such as HttpConnection).

Since:

4.4

HttpAsyncService

public HttpAsyncService(HttpProcessor httpProcessor,
                        HttpAsyncRequestHandlerMapper handlerMapper)

Creates new instance of HttpAsyncServerProtocolHandler.

Parameters:

httpProcessor - HTTP protocol processor.

handlerMapper - Request handler mapper.

Since:

4.3

HttpAsyncService

public HttpAsyncService(HttpProcessor httpProcessor,
                        HttpAsyncRequestHandlerMapper handlerMapper,
                        ExceptionLogger exceptionLogger)

Creates new instance of HttpAsyncServerProtocolHandler.

Parameters:

httpProcessor - HTTP protocol processor.

handlerMapper - Request handler mapper.

exceptionLogger - Exception logger. If null ExceptionLogger.NO_OP will be used. Please note that the exception logger will be only used to log I/O exception thrown while closing Closeable objects (such as HttpConnection).

Since:

4.4

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

createHttpResponse

protected HttpResponse createHttpResponse(int status,
                                          HttpContext context)

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 HttpException,
                        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:

HttpException

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)

toStatusCode

protected int toStatusCode(Exception ex,
                           HttpContext context)

handleAlreadySubmittedResponse

protected void handleAlreadySubmittedResponse(Cancellable cancellable,
                                              HttpContext context)

This method can be used to handle callback set up happened after response submission.

Parameters:

cancellable - Request cancellation callback.

context - Request context.

Since:

4.4

handleAlreadySubmittedResponse

protected void handleAlreadySubmittedResponse(HttpAsyncResponseProducer responseProducer,
                                              HttpContext context)

This method can be used to handle double response submission.

Parameters:

responseProducer - Response producer for second response.

context - Request context.

Since:

4.4

getResponseFactory

public HttpResponseFactory getResponseFactory()

Gets the HttpResponseFactory for this service.

Returns:

the HttpResponseFactory for this service.

Since:

4.4.8

getHttpProcessor

public HttpProcessor getHttpProcessor()

Gets the HttpProcessor for this service.

Returns:

the HttpProcessor for this service.

Since:

4.4.9

getConnectionStrategy

public ConnectionReuseStrategy getConnectionStrategy()

Gets the ConnectionReuseStrategy for this service.

Returns:

the ConnectionReuseStrategy for this service.

Since:

4.4.9

getHandlerMapper

public HttpAsyncRequestHandlerMapper getHandlerMapper()

Gets the HttpAsyncRequestHandlerMapper for this service.

Returns:

the HttpAsyncRequestHandlerMapper for this service.

Since:

4.4.9

getExpectationVerifier

public HttpAsyncExpectationVerifier getExpectationVerifier()

Gets the HttpAsyncExpectationVerifier for this service.

Returns:

the HttpAsyncExpectationVerifier for this service.

Since:

4.4.9

getExceptionLogger

public ExceptionLogger getExceptionLogger()

Gets the ExceptionLogger for this service.

Returns:

the ExceptionLogger for this service.

Since:

4.4.9