Author: buildbot
Date: Mon Nov 10 16:47:20 2014
New Revision: 928623
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/asynchronous-client-http-transport.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
Modified:
websites/production/cxf/content/docs/asynchronous-client-http-transport.html
==============================================================================
---
websites/production/cxf/content/docs/asynchronous-client-http-transport.html
(original)
+++
websites/production/cxf/content/docs/asynchronous-client-http-transport.html
Mon Nov 10 16:47:20 2014
@@ -116,60 +116,18 @@ Apache CXF -- Asynchronous Client HTTP T
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div id="ConfluenceContent"><h1
id="AsynchronousClientHTTPTransport-AsynchronousClientHTTPTransport">Asynchronous
Client HTTP Transport</h1>
-
-<p>By default, CXF uses a transport based on the in-JDK HttpURLConnection
object to perform HTTP requests. The HttpURLConnection object uses a blocking
model for all IO operations which requires a per-thread execution model. From
a pure performance standpoint, this model generally performs very well, but it
does have problems scaling when many requests need to be executed
simultaneously.</p>
-
-<p>Also, the JAX-WS specification allows for generation of asynchronous
methods on generated proxies as well as using asynchronous methods on the
Dispatch objects. These methods can take an AsyncHandler object and return a
polling Future object so applications do not have to wait for the response.
With the HttpURLConnection based transport, CXF was forced to consume a
background thread for each outstanding request.</p>
-
-<p>CXF also has an HTTP client transport that is based on the <a shape="rect"
class="external-link"
href="http://hc.apache.org/httpcomponents-asyncclient-dev/index.html";>Apache
HTTP Components HttpAsyncClient</a> library. The HttpAsyncClient library uses
a non-blocking IO model. This allows many more requests to be outstanding
without consuming extra background threads. It also allows greater control
over things like Keep-Alive handling which is very difficult or impossible with
the HttpURLConnection based transport. However, the non-blocking model does
not perform quite as well as the blocking model for pure synchronous
request/response transactions.</p>
-
-<p>By default, if the cxf-rt-transports-http-hc module is found on the
classpath, CXF will use the HttpAsyncClient based implementation for any Async
calls, but will continue to use the HttpURLConnection based transport for
synchronous calls. This allows a good balance of performance for the common
synchronous cases with scalability for the asynchronous cases. However, using
a contextual property of "use.async.http.conduit" and set to true/false, you
can control whether the async or blocking version is used. If "true", the
HttpAsyncClient will be used even for synchronous calls, if "false",
asynchronous calls will rely on the traditional method of using
HTTPURLConnection along with a work queue to mimic the asynchronocity.</p>
-
-<h3 id="AsynchronousClientHTTPTransport-SettingCredentials">Setting
Credentials</h3>
-
-<p>The "normal" CXF/JAX-WS method of setting user credentials via the
BindingProvider.USERNAME_PROPERTY/PASSWORD_PROPERTY will work with the Async
transport as well. However, the HttpAsyncClient library does have some
additional capabilities around NTLM that can be leveraged. In order to use
that, you need to:</p>
-
-<ul><li>Turn on the AutoRedirect and turn off the Chunking for the Conduit.
This will allow CXF to cache the response in a manner that will allow the
transport to keep resending the request during the authentication
negotiation.</li></ul>
-
-
-<ul><li>Force the use of the Async transport even for synchronous calls
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
-bp.getRequestContext().put("use.async.http.conduit", Boolean.TRUE);
+<div id="ConfluenceContent"><h1
id="AsynchronousClientHTTPTransport-AsynchronousClientHTTPTransport">Asynchronous
Client HTTP Transport</h1><p>By default, CXF uses a transport based on the
in-JDK HttpURLConnection object to perform HTTP requests. The HttpURLConnection
object uses a blocking model for all IO operations which requires a per-thread
execution model. From a pure performance standpoint, this model generally
performs very well, but it does have problems scaling when many requests need
to be executed simultaneously.</p><p>Also, the JAX-WS specification allows for
generation of asynchronous methods on generated proxies as well as using
asynchronous methods on the Dispatch objects. These methods can take an
AsyncHandler object and return a polling Future object so applications do not
have to wait for the response. With the HttpURLConnection based transport, CXF
was forced to consume a background thread for each outstanding
request.</p><p>CXF also has an HTTP client transport
that is based on the <a shape="rect" class="external-link"
href="http://hc.apache.org/httpcomponents-asyncclient-dev/index.html";>Apache
HTTP Components HttpAsyncClient</a> library. Its Maven artifactId is <span
style="line-height: 1.4285715;">cxf-rt-transports-http-hc.</span><span
style="line-height: 1.4285715;"> The HttpAsyncClient library uses a
non-blocking IO model. This allows many more requests to be outstanding without
consuming extra background threads. It also allows greater control over things
like Keep-Alive handling which is very difficult or impossible with the
HttpURLConnection based transport. However, the non-blocking model does not
perform quite as well as the blocking model for pure synchronous
request/response transactions.</span></p><p>By default, if the
cxf-rt-transports-http-hc module is found on the classpath, CXF will use the
HttpAsyncClient based implementation for any Async calls, but will continue to
use the HttpURLConnection based transport for
synchronous calls. This allows a good balance of performance for the common
synchronous cases with scalability for the asynchronous cases. However, using a
contextual property of "use.async.http.conduit" and set to true/false, you can
control whether the async or blocking version is used. If "true", the
HttpAsyncClient will be used even for synchronous calls, if "false",
asynchronous calls will rely on the traditional method of using
HTTPURLConnection along with a work queue to mimic the
asynchronocity.</p><p>Another reason to use the asynchronous transport is to
use HTTP methods that HttpURLConnection does not support. For example, the
github.com REST API specifies the use of PATCH for some cases, but
HttpURLConnection rejects PATCH.</p><h3
id="AsynchronousClientHTTPTransport-UsingtheHTTPComponentsTransportfromJavaCode">Using
the HTTP Components Transport from Java Code</h3><p>To force global use of the
HTTP Components transport, you can set a bus-level property:</p><div class="cod
e panel pdl" style="border-width: 1px;"><div class="codeContent panelContent
pdl">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[ Bus bus = BusFactory.getDefaultBus();
+ // insist on the async connector to use PATCH.
+ bus.setProperty(AsyncHTTPConduit.USE_ASYNC, Boolean.TRUE);]]></script>
+</div></div><pre><span style="font-size: 16.0px;line-height:
1.5625;font-family: Arial , sans-serif;">Setting Credentials</span></pre><p>The
"normal" CXF/JAX-WS method of setting user credentials via the
BindingProvider.USERNAME_PROPERTY/PASSWORD_PROPERTY will work with the Async
transport as well. However, the HttpAsyncClient library does have some
additional capabilities around NTLM that can be leveraged. In order to use
that, you need to:</p><ul><li>Turn on the AutoRedirect and turn off the
Chunking for the Conduit. This will allow CXF to cache the response in a manner
that will allow the transport to keep resending the request during the
authentication negotiation.</li></ul><ul><li><p>Force the use of the Async
transport even for synchronous calls</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[bp.getRequestContext().put("use.async.http.conduit",
Boolean.TRUE);
]]></script>
-</div></div></li></ul>
-
-
-<ul><li>Set the property "org.apache.http.auth.Credentials" to an instance of
the Credentials. For example:
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
-Credentials creds = new NTCredentials("username", "pswd",
null, "domain");
+</div></div></li></ul><ul><li><p>Set the property
"org.apache.http.auth.Credentials" to an instance of the Credentials. For
example:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[Credentials creds = new
NTCredentials("username", "pswd", null, "domain");
bp.getRequestContext().put(Credentials.class.getName(), creds);
]]></script>
-</div></div></li></ul>
-
-
-
-<h3 id="AsynchronousClientHTTPTransport-Configuration">Configuration </h3>
-<p>The Asynchronous HTTP Transport has several options that can set using Bus
properties or via the OSGi configuration services to control various aspects of
the underlying Apache HTTP Components HttpAsyncClient objects.</p>
-
-<p>Settings related to the underlying TCP socket (see <a shape="rect"
class="external-link"
href="http://docs.oracle.com/javase/7/docs/api/java/net/Socket.html";
rel="nofollow">java.net.Socket</a> for a definition of these values):</p>
-
-<div class="table-wrap"><table class="confluenceTable"><tbody><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.TCP_NODELAY
(Default true)</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.SO_KEEPALIVE</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.SO_LINGER</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.SO_TIMEOUT</p></td></tr></tbody></table></div>
-
-
-<p>Settings related to Keep-Alive connection management:</p>
-
-<div class="table-wrap"><table class="confluenceTable"><tbody><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.CONNECTION_TTL</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> Maximum time a connection is
held open in ms. Default is 60000. </p></td></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.MAX_CONNECTIONS</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> Maximum number of connections
opened per host. Default is 1000. </p></td></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.MAX_PER_HOST_CONNECTIONS</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> Maximum number of connections
opened in total. Default is 5000. </p></td></tr></tbody></table></div>
-
-
-<p>Settings related to Apache HttpAsyncClient threads and selectors:</p>
-<div class="table-wrap"><table class="confluenceTable"><tbody><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.ioThreadCount</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> Number of threads
HttpAsyncClient uses to process IO events. Default is "-1" which means one
thread per CPU core.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.interestOpQueued</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> true/false for whether the
interest ops are queues or process directly.</p></td></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.selectInterval</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> Default 1000 ms. How often
the selector thread wakes up if there are no events to process additional
things like queue expirations.</p></td></tr></tbody></table></div>
-
-
-<p>Setting to control which conduit is used</p>
-<div class="table-wrap"><table class="confluenceTable"><tbody><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.usePolicy</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> ALWAYS, ASYNC_ONLY, NEVER.
</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> Similar in
meaning to the "use.async.http.conduit" context property described above.
Whether to use the HttpAsyncClient: ALWAYS for both synchronous and
asynchronous calls, ASYNC_ONLY (default) for asynchronous calls only, NEVER
will use HTTPURLConnection for both types of
calls.</p></td></tr></tbody></table></div></div>
+</div></div></li></ul><h3
id="AsynchronousClientHTTPTransport-Configuration">Configuration</h3><p>The
Asynchronous HTTP Transport has several options that can set using Bus
properties or via the OSGi configuration services to control various aspects of
the underlying Apache HTTP Components HttpAsyncClient objects.</p><p>Settings
related to the underlying TCP socket (see <a shape="rect" class="external-link"
href="http://docs.oracle.com/javase/7/docs/api/java/net/Socket.html";
rel="nofollow">java.net.Socket</a> for a definition of these values):</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.TCP_NODELAY
(Default true)</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.SO_KEEPALIVE</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.SO_LINGER</p></td></tr><tr><td
colspan="
1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.SO_TIMEOUT</p></td></tr></tbody></table></div><p>Settings
related to Keep-Alive connection management:</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.CONNECTION_TTL</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Maximum time a connection is
held open in ms. Default is 60000.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.MAX_CONNECTIONS</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Maximum number of connections
opened per host. Default is 1000.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.MAX_PER_HOST_CONNECTIONS</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Maximum number of connections
opened in total. Default is 5000.</p></td></tr></tbody></t
able></div><p>Settings related to Apache HttpAsyncClient threads and
selectors:</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.ioThreadCount</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Number of threads
HttpAsyncClient uses to process IO events. Default is "-1" which means one
thread per CPU core.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.interestOpQueued</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>true/false for whether the
interest ops are queues or process directly.</p></td></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.selectInterval</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Default 1000 ms. How often the
selector thread wakes up if there are no events to process additional things
like queue expirations.</p></t
d></tr></tbody></table></div><p>Setting to control which conduit is
used</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.usePolicy</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>ALWAYS, ASYNC_ONLY,
NEVER.</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Similar in
meaning to the "use.async.http.conduit" context property described above.
Whether to use the HttpAsyncClient: ALWAYS for both synchronous and
asynchronous calls, ASYNC_ONLY (default) for asynchronous calls only, NEVER
will use HTTPURLConnection for both types of
calls.</p></td></tr></tbody></table></div></div>
</div>
<!-- Content -->
</td>
