cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r990194 - in /websites/production/cxf/content: cache/docs.pageCache docs/jax-rs-client-api.html
Date Wed, 08 Jun 2016 14:47:32 GMT
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>&#160;</p><p>&#160;</p><p>&#160;</p><p>&#160;</p><p>&#160;<span
class="inline-first-p" style="font-size:2em;font-weight:bold">JAX-RS : Client API</span>&#160;</p><p>&#160;</p><p>&#160;</p><p>&#160;</p><p>&#160;</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
          &lt;/jaxrs:headers&gt;
   &lt;/jaxrs:client&gt;  
 </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()&#160; 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>&#160;</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&#160;JAX-RS 2.0&#160;<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>&#160;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&lt;Book&gt; callback = new InvocationCallback&lt;Book&gt;()
{
+  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&lt;Book&gt; bookCallback = new InvocationCallback&lt;Book&gt;()
{
+  public void completed(Book response) {
+     book = response;
+  }
+  public void failed(Throwable error) {
+  }
+};
+// Chapter
+Chapter chapter = null;
+final InvocationCallback&lt;Chapter&gt; chapterCallback = new InvocationCallback&lt;Chapter&gt;()
{
+  public void completed(Chapter response) {
+     chapter = response;
+  }
+  public void failed(Throwable error) {
+  }
+};
+&#160;
+WebClient.getConfig(proxy).getRequestContext().put(InvocationCallback.class.getName(),&#160;
+                                                   Arrays.asList(bookCallback, chapterCallback));
+// Get Book
+assertNull(proxy.getBook(123L));
+Thread.sleep(3);
+assertNotNull(book);
+&#160;
+// 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()&#160;
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>&#160;</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">



Mime
View raw message