hc-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ol...@apache.org
Subject svn commit: r1499798 - in /httpcomponents/httpcore/trunk: httpcore-nio/src/main/java/org/apache/http/impl/nio/pool/BasicNIOConnPool.java src/docbkx/fundamentals.xml src/docbkx/nio-ext.xml
Date Thu, 04 Jul 2013 16:15:24 GMT
Author: olegk
Date: Thu Jul  4 16:15:23 2013
New Revision: 1499798

URL: http://svn.apache.org/r1499798
Log:
Updated HttpCore tutorial sections on i/o reactor config, connection pools and TLS/SSL support

Modified:
    httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/impl/nio/pool/BasicNIOConnPool.java
    httpcomponents/httpcore/trunk/src/docbkx/fundamentals.xml
    httpcomponents/httpcore/trunk/src/docbkx/nio-ext.xml

Modified: httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/impl/nio/pool/BasicNIOConnPool.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/impl/nio/pool/BasicNIOConnPool.java?rev=1499798&r1=1499797&r2=1499798&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/impl/nio/pool/BasicNIOConnPool.java
(original)
+++ httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/impl/nio/pool/BasicNIOConnPool.java
Thu Jul  4 16:15:23 2013
@@ -138,6 +138,13 @@ public class BasicNIOConnPool extends Ab
     }
 
     /**
+     * @since 4.3
+     */
+    public BasicNIOConnPool(final ConnectingIOReactor ioreactor) {
+        this(ioreactor, new BasicNIOConnFactory(ConnectionConfig.DEFAULT), 0);
+    }
+
+    /**
      * @deprecated (4.3) use {@link SocketAddressResolver}
      */
     @Deprecated

Modified: httpcomponents/httpcore/trunk/src/docbkx/fundamentals.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/src/docbkx/fundamentals.xml?rev=1499798&r1=1499797&r2=1499798&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/src/docbkx/fundamentals.xml (original)
+++ httpcomponents/httpcore/trunk/src/docbkx/fundamentals.xml Thu Jul  4 16:15:23 2013
@@ -23,7 +23,7 @@
 
 -->
 <chapter id="fundamentals">
-    <title>Fundamentals</title>
+    <title>HTTP message fundamentals and classic synchronous I/O</title>
     <section>
         <title>HTTP messages</title>
         <section>
@@ -1067,4 +1067,94 @@ EntityUtils.consume(entity);
             </para>
         </section>
     </section>
+    <section>
+        <title>Connection pools</title>
+        <para>
+        Efficient client-side HTTP transports often requires effective re-use of persistent
+        connections. HttpCore facilitates the process of connection re-use by providing support
+        for managing pools of persistent HTTP connections. Connection pool implementations
are
+        thread-safe and can be used concurrently by multiple consumers.
+        </para>
+        <para>
+        By default the pool allows only 20 concurrent connections in total and two concurrent
+        connections per a unique route. The two connection limit is due to the requirements
of the
+        HTTP specification. However, in practical terms this can often be too restrictive.
One can
+        change the pool configuration at runtime to allow for more concurrent connections
depending
+        on a particular application context.
+        </para>
+        <programlisting><![CDATA[
+HttpHost target = new HttpHost("localhost");
+BasicConnPool connpool = new BasicConnPool();
+connpool.setMaxTotal(200);
+connpool.setDefaultMaxPerRoute(10);
+connpool.setMaxPerRoute(target, 20);
+Future<BasicPoolEntry> future = connpool.lease(target, null);
+BasicPoolEntry poolEntry = future.get();
+HttpClientConnection conn = poolEntry.getConnection();
+]]></programlisting>
+        <para>
+        Please note that the connection pool has no way of knowing whether or not a leased
+        connection is still being used. It is the responsibility of the connection pool user
+        to ensure that the connection is released back to the pool once it is not longer
needed,
+        even if the connection is not reusable.
+        </para>
+        <programlisting><![CDATA[
+BasicConnPool connpool = <...>
+Future<BasicPoolEntry> future = connpool.lease(target, null);
+BasicPoolEntry poolEntry = future.get();
+try {
+    HttpClientConnection conn = poolEntry.getConnection();
+} finally {
+    connpool.release(poolEntry, conn.isOpen());
+}
+]]></programlisting>
+        <para>
+        The state of the connection pool can be interrogated at runtime.
+        </para>
+        <programlisting><![CDATA[
+HttpHost target = new HttpHost("localhost");
+BasicConnPool connpool = <...>
+PoolStats totalStats = connpool.getTotalStats();
+System.out.println("total available: " + totalStats.getAvailable());
+System.out.println("total leased: " + totalStats.getLeased());
+System.out.println("total pending: " + totalStats.getPending());
+PoolStats targetStats = connpool.getStats(target);
+System.out.println("target available: " + targetStats.getAvailable());
+System.out.println("target leased: " + targetStats.getLeased());
+System.out.println("target pending: " + targetStats.getPending());
+]]></programlisting>
+        <para>
+        Please note that connection pools do not pro-actively evict expired connections.
Even though
+        expired connection cannot be leased to the requester, the pool may accumulate stale
+        connections over time especially after a period of inactivity. It is generally advisable
+        to force eviction of expired and idle connections from the pool after an extensive
period
+        of inactivity.
+        </para>
+        <programlisting><![CDATA[
+BasicConnPool connpool = <...>
+connpool.closeExpired();
+connpool.closeIdle(1, TimeUnit.MINUTES);
+]]></programlisting>
+    </section>
+    <section>
+        <title>TLS/SSL support</title>
+        <para>
+        Blocking connections can be bound to any arbitrary socket. This makes SSL support
quite
+        straight-forward. Any <classname>SSLSocket</classname> instance can be
bound to a blocking
+        connection in order to make all messages transmitted over than connection secured
by
+        TLS/SSL.
+        </para>
+        <programlisting><![CDATA[
+SSLContext sslcontext = SSLContext.getInstance("Default");
+sslcontext.init(null, null, null);
+SocketFactory sf = sslcontext.getSocketFactory();
+SSLSocket socket = (SSLSocket) sf.createSocket("somehost", 443);
+socket.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" });
+DefaultBHttpClientConnection conn = new DefaultBHttpClientConnection(8 * 1204);
+conn.bind(socket);
+]]></programlisting>
+    </section>
 </chapter>

Modified: httpcomponents/httpcore/trunk/src/docbkx/nio-ext.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/src/docbkx/nio-ext.xml?rev=1499798&r1=1499797&r2=1499798&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/src/docbkx/nio-ext.xml (original)
+++ httpcomponents/httpcore/trunk/src/docbkx/nio-ext.xml Thu Jul  4 16:15:23 2013
@@ -23,9 +23,9 @@
 
 -->
 <chapter id="nio">
-    <title>NIO extensions</title>
+    <title>Asynchronous I/O based on NIO</title>
     <section>
-        <title>Differences from other NIO frameworks</title>
+        <title>Differences from other I/O frameworks</title>
         <para>
         Solves similar problems as other frameworks, but has certain distinct features:
         </para>
@@ -81,8 +81,7 @@ IOReactor ioreactor = new DefaultConnect
             events.
             </para>
             <programlisting><![CDATA[
-IOReactorConfig config = IOReactorConfig.DEFAULT;
-IOReactor ioreactor = new DefaultConnectingIOReactor(config);
+IOReactor ioreactor = new DefaultConnectingIOReactor();
 
 IOEventDispatch eventDispatch = <...>
 ioreactor.execute(eventDispatch);
@@ -397,6 +396,31 @@ SessionRequest sessionRequest = ioreacto
         });
 ]]></programlisting>
         </section>
+    </section>
+    <section>
+        <title>I/O reactor configuration</title>
+        <para>
+        I/O reactors by default use system dependent configuration which in most cases should
be
+        sensible enough.
+        </para>
+        <programlisting><![CDATA[
+IOReactorConfig config = IOReactorConfig.DEFAULT;
+IOReactor ioreactor = new DefaultListeningIOReactor(config);
+]]></programlisting>
+        <para>
+        However in some cases custom settings may be necessary, for instance, in order to
alter
+        default socket properties and timeout values. One should rarely need to change other
+        parameters.
+        </para>
+        <programlisting><![CDATA[
+IOReactorConfig config = IOReactorConfig.custom()
+        .setTcpNoDelay(true)
+        .setSoTimeout(5000)
+        .setSoReuseAddress(true)
+        .setConnectTimeout(5000)
+        .build();
+IOReactor ioreactor = new DefaultListeningIOReactor(config);
+]]></programlisting>
         <section>
             <title>Queuing of I/O interest set operations</title>
             <para>
@@ -413,7 +437,6 @@ SessionRequest sessionRequest = ioreacto
 IOReactorConfig config = IOReactorConfig.custom()
         .setInterestOpQueued(true)
         .build();
-ListeningIOReactor ioreactor = new DefaultListeningIOReactor(config);
 ]]></programlisting>
         </section>
     </section>
@@ -1867,6 +1890,62 @@ HttpResponse response = future.get();
         </section>
     </section>
     <section>
+        <title>Non-blocking connection pools</title>
+        <para>
+        Non-blocking connection pools are quite similar to blocking one with one significant
+        distinction that they have to reply an I/O reactor to establish new connections.
+        As a result connections leased from a non-blocking pool are returned fully initialized
and
+        already bound to a particular I/O session. Non-blocking connections managed by a
connection
+        pool cannot be bound to an arbitrary I/O session.
+        </para>
+        <programlisting><![CDATA[
+HttpHost target = new HttpHost("localhost");
+ConnectingIOReactor ioreactor = <...>
+BasicNIOConnPool connpool = new BasicNIOConnPool(ioreactor);
+connpool.lease(target, null,
+        10, TimeUnit.SECONDS,
+        new FutureCallback<BasicNIOPoolEntry>() {
+            @Override
+            public void completed(BasicNIOPoolEntry entry) {
+                NHttpClientConnection conn = entry.getConnection();
+                System.out.println("Connection successfully leased");
+                // Update connection context and request output
+                conn.requestOutput();
+            }
+
+            @Override
+            public void failed(Exception ex) {
+                System.out.println("Connection request failed");
+                ex.printStackTrace();
+            }
+
+            @Override
+            public void cancelled() {
+            }
+        });
+]]></programlisting>
+        <para>
+        Please note due to event-driven nature of asynchronous communication model it is
quite
+        difficult to ensure proper release of persistent connections back to the pool. One
can make
+        use of <classname>HttpAsyncRequester</classname> to handle connection
lease and release
+        behind the scene.
+        </para>
+        <programlisting><![CDATA[
+ConnectingIOReactor ioreactor = <...>
+HttpProcessor httpproc = <...>
+BasicNIOConnPool connpool = new BasicNIOConnPool(ioreactor);
+HttpAsyncRequester requester = new HttpAsyncRequester(httpproc);
+HttpHost target = new HttpHost("localhost");
+Future<HttpResponse> future = requester.execute(
+        new BasicAsyncRequestProducer(
+                new HttpHost("localhost"),
+                new BasicHttpRequest("GET", "/")),
+        new BasicAsyncResponseConsumer(),
+        connpool);
+]]></programlisting>
+    </section>
+
+    <section>
         <title>Non-blocking TLS/SSL</title>
         <section>
             <title>SSL I/O session</title>



Mime
View raw message