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:

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 SessionRequestinterface.

// 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);

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();
}

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:

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:

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();
}

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:

The following implementations of ConsumingNHttpEntity provided by HttpCore NIO:

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:

The following implementations of ProducingNHttpEntity provided by HttpCore NIO:

String myData = "Hello world on the other side!!";
NByteArrayEntity entity = new NByteArrayEntity(myData.getBytes()); 

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");

File staticFile = new File("/path/to/myapp.jar");
NHttpEntity entity = new NFileEntity(staticFile, 
    "application/java-archive");

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 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);
    }
    
};

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();
    }
    
};

// Initialize asynchronous protocol handler
AsyncNHttpServiceHandler handler;

NHttpRequestHandlerRegistry handlerResolver = 
    new NHttpRequestHandlerRegistry();
handlerReqistry.register("/service/*", myRequestHandler1);
handlerReqistry.register("*.do", myRequestHandler2);
handlerReqistry.register("*", myRequestHandler3);

handler.setHandlerResolver(handlerResolver);

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

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.

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:

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.

// 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.