Author: buildbot
Date: Wed Jun 8 14:47:32 2016
New Revision: 990194
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/jax-rs-client-api.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/cxf/content/docs/jax-rs-client-api.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-client-api.html (original)
+++ websites/production/cxf/content/docs/jax-rs-client-api.html Wed Jun 8
14:47:32 2016
@@ -118,15 +118,15 @@ Apache CXF -- JAX-RS Client API
<!-- Content -->
<div class="wiki-content">
<div
id="ConfluenceContent"><p> </p><p> </p><p> </p><p> </p><p> <span
class="inline-first-p" style="font-size:2em;font-weight:bold">JAX-RS : Client
API</span> </p><p> </p><p> </p><p> </p><p> </p><p><style
type="text/css">/*<![CDATA[*/
-div.rbtoc1443185217131 {padding: 0px;}
-div.rbtoc1443185217131 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1443185217131 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1465397218049 {padding: 0px;}
+div.rbtoc1465397218049 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1465397218049 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1443185217131">
+/*]]>*/</style></p><div class="toc-macro rbtoc1465397218049">
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSClientAPI-MavenDependency">Maven Dependency</a></li><li><a
shape="rect" href="#JAX-RSClientAPI-JAX-RS2.0ClientAPI">JAX-RS 2.0 Client
API</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSClientAPI-JAX-RS2.0andCXFspecificAPI">JAX-RS 2.0 and CXF specific
API</a></li></ul>
</li><li><a shape="rect" href="#JAX-RSClientAPI-Proxy-basedAPI">Proxy-based
API</a>
-<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSClientAPI-Customizingproxies">Customizing proxies</a></li><li><a
shape="rect"
href="#JAX-RSClientAPI-ConvertingproxiestoWebClientsandviceversa">Converting
proxies to Web Clients and vice versa</a></li><li><a shape="rect"
href="#JAX-RSClientAPI-Handlingexceptions">Handling exceptions</a></li><li><a
shape="rect" href="#JAX-RSClientAPI-ConfiguringproxiesinSpring">Configuring
proxies in Spring</a></li><li><a shape="rect"
href="#JAX-RSClientAPI-Injectingproxies">Injecting proxies</a></li><li><a
shape="rect" href="#JAX-RSClientAPI-BufferingResponses">Buffering
Responses</a></li><li><a shape="rect"
href="#JAX-RSClientAPI-Limitations">Limitations</a></li><li><a shape="rect"
href="#JAX-RSClientAPI-Workingwithusermodels">Working with user
models</a></li></ul>
+<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSClientAPI-Customizingproxies">Customizing proxies</a></li><li><a
shape="rect"
href="#JAX-RSClientAPI-ConvertingproxiestoWebClientsandviceversa">Converting
proxies to Web Clients and vice versa</a></li><li><a shape="rect"
href="#JAX-RSClientAPI-Handlingexceptions">Handling exceptions</a></li><li><a
shape="rect" href="#JAX-RSClientAPI-ConfiguringproxiesinSpring">Configuring
proxies in Spring</a></li><li><a shape="rect"
href="#JAX-RSClientAPI-Injectingproxies">Injecting proxies</a></li><li><a
shape="rect" href="#JAX-RSClientAPI-Asynchronousproxyinvocations">Asynchronous
proxy invocations</a></li><li><a shape="rect"
href="#JAX-RSClientAPI-BufferingResponses">Buffering Responses</a></li><li><a
shape="rect" href="#JAX-RSClientAPI-Limitations">Limitations</a></li><li><a
shape="rect" href="#JAX-RSClientAPI-Workingwithusermodels">Working with user
models</a></li></ul>
</li><li><a shape="rect" href="#JAX-RSClientAPI-CXFWebClientAPI">CXF WebClient
API</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSClientAPI-Asynchronousinvocations">Asynchronous
invocations</a></li><li><a shape="rect"
href="#JAX-RSClientAPI-Workingwithexplicitcollections">Working with explicit
collections</a></li><li><a shape="rect"
href="#JAX-RSClientAPI-Handlingexceptions.1">Handling exceptions</a></li><li><a
shape="rect" href="#JAX-RSClientAPI-ConfiguringHTTPclientsinSpring">Configuring
HTTP clients in Spring</a></li></ul>
</li><li><a shape="rect"
href="#JAX-RSClientAPI-XML-centricclients">XML-centric clients</a></li><li><a
shape="rect"
href="#JAX-RSClientAPI-SupportforarbitraryHTTPmethodsforsyncinvocations.">Support
for arbitrary HTTP methods for sync invocations.</a></li><li><a shape="rect"
href="#JAX-RSClientAPI-ThreadSafety">Thread Safety</a></li><li><a shape="rect"
href="#JAX-RSClientAPI-ConfiguringClientsatRuntime">Configuring Clients at
Runtime</a></li><li><a shape="rect"
href="#JAX-RSClientAPI-CreatingclientsprogrammaticallywithnoSpringdependencies">Creating
clients programmatically with no Spring dependencies</a></li><li><a
shape="rect"
href="#JAX-RSClientAPI-ConfiguringanHTTPConduitfromSpring">Configuring an HTTP
Conduit from Spring</a></li><li><a shape="rect"
href="#JAX-RSClientAPI-ClientsandAuthentication">Clients and
Authentication</a></li></ul>
@@ -232,20 +232,57 @@ BookStore proxy = JAXRSClientFactory.cre
</jaxrs:headers>
</jaxrs:client>
</pre>
-</div></div><p>See this <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/resources/jaxrs_soap_rest/WEB-INF/beans.xml";>bean</a>
for a full example of how jaxrs:client can be used to inject a proxy</p><h2
id="JAX-RSClientAPI-BufferingResponses">Buffering Responses</h2><p>One way to
buffer proxy responses is to have a proxy method return JAX-RS Response, use
its bufferEntity()  method (available in JAX-RS 2.0) and use
Response.readEntity which can return typed responses if preferred.</p><p>The
other option is to have a "buffer.proxy.response" property enabled on a given
proxy instance.</p><h2
id="JAX-RSClientAPI-Limitations">Limitations</h2><p>Proxy sub-resource methods
returning Objects can not be invoked. Prefer to have sub-resource methods
returning typed classes: interfaces, abstract classes or concrete
implementations.</p><p><strong>The following applies to CXF 2.6.x-2.4.x
only</strong>:</p><p>When a proxy method re
turning a JAX-RS Response is invoked, the returned Response.getEntity() will
return a response InputStream by default. Starting with CXF 2.3.2 one can
register an org.apache.cxf.jaxrs.client.ResponseReader provider and cast the
Response.getEntity() to more specific application classes:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">ResponseReader reader = new ResponseReader();
-reader.setEntityClass(Book.class);
-
-BookStore bs = JAXRSClientFactory.create("http://localhost:8080/books";,
BookStore.class,
- Collections.singletonList(reader));
-Response r1 = bs.getBook("123");
-Book book = (Book)r1.getEntity();
-
-reader.setEntityClass(Author.class);
-Response r2 = bs.getBookAuthor("123");
-Author book = (Author)r2.getEntity();
-</pre>
-</div></div><h2 id="JAX-RSClientAPI-Workingwithusermodels">Working with user
models</h2><p>Proxies can be created with the external user model being applied
to a proxy class, for example:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>See this <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/resources/jaxrs_soap_rest/WEB-INF/beans.xml";>bean</a>
for a full example of how jaxrs:client can be used to inject a proxy. Note
that WebClient can also be injected as a jaxrs:client.</p><p> </p><h2
id="JAX-RSClientAPI-Asynchronousproxyinvocations">Asynchronous proxy
invocations</h2><p>Starting from CXF 3.1.7 it is possible to do the
asynchronous proxy invocations. One needs to register JAX-RS 2.0 <a
shape="rect" class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/client/InvocationCallback.html";
rel="nofollow">InvocationCallback</a> as a proxy request context
property:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">BookStore proxy =
JAXRSClientFactory.create("http://books";, BookStore.class);
+
+Book book = null;
+final InvocationCallback<Book> callback = new
InvocationCallback<Book>() {
+ public void completed(Book response) {
+ book = response;
+ }
+ public void failed(Throwable error) {
+ }
+};
+
+
+WebClient.getConfig(proxy).getRequestContext().put(InvocationCallback.class.getName(),
callback);
+assertNull(proxy.getBook());
+Thread.sleep(3);
+assertNotNull(book);</pre>
+</div></div><p>If you have a proxy with different methods returning different
response types then either register an Object bound InvocationCallback or
register a collection of type-specific callbacks:</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">BookStore proxy =
JAXRSClientFactory.create("http://books";, BookStore.class);
+
+// Book
+Book book = null;
+final InvocationCallback<Book> bookCallback = new
InvocationCallback<Book>() {
+ public void completed(Book response) {
+ book = response;
+ }
+ public void failed(Throwable error) {
+ }
+};
+// Chapter
+Chapter chapter = null;
+final InvocationCallback<Chapter> chapterCallback = new
InvocationCallback<Chapter>() {
+ public void completed(Chapter response) {
+ chapter = response;
+ }
+ public void failed(Throwable error) {
+ }
+};
+ 
+WebClient.getConfig(proxy).getRequestContext().put(InvocationCallback.class.getName(), 
+ Arrays.asList(bookCallback,
chapterCallback));
+// Get Book
+assertNull(proxy.getBook(123L));
+Thread.sleep(3);
+assertNotNull(book);
+ 
+// Get Book Chapter
+assertNull(proxy.getBookChapter(123L));
+Thread.sleep(3);
+assertNotNull(chapter);</pre>
+</div></div><p>Make sure a proxy is created in a thread safe mode if it is
being accessed by multiple threads for every new request thread to have its own
callback.</p><h2 id="JAX-RSClientAPI-BufferingResponses">Buffering
Responses</h2><p>One way to buffer proxy responses is to have a proxy method
return JAX-RS Response, use its bufferEntity()  method (available in
JAX-RS 2.0) and use Response.readEntity which can return typed responses if
preferred.</p><p>The other option is to have a "buffer.proxy.response" property
enabled on a given proxy instance.</p><h2
id="JAX-RSClientAPI-Limitations">Limitations</h2><p>Proxy sub-resource methods
returning Objects can not be invoked. Prefer to have sub-resource methods
returning typed classes: interfaces, abstract classes or concrete
implementations.</p><p> </p><h2
id="JAX-RSClientAPI-Workingwithusermodels">Working with user
models</h2><p>Proxies can be created with the external user model being applied
to a proxy class, for example
:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">JAXRSClientFactory.createFromModel("http://books";,
BookNoAnnotations.class, "classpath:/resources/model.xml", null);
</pre>
</div></div><p>BookNoAnnotations is either an interface or concrete class with
no JAX-RS annotations. Both client proxies and server endpoints can 'turn' it
into a RESTful resource by applying an external user model.</p><h1
id="JAX-RSClientAPI-CXFWebClientAPI">CXF WebClient API</h1><p>HTTP centric
clients are <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/client/WebClient.java";>WebClient</a>
instances which also implement the <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/client/Client.java";>Client</a>
interface. In addition to setting various Client request properties, you can
also make an explicit HTTP invocation with an HTTP verb being the name of a
given operation :</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
