Contrary to the popular belief, the performance of NIO in terms of raw data throughput is significantly lower than that of blocking I/O. NIO does not necessarily fit all use cases and should be used only where appropriate:
handling of thousands of connections, a significant number of which can be idle.
handling high latency connections.
request / response handling needs to be decoupled.
Solves similar problems as other frameworks, but has certain distinct features:
minimalistic, optimized for data volume intensive protocols such as HTTP.
efficient memory management: data consumer can read only as much input data as it can process without having to allocate more memory.
direct access to the NIO channels where possible.
HttpCore NIO is based on the Reactor pattern as described by Doug Lea. The purpose of I/O
reactors is to react to I/O events and to dispatch event notifications to individual I/O
sessions. The main idea of I/O reactor pattern is to break away from the one thread per
connection model imposed by the classic blocking I/O model. The IOReactor
interface represents an abstract object which implements the Reactor pattern.
Internally, IOReactor
implementations encapsulate
functionality of the NIO java.nio.channels.Selector
.
I/O reactors usually employ a small number of dispatch threads (often as few as one) to dispatch I/O event notifications to a much greater number (often as many as several thousands) of I/O sessions or connections. It is generally recommended to have one dispatch thread per CPU core.
HttpParams params = new BasicHttpParams(); int workerCount = 2; IOReactor ioreactor = new DefaultConnectingIOReactor(workerCount, params);
IOReactor
implementations make use of the
IOEventDispatch
interface to notify clients of events
pending for a particular session. All methods of the IOEventDispatch
are executed on a dispatch thread of the I/O reactor. Therefore, it is
important that processing that takes place in the event methods will not block the
dispatch thread for too long, as the I/O reactor will be unable to react to other
events.
HttpParams params = new BasicHttpParams(); IOReactor ioreactor = new DefaultConnectingIOReactor(2, params); IOEventDispatch eventDispatch = new MyIOEventDispatch(); ioreactor.execute(eventDispatch);
Generic I/O events as defined by the IOEventDispatch
interface:
connected
:
Triggered when a new session has been created.
inputReady
:
Triggered when the session has pending input.
outputReady
:
Triggered when the session is ready for output.
timeout
:
Triggered when the session has timed out.
disconnected
:
Triggered when the session has been terminated.
The shutdown of I/O reactors is a complex process and may usually take a while to complete. I/O reactors will attempt to gracefully terminate all active I/O sessions and dispatch threads approximately within the specified grace period. If any of the I/O sessions fails to terminate correctly, the I/O reactor will forcibly shut down remaining sessions.
long gracePeriod = 3000L; // milliseconds ioreactor.shutdown(gracePeriod);
The IOReactor#shutdown(long)
method is safe to call from any
thread.
The IOSession
interface represents a sequence of
logically related data exchanges between two end points. IOSession
encapsulates functionality of NIO
java.nio.channels.SelectionKey
and
java.nio.channels.SocketChannel
. The channel associated with the
IOSession
can be used to read data from and write data
to the session.
IOSession iosession; ReadableByteChannel ch = (ReadableByteChannel) iosession.channel(); ByteBuffer dst = ByteBuffer.allocate(2048); ch.read(dst);
I/O sessions are not bound to an execution thread, therefore one cannot use the context of the thread to store a session's state. All details about a particular session must be stored within the session itself.
IOSession iosession; Object someState; iosession.setAttribute("state", someState); Object currentState = iosession.getAttribute("state");
Please note that if several sessions make use of shared objects, access to those objects must be made thread-safe.
One can declare an interest in a particular type of I/O events for a particular I/O session by setting its event mask.
IOSession iosession; iosession.setEventMask(SelectionKey.OP_READ | SelectionKey.OP_WRITE);
One can also toggle OP_READ
and OP_WRITE
flags
individually.
iosession.setEvent(SelectionKey.OP_READ); iosession.clearEvent(SelectionKey.OP_READ);
Event notifications will not take place if the corresponding interest flag is not set.
Quite often I/O sessions need to maintain internal I/O buffers in order to transform
input / output data prior to returning it to the consumer or writing it to the
underlying channel. Memory management in HttpCore NIO is based on the fundamental
principle that the data consumer can read only as much input data as it can process
without having to allocate more memory. That means, quite often some input data may
remain unread in one of the internal or external session buffers. The I/O reactor can
query the status of these session buffers, and make sure the consumer gets notified
correctly as more data gets stored in one of the session buffers, thus allowing the
consumer to read the remaining data once it is able to process it. I/O sessions can be
made aware of the status of external session buffers using the
SessionBufferStatus
interface.
IOSession iosession; SessionBufferStatus myBufferStatus = new MySessionBufferStatus(); iosession.setBufferStatus(myBufferStatus); iosession.hasBufferedInput(); iosession.hasBufferedOutput();
One can close an I/O session gracefully by calling IOSession#close()
allowing the session to be closed in an orderly manner or by calling
IOSession#shutdown()
to forcibly close the underlying channel.
The distinction between two methods is of primary importance for those types of I/O
sessions that involve some sort of a session termination handshake such as SSL/TLS
connections.
ListeningIOReactor
represents an I/O reactor capable of
listening for incoming connections on one or several ports.
ListeningIOReactor ioreactor; ListenerEndpoint ep1 = ioreactor.listen(new InetSocketAddress(8081)); ListenerEndpoint ep2 = ioreactor.listen(new InetSocketAddress(8082)); ListenerEndpoint ep3 = ioreactor.listen(new InetSocketAddress(8083)); // Wait until all endpoints are up ep1.waitFor(); ep2.waitFor(); ep3.waitFor();
Once an endpoint is fully initialized it starts accepting incoming connections and
propagates I/O activity notifications to the IOEventDispatch
instance.
One can obtain a set of registered endpoints at runtime, query the status of an endpoint at runtime, and close it if desired.
ListeningIOReactor ioreactor; Set<ListenerEndpoint> eps = ioreactor.getEndpoints(); for (ListenerEndpoint ep: eps) { // Still active? System.out.println(ep.getAddress()); if (ep.isClosed()) { // If not, has it terminated due to an exception? if (ep.getException() != null) { ep.getException().printStackTrace(); } } else { ep.close(); } }
ConnectingIOReactor
represents an I/O reactor capable of
establishing connections with remote hosts.
ConnectingIOReactor ioreactor; SessionRequest sessionRequest = ioreactor.connect( new InetSocketAddress("www.google.com", 80), null, null, null);
Opening a connection to a remote host usually tends to be a time consuming process and
may take a while to complete. One can monitor and control the process of session
initialization by means of the SessionRequest
interface.
// Make sure the request times out if connection // has not been established after 1 sec sessionRequest.setConnectTimeout(1000); // Wait for the request to complete sessionRequest.waitFor(); // Has request terminated due to an exception? if (sessionRequest.getException() != null) { sessionRequest.getException().printStackTrace(); } // Get hold of the new I/O session IOSession iosession = sessionRequest.getSession();
SessionRequest
implementations are expected to be
thread-safe. Session request can be aborted at any time by calling
IOSession#cancel()
from another thread of execution.
if (!sessionRequest.isCompleted()) { sessionRequest.cancel(); }
One can pass several optional parameters to the
ConnectingIOReactor#connect()
method to exert a greater control over the
process of session initialization.
A non-null local socket address parameter can be used to bind the socket to a specific local address.
ConnectingIOReactor ioreactor; SessionRequest sessionRequest = ioreactor.connect( new InetSocketAddress("www.google.com", 80), new InetSocketAddress("192.168.0.10", 1234), null, null);
One can provide an attachment object, which will be added to the new session's context upon initialization. This object can be used to pass an initial processing state to the protocol handler.
SessionRequest sessionRequest = ioreactor.connect( new InetSocketAddress("www.google.com", 80), null, new HttpHost("www.google.ru"), null); IOSession iosession = sessionRequest.getSession(); HttpHost virtualHost = (HttpHost) iosession.getAttribute( IOSession.ATTACHMENT_KEY);
It is often desirable to be able to react to the completion of a session request
asynchronously without having to wait for it, blocking the current thread of execution.
One can optionally provide an implementation SessionRequestCallback
interface to get notified of events related to session requests, such
as request completion, cancellation, failure or timeout.
ConnectingIOReactor ioreactor; SessionRequest sessionRequest = ioreactor.connect( new InetSocketAddress("www.google.com", 80), null, null, new SessionRequestCallback() { public void cancelled(SessionRequest request) { } public void completed(SessionRequest request) { System.out.println("new connection to " + request.getRemoteAddress()); } public void failed(SessionRequest request) { if (request.getException() != null) { request.getException().printStackTrace(); } } public void timeout(SessionRequest request) { } });
Several older JRE implementations (primarily from IBM) include what Java API
documentation refers to as a naive implementation of the
java.nio.channels.SelectionKey
class. The problem with
java.nio.channels.SelectionKey
in such JREs is that reading or writing
of the I/O interest set may block indefinitely if the I/O selector is in the process
of executing a select operation. HttpCore NIO can be configured to operate in a special
mode wherein I/O interest set operations are queued and executed by on the dispatch
thread only when the I/O selector is not engaged in a select operation.
HttpParams params = new BasicHttpParams(); NIOReactorParams.setInterestOpsQueueing(params, true); ListeningIOReactor ioreactor = new DefaultListeningIOReactor(2, params);
Protocol specific exceptions as well as those I/O exceptions thrown in the course of interaction with the session's channel are to be expected and are to be dealt with by specific protocol handlers. These exceptions may result in termination of an individual session but should not affect the I/O reactor and all other active sessions. There are situations, however, when the I/O reactor itself encounters an internal problem such as an I/O exception in the underlying NIO classes or an unhandled runtime exception. Those types of exceptions are usually fatal and will cause the I/O reactor to shut down automatically.
There is a possibility to override this behaviour and prevent I/O reactors from shutting
down automatically in case of a runtime exception or an I/O exception in internal classes.
This can be accomplished by providing a custom implementation of the
IOReactorExceptionHandler
interface.
DefaultConnectingIOReactor ioreactor; ioreactor.setExceptionHandler(new IOReactorExceptionHandler() { public boolean handle(IOException ex) { if (ex instanceof BindException) { // bind failures considered OK to ignore return true; } return false; } public boolean handle(RuntimeException ex) { if (ex instanceof UnsupportedOperationException) { // Unsupported operations considered OK to ignore return true; } return false; } });
One needs to be very careful about discarding exceptions indiscriminately. It is often much better to let the I/O reactor shut down itself cleanly and restart it rather than leaving it in an inconsistent or unstable state.
If an I/O reactor is unable to automatically recover from an I/O or a runtime exception it will enter the shutdown mode. First off, it will close all active listeners and cancel all pending new session requests. Then it will attempt to close all active I/O sessions gracefully giving them some time to flush pending output data and terminate cleanly. Lastly, it will forcibly shut down those I/O sessions that still remain active after the grace period. This is a fairly complex process, where many things can fail at the same time and many different exceptions can be thrown in the course of the shutdown process. The I/O reactor will record all exceptions thrown during the shutdown process, including the original one that actually caused the shutdown in the first place, in an audit log. One can examine the audit log and decide whether it is safe to restart the I/O reactor.
DefaultConnectingIOReactor ioreactor; // Give it 5 sec grace period ioreactor.shutdown(5000); List<ExceptionEvent> events = ioreactor.getAuditLog(); for (ExceptionEvent event: events) { System.err.println("Time: " + event.getTimestamp()); event.getCause().printStackTrace(); }
Effectively non-blocking HTTP connections are wrappers around IOSession
with HTTP specific functionality. Non-blocking HTTP connections are
stateful and not thread-safe. Input / output operations on non-blocking HTTP connections
should be restricted to the dispatch events triggered by the I/O event dispatch thread.
Non-blocking HTTP connections are not bound to a particular thread of execution and
therefore they need to maintain their own execution context. Each non-blocking HTTP
connection has an HttpContext
instance associated with
it, which can be used to maintain a processing state. The HttpContext
instance is thread-safe and can be manipulated from multiple threads.
// Get non-blocking HTTP connection DefaultNHttpClientConnection conn; // State Object myStateObject; HttpContext context = conn.getContext(); context.setAttribute("state", myStateObject);
At any point of time one can obtain the request and response objects currently being transferred over the non-blocking HTTP connection. Any of these objects, or both, can be null if there is no incoming or outgoing message currently being transferred.
NHttpConnection conn; HttpRequest request = conn.getHttpRequest(); if (request != null) { System.out.println("Transferring request: " + request.getRequestLine()); } HttpResponse response = conn.getHttpResponse(); if (response != null) { System.out.println("Transferring response: " + response.getStatusLine()); }
However, please note that the current request and the current response may not necessarily represent the same message exchange! Non-blocking HTTP connections can operate in a full duplex mode. One can process incoming and outgoing messages completely independently from one another. This makes non-blocking HTTP connections fully pipelining capable, but at same time implies that this is the job of the protocol handler to match logically related request and the response messages.
Over-simplified process of submitting a request on the client side may look like this:
// Obtain HTTP connection NHttpClientConnection conn; // Obtain execution context HttpContext context = conn.getContext(); // Obtain processing state Object state = context.getAttribute("state"); // Generate a request based on the state information HttpRequest request = new BasicHttpRequest("GET", "/"); conn.submitRequest(request); System.out.println(conn.isRequestSubmitted());
Over-simplified process of submitting a response on the server side may look like this:
// Obtain HTTP connection NHttpServerConnection conn; // Obtain execution context HttpContext context = conn.getContext(); // Obtain processing state Object state = context.getAttribute("state"); // Generate a response based on the state information HttpResponse response = new BasicHttpResponse(HttpVersion.HTTP_1_1, HttpStatus.SC_OK, "OK"); BasicHttpEntity entity = new BasicHttpEntity(); entity.setContentType("text/plain"); entity.setChunked(true); response.setEntity(entity); conn.submitResponse(response); System.out.println(conn.isResponseSubmitted());
Please note that one should rarely need to transmit messages using these low level methods and should use appropriate higher level HTTP service implementations instead.
All non-blocking HTTP connections classes implement IOControl
interface, which represents a subset of connection functionality for
controlling interest in I/O even notifications. IOControl
instances are expected to be fully thread-safe. Therefore
IOControl
can be used to request / suspend I/O event
notifications from any thread.
One must take special precautions when interacting with non-blocking connections.
HttpRequest
and HttpResponse
are not thread-safe. It is generally advisable that all input / output
operations on a non-blocking connection are executed from the I/O event dispatch
thread.
The following pattern is recommended:
Use IOControl
interface to pass control over
connection's I/O events to another thread / session.
If input / output operations need be executed on that particular connection,
store all the required information (state) in the connection context and
request the appropriate I/O operation by calling
IOControl#requestInput()
or IOControl#requestOutput()
method.
Execute the required operations from the event method on the dispatch thread using information stored in connection context.
Please note all operations that take place in the event methods should not block for too long, because while the dispatch thread remains blocked in one session, it is unable to process events for all other sessions. I/O operations with the underlying channel of the session are not a problem as they are guaranteed to be non-blocking.
The process of content transfer for non-blocking connections works completely
differently compared to that of blocking connections, as non-blocking connections need
to accommodate to the asynchronous nature of the NIO model. The main distinction
between two types of connections is inability to use the usual, but inherently blocking
java.io.InputStream
and java.io.OutputStream
classes to represent streams of inbound and outbound content. HttpCore NIO
provides ContentEncoder
and
ContentDecoder
interfaces to handle the process of asynchronous content
transfer. Non-blocking HTTP connections will instantiate the appropriate implementation
of a content codec based on properties of the entity enclosed with the message.
Non-blocking HTTP connections will fire input events until the content entity is fully transferred.
//Obtain content decoder ContentDecoder decoder; //Read data in ByteBuffer dst = ByteBuffer.allocate(2048); decoder.read(dst); // Decode will be marked as complete when // the content entity is fully transferred if (decoder.isCompleted()) { // Done }
Non-blocking HTTP connections will fire output events until the content entity is marked as fully transferred.
// Obtain content encoder ContentEncoder encoder; // Prepare output data ByteBuffer src = ByteBuffer.allocate(2048); // Write data out encoder.write(src); // Mark content entity as fully transferred when done encoder.complete();
Please note, one still has to provide an HttpEntity instance when submitting an entity
enclosing message to the non-blocking HTTP connection. Properties of that entity will
be used to initialize an ContentEncoder
instance to be
used for transferring entity content. Non-blocking HTTP connections, however, ignore
inherently blocking HttpEntity#getContent()
and
HttpEntity#writeTo()
methods of the enclosed entities.
// Obtain HTTP connection NHttpServerConnection conn; HttpResponse response = new BasicHttpResponse(HttpVersion.HTTP_1_1, HttpStatus.SC_OK, "OK"); BasicHttpEntity entity = new BasicHttpEntity(); entity.setContentType("text/plain"); entity.setChunked(true); entity.setContent(null); response.setEntity(entity); conn.submitResponse(response);
Likewise, incoming entity enclosing message will have an HttpEntity
instance associated with them, but an attempt to call
HttpEntity#getContent()
or HttpEntity#writeTo()
methods will cause an java.lang.IllegalStateException
. The
HttpEntity
instance can be used to determine properties
of the incoming entity such as content length.
// Obtain HTTP connection NHttpClientConnection conn; HttpResponse response = conn.getHttpResponse(); HttpEntity entity = response.getEntity(); if (entity != null) { System.out.println(entity.getContentType()); System.out.println(entity.getContentLength()); System.out.println(entity.isChunked()); }
Default implementations of the non-blocking HTTP connection interfaces support three content transfer mechanisms defined by the HTTP/1.1 specification:
Content-Length
delimited:
The end of the content entity is determined by the value of the
Content-Length
header. Maximum entity length:
Long#MAX_VALUE
.
Identity coding: The end of the content entity is demarcated by closing the underlying connection (end of stream condition). For obvious reasons the identity encoding can only be used on the server side. Max entity length: unlimited.
Chunk coding: The content is sent in small chunks. Max entity length: unlimited.
The appropriate content codec will be created automatically depending on properties of the entity enclosed with the message.
Content codes are optimized to read data directly from or write data directly to the
underlying I/O session's channel, whenever possible avoiding intermediate buffering in
a session buffer. Moreover, those codecs that do not perform any content transformation
(Content-Length
delimited and identity codecs, for example) can
leverage NIO java.nio.FileChannel
methods for significantly
improved performance of file transfer operations both inbound and outbound.
If the actual content decoder implements FileContentDecoder
one can make use of its methods to read incoming content directly to a
file bypassing an intermediate java.nio.ByteBuffer
.
//Obtain content decoder ContentDecoder decoder; //Prepare file channel FileChannel dst; //Make use of direct file I/O if possible if (decoder instanceof FileContentDecoder) { long Bytesread = ((FileContentDecoder) decoder) .transfer(dst, 0, 2048); // Decode will be marked as complete when // the content entity is fully transmitted if (decoder.isCompleted()) { // Done } }
If the actual content encoder implements FileContentEncoder
one can make use of its methods to write outgoing content directly
from a file bypassing an intermediate java.nio.ByteBuffer
.
// Obtain content encoder ContentEncoder encoder; // Prepare file channel FileChannel src; // Make use of direct file I/O if possible if (encoder instanceof FileContentEncoder) { // Write data out long bytesWritten = ((FileContentEncoder) encoder) .transfer(src, 0, 2048); // Mark content entity as fully transferred when done encoder.complete(); }
HTTP I/O event dispatchers serve to convert generic I/O events triggered by an I/O reactor
to HTTP protocol specific events. They rely on NHttpClientHandler
and NHttpServiceHandler
interfaces to
propagate HTTP protocol events to a HTTP protocol handler.
Server side HTTP I/O events as defined by the NHttpServiceHandler
interface:
connected
:
Triggered when a new incoming connection has been created.
requestReceived
:
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
inputReady
events to transfer the request content.
inputReady
:
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 the incoming content, input event notifications can be temporarily suspended
using IOControl
interface.
responseReady
:
Triggered when the connection is ready to accept new HTTP response. The protocol
handler does not have to submit a response if it is not ready.
outputReady
:
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 the outgoing content, output event notifications can be temporarily
suspended using IOControl
interface.
exception
:
Triggered when an I/O error occurrs while reading from or writing to the underlying
channel or when an HTTP protocol violation occurs while receiving an HTTP request.
timeout
:
Triggered when no input is detected on this connection over the maximum period of
inactivity.
closed
:
Triggered when the connection has been closed.
Client side HTTP I/O events as defined by the NHttpClientHandler
interface:
connected
:
Triggered when a new outgoing connection has been created. The attachment object passed
as a parameter to this event is an arbitrary object that was attached to the session
request.
requestReady
:
Triggered when the connection is ready to accept new HTTP request. The protocol handler
does not have to submit a request if it is not ready.
outputReady
:
Triggered when the underlying channel is ready for writing a next portion of the
request entity through the corresponding content encoder. If the content producer is
unable to generate the outgoing content, output event notifications can be temporarily
suspended using IOControl
interface.
responseReceived
:
Triggered when an HTTP response is received. The connection passed as a parameter to
this method is guaranteed to return a valid HTTP response object. If the response
received encloses a response entity this method will be followed a series of
inputReady
events to transfer the response content.
inputReady
:
Triggered when the underlying channel is ready for reading a new portion of the
response entity through the corresponding content decoder. If the content consumer is
unable to process the incoming content, input event notifications can be temporarily
suspended using IOControl
interface.
exception
:
Triggered when an I/O error occurs while reading from or writing to the underlying
channel or when an HTTP protocol violation occurs while receiving an HTTP response..
timeout
:
Triggered when no input is detected on this connection over the maximum period of
inactivity.
closed
:
Triggered when the connection has been closed.
As discussed previously the process of content transfer for non-blocking connections works
completely differently compared to that for blocking connections. For obvious reasons
classic I/O abstraction based on inherently blocking java.io.InputStream
and java.io.OutputStream
classes is not applicable to
the asynchronous process of data transfer. Therefore, non-blocking HTTP entities provide
NIO specific extensions to the HttpEntity interface: ProducingNHttpEntity
and ConsumingNHttpEntity
interfaces.
Implementation classes of these interfaces may throw
java.lang.UnsupportedOperationException
from
HttpEntity#getContent()
or HttpEntity#writeTo()
if
a particular implementation is unable to represent its content stream as instance of
java.io.InputStream
or cannot stream its content out to an
java.io.OutputStream
.
ConsumingNHttpEntity
interface represents a non-blocking
entity that allows content to be consumed from a content decoder.
ConsumingNHttpEntity
extends the base HttpEntity
interface with a number of NIO specific notification methods:
consumeContent
:
Notification that content is available to be read from the decoder.
IOControl
instance passed as a parameter to the
method can be used to suspend input events if the entity is temporarily unable
to allocate more storage to accommodate all incoming content.
finish
:
Notification that any resources allocated for reading can be released.
The following implementations of ConsumingNHttpEntity
provided by HttpCore NIO:
BufferingNHttpEntity
is a subclass of
HttpEntityWrapper
that consumes all incoming content into memory. Once
the content body has been fully received it can be retrieved as an
java.io.InputStream
via HttpEntity#getContent()
, or written to an output stream via HttpEntity#writeTo()
.
ConsumingNHttpEntityTemplate
is a subclass of
HttpEntityWrapper
that decorates the incoming HTTP entity and
delegates the handling of incoming content to a ContentListener
instance.
static class FileWriteListener implements ContentListener { private final FileChannel fileChannel; private long idx = 0; public FileWriteListener(File file) throws IOException { this.fileChannel = new FileInputStream(file).getChannel(); } public void contentAvailable( ContentDecoder decoder, IOControl ioctrl) throws IOException { long transferred; if (decoder instanceof FileContentDecoder) { transferred = ((FileContentDecoder) decoder).transfer( fileChannel, idx, Long.MAX_VALUE); } else { transferred = fileChannel.transferFrom( new ContentDecoderChannel(decoder), idx, Long.MAX_VALUE); } if (transferred > 0) { idx += transferred; } } public void finished() { try { fileChannel.close(); } catch(IOException ignored) {} } } HttpEntity incomingEntity; File file = new File("buffer.bin"); ConsumingNHttpEntity entity = new ConsumingNHttpEntityTemplate( incomingEntity, new FileWriteListener(file));
ProducingNHttpEntity
interface represents a non-blocking
entity that allows content to be written to a content encoder.
ProducingNHttpEntity
extends the base
HttpEntity
interface with a number of NIO specific
notification methods:
produceContent
:
Notification that content can be written to the encoder.
IOControl
instance passed as a parameter to the method can be
used to temporarily suspend output events if the entity is unable to produce
more content. Please note one must call ContentEncoder#complete()
to inform the underlying connection that all content has been
written. Failure to do so could result in the entity never being correctly
delimited.
finish
:
Notification that any resources allocated for writing can be released.
The following implementations of ProducingNHttpEntity
provided by HttpCore NIO:
This is a simple self contained repeatable entity, which receives its content from a given byte array. This byte array is supplied to the constructor.
String myData = "Hello world on the other side!!"; NByteArrayEntity entity = new NByteArrayEntity(myData.getBytes());
It's is a simple, self contained, repeatable entity that retrieves its data from a
java.lang.String
object. It has 2 constructors, one simply
constructs with a given string where the other also takes a character encoding for
the data in the java.lang.String
.
String myData = "Hello world on the other side!!"; // construct without a character encoding NStringEntity myEntity1 = new NStringEntity(myData); // alternatively construct with an encoding NStringEntity myEntity2 = new NStringEntity(myData, "UTF-8");
This entity reads its content body from a file. This class is mostly used to stream large files of different types, so one needs to supply the content type of the file to make sure the content can be correctly recognized and processed by the recipient.
File staticFile = new File("/path/to/myapp.jar"); NHttpEntity entity = new NFileEntity(staticFile, "application/java-archive");
The NHttpEntity
will make use of the direct channel I/O
whenever possible, provided the content encoder is capable of transferring data
directly from a file to the socket of the underlying connection.
AsyncNHttpServiceHandler
is a fully asynchronous HTTP server
side protocol handler that implements the essential requirements of the HTTP protocol
for the server side message processing as described by RFC 2616.
AsyncNHttpServiceHandler
is capable of processing HTTP requests with nearly
constant memory footprint for individual HTTP connections. The handler stores headers
of HTTP messages in memory, while content of message bodies is streamed directly from
the entity to the underlying channel (and vice versa) using
ConsumingNHttpEntity
and ProducingNHttpEntity
interfaces.
When using this implementation, it is important to ensure that entities supplied for
writing implement ProducingNHttpEntity
. Doing so will
allow the entity to be written out asynchronously. If entities supplied for writing do
not implement the ProducingNHttpEntity
interface,
a delegate is added that buffers the entire contents in memory. Additionally,
the buffering might take place in the I/O dispatch thread, which could cause I/O to
block temporarily. For best results, one must ensure that all entities set on
HTTP responses from NHttpRequestHandler
implement
ProducingNHttpEntity
.
If incoming requests enclose a content entity, NHttpRequestHandler
instances are expected to return a ConsumingNHttpEntity
for reading the content. After the entity is finished reading the
data, NHttpRequestHandler#handle()
method is called to
generate a response.
AsyncNHttpServiceHandler
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 HTTP request handlers are expected to take care of
application specific content generation and processing.
HttpParams params; // Initialize HTTP parameters HttpProcessor httpproc; // Initialize HTTP processor AsyncNHttpServiceHandler handler = new AsyncNHttpServiceHandler( httpproc, new DefaultHttpResponseFactory(), new DefaultConnectionReuseStrategy(), params);
NHttpRequestHandler
interface represents a routine
for processing of a specific group of non-blocking HTTP requests.
NHttpRequestHandler
implementations are expected to take care of
protocol specific aspects, whereas individual request handlers are expected take
care of application specific HTTP processing. The main purpose of a request handler
is to generate a response object with a content entity to be send back to the
client in response to the given request.
NHttpRequestHandler myRequestHandler = new NHttpRequestHandler() { public ConsumingNHttpEntity entityRequest( HttpEntityEnclosingRequest request, HttpContext context) throws HttpException, IOException { // Buffer incoming content in memory for simplicity return new BufferingNHttpEntity(request.getEntity(), new HeapByteBufferAllocator()); } public void handle( HttpRequest request, HttpResponse response, NHttpResponseTrigger trigger, HttpContext context) throws HttpException, IOException { response.setStatusCode(HttpStatus.SC_OK); response.addHeader("Content-Type", "text/plain"); response.setEntity( new NStringEntity("some important message")); // Submit response immediately for simplicity trigger.submitResponse(response); } };
Request handlers must be implemented in a thread-safe manner. Similarly to servlets, request handlers should not use instance variables unless access to those variables are synchronized.
The most fundamental difference of the non-blocking request handlers compared to
their blocking counterparts is ability to defer transmission of the HTTP response
back to the client without blocking the I/O thread by delegating the process of
handling the HTTP request to a worker thread. The worker thread can use the
instance of NHttpResponseTrigger
passed as a
parameter to the NHttpRequestHandler#handle
method to
submit a response as at a later point of time once the response becomes available.
NHttpRequestHandler myRequestHandler = new NHttpRequestHandler() { public ConsumingNHttpEntity entityRequest( HttpEntityEnclosingRequest request, HttpContext context) throws HttpException, IOException { // Buffer incoming content in memory for simplicity return new BufferingNHttpEntity(request.getEntity(), new HeapByteBufferAllocator()); } public void handle( HttpRequest request, HttpResponse response, NHttpResponseTrigger trigger, HttpContext context) throws HttpException, IOException { new Thread() { @Override public void run() { try { Thread.sleep(10); } catch(InterruptedException ie) {} try { URI uri = new URI(request.getRequestLine().getUri()); response.setStatusCode(HttpStatus.SC_OK); response.addHeader("Content-Type", "text/plain"); response.setEntity( new NStringEntity("some important message")); trigger.submitResponse(response); } catch(URISyntaxException ex) { trigger.handleException( new HttpException("Invalid request URI: " + ex.getInput())); } } }.start(); } };
Please note HttpResponse
objects are not thread-safe
and may not be modified concurrently. Non-blocking request handlers must ensure
the HTTP response cannot be accessed by more than one thread at a time.
The management of non-blocking HTTP request handlers is quite similar to that of
blocking HTTP request handlers. Usually an instance of
NHttpRequestHandlerResolver
is used to maintain a registry of
request handlers and to matches a request URI to a particular request handler.
HttpCore includes only a very simple implementation of the request handler resolver
based on a trivial pattern matching algorithm:
NHttpRequestHandlerRegistry
supports only three formats:
*
, <uri>*
and
*<uri>
.
// Initialize asynchronous protocol handler AsyncNHttpServiceHandler handler; NHttpRequestHandlerRegistry handlerResolver = new NHttpRequestHandlerRegistry(); handlerReqistry.register("/service/*", myRequestHandler1); handlerReqistry.register("*.do", myRequestHandler2); handlerReqistry.register("*", myRequestHandler3); handler.setHandlerResolver(handlerResolver);
Users are encouraged to provide more sophisticated implementations of
NHttpRequestHandlerResolver
, for instance, based on
regular expressions.
AsyncNHttpClientHandler
is a fully asynchronous HTTP client side
protocol handler that implements the essential requirements of the HTTP protocol for
the client side message processing as described by RFC 2616.
AsyncNHttpClientHandler
is capable of executing HTTP requests with nearly
constant memory footprint for individual HTTP connections. The handler stores headers
of HTTP messages in memory, while content of message bodies is streamed directly from
the entity to the underlying channel (and vice versa) using
ConsumingNHttpEntity
and ProducingNHttpEntity
interfaces.
When using this implementation, it is important to ensure that entities supplied for
writing implement ProducingNHttpEntity
. Doing so will
allow the entity to be written out asynchronously. If entities supplied for writing do
not implement the ProducingNHttpEntity
interface,
a delegate is added that buffers the entire contents in memory. Additionally, the
buffering might take place in the I/O dispatch thread, which could cause I/O to block
temporarily. For best results, one must ensure that all entities set on HTTP requests
from NHttpRequestExecutionHandler
implement
ProducingNHttpEntity
.
If incoming responses enclose a content entity,
NHttpRequestExecutionHandler
is expected to return a
ConsumingNHttpEntity
for reading the content. After the entity is
finished reading the data, NHttpRequestExecutionHandler#handleResponse()
method is called to process the response.
AsyncNHttpClientHandler
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 HTTP request executor is expected to take care of application
specific content generation and processing.
// Initialize HTTP parameters HttpParams params; //Initialize HTTP processor HttpProcessor httpproc; //Create HTTP request execution handler NHttpRequestExecutionHandler execHandler; AsyncNHttpClientHandler handler = new AsyncNHttpClientHandler( httpproc, execHandler, new DefaultConnectionReuseStrategy(), params);
Asynchronous HTTP request execution handler can be used by client-side protocol handlers to trigger the submission of a new HTTP request and the processing of an HTTP response.
HTTP request execution events as defined by the
NHttpRequestExecutionHandler
interface:
initalizeContext
:
Triggered when a new connection has been established and the HTTP context
needs to be initialized. The attachment object passed to this method is
the same object which was passed to the connecting I/O reactor when the
connection request was made. The attachment may optionally contain some
state information required in order to correctly initialize the HTTP
context.
submitRequest
:
Triggered when the underlying connection is ready to send a new HTTP
request to the target host. This method may return null if the client is
not yet ready to send a request. In this case the connection will remain
open and can be activated at a later point. If the request encloses an
entity, the entity must be an instance of
ProducingNHttpEntity
.
responseEntity
:
Triggered when a response is received with an entity. This method should
return a ConsumingNHttpEntity
that will be
used to consume the entity. Null is a valid response value, and will
indicate that the entity should be silently ignored. After the entity is
fully consumed, handleResponse
method is called
to notify a full response and enclosed entity are ready to be processed.
handleResponse
:
Triggered when an HTTP response is ready to be processed.
finalizeContext
:
Triggered when the connection is terminated. This event can be used to
release objects stored in the context or perform some other kind of
cleanup.
NHttpRequestExecutionHandler execHandler = new NHttpRequestExecutionHandler() { private final static String DONE_FLAG = "done"; public void initalizeContext( HttpContext context, Object attachment) { if (attachment != null) { HttpHost virtualHost = (HttpHost) attachment; context.setAttribute(ExecutionContext.HTTP_TARGET_HOST, virtualHost); } } public void finalizeContext(HttpContext context) { context.removeAttribute(DONE_FLAG); } public HttpRequest submitRequest(HttpContext context) { // Submit HTTP GET once Object done = context.getAttribute(DONE_FLAG); if (done == null) { context.setAttribute(DONE_FLAG, Boolean.TRUE); return new BasicHttpRequest("GET", "/"); } else { return null; } } public ConsumingNHttpEntity responseEntity( HttpResponse response, HttpContext context) throws IOException { // Buffer incoming content in memory for simplicity return new BufferingNHttpEntity(response.getEntity(), new HeapByteBufferAllocator()); } public void handleResponse( HttpResponse response, HttpContext context) throws IOException { System.out.println(response.getStatusLine()); if (response.getEntity() != null) { System.out.println( EntityUtils.toString(response.getEntity())); } } };
In addition to asynchronous protocol handlers described above HttpCore ships two
variants of HTTP protocol handlers that emulate blocking I/O model on top of
non-blocking one and allow message content to be produced and consumed using standard
java.io.OutputStream
/ java.io.InputStream
API. Compatibility protocol handlers can work with HTTP request handlers and request
executors that rely on blocking HttpEntity implementations.
Compatibility protocol handlers rely 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 HTTP request executors / HTTP request processors are expected to take care of application specific content generation and processing.
BufferingHttpServiceHandler
and
BufferingHttpClientHandler
are protocol handler implementations that
provide compatibility with the blocking I/O by storing the full content of HTTP
messages in memory. Request / response processing callbacks fire only when the
entire message content has been read into a in-memory buffer. Please note that
request execution / request processing take place the main I/O thread and therefore
individual HTTP request executors / request handlers must ensure they do not block
indefinitely.
Buffering protocol handler should be used only when dealing with HTTP messages that are known to be limited in length.
ThrottlingHttpServiceHandler
and
ThrottlingHttpClientHandler
are protocol handler implementations that
provide compatibility with the blocking I/O model by utilizing shared content
buffers and a fairly small pool of worker threads. The throttling protocol handlers
allocate input / output buffers of constant length upon initialization and
control the rate of I/O events in order to ensure those content buffers do not
ever overflow. This helps ensure nearly constant memory footprint for HTTP
connections and avoid out of memory conditions while streaming content in and out.
Request / response processing callbacks fire immediately when a message is
received. The throttling protocol handlers delegate the task of processing requests
and generating response content to an Executor, which is expected to perform those
tasks using dedicated worker threads in order to avoid blocking the I/O thread.
Usually throttling protocol handlers need only a modest number of worker threads, much fewer than the number of concurrent connections. If the length of the message is smaller or about the size of the shared content buffer worker thread will just store content in the buffer and terminate almost immediately without blocking. The I/O dispatch thread in its turn will take care of sending out the buffered content asynchronously. The worker thread will have to block only when processing large messages and the shared buffer fills up. It is generally advisable to allocate shared buffers of a size of an average content body for optimal performance.
Protocol handlers like the rest of HttpCore classes do not do logging in order to not
impose a choice of a logging framework onto the users. However one can add logging of
the most important connection events by injecting a EventListener
implementation into the protocol handler.
Connection events as defined by the EventListener
interface:
fatalIOException
:
Triggered when an I/O error caused the connection to be terminated.
fatalProtocolException
:
Triggered when an HTTP protocol error caused the connection to be terminated.
connectionOpen
:
Triggered when a new connection has been established.
connectionClosed
:
Triggered when the connection has been terminated.
connectionTimeout
:
Triggered when the connection has timed out.
SSLIOSession
is a decorator class intended to transparently
extend any arbitrary IOSession
with transport layer
security capabilities based on the SSL/TLS protocol. Individual protocol handlers
should be able to work with SSL sessions without special preconditions or
modifications. However, I/O dispatchers need to take some additional actions to ensure
correct functioning of the transport layer encryption.
When the underlying I/O session has been created, the I/O dispatch must call
SSLIOSession#bind()
method in order to put the SSL
session either into a client or a server mode.
When the underlying I/O session is input ready, the I/O dispatcher should check
whether the SSL I/O session is ready to produce input data by calling
SSLIOSession#isAppInputReady()
, pass control to the
protocol handler if it is, and finally call
SSLIOSession#inboundTransport()
method in order to do the
necessary SSL handshaking and decrypt input data.
When the underlying I/O session is output ready, the I/O dispatcher should
check whether the SSL I/O session is ready to accept output data by calling
SSLIOSession#isAppOutputReady()
, pass control to the
protocol handler if it is, and finally call
SSLIOSession#outboundTransport()
method in order to do the nessary
SSL handshaking and encrypt application data.
Applications can customize various aspects of the TLS/SSl protocol by passing a
custom implementation of the SSLIOSessionHandler
interface.
SSL events as defined by the SSLIOSessionHandler
interface:
initalize
:
Triggered when the SSL connection is being initialized. The handler can use
this callback to customize properties of the
javax.net.ssl.SSLEngine
used to establish the SSL session.
verify
:
Triggered when the SSL connection has been established and initial SSL
handshake has been successfully completed. The handler can use this
callback to verify properties of the SSLSession. For instance this would
be the right place to enforce SSL cipher strength, validate certificate
chain and do hostname checks.
// Get hold of new I/O session IOSession iosession; // Initialize default SSL context SSLContext sslcontext = SSLContext.getInstance("SSL"); sslcontext.init(null, null, null); SSLIOSession sslsession = new SSLIOSession( iosession, sslcontext, new SSLIOSessionHandler() { public void initalize( SSLEngine sslengine, HttpParams params) throws SSLException { // Ask clients to authenticate sslengine.setWantClientAuth(true); // Enforce strong ciphers sslengine.setEnabledCipherSuites(new String[] { "TLS_RSA_WITH_AES_256_CBC_SHA", "TLS_DHE_RSA_WITH_AES_256_CBC_SHA", "TLS_DHE_DSS_WITH_AES_256_CBC_SHA" }); } public void verify( SocketAddress remoteAddress, SSLSession session) throws SSLException { X509Certificate[] certs = session.getPeerCertificateChain(); // Examine peer certificate chain for (X509Certificate cert: certs) { System.out.println(cert.toString()); } } });
HttpCore provides SSLClientIOEventDispatch
and
SSLServerIOEventDispatch
I/O dispatch implementations that can be used to
SSL enable connections managed by any arbitrary I/O reactor. The dispatches take all
the necessary actions to wrap active I/O sessions with the SSL I/O session decorator
and ensure correct handling of SSL protocol handshaking.