Fundamentals

; Thu, 4 Jul 2013 16:15:24 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit 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 -0000 To: commits@hc.apache.org From: olegk@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20130704161524.3D4022388860@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org 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 @@ --> - Fundamentals + HTTP message fundamentals and classic synchronous I/O

HTTP messages

@@ -1067,4 +1067,94 @@ EntityUtils.consume(entity);

+ Connection pools + + 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. + + + 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. + + future = connpool.lease(target, null); +BasicPoolEntry poolEntry = future.get(); +HttpClientConnection conn = poolEntry.getConnection(); +]]> + + 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. + + +Future future = connpool.lease(target, null); +BasicPoolEntry poolEntry = future.get(); +try { + HttpClientConnection conn = poolEntry.getConnection(); +} finally { + connpool.release(poolEntry, conn.isOpen()); +} +]]> + + The state of the connection pool can be interrogated at runtime. + + +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()); +]]> + + 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. + + +connpool.closeExpired(); +connpool.closeIdle(1, TimeUnit.MINUTES); +]]> +

+ TLS/SSL support + + Blocking connections can be bound to any arbitrary socket. This makes SSL support quite + straight-forward. Any SSLSocket instance can be bound to a blocking + connection in order to make all messages transmitted over than connection secured by + TLS/SSL. + + +

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 @@ --> - NIO extensions + Asynchronous I/O based on NIO

- Differences from other NIO frameworks + Differences from other I/O frameworks Solves similar problems as other frameworks, but has certain distinct features: @@ -81,8 +81,7 @@ IOReactor ioreactor = new DefaultConnect events. ioreactor.execute(eventDispatch); @@ -397,6 +396,31 @@ SessionRequest sessionRequest = ioreacto }); ]]>

+ +

+ I/O reactor configuration + + I/O reactors by default use system dependent configuration which in most cases should be + sensible enough. + + + + 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. + +

Queuing of I/O interest set operations @@ -413,7 +437,6 @@ SessionRequest sessionRequest = ioreacto IOReactorConfig config = IOReactorConfig.custom() .setInterestOpQueued(true) .build(); -ListeningIOReactor ioreactor = new DefaultListeningIOReactor(config); ]]>

@@ -1867,6 +1890,62 @@ HttpResponse response = future.get();

+ Non-blocking connection pools + + 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. + + +BasicNIOConnPool connpool = new BasicNIOConnPool(ioreactor); +connpool.lease(target, null, + 10, TimeUnit.SECONDS, + new FutureCallback() { + @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() { + } + }); +]]> + + 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 HttpAsyncRequester to handle connection lease and release + behind the scene. + + +HttpProcessor httpproc = <...> +BasicNIOConnPool connpool = new BasicNIOConnPool(ioreactor); +HttpAsyncRequester requester = new HttpAsyncRequester(httpproc); +HttpHost target = new HttpHost("localhost"); +Future future = requester.execute( + new BasicAsyncRequestProducer( + new HttpHost("localhost"), + new BasicHttpRequest("GET", "/")), + new BasicAsyncResponseConsumer(), + connpool); +]]> +

+ +

Non-blocking TLS/SSL

SSL I/O session