You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hc.apache.org by ol...@apache.org on 2013/07/04 18:15:24 UTC
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
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>