Package org.asynchttpclient

Interface AsyncHandler<T>

Type Parameters:

T - Type of object returned by the Future.get()

All Known Subinterfaces:

ProgressAsyncHandler<T>

All Known Implementing Classes:

AsyncCompletionHandler, AsyncCompletionHandlerBase, BodyDeferringAsyncHandler, ResumableAsyncHandler, TransferCompletionHandler, WebSocketUpgradeHandler

public interface AsyncHandler<T>

An asynchronous handler or callback which gets invoked as soon as some data is available when processing an asynchronous response.
Callback methods get invoked in the following order:

1. onStatusReceived(HttpResponseStatus),
2. onHeadersReceived(HttpHeaders),
3. onBodyPartReceived(HttpResponseBodyPart), which could be invoked multiple times,
4. onTrailingHeadersReceived(HttpHeaders), which is only invoked if trailing HTTP headers are received
5. onCompleted(), once the response has been fully read.

Returning a AsyncHandler.State.ABORT from any of those callback methods will interrupt asynchronous response processing. After that, only onCompleted() is going to be called.
AsyncHandlers aren't thread safe. Hence, you should avoid re-using the same instance when doing concurrent requests. As an example, the following may produce unexpected results:

   AsyncHandler ah = new AsyncHandler() {....};
   AsyncHttpClient client = new AsyncHttpClient();
   client.prepareGet("http://...").execute(ah);
   client.prepareGet("http://...").execute(ah);
 

It is recommended to create a new instance instead.

Do NOT perform any blocking operations in any of these methods. A typical example would be trying to send another request and calling get() on its future. There's a chance you might end up in a deadlock. If you really need to perform a blocking operation, execute it in a different dedicated thread pool.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	AsyncHandler.State

Method Summary

Modifier and Type	Method	Description
AsyncHandler.State	onBodyPartReceived(HttpResponseBodyPart bodyPart)	Invoked as soon as some response body part are received.
T	onCompleted()	Invoked once the HTTP response processing is finished.
default void	onConnectionOffer(io.netty.channel.Channel connection)	Notify the callback when trying to offer a connection to the pool.
default void	onConnectionPoolAttempt()	Notify the callback when trying to fetch a connection from the pool.
default void	onConnectionPooled(io.netty.channel.Channel connection)	Notify the callback when a new connection was successfully fetched from the pool.
AsyncHandler.State	onHeadersReceived(io.netty.handler.codec.http.HttpHeaders headers)	Invoked as soon as the HTTP headers have been received.
default void	onHostnameResolutionAttempt(String name)	Notify the callback before hostname resolution
default void	onHostnameResolutionFailure(String name, Throwable cause)	Notify the callback after hostname resolution failed.
default void	onHostnameResolutionSuccess(String name, List<InetSocketAddress> addresses)	Notify the callback after hostname resolution was successful.
default void	onRequestSend(NettyRequest request)	Notify the callback when a request is being written on the channel.
default void	onRetry()	Notify the callback every time a request is being retried.
AsyncHandler.State	onStatusReceived(HttpResponseStatus responseStatus)	Invoked as soon as the HTTP status line has been received
default void	onTcpConnectAttempt(InetSocketAddress remoteAddress)	Notify the callback when trying to open a new connection.
default void	onTcpConnectFailure(InetSocketAddress remoteAddress, Throwable cause)	Notify the callback after a failed connect.
default void	onTcpConnectSuccess(InetSocketAddress remoteAddress, io.netty.channel.Channel connection)	Notify the callback after a successful connect
void	onThrowable(Throwable t)	Invoked when an unexpected exception occurs during the processing of the response.
default void	onTlsHandshakeAttempt()	Notify the callback before TLS handshake
default void	onTlsHandshakeFailure(Throwable cause)	Notify the callback after the TLS failed
default void	onTlsHandshakeSuccess(SSLSession sslSession)	Notify the callback after the TLS was successful
default AsyncHandler.State	onTrailingHeadersReceived(io.netty.handler.codec.http.HttpHeaders headers)	Invoked when trailing headers have been received.

Method Detail

onStatusReceived

AsyncHandler.State onStatusReceived(HttpResponseStatus responseStatus)
                             throws Exception

Invoked as soon as the HTTP status line has been received

Parameters:

responseStatus - the status code and test of the response

Returns:

a AsyncHandler.State telling to CONTINUE or ABORT the current processing.

Throws:

Exception - if something wrong happens

onHeadersReceived

AsyncHandler.State onHeadersReceived(io.netty.handler.codec.http.HttpHeaders headers)
                              throws Exception

Invoked as soon as the HTTP headers have been received.

Parameters:

headers - the HTTP headers.

Returns:

a AsyncHandler.State telling to CONTINUE or ABORT the current processing.

Throws:

Exception - if something wrong happens

onBodyPartReceived

AsyncHandler.State onBodyPartReceived(HttpResponseBodyPart bodyPart)
                               throws Exception

Invoked as soon as some response body part are received. Could be invoked many times. Beware that, depending on the provider (Netty) this can be notified with empty body parts.

Parameters:

bodyPart - response's body part.

Returns:

a AsyncHandler.State telling to CONTINUE or ABORT the current processing. Aborting will also close the connection.

Throws:

Exception - if something wrong happens

onTrailingHeadersReceived

default AsyncHandler.State onTrailingHeadersReceived(io.netty.handler.codec.http.HttpHeaders headers)
                                              throws Exception

Invoked when trailing headers have been received.

Parameters:

headers - the trailing HTTP headers.

Returns:

a AsyncHandler.State telling to CONTINUE or ABORT the current processing.

Throws:

Exception - if something wrong happens

onThrowable

void onThrowable(Throwable t)

Invoked when an unexpected exception occurs during the processing of the response. The exception may have been produced by implementation of onXXXReceived method invocation.

Parameters:

t - a Throwable

onCompleted

@Nullable
T onCompleted()
       throws Exception

Invoked once the HTTP response processing is finished.
Gets always invoked as last callback method.

Returns:

T Value that will be returned by the associated Future

Throws:

Exception - if something wrong happens

onHostnameResolutionAttempt

default void onHostnameResolutionAttempt(String name)

Notify the callback before hostname resolution

Parameters:

name - the name to be resolved

onHostnameResolutionSuccess

default void onHostnameResolutionSuccess(String name,
                                         List<InetSocketAddress> addresses)

Notify the callback after hostname resolution was successful.

Parameters:

name - the name to be resolved

addresses - the resolved addresses

onHostnameResolutionFailure

default void onHostnameResolutionFailure(String name,
                                         Throwable cause)

Notify the callback after hostname resolution failed.

Parameters:

name - the name to be resolved

cause - the failure cause

onTcpConnectAttempt

default void onTcpConnectAttempt(InetSocketAddress remoteAddress)

Notify the callback when trying to open a new connection.

Might be called several times if the name was resolved to multiple addresses, and we failed to connect to the first(s) one(s).

Parameters:

remoteAddress - the address we try to connect to

onTcpConnectSuccess

default void onTcpConnectSuccess(InetSocketAddress remoteAddress,
                                 io.netty.channel.Channel connection)

Notify the callback after a successful connect

Parameters:

remoteAddress - the address we try to connect to

connection - the connection

onTcpConnectFailure

default void onTcpConnectFailure(InetSocketAddress remoteAddress,
                                 Throwable cause)

Notify the callback after a failed connect.

Might be called several times, or be followed by onTcpConnectSuccess when the name was resolved to multiple addresses.

Parameters:

remoteAddress - the address we try to connect to

cause - the cause of the failure

onTlsHandshakeAttempt

default void onTlsHandshakeAttempt()

Notify the callback before TLS handshake

onTlsHandshakeSuccess

default void onTlsHandshakeSuccess(SSLSession sslSession)

Notify the callback after the TLS was successful

onTlsHandshakeFailure

default void onTlsHandshakeFailure(Throwable cause)

Notify the callback after the TLS failed

Parameters:

cause - the cause of the failure

onConnectionPoolAttempt

default void onConnectionPoolAttempt()

Notify the callback when trying to fetch a connection from the pool.

onConnectionPooled

default void onConnectionPooled(io.netty.channel.Channel connection)

Notify the callback when a new connection was successfully fetched from the pool.

Parameters:

connection - the connection

onConnectionOffer

default void onConnectionOffer(io.netty.channel.Channel connection)

Notify the callback when trying to offer a connection to the pool.

Parameters:

connection - the connection

onRequestSend

default void onRequestSend(NettyRequest request)

Notify the callback when a request is being written on the channel. If the original request causes multiple requests to be sent, for example, because of authorization or retry, it will be notified multiple times.

Parameters:

request - the real request object as passed to the provider

onRetry

default void onRetry()

Notify the callback every time a request is being retried.