Return-Path: 
 <commits-return-4805-apmail-hc-commits-archive=hc.apache.org@hc.apache.org>
X-Original-To: apmail-hc-commits-archive@www.apache.org
Delivered-To: apmail-hc-commits-archive@www.apache.org
Received: from mail.apache.org (hermes.apache.org [140.211.11.3])
	by minotaur.apache.org (Postfix) with SMTP id 02DCE9F9E
	for <apmail-hc-commits-archive@www.apache.org>;
 Tue, 17 Jan 2012 20:24:24 +0000 (UTC)
Received: (qmail 25390 invoked by uid 500); 17 Jan 2012 20:24:23 -0000
Delivered-To: apmail-hc-commits-archive@hc.apache.org
Received: (qmail 25358 invoked by uid 500); 17 Jan 2012 20:24:23 -0000
Mailing-List: contact commits-help@hc.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:commits-help@hc.apache.org>
List-Unsubscribe: <mailto:commits-unsubscribe@hc.apache.org>
List-Post: <mailto:commits@hc.apache.org>
List-Id: <commits.hc.apache.org>
Reply-To: "HttpComponents Project" <dev@hc.apache.org>
Delivered-To: mailing list commits@hc.apache.org
Received: (qmail 25348 invoked by uid 99); 17 Jan 2012 20:24:23 -0000
Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136)
    by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 17 Jan 2012 20:24:23 +0000
X-ASF-Spam-Status: No, hits=-2000.0 required=5.0
	tests=ALL_TRUSTED
X-Spam-Check-By: apache.org
Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4)
    by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 17 Jan 2012 20:24:19 +0000
Received: from eris.apache.org (localhost [127.0.0.1])
	by eris.apache.org (Postfix) with ESMTP id 404412388A9B
	for <commits@hc.apache.org>; Tue, 17 Jan 2012 20:23:59 +0000 (UTC)
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1232562 [3/4] - in
 /httpcomponents/httpcore/trunk/src/docbkx:
 advanced.xml fundamentals.xml index.xml nio-ext.xml preface.xml
Date: Tue, 17 Jan 2012 20:23:58 -0000
To: commits@hc.apache.org
From: olegk@apache.org
X-Mailer: svnmailer-1.0.8-patched
Message-Id: <20120117202359.404412388A9B@eris.apache.org>

Modified: httpcomponents/httpcore/trunk/src/docbkx/nio-ext.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/src/docbkx/nio-ext.xml?rev=1232562&r1=1232561&r2=1232562&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/src/docbkx/nio-ext.xml (original)
+++ httpcomponents/httpcore/trunk/src/docbkx/nio-ext.xml Tue Jan 17 20:23:58 2012
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
                  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
-<!-- 
+<!--
    ====================================================================
    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
@@ -27,9 +27,9 @@
     <section>
         <title>Benefits and shortcomings of the non-blocking I/O model</title>
         <para>
-        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: 
+        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:
         </para>
         <itemizedlist>
             <listitem>
@@ -52,7 +52,7 @@
     <section>
         <title>Differences from other NIO frameworks</title>
         <para>
-        Solves similar problems as other frameworks, but has certain distinct features: 
+        Solves similar problems as other frameworks, but has certain distinct features:
         </para>
         <itemizedlist>
             <listitem>
@@ -62,7 +62,7 @@
             </listitem>
             <listitem>
                 <para>
-                efficient memory management: data consumer can read only as much input data as it 
+                efficient memory management: data consumer can read only as much input data as it
                 can process without having to allocate more memory.
                 </para>
             </listitem>
@@ -76,46 +76,46 @@
     <section>
         <title>I/O reactor</title>
         <para>
-        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 
+        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 <interfacename>IOReactor
-        </interfacename> interface represents an abstract object which implements the Reactor pattern. 
-        Internally, <interfacename>IOReactor</interfacename> implementations encapsulate 
+        </interfacename> interface represents an abstract object which implements the Reactor pattern.
+        Internally, <interfacename>IOReactor</interfacename> implementations encapsulate
         functionality of the NIO <classname>java.nio.channels.Selector</classname>.
         </para>
         <para>
-        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 
+        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.
         </para>
         <programlisting><![CDATA[
 HttpParams params = new BasicHttpParams();
 int workerCount = 2;
-IOReactor ioreactor = new DefaultConnectingIOReactor(workerCount, 
+IOReactor ioreactor = new DefaultConnectingIOReactor(workerCount,
     params);
 ]]></programlisting>
         <section>
             <title>I/O dispatchers</title>
             <para>
-            <interfacename>IOReactor</interfacename> implementations make use of the 
-            <interfacename>IOEventDispatch</interfacename> interface to notify clients of events 
+            <interfacename>IOReactor</interfacename> implementations make use of the
+            <interfacename>IOEventDispatch</interfacename> interface to notify clients of events
             pending for a particular session. All methods of the <interfacename>IOEventDispatch
-            </interfacename> 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. 
+            </interfacename> 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.
             </para>
             <programlisting><![CDATA[
 HttpParams params = new BasicHttpParams();
 IOReactor ioreactor = new DefaultConnectingIOReactor(2, params);
-     
+
 IOEventDispatch eventDispatch = new MyIOEventDispatch();
 ioreactor.execute(eventDispatch);
 ]]></programlisting>
             <para>
-            Generic I/O events as defined by the <interfacename>IOEventDispatch</interfacename> 
+            Generic I/O events as defined by the <interfacename>IOEventDispatch</interfacename>
             interface:
             </para>
             <itemizedlist>
@@ -164,45 +164,45 @@ ioreactor.execute(eventDispatch);
         <section>
             <title>I/O reactor shutdown</title>
             <para>
-            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.    
+            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.
             </para>
             <programlisting><![CDATA[
 long gracePeriod = 3000L; // milliseconds
 ioreactor.shutdown(gracePeriod);
 ]]></programlisting>
             <para>
-            The <methodname>IOReactor#shutdown(long)</methodname> method is safe to call from any 
+            The <methodname>IOReactor#shutdown(long)</methodname> method is safe to call from any
             thread.
             </para>
         </section>
         <section>
             <title>I/O sessions</title>
             <para>
-            The <interfacename>IOSession</interfacename> interface represents a sequence of 
+            The <interfacename>IOSession</interfacename> interface represents a sequence of
             logically related data exchanges between two end points. <interfacename>IOSession
             </interfacename> encapsulates functionality of NIO <classname>
             java.nio.channels.SelectionKey</classname> and <classname>
-            java.nio.channels.SocketChannel</classname>. The channel associated with the 
-            <interfacename>IOSession</interfacename> can be used to read data from and write data 
+            java.nio.channels.SocketChannel</classname>. The channel associated with the
+            <interfacename>IOSession</interfacename> can be used to read data from and write data
             to the session.
             </para>
             <programlisting><![CDATA[
 IOSession iosession;
 ReadableByteChannel ch = (ReadableByteChannel) iosession.channel();
-ByteBuffer dst = ByteBuffer.allocate(2048); 
+ByteBuffer dst = ByteBuffer.allocate(2048);
 ch.read(dst);
 ]]></programlisting>
         </section>
         <section>
             <title>I/O session state management</title>
             <para>
-            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. 
+            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.
             </para>
             <programlisting><![CDATA[
 IOSession iosession;
@@ -211,22 +211,22 @@ iosession.setAttribute("state", someStat
 Object currentState = iosession.getAttribute("state");
 ]]></programlisting>
             <para>
-            Please note that if several sessions make use of shared objects, access to those 
-            objects must be made thread-safe. 
+            Please note that if several sessions make use of shared objects, access to those
+            objects must be made thread-safe.
             </para>
         </section>
         <section>
             <title>I/O session event mask</title>
             <para>
-            One can declare an interest in a particular type of I/O events for a particular I/O 
-            session by setting its event mask. 
+            One can declare an interest in a particular type of I/O events for a particular I/O
+            session by setting its event mask.
             </para>
             <programlisting><![CDATA[
 IOSession iosession;
 iosession.setEventMask(SelectionKey.OP_READ | SelectionKey.OP_WRITE);
 ]]></programlisting>
             <para>
-            One can also toggle <literal>OP_READ</literal> and <literal>OP_WRITE</literal> flags 
+            One can also toggle <literal>OP_READ</literal> and <literal>OP_WRITE</literal> flags
             individually.
             </para>
             <programlisting><![CDATA[
@@ -240,21 +240,21 @@ iosession.clearEvent(SelectionKey.OP_REA
         <section>
             <title>I/O session buffers</title>
             <para>
-            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 
+            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 <interfacename>
-            SessionBufferStatus</interfacename> interface. 
+            SessionBufferStatus</interfacename> interface.
             </para>
             <programlisting><![CDATA[
 IOSession iosession;
-SessionBufferStatus myBufferStatus = new MySessionBufferStatus(); 
+SessionBufferStatus myBufferStatus = new MySessionBufferStatus();
 iosession.setBufferStatus(myBufferStatus);
 iosession.hasBufferedInput();
 iosession.hasBufferedOutput();
@@ -263,23 +263,23 @@ iosession.hasBufferedOutput();
         <section>
             <title>I/O session shutdown</title>
             <para>
-            One can close an I/O session gracefully by calling <methodname>IOSession#close() 
-            </methodname> allowing the session to be closed in an orderly manner or by calling 
-            <methodname>IOSession#shutdown()</methodname> 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 
+            One can close an I/O session gracefully by calling <methodname>IOSession#close()
+            </methodname> allowing the session to be closed in an orderly manner or by calling
+            <methodname>IOSession#shutdown()</methodname> 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.
             </para>
         </section>
         <section>
             <title>Listening I/O reactors</title>
             <para>
-            <interfacename>ListeningIOReactor</interfacename> represents an I/O reactor capable of 
+            <interfacename>ListeningIOReactor</interfacename> represents an I/O reactor capable of
             listening for incoming connections on one or several ports.
             </para>
             <programlisting><![CDATA[
 ListeningIOReactor ioreactor;
-        
+
 ListenerEndpoint ep1 = ioreactor.listen(new InetSocketAddress(8081));
 ListenerEndpoint ep2 = ioreactor.listen(new InetSocketAddress(8082));
 ListenerEndpoint ep3 = ioreactor.listen(new InetSocketAddress(8083));
@@ -290,17 +290,17 @@ ep2.waitFor();
 ep3.waitFor();
 ]]></programlisting>
             <para>
-            Once an endpoint is fully initialized it starts accepting incoming connections and 
+            Once an endpoint is fully initialized it starts accepting incoming connections and
             propagates I/O activity notifications to the <interfacename>IOEventDispatch
             </interfacename> instance.
             </para>
             <para>
-            One can obtain a set of registered endpoints at runtime, query the status of an 
+            One can obtain a set of registered endpoints at runtime, query the status of an
             endpoint at runtime, and close it if desired.
             </para>
             <programlisting><![CDATA[
 ListeningIOReactor ioreactor;
-        
+
 Set<ListenerEndpoint> eps = ioreactor.getEndpoints();
 for (ListenerEndpoint ep: eps) {
     // Still active?
@@ -319,23 +319,23 @@ for (ListenerEndpoint ep: eps) {
         <section>
             <title>Connecting I/O reactors</title>
             <para>
-            <interfacename>ConnectingIOReactor</interfacename> represents an I/O reactor capable of 
+            <interfacename>ConnectingIOReactor</interfacename> represents an I/O reactor capable of
             establishing connections with remote hosts.
             </para>
             <programlisting><![CDATA[
 ConnectingIOReactor ioreactor;
 
 SessionRequest sessionRequest = ioreactor.connect(
-        new InetSocketAddress("www.google.com", 80), 
+        new InetSocketAddress("www.google.com", 80),
         null, null, null);
 ]]></programlisting>
             <para>
-            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 <interfacename>SessionRequest</interfacename>interface. 
+            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 <interfacename>SessionRequest</interfacename>interface.
             </para>
             <programlisting><![CDATA[
-// Make sure the request times out if connection 
+// Make sure the request times out if connection
 // has not been established after 1 sec
 sessionRequest.setConnectTimeout(1000);
 // Wait for the request to complete
@@ -348,7 +348,7 @@ if (sessionRequest.getException() != nul
 IOSession iosession = sessionRequest.getSession();
 ]]></programlisting>
             <para>
-            <interfacename>SessionRequest</interfacename> implementations are expected to be 
+            <interfacename>SessionRequest</interfacename> implementations are expected to be
             thread-safe. Session request can be aborted at any time by calling <methodname>
             IOSession#cancel()</methodname> from another thread of execution.
             </para>
@@ -359,40 +359,40 @@ if (!sessionRequest.isCompleted()) {
 ]]></programlisting>
             <para>
             One can pass several optional parameters to the <methodname>
-            ConnectingIOReactor#connect()</methodname> method to exert a greater control over the 
-            process of session initialization. 
+            ConnectingIOReactor#connect()</methodname> method to exert a greater control over the
+            process of session initialization.
             </para>
             <para>
-            A non-null local socket address parameter can be used to bind the socket to a specific 
+            A non-null local socket address parameter can be used to bind the socket to a specific
             local address.
             </para>
             <programlisting><![CDATA[
 ConnectingIOReactor ioreactor;
 
 SessionRequest sessionRequest = ioreactor.connect(
-        new InetSocketAddress("www.google.com", 80), 
-        new InetSocketAddress("192.168.0.10", 1234), 
+        new InetSocketAddress("www.google.com", 80),
+        new InetSocketAddress("192.168.0.10", 1234),
         null, null);
 ]]></programlisting>
             <para>
-            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 
+            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.
             </para>
             <programlisting><![CDATA[
 SessionRequest sessionRequest = ioreactor.connect(
-        new InetSocketAddress("www.google.com", 80), 
+        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);
 ]]></programlisting>
             <para>
-            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. 
+            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 <interfacename>SessionRequestCallback
-            </interfacename> interface to get notified of events related to session requests, such 
+            </interfacename> interface to get notified of events related to session requests, such
             as request completion, cancellation, failure or timeout.
             </para>
             <programlisting><![CDATA[
@@ -406,7 +406,7 @@ SessionRequest sessionRequest = ioreacto
             }
 
             public void completed(SessionRequest request) {
-                System.out.println("new connection to " + 
+                System.out.println("new connection to " +
                     request.getRemoteAddress());
             }
 
@@ -418,20 +418,20 @@ SessionRequest sessionRequest = ioreacto
 
             public void timeout(SessionRequest request) {
             }
-            
+
         });
 ]]></programlisting>
         </section>
         <section>
             <title>Queuing of I/O interest set operations</title>
             <para>
-            Several older JRE implementations (primarily from IBM) include what Java API 
+            Several older JRE implementations (primarily from IBM) include what Java API
             documentation refers to as a naive implementation of the <classname>
             java.nio.channels.SelectionKey</classname> class. The problem with <classname>
-            java.nio.channels.SelectionKey</classname> 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 
+            java.nio.channels.SelectionKey</classname> 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.
             </para>
             <programlisting><![CDATA[
@@ -444,17 +444,17 @@ ListeningIOReactor ioreactor = new Defau
     <section>
         <title>I/O reactor exception handling</title>
         <para>
-        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 
+        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.
         </para>
         <para>
-        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. 
+        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 <interfacename>
         IOReactorExceptionHandler</interfacename> interface.
         </para>
@@ -478,27 +478,27 @@ ioreactor.setExceptionHandler(new IOReac
         }
         return false;
     }
-    
+
 });
 ]]></programlisting>
         <para>
-        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 
+        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.
         </para>
         <section>
             <title>I/O reactor audit log</title>
             <para>
-            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 
+            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.
             </para>
             <programlisting><![CDATA[
@@ -518,16 +518,16 @@ for (ExceptionEvent event: events) {
         <title>Non-blocking HTTP connections</title>
         <para>
         Effectively non-blocking HTTP connections are wrappers around <interfacename>IOSession
-        </interfacename> 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. 
+        </interfacename> 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.
         </para>
         <section>
             <title>Execution context of non-blocking HTTP connections</title>
             <para>
-            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 <interfacename>HttpContext</interfacename> instance associated with 
+            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 <interfacename>HttpContext</interfacename> instance associated with
             it, which can be used to maintain a processing state. The <interfacename>HttpContext
             </interfacename> instance is thread-safe and can be manipulated from multiple threads.
             </para>
@@ -544,8 +544,8 @@ context.setAttribute("state", myStateObj
         <section>
             <title>Working with non-blocking HTTP connections</title>
             <para>
-            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 
+            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.
             </para>
             <programlisting><![CDATA[
@@ -553,21 +553,21 @@ NHttpConnection conn;
 
 HttpRequest request = conn.getHttpRequest();
 if (request != null) {
-    System.out.println("Transferring request: " + 
+    System.out.println("Transferring request: " +
         request.getRequestLine());
 }
 HttpResponse response = conn.getHttpResponse();
 if (response != null) {
-    System.out.println("Transferring response: " + 
+    System.out.println("Transferring response: " +
         response.getStatusLine());
 }
 ]]></programlisting>
             <para>
-            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 
+            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.
             </para>
             <para>
@@ -585,7 +585,7 @@ Object state = context.getAttribute("sta
 
 // Generate a request based on the state information
 HttpRequest request = new BasicHttpRequest("GET", "/");
-    
+
 conn.submitRequest(request);
 System.out.println(conn.isRequestSubmitted());
 ]]></programlisting>
@@ -603,18 +603,18 @@ HttpContext context = conn.getContext();
 Object state = context.getAttribute("state");
 
 // Generate a response based on the state information
-HttpResponse response = new BasicHttpResponse(HttpVersion.HTTP_1_1, 
+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());
 ]]></programlisting>
             <para>
-            Please note that one should rarely need to transmit messages using these low level 
+            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.
             </para>
         </section>
@@ -622,18 +622,18 @@ System.out.println(conn.isResponseSubmit
             <title>HTTP I/O control</title>
             <para>
             All non-blocking HTTP connections classes implement <interfacename>IOControl
-            </interfacename> interface, which represents a subset of connection functionality for 
+            </interfacename> interface, which represents a subset of connection functionality for
             controlling interest in I/O even notifications. <interfacename>IOControl
-            </interfacename> instances are expected to be fully thread-safe. Therefore 
-            <interfacename>IOControl</interfacename> can be used to request / suspend I/O event 
-            notifications from any thread. 
+            </interfacename> instances are expected to be fully thread-safe. Therefore
+            <interfacename>IOControl</interfacename> can be used to request / suspend I/O event
+            notifications from any thread.
             </para>
             <para>
-            One must take special precautions when interacting with non-blocking connections. 
+            One must take special precautions when interacting with non-blocking connections.
             <interfacename>HttpRequest</interfacename> and <interfacename>HttpResponse
-            </interfacename>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.   
+            </interfacename>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.
             </para>
             <para>
             The following pattern is recommended:
@@ -641,14 +641,14 @@ System.out.println(conn.isResponseSubmit
             <itemizedlist>
                 <listitem>
                     <para>
-                    Use <interfacename>IOControl</interfacename> interface to pass control over 
+                    Use <interfacename>IOControl</interfacename> interface to pass control over
                     connection's I/O events to another thread / session.
                     </para>
                 </listitem>
                 <listitem>
                     <para>
-                    If input / output operations need be executed on that particular connection, 
-                    store all the required information (state) in the connection context and 
+                    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 <methodname>
                     IOControl#requestInput()</methodname> or <methodname>IOControl#requestOutput()
                     </methodname> method.
@@ -656,90 +656,90 @@ System.out.println(conn.isResponseSubmit
                 </listitem>
                 <listitem>
                     <para>
-                    Execute the required operations from the event method on the dispatch thread 
+                    Execute the required operations from the event method on the dispatch thread
                     using information stored in connection context.
                     </para>
                 </listitem>
             </itemizedlist>
             <para>
-            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.  
+            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.
             </para>
         </section>
         <section>
             <title>Non-blocking content transfer</title>
             <para>
-            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 
+            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
             <classname>java.io.InputStream</classname> and <classname>java.io.OutputStream
-            </classname> classes to represent streams of inbound and outbound content. HttpCore NIO 
+            </classname> classes to represent streams of inbound and outbound content. HttpCore NIO
             provides <interfacename>ContentEncoder</interfacename> and <interfacename>
-            ContentDecoder</interfacename> 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.   
+            ContentDecoder</interfacename> 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.
             </para>
             <para>
-            Non-blocking HTTP connections will fire input events until the content entity is fully 
+            Non-blocking HTTP connections will fire input events until the content entity is fully
             transferred.
             </para>
             <programlisting><![CDATA[
 //Obtain content decoder
 ContentDecoder decoder;
 //Read data in
-ByteBuffer dst = ByteBuffer.allocate(2048); 
+ByteBuffer dst = ByteBuffer.allocate(2048);
 decoder.read(dst);
-// Decode will be marked as complete when 
+// Decode will be marked as complete when
 // the content entity is fully transferred
 if (decoder.isCompleted()) {
     // Done
 }
 ]]></programlisting>
             <para>
-            Non-blocking HTTP connections will fire output events until the content entity is 
+            Non-blocking HTTP connections will fire output events until the content entity is
             marked as fully transferred.
             </para>
             <programlisting><![CDATA[
 // Obtain content encoder
 ContentEncoder encoder;
-// Prepare output data 
-ByteBuffer src = ByteBuffer.allocate(2048); 
+// Prepare output data
+ByteBuffer src = ByteBuffer.allocate(2048);
 // Write data out
 encoder.write(src);
 // Mark content entity as fully transferred when done
 encoder.complete();
 ]]></programlisting>
             <para>
-            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 <interfacename>ContentEncoder</interfacename> instance to be 
-            used for transferring entity content. Non-blocking HTTP connections, however, ignore 
+            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 <interfacename>ContentEncoder</interfacename> instance to be
+            used for transferring entity content. Non-blocking HTTP connections, however, ignore
             inherently blocking <methodname>HttpEntity#getContent()</methodname> and <methodname>
-            HttpEntity#writeTo()</methodname> methods of the enclosed entities. 
+            HttpEntity#writeTo()</methodname> methods of the enclosed entities.
             </para>
             <programlisting><![CDATA[
 // Obtain HTTP connection
 NHttpServerConnection conn;
 
-HttpResponse response = new BasicHttpResponse(HttpVersion.HTTP_1_1, 
+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);
 ]]></programlisting>
             <para>
             Likewise, incoming entity enclosing message will have an <interfacename>HttpEntity
             </interfacename> instance associated with them, but an attempt to call <methodname>
-            HttpEntity#getContent()</methodname> or <methodname>HttpEntity#writeTo()</methodname> 
-            methods will cause an <classname>java.lang.IllegalStateException</classname>. The 
-            <interfacename>HttpEntity</interfacename> instance can be used to determine properties 
+            HttpEntity#getContent()</methodname> or <methodname>HttpEntity#writeTo()</methodname>
+            methods will cause an <classname>java.lang.IllegalStateException</classname>. The
+            <interfacename>HttpEntity</interfacename> instance can be used to determine properties
             of the incoming entity such as content length.
             </para>
             <programlisting><![CDATA[
@@ -758,7 +758,7 @@ if (entity != null) {
         <section>
             <title>Supported non-blocking content transfer mechanisms</title>
             <para>
-            Default implementations of the non-blocking HTTP connection interfaces support three 
+            Default implementations of the non-blocking HTTP connection interfaces support three
             content transfer mechanisms defined by the HTTP/1.1 specification:
             </para>
             <itemizedlist>
@@ -766,8 +766,8 @@ if (entity != null) {
                     <formalpara>
                     <title><literal>Content-Length</literal> delimited:</title>
                     <para>
-                    The end of the content entity is determined by the value of the 
-                    <literal>Content-Length</literal> header. Maximum entity length: 
+                    The end of the content entity is determined by the value of the
+                    <literal>Content-Length</literal> header. Maximum entity length:
                     <methodname>Long#MAX_VALUE</methodname>.
                     </para>
                     </formalpara>
@@ -776,8 +776,8 @@ if (entity != null) {
                     <formalpara>
                     <title>Identity coding:</title>
                     <para>
-                    The end of the content entity is demarcated by closing the underlying 
-                    connection (end of stream condition). For obvious reasons the identity encoding 
+                    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.
                     </para>
                     </formalpara>
@@ -792,23 +792,23 @@ if (entity != null) {
                 </listitem>
             </itemizedlist>
             <para>
-            The appropriate content codec will be created automatically depending on properties of 
+            The appropriate content codec will be created automatically depending on properties of
             the entity enclosed with the message.
             </para>
         </section>
         <section>
             <title>Direct channel I/O</title>
             <para>
-            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 
-            (<literal>Content-Length</literal> delimited and identity codecs, for example) can 
-            leverage NIO <classname>java.nio.FileChannel</classname> methods for significantly 
-            improved performance of file transfer operations both inbound and outbound.  
+            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
+            (<literal>Content-Length</literal> delimited and identity codecs, for example) can
+            leverage NIO <classname>java.nio.FileChannel</classname> methods for significantly
+            improved performance of file transfer operations both inbound and outbound.
             </para>
             <para>
             If the actual content decoder implements <interfacename>FileContentDecoder
-            </interfacename> one can make use of its methods to read incoming content directly to a 
+            </interfacename> one can make use of its methods to read incoming content directly to a
             file bypassing an intermediate <classname>java.nio.ByteBuffer</classname>.
             </para>
             <programlisting><![CDATA[
@@ -820,7 +820,7 @@ FileChannel dst;
 if (decoder instanceof FileContentDecoder) {
     long Bytesread = ((FileContentDecoder) decoder)
         .transfer(dst, 0, 2048);
-     // Decode will be marked as complete when 
+     // Decode will be marked as complete when
      // the content entity is fully transmitted
      if (decoder.isCompleted()) {
          // Done
@@ -829,7 +829,7 @@ if (decoder instanceof FileContentDecode
 ]]></programlisting>
             <para>
             If the actual content encoder implements <interfacename>FileContentEncoder
-            </interfacename> one can make use of its methods to write outgoing content directly 
+            </interfacename> one can make use of its methods to write outgoing content directly
             from a file bypassing an intermediate <classname>java.nio.ByteBuffer</classname>.
             </para>
             <programlisting><![CDATA[
@@ -841,7 +841,7 @@ FileChannel src;
 if (encoder instanceof FileContentEncoder) {
     // Write data out
     long bytesWritten = ((FileContentEncoder) encoder)
-        .transfer(src, 0, 2048); 
+        .transfer(src, 0, 2048);
     // Mark content entity as fully transferred when done
     encoder.complete();
 }
@@ -851,9 +851,9 @@ if (encoder instanceof FileContentEncode
     <section>
         <title>HTTP I/O event dispatchers</title>
         <para>
-        HTTP I/O event dispatchers serve to convert generic I/O events triggered by an I/O reactor 
+        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 <interfacename>NHttpClientEventHandler
-        </interfacename> and <interfacename>NHttpServerEventHandler</interfacename> interfaces to 
+        </interfacename> and <interfacename>NHttpServerEventHandler</interfacename> interfaces to
         propagate HTTP protocol events to a HTTP protocol handler.
         </para>
         <para>
@@ -873,9 +873,9 @@ if (encoder instanceof FileContentEncode
                 <formalpara>
                 <title><methodname>requestReceived</methodname>:</title>
                 <para>
-                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 
+                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
                 <methodname>inputReady</methodname> events to transfer the request content.
                 </para>
                 </formalpara>
@@ -884,9 +884,9 @@ if (encoder instanceof FileContentEncode
                 <formalpara>
                 <title><methodname>inputReady</methodname>:</title>
                 <para>
-                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 
+                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 <interfacename>IOControl</interfacename> interface.
                 </para>
                 </formalpara>
@@ -895,7 +895,7 @@ if (encoder instanceof FileContentEncode
                 <formalpara>
                 <title><methodname>responseReady</methodname>:</title>
                 <para>
-                Triggered when the connection is ready to accept new HTTP response. The protocol 
+                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.
                 </para>
                 </formalpara>
@@ -904,9 +904,9 @@ if (encoder instanceof FileContentEncode
                 <formalpara>
                 <title><methodname>outputReady</methodname>:</title>
                 <para>
-                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 
+                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 <interfacename>IOControl</interfacename> interface.
                 </para>
                 </formalpara>
@@ -915,7 +915,7 @@ if (encoder instanceof FileContentEncode
                 <formalpara>
                 <title><methodname>exception</methodname>:</title>
                 <para>
-                Triggered when an I/O error occurrs while reading from or writing to the underlying 
+                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.
                 </para>
                 </formalpara>
@@ -924,7 +924,7 @@ if (encoder instanceof FileContentEncode
                 <formalpara>
                 <title><methodname>timeout</methodname>:</title>
                 <para>
-                Triggered when no input is detected on this connection over the maximum period of 
+                Triggered when no input is detected on this connection over the maximum period of
                 inactivity.
                 </para>
                 </formalpara>
@@ -947,8 +947,8 @@ if (encoder instanceof FileContentEncode
                 <formalpara>
                 <title><methodname>connected</methodname>:</title>
                 <para>
-                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 
+                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.
                 </para>
                 </formalpara>
@@ -957,7 +957,7 @@ if (encoder instanceof FileContentEncode
                 <formalpara>
                 <title><methodname>requestReady</methodname>:</title>
                 <para>
-                Triggered when the connection is ready to accept new HTTP request. The protocol handler 
+                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.
                 </para>
                 </formalpara>
@@ -966,9 +966,9 @@ if (encoder instanceof FileContentEncode
                 <formalpara>
                 <title><methodname>outputReady</methodname>:</title>
                 <para>
-                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 
+                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 <interfacename>IOControl</interfacename> interface.
                 </para>
                 </formalpara>
@@ -977,9 +977,9 @@ if (encoder instanceof FileContentEncode
                 <formalpara>
                 <title><methodname>responseReceived</methodname>:</title>
                 <para>
-                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 
+                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
                 <methodname>inputReady</methodname> events to transfer the response content.
                 </para>
                 </formalpara>
@@ -988,9 +988,9 @@ if (encoder instanceof FileContentEncode
                 <formalpara>
                 <title><methodname>inputReady</methodname>:</title>
                 <para>
-                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 
+                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 <interfacename>IOControl</interfacename> interface.
                 </para>
                 </formalpara>
@@ -999,7 +999,7 @@ if (encoder instanceof FileContentEncode
                 <formalpara>
                 <title><methodname>exception</methodname>:</title>
                 <para>
-                Triggered when an I/O error occurs while reading from or writing to the underlying 
+                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..
                 </para>
                 </formalpara>
@@ -1008,7 +1008,7 @@ if (encoder instanceof FileContentEncode
                 <formalpara>
                 <title><methodname>timeout</methodname>:</title>
                 <para>
-                Triggered when no input is detected on this connection over the maximum period of 
+                Triggered when no input is detected on this connection over the maximum period of
                 inactivity.
                 </para>
                 </formalpara>
@@ -1026,13 +1026,13 @@ if (encoder instanceof FileContentEncode
     <section>
         <title>Non-blocking HTTP content producers</title>
         <para>
-        As discussed previously the process of content transfer for non-blocking connections works 
-        completely differently compared to that for blocking connections. For obvious reasons 
+        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 <classname>java.io.InputStream
-        </classname> and <classname>java.io.OutputStream</classname> classes is not well suited 
+        </classname> and <classname>java.io.OutputStream</classname> classes is not well suited
         for asynchronous data transfer. In order to avoid inefficient and potentially blocking
         I/O operation redirection through <methodname>java.nio.channels.Channles#newChannel
-        </methodname> non-blocking HTTP entities are expected to implement NIO specific extension 
+        </methodname> non-blocking HTTP entities are expected to implement NIO specific extension
         interface <interfacename>HttpAsyncContentProducer</interfacename>.
         </para>
         <para>
@@ -1045,11 +1045,11 @@ if (encoder instanceof FileContentEncode
                 <title><methodname>produceContent</methodname>:</title>
                 <para>
                 Invoked to write out a chunk of content to the <interfacename>ContentEncoder
-                </interfacename>. The <interfacename>IOControl</interfacename> interface can be 
-                used to suspend output events if the entity is temporarily unable to produce more 
-                content. When all content is finished, the producer MUST call 
-                <methodname>ContentEncoder#complete()</methodname>. Failure to do so may cause 
-                the entity to be incorrectly delimited.                    
+                </interfacename>. The <interfacename>IOControl</interfacename> interface can be
+                used to suspend output events if the entity is temporarily unable to produce more
+                content. When all content is finished, the producer MUST call
+                <methodname>ContentEncoder#complete()</methodname>. Failure to do so may cause
+                the entity to be incorrectly delimited.
                 </para>
                 </formalpara>
             </listitem>
@@ -1057,7 +1057,7 @@ if (encoder instanceof FileContentEncode
                 <formalpara>
                 <title><methodname>isRepeatable</methodname>:</title>
                 <para>
-                Determines whether or not this producer is capable of producing its content more 
+                Determines whether or not this producer is capable of producing its content more
                 than once. Repeatable content producers are expected to be able to recreate
                 their content even after having been closed.
                 </para>
@@ -1075,7 +1075,7 @@ if (encoder instanceof FileContentEncode
         <section>
             <title>Creating non-blocking entities</title>
             <para>
-            Several HTTP entity implementations included in HttpCore NIO support 
+            Several HTTP entity implementations included in HttpCore NIO support
             <interfacename>HttpAsyncContentProducer</interfacename> interface:
             </para>
             <itemizedlist>
@@ -1104,20 +1104,20 @@ if (encoder instanceof FileContentEncode
             <section id="bytearray-n-entity">
                 <title><classname>NByteArrayEntity</classname></title>
                 <para>
-                This is a simple self contained repeatable entity, which receives its content from 
+                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.
                 </para>
                 <programlisting><![CDATA[
 String myData = "Hello world on the other side!!";
-NByteArrayEntity entity = new NByteArrayEntity(myData.getBytes()); 
+NByteArrayEntity entity = new NByteArrayEntity(myData.getBytes());
     ]]></programlisting>
             </section>
             <section id="string-n-entity">
                 <title><classname>NStringEntity</classname></title>
                 <para>
-                It's is a simple, self contained, repeatable entity that retrieves its data from a 
-                <classname>java.lang.String</classname> object. It has 2 constructors, one simply 
-                constructs with a given string where the other also takes a character encoding for 
+                It's is a simple, self contained, repeatable entity that retrieves its data from a
+                <classname>java.lang.String</classname> 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 <classname>java.lang.String</classname>.
                 </para>
                 <programlisting><![CDATA[
@@ -1131,50 +1131,50 @@ NStringEntity myEntity2 = new NStringEnt
             <section id="file-n-entity">
                 <title><classname>NFileEntity</classname></title>
                 <para>
-                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 
+                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.
                 </para>
                 <programlisting><![CDATA[
 File staticFile = new File("/path/to/myapp.jar");
-NHttpEntity entity = new NFileEntity(staticFile, 
+NHttpEntity entity = new NFileEntity(staticFile,
     ContentType.create("application/java-archive", null));
     ]]></programlisting>
                 <para>
-                The <classname>NHttpEntity</classname> will make use of the direct channel I/O 
-                whenever possible, provided the content encoder is capable of transferring data 
+                The <classname>NHttpEntity</classname> 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.
                 </para>
             </section>
         </section>
-    </section>    
+    </section>
     <section>
         <title>Non-blocking HTTP protocol handlers</title>
         <section>
             <title>Asynchronous HTTP service</title>
             <para>
-            <classname>HttpAsyncService</classname> is a fully asynchronous HTTP server side 
+            <classname>HttpAsyncService</classname> is a fully asynchronous HTTP server side
             protocol handler based on the non-blocking (NIO) I/O model. <classname>
-            HttpAsyncService</classname> translates individual events fired through the 
-            <interfacename>NHttpServerEventHandler</interfacename> interface into logically 
+            HttpAsyncService</classname> translates individual events fired through the
+            <interfacename>NHttpServerEventHandler</interfacename> interface into logically
             related HTTP message exchanges.
             </para>
             <para>
-            Upon receiving an incoming request the <classname>HttpAsyncService</classname> 
+            Upon receiving an incoming request the <classname>HttpAsyncService</classname>
             verifies the message for compliance with the server expectations using <interfacename>
             HttpAsyncExpectationVerifier</interfacename>, if provided, and then <interfacename>
-            HttpAsyncRequestHandlerResolver</interfacename> is used to resolve the request URI to 
-            a particular <interfacename>HttpAsyncRequestHandler</interfacename> intended to handle 
+            HttpAsyncRequestHandlerResolver</interfacename> is used to resolve the request URI to
+            a particular <interfacename>HttpAsyncRequestHandler</interfacename> intended to handle
             the request with the given URI. The protocol handler uses the selected <interfacename>
-            HttpAsyncRequestHandler</interfacename> instance to process the incoming request and 
+            HttpAsyncRequestHandler</interfacename> instance to process the incoming request and
             to generate an outgoing response.
             </para>
             <para>
             <classname>HttpAsyncService</classname> relies on <interfacename>HttpProcessor
-            </interfacename> 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 implement 
+            </interfacename> 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 implement
             application specific content generation and processing.
             </para>
             <programlisting><![CDATA[
@@ -1185,10 +1185,10 @@ HttpProcessor httpproc;
 HttpAsyncRequestHandlerResolver handlerResolver;
 // Initialize HTTP request resolver
 HttpAsyncService protocolHandler = new HttpAsyncService(
-        httpproc, 
-        new DefaultConnectionReuseStrategy(), 
+        httpproc,
+        new DefaultConnectionReuseStrategy(),
         new DefaultHttpResponseFactory(),
-        handlerResolver, 
+        handlerResolver,
         null,
         params);
 NHttpConnectionFactory<DefaultNHttpServerConnection> connFactory;
@@ -1198,12 +1198,12 @@ IOEventDispatch ioEventDispatch = new De
             <section>
                 <title>Non-blocking HTTP request handlers</title>
                 <para>
-                <interfacename>HttpAsyncRequestHandler</interfacename> represents a routine for 
-                asynchronous processing of a specific group of non-blocking HTTP requests. 
+                <interfacename>HttpAsyncRequestHandler</interfacename> represents a routine for
+                asynchronous processing of a specific group of non-blocking HTTP requests.
                 Protocol handlers are designed to take care of protocol specific aspects, whereas
-                individual request handlers are expected to 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 sent back to the client in response to the given 
+                individual request handlers are expected to 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 sent back to the client in response to the given
                 request.
                 </para>
                 <programlisting><![CDATA[
@@ -1222,7 +1222,7 @@ HttpAsyncRequestHandler<HttpRequest> myH
             final HttpContext context) throws HttpException, IOException {
         HttpResponse response = httpexchange.getResponse();
         response.setStatusCode(HttpStatus.SC_OK);
-        NFileEntity body = new NFileEntity(new File("static.html"), 
+        NFileEntity body = new NFileEntity(new File("static.html"),
                 ContentType.create("text/html", null));
         response.setEntity(body);
         httpexchange.submitResponse(new BasicAsyncResponseProducer(response));
@@ -1231,20 +1231,20 @@ HttpAsyncRequestHandler<HttpRequest> myH
 };
 ]]></programlisting>
                 <para>
-                Request handlers must be implemented in a thread-safe manner. Similarly to 
-                servlets, request handlers should not use instance variables unless access to those 
+                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.
                 </para>
             </section>
             <section>
                 <title>Asynchronous HTTP exchange</title>
                 <para>
-                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 or another service. The instance of 
-                <interfacename>HttpAsyncExchange</interfacename> passed as a parameter to the 
-                <methodname>HttpAsyncRequestHandler#handle</methodname> method to submit 
+                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 or another service. The instance of
+                <interfacename>HttpAsyncExchange</interfacename> passed as a parameter to the
+                <methodname>HttpAsyncRequestHandler#handle</methodname> method to submit
                 a response as at a later point once response content becomes available.
                 </para>
                 <para>
@@ -1272,7 +1272,7 @@ HttpAsyncRequestHandler<HttpRequest> myH
                         <formalpara>
                         <title><methodname>submitResponse</methodname>:</title>
                         <para>
-                        Submits an HTTP response and completed the message exchange. 
+                        Submits an HTTP response and completed the message exchange.
                         </para>
                         </formalpara>
                     </listitem>
@@ -1280,7 +1280,7 @@ HttpAsyncRequestHandler<HttpRequest> myH
                         <formalpara>
                         <title><methodname>isCompleted</methodname>:</title>
                         <para>
-                        Determines whether or not the message exchange has been completed. 
+                        Determines whether or not the message exchange has been completed.
                         </para>
                         </formalpara>
                     </listitem>
@@ -1288,10 +1288,10 @@ HttpAsyncRequestHandler<HttpRequest> myH
                         <formalpara>
                         <title><methodname>setCallback</methodname>:</title>
                         <para>
-                        Sets <interfacename>Cancellable</interfacename> callback to be invoked 
-                        in case the underlying connection times out or gets terminated prematurely 
-                        by the client. This callback can be used to cancel a long running response 
-                        generating process if a response is no longer needed. 
+                        Sets <interfacename>Cancellable</interfacename> callback to be invoked
+                        in case the underlying connection times out or gets terminated prematurely
+                        by the client. This callback can be used to cancel a long running response
+                        generating process if a response is no longer needed.
                         </para>
                         </formalpara>
                     </listitem>
@@ -1299,7 +1299,7 @@ HttpAsyncRequestHandler<HttpRequest> myH
                         <formalpara>
                         <title><methodname>setTimeout</methodname>:</title>
                         <para>
-                        Sets timeout for this message exchange. 
+                        Sets timeout for this message exchange.
                         </para>
                         </formalpara>
                     </listitem>
@@ -1307,7 +1307,7 @@ HttpAsyncRequestHandler<HttpRequest> myH
                         <formalpara>
                         <title><methodname>getTimeout</methodname>:</title>
                         <para>
-                        Returns timeout for this message exchange. 
+                        Returns timeout for this message exchange.
                         </para>
                         </formalpara>
                     </listitem>
@@ -1328,39 +1328,39 @@ HttpAsyncRequestHandler<HttpRequest> myH
             final HttpContext context) throws HttpException, IOException {
 
         new Thread() {
-            
+
             @Override
             public void run() {
-                try { 
-                    Thread.sleep(10); 
-                } 
+                try {
+                    Thread.sleep(10);
+                }
                 catch(InterruptedException ie) {}
                 HttpResponse response = httpexchange.getResponse();
                 response.setStatusCode(HttpStatus.SC_OK);
-                NFileEntity body = new NFileEntity(new File("static.html"), 
+                NFileEntity body = new NFileEntity(new File("static.html"),
                         ContentType.create("text/html", null));
                 response.setEntity(body);
                 httpexchange.submitResponse(new BasicAsyncResponseProducer(response));
             }
         }.start();
-        
+
     }
 
 };
 ]]></programlisting>
                 <para>
-                Please note <interfacename>HttpResponse</interfacename> instances are not 
-                thread-safe and may not be modified concurrently. Non-blocking request handlers 
+                Please note <interfacename>HttpResponse</interfacename> instances are not
+                thread-safe and may not be modified concurrently. Non-blocking request handlers
                 must ensure HTTP response cannot be accessed by more than one thread at a time.
                 </para>
             </section>
             <section>
                 <title>Asynchronous HTTP request consumer</title>
                 <para>
-                <interfacename>HttpAsyncRequestConsumer</interfacename> facilities the process of 
+                <interfacename>HttpAsyncRequestConsumer</interfacename> facilities the process of
                 asynchronous processing of HTTP requests. It is a callback interface used by
-                <interfacename>HttpAsyncRequestHandler</interfacename>s to process an incoming 
-                HTTP request message and to stream its content from a non-blocking server side 
+                <interfacename>HttpAsyncRequestHandler</interfacename>s to process an incoming
+                HTTP request message and to stream its content from a non-blocking server side
                 HTTP connection.
                 </para>
                 <para>
@@ -1382,16 +1382,16 @@ HttpAsyncRequestHandler<HttpRequest> myH
                         <para>
                         Invoked to process a chunk of content from the <interfacename>
                         ContentDecoder</interfacename>. The <interfacename>IOControl
-                        </interfacename> interface can be used to suspend input events if 
+                        </interfacename> interface can be used to suspend input events if
                         the consumer is temporarily unable to consume more content.
                         </para>
                         <para>
                         The consumer can use the <methodname>ContentDecoder#isCompleted()
-                        </methodname> method to find out whether or not the message content 
+                        </methodname> method to find out whether or not the message content
                         has been fully consumed.
                         </para>
                         <para>
-                        This event is invoked only for if the incoming request message has 
+                        This event is invoked only for if the incoming request message has
                         a content entity enclosed in it.
                         </para>
                         </formalpara>
@@ -1400,7 +1400,7 @@ HttpAsyncRequestHandler<HttpRequest> myH
                         <formalpara>
                         <title><methodname>requestCompleted</methodname>:</title>
                         <para>
-                        Invoked to signal that the request has been fully processed. 
+                        Invoked to signal that the request has been fully processed.
                         </para>
                         </formalpara>
                     </listitem>
@@ -1408,7 +1408,7 @@ HttpAsyncRequestHandler<HttpRequest> myH
                         <formalpara>
                         <title><methodname>failed</methodname>:</title>
                         <para>
-                        Invoked to signal that the request processing terminated abnormally. 
+                        Invoked to signal that the request processing terminated abnormally.
                         </para>
                         </formalpara>
                     </listitem>
@@ -1416,9 +1416,9 @@ HttpAsyncRequestHandler<HttpRequest> myH
                         <formalpara>
                         <title><methodname>getException</methodname>:</title>
                         <para>
-                        Returns an exception in case of an abnormal termination. This method 
-                        returns <code>null</code> if the request execution is still ongoing or if 
-                        it completed successfully. 
+                        Returns an exception in case of an abnormal termination. This method
+                        returns <code>null</code> if the request execution is still ongoing or if
+                        it completed successfully.
                         </para>
                         </formalpara>
                     </listitem>
@@ -1426,8 +1426,8 @@ HttpAsyncRequestHandler<HttpRequest> myH
                         <formalpara>
                         <title><methodname>getResult</methodname>:</title>
                         <para>
-                        Returns a result of the request execution, when available. This method 
-                        returns <code>null</code> if the request execution is still ongoing. 
+                        Returns a result of the request execution, when available. This method
+                        returns <code>null</code> if the request execution is still ongoing.
                         </para>
                         </formalpara>
                     </listitem>
@@ -1438,8 +1438,8 @@ HttpAsyncRequestHandler<HttpRequest> myH
                         Determines whether or not the request execution completed. If the
                         request processing terminated normally <methodname>getResult()</methodname>
                         can be used to obtain the result. If the request processing terminated
-                        abnormally <methodname>getException()</methodname> can be used to obtain 
-                        the cause. 
+                        abnormally <methodname>getException()</methodname> can be used to obtain
+                        the cause.
                         </para>
                         </formalpara>
                     </listitem>
@@ -1453,26 +1453,26 @@ HttpAsyncRequestHandler<HttpRequest> myH
                     </listitem>
                 </itemizedlist>
                 <para>
-                <interfacename>HttpAsyncRequestConsumer</interfacename> implementations are 
+                <interfacename>HttpAsyncRequestConsumer</interfacename> implementations are
                 expected to be tread-safe.
                 </para>
                 <para>
-                <classname>BasicAsyncRequestConsumer</classname> is a very basic implementation 
+                <classname>BasicAsyncRequestConsumer</classname> is a very basic implementation
                 of the <interfacename>HttpAsyncRequestConsumer</interfacename> interface shipped
-                with the library. Please note that this consumer buffers request content in memory and 
+                with the library. Please note that this consumer buffers request content in memory and
                 therefore should be used for relatively small request messages.
                 </para>
             </section>
             <section>
                 <title>Asynchronous HTTP response producer</title>
                 <para>
-                <interfacename>HttpAsyncResponseProducer</interfacename> facilities the process of 
+                <interfacename>HttpAsyncResponseProducer</interfacename> facilities the process of
                 asynchronous generation of HTTP responses. It is a callback interface used by
-                <interfacename>HttpAsyncRequestHandler</interfacename>s to generate an HTTP response 
+                <interfacename>HttpAsyncRequestHandler</interfacename>s to generate an HTTP response
                 message and to stream its content to a non-blocking server side HTTP connection.
                 </para>
                 <para>
-                HTTP I/O events and methods as defined by the 
+                HTTP I/O events and methods as defined by the
                 <interfacename>HttpAsyncResponseProducer</interfacename> interface:
                 </para>
                 <itemizedlist>
@@ -1480,7 +1480,7 @@ HttpAsyncRequestHandler<HttpRequest> myH
                         <formalpara>
                         <title><methodname>generateResponse</methodname>:</title>
                         <para>
-                        Invoked to generate a HTTP response message head. 
+                        Invoked to generate a HTTP response message head.
                         </para>
                         </formalpara>
                     </listitem>
@@ -1490,16 +1490,16 @@ HttpAsyncRequestHandler<HttpRequest> myH
                         <para>
                         Invoked to write out a chunk of content to the <interfacename>
                         ContentEncoder</interfacename>. The <interfacename>IOControl
-                        </interfacename> interface can be used to suspend output events if 
+                        </interfacename> interface can be used to suspend output events if
                         the producer is temporarily unable to produce more content.
                         </para>
                         <para>
                         When all content is finished, the producer MUST call <methodname>
-                        ContentEncoder#complete()</methodname>. Failure to do so may cause 
+                        ContentEncoder#complete()</methodname>. Failure to do so may cause
                         the entity to be incorrectly delimited.
                         </para>
                         <para>
-                        This event is invoked only for if the outgoing response message has 
+                        This event is invoked only for if the outgoing response message has
                         a content entity enclosed in it, that is <methodname>
                         HttpResponse#getEntity()</methodname> returns <code>null</code>.
                         </para>
@@ -1509,7 +1509,7 @@ HttpAsyncRequestHandler<HttpRequest> myH
                         <formalpara>
                         <title><methodname>responseCompleted</methodname>:</title>
                         <para>
-                        Invoked to signal that the response has been fully written out. 
+                        Invoked to signal that the response has been fully written out.
                         </para>
                         </formalpara>
                     </listitem>
@@ -1517,7 +1517,7 @@ HttpAsyncRequestHandler<HttpRequest> myH
                         <formalpara>
                         <title><methodname>failed</methodname>:</title>
                         <para>
-                        Invoked to signal that the response processing terminated abnormally. 
+                        Invoked to signal that the response processing terminated abnormally.
                         </para>
                         </formalpara>
                     </listitem>
@@ -1531,41 +1531,41 @@ HttpAsyncRequestHandler<HttpRequest> myH
                     </listitem>
                 </itemizedlist>
                 <para>
-                <interfacename>HttpAsyncResponseProducer</interfacename> implementations are 
+                <interfacename>HttpAsyncResponseProducer</interfacename> implementations are
                 expected to be tread-safe.
                 </para>
                 <para>
-                <classname>BasicAsyncResponseProducer</classname> is a basic implementation 
+                <classname>BasicAsyncResponseProducer</classname> is a basic implementation
                 of the <interfacename>HttpAsyncResponseProducer</interfacename> interface shipped
                 with the library. The producer can make use of the <interfacename>
-                HttpAsyncContentProducer</interfacename> interface to efficiently stream out 
-                message content to a non-blocking HTTP connection, if it is implemented by the 
+                HttpAsyncContentProducer</interfacename> interface to efficiently stream out
+                message content to a non-blocking HTTP connection, if it is implemented by the
                 <interfacename>HttpEntity</interfacename> enclosed in the response.
                 </para>
             </section>
             <section>
                 <title>Non-blocking request handler resolver</title>
                 <para>
-                The management of non-blocking HTTP request handlers is quite similar to that of 
+                The management of non-blocking HTTP request handlers is quite similar to that of
                 blocking HTTP request handlers. Usually an instance of <interfacename>
-                HttpAsyncRequestHandlerResolver</interfacename> 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 
+                HttpAsyncRequestHandlerResolver</interfacename> 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

[... 503 lines stripped ...]