You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cxf.apache.org by bu...@apache.org on 2018/03/22 00:07:45 UTC
svn commit: r1027112 - in /websites/production/cxf/content:
cache/docs.pageCache docs/jax-rs-basics.html
docs/jax-rs-project-reactor-support.html docs/jax-rs.html
Author: buildbot
Date: Thu Mar 22 00:07:45 2018
New Revision: 1027112
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/jax-rs-basics.html
websites/production/cxf/content/docs/jax-rs-project-reactor-support.html
websites/production/cxf/content/docs/jax-rs.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/cxf/content/docs/jax-rs-basics.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-basics.html (original)
+++ websites/production/cxf/content/docs/jax-rs-basics.html Thu Mar 22 00:07:45 2018
@@ -32,9 +32,9 @@
<link type="text/css" rel="stylesheet" href="/resources/highlighter/styles/shThemeCXF.css">
<script src='/resources/highlighter/scripts/shCore.js'></script>
-<script src='/resources/highlighter/scripts/shBrushBash.js'></script>
-<script src='/resources/highlighter/scripts/shBrushXml.js'></script>
<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
+<script src='/resources/highlighter/scripts/shBrushXml.js'></script>
+<script src='/resources/highlighter/scripts/shBrushBash.js'></script>
<script>
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -122,14 +122,14 @@ Apache CXF -- JAX-RS Basics
 </p><p> </p><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1508777414809 {padding: 0px;}
-div.rbtoc1508777414809 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1508777414809 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1521676929778 {padding: 0px;}
+div.rbtoc1521676929778 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1521676929778 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1508777414809">
+/*]]>*/</style></p><div class="toc-macro rbtoc1521676929778">
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSBasics-WhatisNewinJAX-RS2.1">What is New in JAX-RS 2.1</a>
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSBasics-ReactiveClientAPI">Reactive Client API</a>
-<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSBasics-CompletionStage">CompletionStage</a></li><li><a shape="rect" href="#JAX-RSBasics-RxJava">RxJava</a></li></ul>
+<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSBasics-CompletionStage">CompletionStage</a></li><li><a shape="rect" href="#JAX-RSBasics-RxJava">RxJava</a></li><li><a shape="rect" href="#JAX-RSBasics-RxJava2">RxJava2</a></li><li><a shape="rect" href="#JAX-RSBasics-ProjectReactor">Project Reactor</a></li></ul>
</li><li><a shape="rect" href="#JAX-RSBasics-CompletableFutureasamethodreturnvalue">CompletableFuture as a method return value</a></li><li><a shape="rect" href="#JAX-RSBasics-ServerSentEvents">Server Sent Events</a></li><li><a shape="rect" href="#JAX-RSBasics-SubResourcesasClasses">SubResources as Classes</a></li><li><a shape="rect" href="#JAX-RSBasics-CXFNIOExtension">CXF NIO Extension</a></li></ul>
</li><li><a shape="rect" href="#JAX-RSBasics-WhatisNewinJAX-RS2.0">What is New in JAX-RS 2.0</a>
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSBasics-Filters">Filters</a>
@@ -152,7 +152,7 @@ div.rbtoc1508777414809 li {margin-left:
</li><li><a shape="rect" href="#JAX-RSBasics-MessageBodyProviders">Message Body Providers</a>
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSBasics-CustomMessageBodyProviders">Custom Message Body Providers</a></li><li><a shape="rect" href="#JAX-RSBasics-Registeringcustomproviders">Registering custom providers</a></li></ul>
</li><li><a shape="rect" href="#JAX-RSBasics-Customizingmediatypesformessagebodyproviders">Customizing media types for message body providers</a></li><li><a shape="rect" href="#JAX-RSBasics-AdvancedHTTP">Advanced HTTP</a></li></ul>
-</div><h1 id="JAX-RSBasics-WhatisNewinJAX-RS2.1">What is New in JAX-RS 2.1</h1><h2 id="JAX-RSBasics-ReactiveClientAPI">Reactive Client API</h2><p>JAX-RS 2.1 introduces <a shape="rect" class="external-link" href="https://github.com/jax-rs/api/blob/master/jaxrs-api/src/main/java/javax/ws/rs/client/RxInvoker.java" rel="nofollow">RxInvoker</a> which can help with removing <a shape="rect" class="external-link" href="https://github.com/jax-rs/api/blob/master/jaxrs-api/src/main/java/javax/ws/rs/client/InvocationCallback.java" rel="nofollow">InvocationCallback</a>s from the asynchronous client code. </p><h3 id="JAX-RSBasics-CompletionStage">CompletionStage</h3><p>Default <a shape="rect" class="external-link" href="https://github.com/jax-rs/api/blob/master/jaxrs-api/src/main/java/javax/ws/rs/client/CompletionStageRxInvoker.java" rel="nofollow">CompletionStageRxInvoker</a> can be accessed via <a shape="rect" class="external-link" href="https://github.com/jax-rs/api/blob/master/jaxrs-api/
src/main/java/javax/ws/rs/client/RxInvoker.java" rel="nofollow">Invocation.rx()</a>.</p><h3 id="JAX-RSBasics-RxJava">RxJava</h3><p>Custom <a shape="rect" class="external-link" href="https://github.com/jax-rs/api/blob/master/jaxrs-api/src/main/java/javax/ws/rs/client/RxInvokerProvider.java" rel="nofollow">RxInvokerProvider</a> can be registered with the Client as a provider. CXF ships one three such custom providers, org.apache.cxf.jaxrs.rx.client.ObservableRxInvokerProvider (RxJava1),</p><p>org.apache.cxf.jaxrs.rx2.client.ObservableRxInvokerProvider (RxJava2) and org.apache.cxf.jaxrs.rx2.client.FlowableRxInvokerProvider (RxJava2).</p><p>Registering it with the Client allows for working with RxJava1 Observable or RxJava2 Observable or Flowable by doing <a shape="rect" class="external-link" href="https://github.com/jax-rs/api/blob/master/jaxrs-api/src/main/java/javax/ws/rs/client/Invocation.java#L312" rel="nofollow">Invocation.rx(Class<T> clazz)</a>, example,</p><p>Inv
ocation.rx(org.apache.cxf.jaxrs.rx2.client.FlowableRxInvoker.class), etc.</p><p>Please see <a shape="rect" href="jax-rs-rxjava.html">JAX-RS RxJava</a> for more information.</p><h2 id="JAX-RSBasics-CompletableFutureasamethodreturnvalue">CompletableFuture as a method return value</h2><p>In JAX-RS 2.1 one can return CompletableFuture (or CompletionStage) from a resource method without having to deal directly with JAX-RS AsyncResponse API. </p><p>Please see <a shape="rect" href="jax-rs-rxjava.html">JAX-RS RxJava</a> for more information about returning RxJava Observable.</p><h2 id="JAX-RSBasics-ServerSentEvents">Server Sent Events</h2><p>JAX-RS 2.1 provides a <a shape="rect" class="external-link" href="https://github.com/jax-rs/api/tree/master/examples/src/main/java/jaxrs/examples/sse" rel="nofollow">comprehensive support</a> for <a shape="rect" class="external-link" href="https://en.wikipedia.org/wiki/Server-sent_events" rel="nofollow">SSE</a>.</p><p>org.apache.cxf/cxf-rt-rs-
sse/3.2.0 dependency will need to be added. CXF SSE implementation currently depends on Atmosphere.</p><h2 id="JAX-RSBasics-SubResourcesasClasses">SubResources as Classes</h2><p>Sometimes subresource may need to have the request context information available to them. One valid and simple approach is to pass these contexts to them from the parent class which instantiates a subresource - but sometimes this approach does not work.</p><p>In JAX-RS 2.0 one can use <a shape="rect" class="external-link" href="https://github.com/jax-rs/api/blob/master/jaxrs-api/src/main/java/javax/ws/rs/container/ResourceContext.java" rel="nofollow">ResourceContext</a> to instantiate a subresource instance with the runtime taking care of injecting the contexts if needed. JAX-RS 2.1 introduces a shortcut where returning a subresource class from a subresource locator method, with the runtime istantiating the class and injecting the contexts if needed</p><h2 id="JAX-RSBasics-CXFNIOExtension">CXF NIO Extension<
/h2><p>Please see <a shape="rect" href="jax-rs-nio.html">JAX-RS NIO</a> for more information about this CXF 3.2.0 extension which is based on the early JAX-RS 2.1 API prototype.</p><h1 id="JAX-RSBasics-WhatisNewinJAX-RS2.0">What is New in JAX-RS 2.0</h1><h2 id="JAX-RSBasics-Filters">Filters</h2><h3 id="JAX-RSBasics-Server">Server</h3><p><a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/container/ContainerRequestFilter.html" rel="nofollow">ContainerRequestFilter</a> and <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/container/ContainerResponseFilter.html" rel="nofollow">ContainerResponseFilter</a> are new server-side request and response filters which can be used to customize various properties of a given request and response.</p><p>ContainerRequestFilter annotated with a <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/container/PreMatching.html" rel="
nofollow">PreMatching</a> annotation will be run before the runtime has matched a request to a specific JAX-RS root resource and method. Prematching filters can be used to affect the matching process.</p><p>The request filters without the PreMatching annotation will run after the JAX-RS resource method has been selected.</p><p>ContainerRequestFilter can be used to <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/container/ContainerRequestContext.html#abortWith(javax.ws.rs.core.Response)" rel="nofollow">block</a> a request.</p><p>The filters can be bound to individual resource methods only with the help of custom <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/NameBinding.html" rel="nofollow">NameBinding</a>s.</p><p>Multiple request and response filters can be executed in the specific order by using javax.annotation.Priority annotations. See <a shape="rect" class="external-link" href="https://jax
-rs.github.io/apidocs/2.0/javax/ws/rs/Priorities.html" rel="nofollow">Priorities</a> for more information. Request filters are sorted in the ascending order, response filters - in the descending order.</p><h3 id="JAX-RSBasics-Client">Client</h3><p><a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/client/ClientRequestFilter.html" rel="nofollow">ClientRequestFilter</a> and <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/client/ClientResponseFilter.html" rel="nofollow">ClientResponseFilter</a> are new client-side request and response filters which can be used to customize various properties of a given request and response.</p><p>ClientRequestFilter can be used to <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/client/ClientRequestContext.html#abortWith(javax.ws.rs.core.Response)" rel="nofollow">block</a> a request.</p><p>Request filters are sorted in the
ascending order, response filters - in the descending order. See <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/Priorities.html" rel="nofollow">Priorities</a> for more information.</p><h2 id="JAX-RSBasics-Interceptors">Interceptors</h2><p><a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/ext/ReaderInterceptor.html" rel="nofollow">ReaderInterceptor</a> and <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/ext/WriterInterceptor.html" rel="nofollow">WriterInterceptor</a> can be used in addition to filters or on its own to customize requests and responses on server and client sides.</p><p>Interceptors can be useful to customize the reading/writing process and block JAX-RS MessageBodyWriter or MessageBodyReader providers.</p><p>The interceptors used on the server side can be bound to individual resource methods only with the help of custom <a shape="rect" cl
ass="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/NameBinding.html" rel="nofollow">NameBinding</a>s.</p><p>All interceptors are sorted in the ascending order. See <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/Priorities.html" rel="nofollow">Priorities</a> for more information.</p><h2 id="JAX-RSBasics-DynamicFeatures">Dynamic Features</h2><p><a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/container/DynamicFeature.html" rel="nofollow">Dynamic Feature</a> is a server side feature that can be used to attach request and response filters as well as reader and writer interceptors to specific resource methods. It is an alternative approach to using the NameBindings and offer a finer-grained control over the binding process.</p><h2 id="JAX-RSBasics-Exceptions">Exceptions</h2><p>Dedicated exception classes representing various HTTP error or redirect conditions have been introdu
ced, see the 'javax.ws.rs' Package <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/package-frame.html" rel="nofollow">Exceptions section</a>.</p><p>For example, instead of throwing a "new WebApplicationException(404)" one is better to do "new NotFoundException()". The finer-grained exception hierarchy allows for a finer-grained support of exception mappers. It also opens a way to check WebApplicationException and all of its subclasses when catching the HTTP exceptions on the client side.</p><p>Note that on the client side, ProcessingException can be used to catch client-related exceptions while ResponseProcessingException can be used to narrow down the client side exceptions specifically related to processing the response message.</p><h2 id="JAX-RSBasics-Suspendedinvocations">Suspended invocations</h2><p>One of the best JAX-RS 2.0 features is the support for server-side asynchronous invocations. Please see the <a shape="rect" class="exter
nal-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/container/AsyncResponse.html" rel="nofollow">AsyncResponse</a> documentation which provides a very good overview of this feature.</p><p>See also this <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/BookContinuationStore.java" rel="nofollow">test resource</a>.</p><p>Typically, the resource method accepting AsyncResponse will either store it and start a new thread to finish the request, the method will return and the invocation will be suspended, then eventually another thread (either the one which initiated an internal job or some other thread) will resume the suspended call. Note in this case the invocation will be suspended indefinitely until it is resumed.</p><p>Another approach is to have AsyncResponse suspended for a limited period of time only and also register a <a shape="rect" class="external-link" href="https://jax-r
s.github.io/apidocs/2.0/javax/ws/rs/container/TimeoutHandler.html" rel="nofollow">TimeoutHandler</a>. The latter will be invoked when the invocation is resumed by the container after the timeout has expired and the handler will either complete the invocation or suspend it again till it is ready to finish it.</p><p><a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/container/CompletionCallback.html" rel="nofollow">CompletionCallback</a> can be registered with AsyncResponse to receive the notifications when the async response has been sent back.</p><p><a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/container/ConnectionCallback.html" rel="nofollow">ConnectionCallback</a> is supported starting from CXF 3.0.0-milestone2.</p><p>This feature can help developers write very sophisticated asynchronous applications.</p><p>Please also see the page about CXF <a shape="rect" href="continuations.html">Continuati
ons</a> API which JAX-RS 2.0 AsyncResponse implementation is based upon and <br clear="none"> <a shape="rect" href="http://cxf.apache.org/docs/servlet-transport.html">how to configure</a> CXFServlet.</p><h2 id="JAX-RSBasics-Parameterconverters">Parameter converters</h2><p><a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/ext/ParamConverterProvider.html" rel="nofollow">ParamConverterProvider</a> can be used to manage the conversion of custom Objects to String and vice versa on the server and client sides, when processing JAX-RS parameters representing URI parts or headers or form elements and when a default conversion mechanism does not work. For example, java.util.Date constructor accepting a String may have to be replaced a custom ParamConverter.</p><h2 id="JAX-RSBasics-Beanparameters">Bean parameters</h2><p><a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/BeanParam.html" rel="nofollow">BeanParam
</a> can be used to get JAX-RS parameters representing URI parts or headers or form elements and also contexts injected into a single bean container.</p><p>Note the CXF extension supporting the injection of all the parameters of specific JAX-RS type (example, QueryParam("") MyBean) is different, it only allows to get all the query parameters injected, but it also does not require that bean properties are annotated with QueryParam/etc annotations.</p><h2 id="JAX-RSBasics-ResourceInfo">ResourceInfo</h2><p><a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/container/ResourceInfo.html" rel="nofollow">ResourceInfo</a> is a new JAX-RS context which can be injected into filters and interceptors and checked which resource class and method are about to be invoked.</p><h2 id="JAX-RSBasics-Injectionintosubresources">Injection into subresources</h2><p>Subresources can get JAX-RS contexts injected directly into their fields with the help of <a shape="rec
t" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/container/ResourceContext.html" rel="nofollow">ResourceContext</a>.</p><p>When possible, having a parent resource injecting the contexts into a given subresource instance via a setter or constructor can offer a much simpler alternative.</p><h2 id="JAX-RSBasics-Updatestothematchingalgorithm">Updates to the matching algorithm</h2><p>JAX-RS 2.0 supports a proper resource method selection in cases where multiple root resource classes have the same Path value, for example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div><h1 id="JAX-RSBasics-WhatisNewinJAX-RS2.1">What is New in JAX-RS 2.1</h1><h2 id="JAX-RSBasics-ReactiveClientAPI">Reactive Client API</h2><p>JAX-RS 2.1 introduces <a shape="rect" class="external-link" href="https://github.com/jax-rs/api/blob/master/jaxrs-api/src/main/java/javax/ws/rs/client/RxInvoker.java" rel="nofollow">RxInvoker</a> which can help with removing <a shape="rect" class="external-link" href="https://github.com/jax-rs/api/blob/master/jaxrs-api/src/main/java/javax/ws/rs/client/InvocationCallback.java" rel="nofollow">InvocationCallback</a>s from the asynchronous client code. </p><h3 id="JAX-RSBasics-CompletionStage">CompletionStage</h3><p>Default <a shape="rect" class="external-link" href="https://github.com/jax-rs/api/blob/master/jaxrs-api/src/main/java/javax/ws/rs/client/CompletionStageRxInvoker.java" rel="nofollow">CompletionStageRxInvoker</a> can be accessed via <a shape="rect" class="external-link" href="https://github.com/jax-rs/api/blob/master/jaxrs-api/
src/main/java/javax/ws/rs/client/RxInvoker.java" rel="nofollow">Invocation.rx()</a>.</p><h3 id="JAX-RSBasics-RxJava">RxJava</h3><p>Custom <a shape="rect" class="external-link" href="https://github.com/jax-rs/api/blob/master/jaxrs-api/src/main/java/javax/ws/rs/client/RxInvokerProvider.java" rel="nofollow">RxInvokerProvider</a> can be registered with the Client as a provider. CXF ships one three such custom providers, org.apache.cxf.jaxrs.rx.client.ObservableRxInvokerProvider (RxJava1),</p><p>org.apache.cxf.jaxrs.rx2.client.ObservableRxInvokerProvider (RxJava2) and org.apache.cxf.jaxrs.rx2.client.FlowableRxInvokerProvider (RxJava2).</p><p>Registering it with the Client allows for working with RxJava1 Observable or RxJava2 Observable or Flowable by doing <a shape="rect" class="external-link" href="https://github.com/jax-rs/api/blob/master/jaxrs-api/src/main/java/javax/ws/rs/client/Invocation.java#L312" rel="nofollow">Invocation.rx(Class<T> clazz)</a>, example,</p><p>Inv
ocation.rx(org.apache.cxf.jaxrs.rx2.client.FlowableRxInvoker.class), etc.</p><p>Please see <a shape="rect" href="jax-rs-rxjava.html">JAX-RS RxJava</a> for more information.</p><h3 id="JAX-RSBasics-RxJava2">RxJava2</h3><p>RxJava2 can be used as a rx type when registered.  Please see <a shape="rect" href="jax-rs-rxjava.html">JAX-RS RxJava</a> for full information.</p><h3 id="JAX-RSBasics-ProjectReactor">Project Reactor</h3><p>Project Reactor can be used as a rx type when registered.  Please see <a shape="rect" href="jax-rs-project-reactor-support.html">JAX-RS Project Reactor Support</a> for full information.</p><h2 id="JAX-RSBasics-CompletableFutureasamethodreturnvalue">CompletableFuture as a method return value</h2><p>In JAX-RS 2.1 one can return CompletableFuture (or CompletionStage) from a resource method without having to deal directly with JAX-RS AsyncResponse API. </p><p>Please see <a shape="rect" href="jax-rs-rxjava.html">JAX-RS RxJava</a> for
more information about returning RxJava Observable.</p><h2 id="JAX-RSBasics-ServerSentEvents">Server Sent Events</h2><p>JAX-RS 2.1 provides a <a shape="rect" class="external-link" href="https://github.com/jax-rs/api/tree/master/examples/src/main/java/jaxrs/examples/sse" rel="nofollow">comprehensive support</a> for <a shape="rect" class="external-link" href="https://en.wikipedia.org/wiki/Server-sent_events" rel="nofollow">SSE</a>.</p><p>org.apache.cxf/cxf-rt-rs-sse/3.2.0 dependency will need to be added. CXF SSE implementation currently depends on Atmosphere.</p><h2 id="JAX-RSBasics-SubResourcesasClasses">SubResources as Classes</h2><p>Sometimes subresource may need to have the request context information available to them. One valid and simple approach is to pass these contexts to them from the parent class which instantiates a subresource - but sometimes this approach does not work.</p><p>In JAX-RS 2.0 one can use <a shape="rect" class="external-link" href="https://github.com/jax-
rs/api/blob/master/jaxrs-api/src/main/java/javax/ws/rs/container/ResourceContext.java" rel="nofollow">ResourceContext</a> to instantiate a subresource instance with the runtime taking care of injecting the contexts if needed. JAX-RS 2.1 introduces a shortcut where returning a subresource class from a subresource locator method, with the runtime istantiating the class and injecting the contexts if needed</p><h2 id="JAX-RSBasics-CXFNIOExtension">CXF NIO Extension</h2><p>Please see <a shape="rect" href="jax-rs-nio.html">JAX-RS NIO</a> for more information about this CXF 3.2.0 extension which is based on the early JAX-RS 2.1 API prototype.</p><h1 id="JAX-RSBasics-WhatisNewinJAX-RS2.0">What is New in JAX-RS 2.0</h1><h2 id="JAX-RSBasics-Filters">Filters</h2><h3 id="JAX-RSBasics-Server">Server</h3><p><a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/container/ContainerRequestFilter.html" rel="nofollow">ContainerRequestFilter</a> and <a shape="rect
" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/container/ContainerResponseFilter.html" rel="nofollow">ContainerResponseFilter</a> are new server-side request and response filters which can be used to customize various properties of a given request and response.</p><p>ContainerRequestFilter annotated with a <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/container/PreMatching.html" rel="nofollow">PreMatching</a> annotation will be run before the runtime has matched a request to a specific JAX-RS root resource and method. Prematching filters can be used to affect the matching process.</p><p>The request filters without the PreMatching annotation will run after the JAX-RS resource method has been selected.</p><p>ContainerRequestFilter can be used to <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/container/ContainerRequestContext.html#abortWith(javax.ws.rs.core.Respo
nse)" rel="nofollow">block</a> a request.</p><p>The filters can be bound to individual resource methods only with the help of custom <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/NameBinding.html" rel="nofollow">NameBinding</a>s.</p><p>Multiple request and response filters can be executed in the specific order by using javax.annotation.Priority annotations. See <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/Priorities.html" rel="nofollow">Priorities</a> for more information. Request filters are sorted in the ascending order, response filters - in the descending order.</p><h3 id="JAX-RSBasics-Client">Client</h3><p><a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/client/ClientRequestFilter.html" rel="nofollow">ClientRequestFilter</a> and <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/client/ClientResponse
Filter.html" rel="nofollow">ClientResponseFilter</a> are new client-side request and response filters which can be used to customize various properties of a given request and response.</p><p>ClientRequestFilter can be used to <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/client/ClientRequestContext.html#abortWith(javax.ws.rs.core.Response)" rel="nofollow">block</a> a request.</p><p>Request filters are sorted in the ascending order, response filters - in the descending order. See <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/Priorities.html" rel="nofollow">Priorities</a> for more information.</p><h2 id="JAX-RSBasics-Interceptors">Interceptors</h2><p><a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/ext/ReaderInterceptor.html" rel="nofollow">ReaderInterceptor</a> and <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/jav
ax/ws/rs/ext/WriterInterceptor.html" rel="nofollow">WriterInterceptor</a> can be used in addition to filters or on its own to customize requests and responses on server and client sides.</p><p>Interceptors can be useful to customize the reading/writing process and block JAX-RS MessageBodyWriter or MessageBodyReader providers.</p><p>The interceptors used on the server side can be bound to individual resource methods only with the help of custom <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/NameBinding.html" rel="nofollow">NameBinding</a>s.</p><p>All interceptors are sorted in the ascending order. See <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/Priorities.html" rel="nofollow">Priorities</a> for more information.</p><h2 id="JAX-RSBasics-DynamicFeatures">Dynamic Features</h2><p><a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/container/DynamicFeatur
e.html" rel="nofollow">Dynamic Feature</a> is a server side feature that can be used to attach request and response filters as well as reader and writer interceptors to specific resource methods. It is an alternative approach to using the NameBindings and offer a finer-grained control over the binding process.</p><h2 id="JAX-RSBasics-Exceptions">Exceptions</h2><p>Dedicated exception classes representing various HTTP error or redirect conditions have been introduced, see the 'javax.ws.rs' Package <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/package-frame.html" rel="nofollow">Exceptions section</a>.</p><p>For example, instead of throwing a "new WebApplicationException(404)" one is better to do "new NotFoundException()". The finer-grained exception hierarchy allows for a finer-grained support of exception mappers. It also opens a way to check WebApplicationException and all of its subclasses when catching the HTTP exceptions on the client
side.</p><p>Note that on the client side, ProcessingException can be used to catch client-related exceptions while ResponseProcessingException can be used to narrow down the client side exceptions specifically related to processing the response message.</p><h2 id="JAX-RSBasics-Suspendedinvocations">Suspended invocations</h2><p>One of the best JAX-RS 2.0 features is the support for server-side asynchronous invocations. Please see the <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/container/AsyncResponse.html" rel="nofollow">AsyncResponse</a> documentation which provides a very good overview of this feature.</p><p>See also this <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/BookContinuationStore.java" rel="nofollow">test resource</a>.</p><p>Typically, the resource method accepting AsyncResponse will either store it and start a new thread to fi
nish the request, the method will return and the invocation will be suspended, then eventually another thread (either the one which initiated an internal job or some other thread) will resume the suspended call. Note in this case the invocation will be suspended indefinitely until it is resumed.</p><p>Another approach is to have AsyncResponse suspended for a limited period of time only and also register a <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/container/TimeoutHandler.html" rel="nofollow">TimeoutHandler</a>. The latter will be invoked when the invocation is resumed by the container after the timeout has expired and the handler will either complete the invocation or suspend it again till it is ready to finish it.</p><p><a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/container/CompletionCallback.html" rel="nofollow">CompletionCallback</a> can be registered with AsyncResponse to receive t
he notifications when the async response has been sent back.</p><p><a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/container/ConnectionCallback.html" rel="nofollow">ConnectionCallback</a> is supported starting from CXF 3.0.0-milestone2.</p><p>This feature can help developers write very sophisticated asynchronous applications.</p><p>Please also see the page about CXF <a shape="rect" href="continuations.html">Continuations</a> API which JAX-RS 2.0 AsyncResponse implementation is based upon and <br clear="none"> <a shape="rect" href="http://cxf.apache.org/docs/servlet-transport.html">how to configure</a> CXFServlet.</p><h2 id="JAX-RSBasics-Parameterconverters">Parameter converters</h2><p><a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/ext/ParamConverterProvider.html" rel="nofollow">ParamConverterProvider</a> can be used to manage the conversion of custom Objects to String and vice versa on the ser
ver and client sides, when processing JAX-RS parameters representing URI parts or headers or form elements and when a default conversion mechanism does not work. For example, java.util.Date constructor accepting a String may have to be replaced a custom ParamConverter.</p><h2 id="JAX-RSBasics-Beanparameters">Bean parameters</h2><p><a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/BeanParam.html" rel="nofollow">BeanParam</a> can be used to get JAX-RS parameters representing URI parts or headers or form elements and also contexts injected into a single bean container.</p><p>Note the CXF extension supporting the injection of all the parameters of specific JAX-RS type (example, QueryParam("") MyBean) is different, it only allows to get all the query parameters injected, but it also does not require that bean properties are annotated with QueryParam/etc annotations.</p><h2 id="JAX-RSBasics-ResourceInfo">ResourceInfo</h2><p><a shape="rect" class=
"external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/container/ResourceInfo.html" rel="nofollow">ResourceInfo</a> is a new JAX-RS context which can be injected into filters and interceptors and checked which resource class and method are about to be invoked.</p><h2 id="JAX-RSBasics-Injectionintosubresources">Injection into subresources</h2><p>Subresources can get JAX-RS contexts injected directly into their fields with the help of <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/container/ResourceContext.html" rel="nofollow">ResourceContext</a>.</p><p>When possible, having a parent resource injecting the contexts into a given subresource instance via a setter or constructor can offer a much simpler alternative.</p><h2 id="JAX-RSBasics-Updatestothematchingalgorithm">Updates to the matching algorithm</h2><p>JAX-RS 2.0 supports a proper resource method selection in cases where multiple root resource classes have the same Pat
h value, 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;">@Path("/")
public class Root1 {
@Path("/1")
Modified: websites/production/cxf/content/docs/jax-rs-project-reactor-support.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-project-reactor-support.html (original)
+++ websites/production/cxf/content/docs/jax-rs-project-reactor-support.html Thu Mar 22 00:07:45 2018
@@ -28,6 +28,15 @@
<meta name="description" content="Apache CXF, Services Framework - JAX-RS Project Reactor Support">
+<link type="text/css" rel="stylesheet" href="/resources/highlighter/styles/shCoreCXF.css">
+<link type="text/css" rel="stylesheet" href="/resources/highlighter/styles/shThemeCXF.css">
+
+<script src='/resources/highlighter/scripts/shCore.js'></script>
+<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
+<script>
+ SyntaxHighlighter.defaults['toolbar'] = false;
+ SyntaxHighlighter.all();
+</script>
<title>
@@ -107,7 +116,64 @@ Apache CXF -- JAX-RS Project Reactor Sup
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div id="ConfluenceContent"></div>
+<div id="ConfluenceContent"><p><style type="text/css">/*<![CDATA[*/
+div.rbtoc1521676930137 {padding: 0px;}
+div.rbtoc1521676930137 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1521676930137 li {margin-left: 0px;padding-left: 0px;}
+
+/*]]>*/</style></p><div class="toc-macro rbtoc1521676930137">
+<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSProjectReactorSupport-ProjectReactorsupport">Project Reactor support</a>
+<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSProjectReactorSupport-Introduction">Introduction</a></li><li><a shape="rect" href="#JAX-RSProjectReactorSupport-Client">Client</a></li><li><a shape="rect" href="#JAX-RSProjectReactorSupport-Server">Server</a>
+<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSProjectReactorSupport-Asamethodreturnvalue">As a method return value</a></li><li><a shape="rect" href="#JAX-RSProjectReactorSupport-CombiningFlux/MonowithAsyncResponse">Combining Flux/Mono with AsyncResponse</a></li></ul>
+</li></ul>
+</li></ul>
+</div><h1 id="JAX-RSProjectReactorSupport-ProjectReactorsupport">Project Reactor support</h1><h2 id="JAX-RSProjectReactorSupport-Introduction">Introduction</h2><p>Project Reactor support for Flux and Mono are provided from the Rx Project Reactor extension.  This allows you to develop applications in a reactive fashion on both the client and server side.</p><p>org.apache.cxf/cxf-rt-rs-extension-reactor/3.2.3 and io.projectreactor/reactor-core/3.1.0.RELEASE dependencies are required.</p><h2 id="JAX-RSProjectReactorSupport-Client">Client</h2><p>The following simple example uses ObservableRxInvoker. org.apache.cxf.jaxrs.rx2.client.FlowableRxInvoker can be used if needed instead.  Reviewing our <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/reactive" rel="nofollow">systests for reactive</a> may help as well.</p><div class="code panel pdl" style="border-width: 1px;"><div cl
ass="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">String address = "http://localhost:" + PORT + "/reactor/flux/textJson";
+List<HelloWorldBean> collector = new ArrayList<>();
+ClientBuilder.newClient()
+ .register(new JacksonJsonProvider())
+ .register(new ReactorInvokerProvider())
+ .target(address)
+ .request("application/json")
+ .rx(ReactorInvoker.class)
+ .get(HelloWorldBean.class)
+ .doOnNext(collector::add)
+ .subscribe();
+// make sure to do a Thread.sleep or wait for the response to come back if you're trying to collect</pre>
+</div></div><h2 id="JAX-RSProjectReactorSupport-Server">Server</h2><h3 id="JAX-RSProjectReactorSupport-Asamethodreturnvalue">As a method return value</h3><pre>One simply returns reactor.core.publisher.Mono or reactor.core.publisher.Flux from the method and the runtime will make sure the response is finalized once the Flux/Mono flow is complete.</pre><p>The only requirement is that one has to register a custom JAX-RS invoker, org.apache.cxf.jaxrs.reactor.server.ReactorInvoker. It does all the default JAXRSInvoker does and only checks if Flux or Mono are returned - if yes then it links it internally with the JAX-RS AsyncResponse.  The invoker can be automatically registered with a lot of sensible defaults by using org.apache.cxf.jaxrs.reactor.server.ReactorCustomizer.</p><p>The built in invoker handles Flux and Mono based on proper semantics.  For instance, reading a JAX-RS response object is always a Mono (0 to 1 elements), but any method containing flux will conv
ert to a Flux operation meant to contain 0 to n elements.  You would typically use a Flux on a get with an arbitrary data set converted from a JSON array, Mono would likely be the right solution for any time you want to read the Response object.</p><h3 id="JAX-RSProjectReactorSupport-CombiningFlux/MonowithAsyncResponse">Combining Flux/Mono with AsyncResponse</h3><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;">JAXRSServerFactoryBean sf = new JAXRSServerFactoryBean();
+sf.setProvider(new JacksonJsonProvider());
+new ReactorCustomizer().customize(sf); // use a JAXRSServerFactoryCustomizationExtension to customize the server
+sf.setResourceClasses(FluxService.class);
+sf.setResourceProvider(FluxService.class,
+ new SingletonResourceProvider(new FluxService(), true));
+sf.setAddress("http://localhost:" + PORT + "/");
+server = sf.create();</pre>
+</div></div><p> </p><p> </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;">import org.apache.cxf.jaxrs.reactivestreams.server.JsonStreamingAsyncSubscriber;
+import reactor.core.publisher.Flux;
+import reactor.core.scheduler.Schedulers;
+
+@GET
+@Produces("application/json")
+@Path("textJsonImplicitListAsyncStream")
+public void getJsonImplicitListStreamingAsync(@Suspended AsyncResponse ar) {
+ Flux.just("Hello", "Ciao")
+ .map(HelloWorldBean::new)
+ .subscribeOn(Schedulers.parallel())
+ .subscribe(new JsonStreamingAsyncSubscriber<>(ar));
+}
+ 
+// or you can just return the Flux
+@GET
+@Produces("application/json")
+@Path("textJsonImplicitListAsyncStream2")
+public Flux<HelloWorldBean> getJsonImplicitListStreamingAsync2() {
+ return Flux.just("Hello", "Ciao")
+ .map(HelloWorldBean::new)
+ .subscribeOn(Schedulers.parallel());
+}</pre>
+</div></div></div>
</div>
<!-- Content -->
</td>
Modified: websites/production/cxf/content/docs/jax-rs.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs.html (original)
+++ websites/production/cxf/content/docs/jax-rs.html Thu Mar 22 00:07:45 2018
@@ -121,11 +121,11 @@ Apache CXF -- JAX-RS
 </p><p> </p><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1516813006846 {padding: 0px;}
-div.rbtoc1516813006846 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1516813006846 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1521676928720 {padding: 0px;}
+div.rbtoc1521676928720 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1521676928720 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1516813006846">
+/*]]>*/</style></p><div class="toc-macro rbtoc1521676928720">
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RS-Introduction">Introduction</a></li><li><a shape="rect" href="#JAX-RS-JAX-RSCompliance">JAX-RS Compliance</a>
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RS-2.1Final">2.1 Final</a></li><li><a shape="rect" href="#JAX-RS-2.0Final">2.0 Final</a></li><li><a shape="rect" href="#JAX-RS-1.1">1.1</a></li></ul>
</li><li><a shape="rect" href="#JAX-RS-Projectsetupandconfiguration">Project setup and configuration</a>
@@ -233,7 +233,7 @@ public void upload(@Multipart InputStrea
</dependency>
</pre>
-</div></div><h1 id="JAX-RS-WhatisNew">What is New</h1><ul><li>Complete support for JAX-RS 2.1, please see <a shape="rect" href="jax-rs-basics.html">JAX-RS Basics</a> for more information</li><li><a shape="rect" href="jax-rs-nio.html">JAX-RS NIO</a> extension based on the early JAX-RS 2.1 API prototype.</li><li><a shape="rect" href="jax-rs-rxjava.html">JAX-RS RxJava</a> Observable support: as a standard JAX-RS 2.1 RxInvoker client provider and returning it asynchronously from the resource methods (CXF extension) </li><li>Complete support for JAX-RS 2.0, please see <a shape="rect" href="jax-rs-basics.html">JAX-RS Basics</a> for more information</li><li>Bean Validation 1.1 Support, please see <a shape="rect" href="http://cxf.apache.org/docs/validationfeature.html">http://cxf.apache.org/docs/validationfeature.html</a> for more information</li><li><a shape="rect" href="http://cxf.apache.org/docs/swagger2feature.html">Swagger Feature</a> for generating <a shape="rect" class="external
-link" href="http://swagger.io/specification/" rel="nofollow">Swagger API</a> documentation from JAX-RS endpoints</li></ul><h1 id="JAX-RS-GettingStartedwithJAX-RS">Getting Started with JAX-RS</h1><h2 id="JAX-RS-UnderstandingtheBasics">Understanding the Basics</h2><p>You are encouraged to read JAX-RS 2.1 <a shape="rect" class="external-link" href="http://jcp.org/en/jsr/detail?id=370" rel="nofollow">JSR-370</a> specification to find out the information not covered by this documentation. The specification enhances JAX-RS 2.0 by introducing a support for Reactive Client API extensions, Server Sent Events (client and server), returning CompletableFuture from the resource methods and the sub-resource classes (as opposed to instances) from the sub-resource locators.</p><p>You are also encouraged to read JAX-RS 2.0 <a shape="rect" class="external-link" href="http://jcp.org/en/jsr/detail?id=339" rel="nofollow">JSR-339</a> specification to find out the information not covered by this document
ation. The specification introduces many terms such as root resources, resource methods, sub-resources and sub-resource locators, message body readers and writers. JAX-RS 2.0 additionally introduces filters, interceptors, new client API, features, new exception classes, server-side support for asynchronous invocations.</p><p>Please see the <a shape="rect" href="jax-rs-basics.html">JAX-RS Basics</a> page for more information.</p><h2 id="JAX-RS-SupportforDataBindings">Support for Data Bindings</h2><p>JAX-RS MessageBodyReader and MessageBodyWriter can be used to create data bindings for reading and writing data in a number of different formats. Compliant JAX-RS implementations are expected to support JAXB-annotated beans, JAXP Source objects, InputStreams, etc.</p><p>In addition, CXF JAX-RS lets users reuse existing CXF DataBindings for working with JAXB, XBeans, Aegis and SDO.</p><p>Please see the <a shape="rect" href="jax-rs-data-bindings.html">JAX-RS Data Bindings</a> page for more
information.</p><h2 id="JAX-RS-HowRequestURIisMatched">How Request URI is Matched</h2><p>Lets assume you have a web application called 'rest' (example, a 'rest.war' archive). CXFServlet's url-pattern is "/test/*". Finally, jaxrs:server's address is "/bar".</p><p>Requests like /rest/test/bar or /rest/test/bar/baz will be delivered to one of the resource classes in a given jaxrs:server endpoint. For the former request to be handled, a resource class with @Path("/") should be available, in the latter case - at least @Path("/") or a more specific @Path("/baz").</p><p>The same requirement can be expressed by having a CXFServlet with "/*" and jaxrs:server with "/test/bar".</p><p>When both CXFServlet and jaxrs:server use "/" then it's a root resource class which should provide a @Path with at least "/test/bar" for the above requests to be matched.</p><p>Generally, it can be a good idea to specify the URI segments which are more likely to change now and then with CXFServlets or jaxrs:server
.</p><h2 id="JAX-RS-ClientAPI">Client API</h2><p>CXF 3.0.0 implements JAX-RS 2.0 Client API.</p><p>CXF 2.7.x or earlier provides a comprehensive support for developing RESTful clients by supporting 3 flavors of the client API: proxy-based, HTTP-centric and XML-centric. CXF-specific client API is supported alongside new JAX-RS 2.0 Client API in CXF 3.0.0.</p><p>Please see the <a shape="rect" href="jax-rs-client-api.html">JAX-RS Client API</a> page for more information.</p><h2 id="JAX-RS-BeanValidation">Bean Validation</h2><p>Bean Validation 1.1 is supported since CXF 3.0.0-milestone1. Please see the <a shape="rect" href="http://cxf.apache.org/docs/validationfeature.html">http://cxf.apache.org/docs/validationfeature.html</a> for more information.</p><h2 id="JAX-RS-Filters,InterceptorsandInvokers">Filters, Interceptors and Invokers</h2><p>It is possible to intercept and modify the inbound and outbound calls with the help of CXF JAX-RS filters and/or CXF interceptors. Additionally, cust
om invokers offer an option to intercept a call immediately before a service bean is invoked.</p><p>Please see the <a shape="rect" href="jax-rs-filters.html">JAX-RS Filters</a> page for more information.</p><p>Please see the <a shape="rect" href="jax-rs-basics.html">JAX-RS Basics</a> page for more information about new JAX-RS 2.0 filters and interceptors available in CXF 2.7.x and 3.0.0.</p><h2 id="JAX-RS-ServicelistingsandWADLsupport">Service listings and WADL support</h2><p><strong>New</strong>: Swagger feature has been introduced.</p><p>CXF JAX-RS supports <a shape="rect" class="external-link" href="http://www.w3.org/Submission/wadl" rel="nofollow">WADL</a>. CXF JAX-RS service endpoints can be listed in the service listings page and users can check the WADL documents.</p><p>Please see the <a shape="rect" href="jaxrs-services-description.html">JAXRS Services Description</a> page for more information.</p><h2 id="JAX-RS-ConfiguringJAX-RSservices">Configuring JAX-RS services</h2><p>J
AX-RS services can be configured programmatically, using Blueprint, Spring or CXFNonSpringJAXRSServlet.</p><p>Please see the <a shape="rect" href="jaxrs-services-configuration.html">JAXRS Services Configuration</a> page for more information.</p><h2 id="JAX-RS-Testing">Testing</h2><p>JAX-RS services can be easily tested using the embedded Jetty or CXF Local Transport.<br clear="none"> Please see the <a shape="rect" href="https://cwiki.apache.org/confluence/display/CXF20DOC/JAXRS+Testing">JAXRS Testing</a> page for more information.</p><h2 id="JAX-RS-Debugging">Debugging</h2><p>One may want to use a browser to test how a given HTTP resource reacts to different HTTP Accept or Accept-Language header values and request methods. For example, if a resource class supports a "/resource" URI then one can test the resource class using one of the following queries :</p><p><code>> GET /resource.xml</code> <br clear="none"> <code>> GET /resource.en</code></p><p>The runtime will replace '.xm
l' or '.en' with an appropriate header value. For it to know the type or language value associated with a given URI suffix, some configuration needs to be done. Here's an example of how it can be done with Spring:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><h1 id="JAX-RS-WhatisNew">What is New</h1><ul><li>Complete support for JAX-RS 2.1, please see <a shape="rect" href="jax-rs-basics.html">JAX-RS Basics</a> for more information</li><li><a shape="rect" href="jax-rs-nio.html">JAX-RS NIO</a> extension based on the early JAX-RS 2.1 API prototype.</li><li><a shape="rect" href="jax-rs-rxjava.html">JAX-RS RxJava</a> Observable support: as a standard JAX-RS 2.1 RxInvoker client provider and returning it asynchronously from the resource methods (CXF extension) </li><li><a shape="rect" href="jax-rs-project-reactor-support.html">JAX-RS Project Reactor</a> Support also based on the JAX-RS 2.1 RxInvoker paradigm</li><li>Complete support for JAX-RS 2.0, please see <a shape="rect" href="jax-rs-basics.html">JAX-RS Basics</a> for more information</li><li>Bean Validation 1.1 Support, please see <a shape="rect" href="http://cxf.apache.org/docs/validationfeature.html">http://cxf.apache.org/docs/validationfeature.html</a> for more informa
tion</li><li><a shape="rect" href="http://cxf.apache.org/docs/swagger2feature.html">Swagger Feature</a> for generating <a shape="rect" class="external-link" href="http://swagger.io/specification/" rel="nofollow">Swagger API</a> documentation from JAX-RS endpoints</li></ul><h1 id="JAX-RS-GettingStartedwithJAX-RS">Getting Started with JAX-RS</h1><h2 id="JAX-RS-UnderstandingtheBasics">Understanding the Basics</h2><p>You are encouraged to read JAX-RS 2.1 <a shape="rect" class="external-link" href="http://jcp.org/en/jsr/detail?id=370" rel="nofollow">JSR-370</a> specification to find out the information not covered by this documentation. The specification enhances JAX-RS 2.0 by introducing a support for Reactive Client API extensions, Server Sent Events (client and server), returning CompletableFuture from the resource methods and the sub-resource classes (as opposed to instances) from the sub-resource locators.</p><p>You are also encouraged to read JAX-RS 2.0 <a shape="rect" class="exter
nal-link" href="http://jcp.org/en/jsr/detail?id=339" rel="nofollow">JSR-339</a> specification to find out the information not covered by this documentation. The specification introduces many terms such as root resources, resource methods, sub-resources and sub-resource locators, message body readers and writers. JAX-RS 2.0 additionally introduces filters, interceptors, new client API, features, new exception classes, server-side support for asynchronous invocations.</p><p>Please see the <a shape="rect" href="jax-rs-basics.html">JAX-RS Basics</a> page for more information.</p><h2 id="JAX-RS-SupportforDataBindings">Support for Data Bindings</h2><p>JAX-RS MessageBodyReader and MessageBodyWriter can be used to create data bindings for reading and writing data in a number of different formats. Compliant JAX-RS implementations are expected to support JAXB-annotated beans, JAXP Source objects, InputStreams, etc.</p><p>In addition, CXF JAX-RS lets users reuse existing CXF DataBindings for w
orking with JAXB, XBeans, Aegis and SDO.</p><p>Please see the <a shape="rect" href="jax-rs-data-bindings.html">JAX-RS Data Bindings</a> page for more information.</p><h2 id="JAX-RS-HowRequestURIisMatched">How Request URI is Matched</h2><p>Lets assume you have a web application called 'rest' (example, a 'rest.war' archive). CXFServlet's url-pattern is "/test/*". Finally, jaxrs:server's address is "/bar".</p><p>Requests like /rest/test/bar or /rest/test/bar/baz will be delivered to one of the resource classes in a given jaxrs:server endpoint. For the former request to be handled, a resource class with @Path("/") should be available, in the latter case - at least @Path("/") or a more specific @Path("/baz").</p><p>The same requirement can be expressed by having a CXFServlet with "/*" and jaxrs:server with "/test/bar".</p><p>When both CXFServlet and jaxrs:server use "/" then it's a root resource class which should provide a @Path with at least "/test/bar" for the above requests to be mat
ched.</p><p>Generally, it can be a good idea to specify the URI segments which are more likely to change now and then with CXFServlets or jaxrs:server.</p><h2 id="JAX-RS-ClientAPI">Client API</h2><p>CXF 3.0.0 implements JAX-RS 2.0 Client API.</p><p>CXF 2.7.x or earlier provides a comprehensive support for developing RESTful clients by supporting 3 flavors of the client API: proxy-based, HTTP-centric and XML-centric. CXF-specific client API is supported alongside new JAX-RS 2.0 Client API in CXF 3.0.0.</p><p>Please see the <a shape="rect" href="jax-rs-client-api.html">JAX-RS Client API</a> page for more information.</p><h2 id="JAX-RS-BeanValidation">Bean Validation</h2><p>Bean Validation 1.1 is supported since CXF 3.0.0-milestone1. Please see the <a shape="rect" href="http://cxf.apache.org/docs/validationfeature.html">http://cxf.apache.org/docs/validationfeature.html</a> for more information.</p><h2 id="JAX-RS-Filters,InterceptorsandInvokers">Filters, Interceptors and Invokers</h2><p
>It is possible to intercept and modify the inbound and outbound calls with the help of CXF JAX-RS filters and/or CXF interceptors. Additionally, custom invokers offer an option to intercept a call immediately before a service bean is invoked.</p><p>Please see the <a shape="rect" href="jax-rs-filters.html">JAX-RS Filters</a> page for more information.</p><p>Please see the <a shape="rect" href="jax-rs-basics.html">JAX-RS Basics</a> page for more information about new JAX-RS 2.0 filters and interceptors available in CXF 2.7.x and 3.0.0.</p><h2 id="JAX-RS-ServicelistingsandWADLsupport">Service listings and WADL support</h2><p><strong>New</strong>: Swagger feature has been introduced.</p><p>CXF JAX-RS supports <a shape="rect" class="external-link" href="http://www.w3.org/Submission/wadl" rel="nofollow">WADL</a>. CXF JAX-RS service endpoints can be listed in the service listings page and users can check the WADL documents.</p><p>Please see the <a shape="rect" href="jaxrs-services-descrip
tion.html">JAXRS Services Description</a> page for more information.</p><h2 id="JAX-RS-ConfiguringJAX-RSservices">Configuring JAX-RS services</h2><p>JAX-RS services can be configured programmatically, using Blueprint, Spring or CXFNonSpringJAXRSServlet.</p><p>Please see the <a shape="rect" href="jaxrs-services-configuration.html">JAXRS Services Configuration</a> page for more information.</p><h2 id="JAX-RS-Testing">Testing</h2><p>JAX-RS services can be easily tested using the embedded Jetty or CXF Local Transport.<br clear="none"> Please see the <a shape="rect" href="https://cwiki.apache.org/confluence/display/CXF20DOC/JAXRS+Testing">JAXRS Testing</a> page for more information.</p><h2 id="JAX-RS-Debugging">Debugging</h2><p>One may want to use a browser to test how a given HTTP resource reacts to different HTTP Accept or Accept-Language header values and request methods. For example, if a resource class supports a "/resource" URI then one can test the resource class using one of the
following queries :</p><p><code>> GET /resource.xml</code> <br clear="none"> <code>> GET /resource.en</code></p><p>The runtime will replace '.xml' or '.en' with an appropriate header value. For it to know the type or language value associated with a given URI suffix, some configuration needs to be done. Here's an example of how it can be done with Spring:</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;"> <jaxrs:server id="customerService" address="/">
<jaxrs:serviceBeans>
<bean class="org.apache.cxf.jaxrs.systests.CustomerService" />