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 2019/09/13 15:56:45 UTC
svn commit: r1050052 - in /websites/production/cxf/content:
cache/docs.pageCache docs/jax-rs-basics.html
Author: buildbot
Date: Fri Sep 13 15:56:44 2019
New Revision: 1050052
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/jax-rs-basics.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 Fri Sep 13 15:56:44 2019
@@ -118,15 +118,15 @@ Apache CXF -- JAX-RS Basics
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div id="ConfluenceContent"><p> </p><p> <span style="font-size:2em;font-weight:bold">JAX-RS: Understanding the Basics</span>
+<div id="ConfluenceContent"><p><br clear="none"></p><p><br clear="none"><span style="font-size:2em;font-weight:bold">JAX-RS: Understanding the Basics</span>
- </p><p> </p><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1524513388495 {padding: 0px;}
-div.rbtoc1524513388495 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1524513388495 li {margin-left: 0px;padding-left: 0px;}
+<br clear="none"></p><p><br clear="none"></p><p><style type="text/css">/*<![CDATA[*/
+div.rbtoc1568390166047 {padding: 0px;}
+div.rbtoc1568390166047 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1568390166047 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1524513388495">
+/*]]>*/</style></p><div class="toc-macro rbtoc1568390166047">
<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><li><a shape="rect" href="#JAX-RSBasics-RxJava2">RxJava2</a></li><li><a shape="rect" href="#JAX-RSBasics-ProjectReactor">Project Reactor</a></li></ul>
@@ -152,8 +152,8 @@ div.rbtoc1524513388495 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><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("/")
+</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 serv
er 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 Path
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">@Path("/")
public class Root1 {
@Path("/1")
@GET
@@ -167,8 +167,8 @@ public class Root2 {
public Response get() {...}
}
</pre>
-</div></div><p>In JAX-RS 1.1 a request with URI such as "/1" is not guaranteed to be matched and in CXF 2.7.x or earlier the use of CXF specific ResourceComparator is required to ensure Root1 and its get() method gets selected. In CXF 3.0.0 Root1 get() will always be correctly selected. Note ResourceComparator may still be of help in some cases even in CXF 3.0.0.</p><h2 id="JAX-RSBasics-Link">Link</h2><p><a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/core/Link.html" rel="nofollow">Link</a> is a utility class for building HTTP links as HTTP Link headers or application data links. <br clear="none"> UriInfo, UriBuilder, Response and ResponseBuilder classes have been enhanced to support Link.</p><h2 id="JAX-RSBasics-ClientAPI">Client API</h2><p>JAX-RS 2.0 Client API has been completely implemented in CXF 3.0.0, please see the <a shape="rect" href="http://cxf.apache.org/docs/jax-rs-client-api.html#JAX-RSClientAPI-JAXRS2.0ClientAPI">Client API
page</a> for more information.</p><h1 id="JAX-RSBasics-Resourceclass">Resource class</h1><p>A resource class is a Java class annotated with JAX-RS annotations to represent a Web resource. Two types of resource classes are available: root resource classes and subresource classes. A root resource class is annotated with at least a @Path annotation, while subresource classes typically have no root @Path values. A typical root resource class in JAX-RS looks like this below:</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;">package demo.jaxrs.server;
+</div></div><p>In JAX-RS 1.1 a request with URI such as "/1" is not guaranteed to be matched and in CXF 2.7.x or earlier the use of CXF specific ResourceComparator is required to ensure Root1 and its get() method gets selected. In CXF 3.0.0 Root1 get() will always be correctly selected. Note ResourceComparator may still be of help in some cases even in CXF 3.0.0.</p><h2 id="JAX-RSBasics-Link">Link</h2><p><a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/core/Link.html" rel="nofollow">Link</a> is a utility class for building HTTP links as HTTP Link headers or application data links. <br clear="none">UriInfo, UriBuilder, Response and ResponseBuilder classes have been enhanced to support Link.</p><h2 id="JAX-RSBasics-ClientAPI">Client API</h2><p>JAX-RS 2.0 Client API has been completely implemented in CXF 3.0.0, please see the <a shape="rect" href="http://cxf.apache.org/docs/jax-rs-client-api.html#JAX-RSClientAPI-JAXRS2.0ClientAPI">Client API
page</a> for more information.</p><h1 id="JAX-RSBasics-Resourceclass">Resource class</h1><p>A resource class is a Java class annotated with JAX-RS annotations to represent a Web resource. Two types of resource classes are available: root resource classes and subresource classes. A root resource class is annotated with at least a @Path annotation, while subresource classes typically have no root @Path values. A typical root resource class in JAX-RS looks like this below:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">package demo.jaxrs.server;
import java.util.HashMap;
import java.util.Map;
@@ -224,7 +224,7 @@ public class CustomerService {
}
</pre>
</div></div><p>Customer resource class can handle requests starting from /customerservice. When /customerservice requests are matched to this class, its getCustomers() method will be selected. updateCustomer(), deleteCustomer() and addCustomer() are used to serve POST, PUT and DELETE requests starting from /customerservice/customer, while getOrder() method delegates the handling of requests like /customerservice/orders/1 to a subresource locator Order.</p><p>The @Produces annotation is used to specify the format of the response. When not available on the resource method, it's inherited from a class, and if it's not available on the class then it's inherited from a corresponding message body writer, if any. Default value is */*, but it's recommended that some definite value is specified. The same applies to @Consumes, except that it's the message body <em>readers</em> that are checked as the last resort.</p><p>For example, getCustomers() method inherits @Produces annotation from its
class, while getCustomer() method overrides it with its own value.</p><h1 id="JAX-RSBasics-@Path">@Path</h1><p>The @Path annotation is applied to resource classes or methods. The value of @Path annotation is a relative URI path and follows the URI Template format and may include arbitrary regular expressions. When not available on the resource method, it's inherited from a 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;">@Path("/customers/{id}")
+<pre class="brush: java; gutter: false; theme: Default">@Path("/customers/{id}")
public class CustomerResource {
@GET
@@ -249,8 +249,8 @@ public class CustomerResource {
}
</pre>
-</div></div><p>This example is similar to the one above it, but it also shows that an {id} template variable specified as part of the root @Path expression is reused by resource methods and a custom regular expression is specified by a findItem() method (note that a variable name is separated by ':' from an actual expression).</p><p>In this example, a request like 'GET /customers/1/order/2/price/2000/weight/2' will be served by the findItem() method.<br clear="none"> List<PathSegment> can be used to get to all the path segments in 'price/2000/weight/2' captured by the regular expression.</p><p>More information about Path annotations can be found from <a shape="rect" class="external-link" href="http://jcp.org/en/jsr/detail?id=311" rel="nofollow">JAX-RS spec </a> section 2.3.</p><h1 id="JAX-RSBasics-HTTPMethod">HTTP Method</h1><p>The JAX-RS specification defines a number of annotations such as @GET, @PUT, @POST and @DELETE. Using an @HttpMethod designator, one can create a custo
m annotation such as @Update or @Patch. 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;">package org.apache.cxf.customverb;
+</div></div><p>This example is similar to the one above it, but it also shows that an {id} template variable specified as part of the root @Path expression is reused by resource methods and a custom regular expression is specified by a findItem() method (note that a variable name is separated by ':' from an actual expression).</p><p>In this example, a request like 'GET /customers/1/order/2/price/2000/weight/2' will be served by the findItem() method.<br clear="none">List<PathSegment> can be used to get to all the path segments in 'price/2000/weight/2' captured by the regular expression.</p><p>More information about Path annotations can be found from <a shape="rect" class="external-link" href="http://jcp.org/en/jsr/detail?id=311" rel="nofollow">JAX-RS spec </a> section 2.3.</p><h1 id="JAX-RSBasics-HTTPMethod">HTTP Method</h1><p>The JAX-RS specification defines a number of annotations such as @GET, @PUT, @POST and @DELETE. Using an @HttpMethod designator, one can create a custom
annotation such as @Update or @Patch. 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">package org.apache.cxf.customverb;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
@@ -263,8 +263,8 @@ import java.lang.annotation.Target;
public @interface PATCH {
}
</pre>
-</div></div><h2 id="JAX-RSBasics-DefaultHttpMethod">Default Http Method</h2><p>CXF 3.0.4 introduces a new extension, a org.apache.cxf.jaxrs.ext.DefaultMethod annotation. It can be used to match arbitrary HTTP methods on a single resource method. This can be used in some advanced scenarious for integrating the CXF JAX-RS runtime into non-JAX-RS environments as well as in cases where it is awkward/difficult to have every HTTP method listed for a given path segment. CXF users need to be aware using this option will lead to a non-portable JAX-RS code.</p><p> </p><h1 id="JAX-RSBasics-Returntypes">Return types</h1><p>Either javax.ws.rs.core.Response or custom type can be returned. javax.ws.rs.core.Response can be used to set the HTTP response code, headers and entity. JAX-RS MessageBodyWriters (see below) are in charge of serializing the response entities, those which are returned directly or as part of javax.ws.rs.core.Response.</p><h1 id="JAX-RSBasics-ResponseStreaming">Response St
reaming </h1><h2 id="JAX-RSBasics-JAX-RSStreamingOutput">JAX-RS StreamingOutput</h2><p><a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/core/StreamingOutput.html" rel="nofollow">StreamingOutput</a> can be used to stream the data to the client, 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;">@GET
+</div></div><h2 id="JAX-RSBasics-DefaultHttpMethod">Default Http Method</h2><p>CXF 3.0.4 introduces a new extension, a org.apache.cxf.jaxrs.ext.DefaultMethod annotation. It can be used to match arbitrary HTTP methods on a single resource method. This can be used in some advanced scenarious for integrating the CXF JAX-RS runtime into non-JAX-RS environments as well as in cases where it is awkward/difficult to have every HTTP method listed for a given path segment. CXF users need to be aware using this option will lead to a non-portable JAX-RS code.</p><p><br clear="none"></p><h1 id="JAX-RSBasics-Returntypes">Return types</h1><p>Either javax.ws.rs.core.Response or custom type can be returned. javax.ws.rs.core.Response can be used to set the HTTP response code, headers and entity. JAX-RS MessageBodyWriters (see below) are in charge of serializing the response entities, those which are returned directly or as part of javax.ws.rs.core.Response.</p><h1 id="JAX-RSBasics-ResponseStreaming">
Response Streaming </h1><h2 id="JAX-RSBasics-JAX-RSStreamingOutput">JAX-RS StreamingOutput</h2><p><a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.0/javax/ws/rs/core/StreamingOutput.html" rel="nofollow">StreamingOutput</a> can be used to stream the data to the client, 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">@GET
@Path("/books/pdf")
@Produces("application/pdf")
public StreamingOutput getPdf() {
@@ -276,7 +276,7 @@ public StreamingOutput getPdf() {
}
</pre>
</div></div><h2 id="JAX-RSBasics-CXFStreamingResponse">CXF StreamingResponse</h2><p>CXF 3.0.0 introduces <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/StreamingResponse.java" rel="nofollow">StreamingResponse</a> extension. It can be used with the WebSocket transport or as a possible replacement for the code working with <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.1/javax/ws/rs/core/StreamingOutput.html" rel="nofollow">StreamingOutput</a>.</p><p>For example, consider that a number of resources need to be returned as they become available:</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;">@GET
+<pre class="brush: java; gutter: false; theme: Default">@GET
@Path("/books")
@Produces("application/xml")
public StreamingResponse<Book> getBooks() {
@@ -290,8 +290,8 @@ public StreamingResponse<Book> get
};
}
</pre>
-</div></div><h1 id="JAX-RSBasics-Exceptionhandling">Exception handling</h1><p>One can either throw an unchecked WebApplicationException or return Response with a proper error code set.<br clear="none"> The former option may be a better one when no JAX-RS types can be added to method signatures.</p><p>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("/customerservice/")
+</div></div><h1 id="JAX-RSBasics-Exceptionhandling">Exception handling</h1><p>One can either throw an unchecked WebApplicationException or return Response with a proper error code set.<br clear="none">The former option may be a better one when no JAX-RS types can be added to method signatures.</p><p>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">@Path("/customerservice/")
public class CustomerService {
@@ -310,18 +310,18 @@ public class CustomerService {
}
</pre>
</div></div><p>Yet another option is to register an ExceptionMapper provider. Ex :</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;">public BookExceptionMapper implements ExceptionMapper<BookException> {
+<pre class="brush: java; gutter: false; theme: Default">public BookExceptionMapper implements ExceptionMapper<BookException> {
public Response toResponse(BookException ex) {
// convert to Response
}
}
</pre>
-</div></div><p>This allows for throwing a checked or runtime exception from an application code and map it to an HTTP response in a registered provider.</p><p>Have a look please at <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/security/SecurityExceptionMapper.java">this exception mapper</a> which converts Spring Security exceptions into HTTP 403 error code for another example.</p><p>Note that when no mappers are found for custom exceptions, they are propagated to the underlying container as required by the specification where they will typically be wrapped in ServlerException, eventually resulting in HTTP 500 status being returned by default. Thus one option for intercepting the exceptions is to register a custom servlet filter which will catch ServletExceptions and handle the causes.</p><p>This propagation can be disabled by registering a boolean jaxrs property 'org.apache.cxf.propagat
e.exception' with a false value. If such property is set and no exception mapper can be found for a given exception then it will be wrapped into an xml error response by the CXF <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/bindings/xml/src/main/java/org/apache/cxf/binding/xml/interceptor/XMLFaultOutInterceptor.java">XMLFaultOutInterceptor</a>.</p><p>One can also register a custom CXF out fault interceptor which can handle all the exceptions by writing directly to the HttpServletResponse stream or XMLStreamWriter (as XMLFaultOutInterceptor does). For example, see this <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/CustomOutFaultInterceptor.java">test interceptor</a>.</p><h2 id="JAX-RSBasics-MappingexceptionsthrownfromCXFinterceptors">Mapping exceptions thrown from CXF interceptors</h2><p>Starting from CXF 2.7.8 it is also possible to use registe
red ExceptionMappers to map the exceptions thrown from CXF server in interceptors which are registered after JAXRSInInterceptor (Phase.UNMARSHAL) and out interceptors registered before JAXRSOutInterceptor (Phase.MARSHAL).<br clear="none"> In earlier CXF versions such exceptions are only possible to handle with CXF fault in interceptors.</p><p>In order to get the exceptions thrown from CXF in interceptors mapped, set a "map.cxf.interceptor.fault" contextual property to true - needed in CXF 2.7.8 to ensure existing in fault interceptors are not affected; the mapping is done by default starting from CXF 3.0.0.</p><p>In order to get the exceptions thrown from CXF out interceptors mapped, add org.apache.cxf.jaxrs.interceptor.JAXRSOutExceptionMapperInterceptor to the list of out interceptors.</p><h2 id="JAX-RSBasics-CustomizingdefaultWebApplicationExceptionmapper">Customizing default WebApplicationException mapper</h2><p>CXF ships a WebApplicationException mapper, org.apache.cxf.jaxrs.imp
l.WebApplicationExceptionMapper. By default it logs a stack trace at a warning level and returns Response available in the captured exception.<br clear="none"> It can be configured to log a stack trace at a trace level, by setting a 'printStackTrace' property to 'false'. Alternatively, if org.apache.cxf.logging.FaultListener is registered (as a contextual property) and indicates that it handled a given exception, then no more logging is done.</p><p>A simple text error message can also be optionally reported, by setting an 'addMessageToResponse' property to 'true', example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><bean id="exceptionMapper" class="org.apache.cxf.jaxrs.impl.WebApplicationExceptionMapper">
+</div></div><p>This allows for throwing a checked or runtime exception from an application code and map it to an HTTP response in a registered provider.</p><p>Have a look please at <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/security/SecurityExceptionMapper.java">this exception mapper</a> which converts Spring Security exceptions into HTTP 403 error code for another example.</p><p>Note that when no mappers are found for custom exceptions, they are propagated to the underlying container as required by the specification where they will typically be wrapped in ServlerException, eventually resulting in HTTP 500 status being returned by default. Thus one option for intercepting the exceptions is to register a custom servlet filter which will catch ServletExceptions and handle the causes.</p><p>This propagation can be disabled by registering a boolean jaxrs property 'org.apache.cxf.propagat
e.exception' with a false value. If such property is set and no exception mapper can be found for a given exception then it will be wrapped into an xml error response by the CXF <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/bindings/xml/src/main/java/org/apache/cxf/binding/xml/interceptor/XMLFaultOutInterceptor.java">XMLFaultOutInterceptor</a>.</p><p>One can also register a custom CXF out fault interceptor which can handle all the exceptions by writing directly to the HttpServletResponse stream or XMLStreamWriter (as XMLFaultOutInterceptor does). For example, see this <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/CustomOutFaultInterceptor.java">test interceptor</a>.</p><h2 id="JAX-RSBasics-MappingexceptionsthrownfromCXFinterceptors">Mapping exceptions thrown from CXF interceptors</h2><p>Starting from CXF 2.7.8 it is also possible to use registe
red ExceptionMappers to map the exceptions thrown from CXF server in interceptors which are registered after JAXRSInInterceptor (Phase.UNMARSHAL) and out interceptors registered before JAXRSOutInterceptor (Phase.MARSHAL).<br clear="none">In earlier CXF versions such exceptions are only possible to handle with CXF fault in interceptors.</p><p>In order to get the exceptions thrown from CXF in interceptors mapped, set a "map.cxf.interceptor.fault" contextual property to true - needed in CXF 2.7.8 to ensure existing in fault interceptors are not affected; the mapping is done by default starting from CXF 3.0.0.</p><p>In order to get the exceptions thrown from CXF out interceptors mapped, add org.apache.cxf.jaxrs.interceptor.JAXRSOutExceptionMapperInterceptor to the list of out interceptors.</p><h2 id="JAX-RSBasics-CustomizingdefaultWebApplicationExceptionmapper">Customizing default WebApplicationException mapper</h2><p>CXF ships a WebApplicationException mapper, org.apache.cxf.jaxrs.impl
.WebApplicationExceptionMapper. By default it logs a stack trace at a warning level and returns Response available in the captured exception.<br clear="none">It can be configured to log a stack trace at a trace level, by setting a 'printStackTrace' property to 'false'. Alternatively, if org.apache.cxf.logging.FaultListener is registered (as a contextual property) and indicates that it handled a given exception, then no more logging is done.</p><p>A simple text error message can also be optionally reported, by setting an 'addMessageToResponse' property to 'true', example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: xml; gutter: false; theme: Default"><bean id="exceptionMapper" class="org.apache.cxf.jaxrs.impl.WebApplicationExceptionMapper">
<property name="addMessageToResponse" value="true" />
</bean></pre>
-</div></div><p><br clear="none"> Note that the custom WebApplicationException mapper, if registered, will be preferred to the default one.</p><h1 id="JAX-RSBasics-DealingwithParameters">Dealing with Parameters</h1><p>PathParam annotation is used to map a given Path template variable to a method parameter.<br clear="none"> 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("/customer/{id}")
+</div></div><p><br clear="none">Note that the custom WebApplicationExceptionMapper, if registered, will be preferred to the default one in normal cases. However, the default WebApplicationExceptionMapper will win over custom WebApplicationExceptionMapper which are less specific (ex, RuntimeException mappers) but which expect to catch WebApplicationException.  And there is a property "make.default.wae.least.specific" is introduced to ensure a CXF custom WebApplicationExceptionMapper can still win over in this specific case.</p><h1 id="JAX-RSBasics-DealingwithParameters">Dealing with Parameters</h1><p>PathParam annotation is used to map a given Path template variable to a method parameter.<br clear="none">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">@Path("/customer/{id}")
public class CustomerService {
@@ -332,8 +332,8 @@ public class CustomerService {
}
}
</pre>
-</div></div><p>In this case a template variable id available from a root class annotation is mapped to a parameter of type Long, while a name variable is mapped to a parameter of type String.</p><p>@QueryParam, @HeaderParam, @MatrixParam, @FormParam and @CookieParam annotations are also supported.</p><p>Note that the parameters, marked with @FormParam annotation, can take the values from the query parameters in case, if request body is already consumed. This is defined in JAX-RS specification due to the filters (Spring security, etc) consuming the body and thus JAX-RS form parameters becoming empty. User can optionally deactivate standard behavior through setting "set.form.parameters.from.http.parameters" message property to false.</p><p>Parameters can be of type String or of any type that have constructors accepting a String parameter or stat ic valueOf(String s) methods. <br clear="none"> Additionally CXF JAXRS checks for static fromString(String s) method, so types with no valueO
f(String) factory methods can also be dealt with:</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;">public enum Gender {
+</div></div><p>In this case a template variable id available from a root class annotation is mapped to a parameter of type Long, while a name variable is mapped to a parameter of type String.</p><p>@QueryParam, @HeaderParam, @MatrixParam, @FormParam and @CookieParam annotations are also supported.</p><p>Note that the parameters, marked with @FormParam annotation, can take the values from the query parameters in case, if request body is already consumed. This is defined in JAX-RS specification due to the filters (Spring security, etc) consuming the body and thus JAX-RS form parameters becoming empty. User can optionally deactivate standard behavior through setting "set.form.parameters.from.http.parameters" message property to false.</p><p>Parameters can be of type String or of any type that have constructors accepting a String parameter or stat ic valueOf(String s) methods. <br clear="none">Additionally CXF JAXRS checks for static fromString(String s) method, so types with no valueOf
(String) factory methods can also be dealt with:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">public enum Gender {
MALE,
FEMALE;
@@ -359,7 +359,7 @@ public class Service {
}
</pre>
</div></div><p>Note that on the trunk enums with fromValue() factory methods are also supported.</p><p>JAX-RS PathSegment is also supported. A sequence of identically named parameters (queries, headers, etc) can be mapped to List or Set or SortedSet.</p><p>CXF JAXRS supports ParameterHandler extensions which can be used to deal with method parameters annotated with one of the JAXRS parameter annotations :</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;">public class MapHandler implements ParameterHandler<Map> {
+<pre class="brush: java; gutter: false; theme: Default">public class MapHandler implements ParameterHandler<Map> {
public Map fromString(String s) {...}
}
@@ -374,16 +374,16 @@ public class Service {
}
}
</pre>
-</div></div><p>Note that ParameterHandlers can not be used to deal with parameters representing a message body, "byte[] byte" in this example. MessageBodyReaders have to deal with this task. That said, a given MessageBodyReader implementation can also implement ParameterHandler.</p><p>ParameterHandlers can be registered as providers either from Spring or programmatically.<br clear="none"> Note that by default the handlers are checked last after all the other options recommended by the JAX-RS specification have been tried.<br clear="none"> Starting from CXF 2.5.3 the handlers will always be checked first for java.util.Date and java.util.Locale parameters. Additionally, a "check.parameter.handlers.first" contextual property can be used to get the handlers checked first when the parameters of other types are processed.</p><p>All the parameters are automatically decoded. This can be disabled by using @Encoded annotation.<br clear="none"> Parameters can have a default value set using a D
efaultValue annotation :</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;"> public Response updateCustomer(@DefaultValue("123") @QueryParam("id") Long id, @PathParam("name") String name) { ... }
+</div></div><p>Note that ParameterHandlers can not be used to deal with parameters representing a message body, "byte[] byte" in this example. MessageBodyReaders have to deal with this task. That said, a given MessageBodyReader implementation can also implement ParameterHandler.</p><p>ParameterHandlers can be registered as providers either from Spring or programmatically.<br clear="none">Note that by default the handlers are checked last after all the other options recommended by the JAX-RS specification have been tried.<br clear="none">Starting from CXF 2.5.3 the handlers will always be checked first for java.util.Date and java.util.Locale parameters. Additionally, a "check.parameter.handlers.first" contextual property can be used to get the handlers checked first when the parameters of other types are processed.</p><p>All the parameters are automatically decoded. This can be disabled by using @Encoded annotation.<br clear="none">Parameters can have a default value set using a Defa
ultValue annotation :</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"> public Response updateCustomer(@DefaultValue("123") @QueryParam("id") Long id, @PathParam("name") String name) { ... }
</pre>
</div></div><p>JAX-RS mandates that only a single method parameter which is not annotated with JAXRS annotations applicable to method parameters is allowed in a resource method. 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;">public Response do(@PathParam("id") String id, String body) {
+<pre class="brush: java; gutter: false; theme: Default">public Response do(@PathParam("id") String id, String body) {
}
</pre>
</div></div><p>Parameters like 'String body' are expected to represent the request body/input stream. It's the job of JAX-RS MessageBodyReaders to deserialize the request body into an object of the expected type.</p><p>It's also possible to inject all types of parameters into fields or through dedicated setters. For example, the first code fragment in this section can be rewritten like this:</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("/customer/{id}")
+<pre class="brush: java; gutter: false; theme: Default">@Path("/customer/{id}")
public class CustomerService {
@PathParam("id")
@@ -404,7 +404,7 @@ public class CustomerService {
}
</pre>
</div></div><h2 id="JAX-RSBasics-Parameterbeans">Parameter beans</h2><p>There's a CXF extension which makes it possible to inject a sequence of @PathParam, @QueryParam, @FormParam or @MatrixParam parameters into a bean. 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("/customer/{id}")
+<pre class="brush: java; gutter: false; theme: Default">@Path("/customer/{id}")
public class CustomerService {
@@ -443,7 +443,7 @@ public class OrderBean {
</pre>
</div></div><p>Note that there's a single @PathParam with an empty value in updateCustomer() - this is an extension bit. The value for a template variable 'id' is injected into Customer.setId(Long id), while the value for 'name' is injected into Customer.setName(String s). The setter methods should have a single parameter, the conversion from the actual value to the parameter instance follows the same procedure as outlined above.</p><p>Similarly, in getCustomerOrder(), OrderBean can be injected with corresponding values from a query string like ?id=1&weight=2 or from matrix parameters set as part of one of the path segments : /customer/1/order;id=1;weight=2. Likewise, in addCustomerOrder(), FormParam("") can capture all the values submitted from an HTML form and inject them into OrderBean.</p><p>Nested beans are also supported, which among other things, makes it possible to formulate advanced search queries. For example, given the following bean definitions:</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;">class Name {
+<pre class="brush: java; gutter: false; theme: Default">class Name {
String first;
String last;
}
@@ -468,15 +468,15 @@ class MyService
Person getPerson(@QueryParam("") Person person);
}
</pre>
-</div></div><p>a query like</p><p>> /getPerson?sex=M&legalName.first=John&legalName.last=Doe&homeAddr.city=Reno&homeAddr.state=NV</p><p>will result in a Person bean being properly initialized and all the search criteria being captured and easily accessible. Note more enhancements are being planned in this area.</p><h1 id="JAX-RSBasics-Resourcelifecycles">Resource lifecycles</h1><p>The scopes which are supported by default are Singleton and Prototype(per-request).<br clear="none"> Note that JAXRS MessageBodyWriter and MessageBodyReader providers are always singletons.</p><p>Classes with prototype scopes can get JAXRS contexts or parameters injected at construction time:</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("/")
+</div></div><p>a query like</p><p>> /getPerson?sex=M&legalName.first=John&legalName.last=Doe&homeAddr.city=Reno&homeAddr.state=NV</p><p>will result in a Person bean being properly initialized and all the search criteria being captured and easily accessible. Note more enhancements are being planned in this area.</p><h1 id="JAX-RSBasics-Resourcelifecycles">Resource lifecycles</h1><p>The scopes which are supported by default are Singleton and Prototype(per-request).<br clear="none">Note that JAXRS MessageBodyWriter and MessageBodyReader providers are always singletons.</p><p>Classes with prototype scopes can get JAXRS contexts or parameters injected at construction time:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">@Path("/")
public class PerRequestResourceClass {
public PerRequestResourceClass(@Context HttpHeaders headers, @QueryParam("id") Long id) {}
}
</pre>
-</div></div><p>Classes with singleton scopes can only have contexts injected at the construction time and it is only a CXFNonSpringJaxrsServlet which can do it. In most cases you can have contexts injected as bean properties right after construction time.</p><p>See the "Lifecycle management" section for more details.</p><h1 id="JAX-RSBasics-Overviewoftheselectionalgorithm.">Overview of the selection algorithm.</h1><p>The JAX-RS Selection algorithm is used to select root resource classes, resource methods and subresource locators.</p><h2 id="JAX-RSBasics-Selectingbetweenmultipleresourceclasses">Selecting between multiple resource classes</h2><p>When multiple resource classes match a given URI request, the following algorithm is used :<br clear="none"> 1. Prefer the resource class which has more literal characters in its @Path annotation.</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("/bar/{id}")
+</div></div><p>Classes with singleton scopes can only have contexts injected at the construction time and it is only a CXFNonSpringJaxrsServlet which can do it. In most cases you can have contexts injected as bean properties right after construction time.</p><p>See the "Lifecycle management" section for more details.</p><h1 id="JAX-RSBasics-Overviewoftheselectionalgorithm.">Overview of the selection algorithm.</h1><p>The JAX-RS Selection algorithm is used to select root resource classes, resource methods and subresource locators.</p><h2 id="JAX-RSBasics-Selectingbetweenmultipleresourceclasses">Selecting between multiple resource classes</h2><p>When multiple resource classes match a given URI request, the following algorithm is used :<br clear="none">1. Prefer the resource class which has more literal characters in its @Path annotation.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">@Path("/bar/{id}")
public class Test1 {}
@Path("/bar/{id}/baz")
public class Test2 {}
@@ -486,19 +486,19 @@ public class Test3 {}
public class Test4 {}
</pre>
</div></div><p>Both classes match /bar/1/baz requests but Test2 will be selected as it has 9 Path literal characters compared to 5 in Test1. Similarly, Test4 wins against Test3 when a /foo/ request arrives.</p><p>2. Prefer the resource class which has more capturing groups in its @Path annotation.</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("/bar/{id}/")
+<pre class="brush: java; gutter: false; theme: Default">@Path("/bar/{id}/")
public class Test1 {}
@Path("/bar/{id}/{id2}")
public class Test2 {}
</pre>
</div></div><p>Both classes match /bar/1/2 requests and both have the same number of literal characters but Test2 will be selected as it has 2 Path capturing groups (id and id1) as opposed to 1 in Test1.</p><p>3. Prefer the resource class which has more capturing groups with arbitrary regular expressions in its @Path annotation.</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("/bar/{id:.+}/baz/{id2}")
+<pre class="brush: java; gutter: false; theme: Default">@Path("/bar/{id:.+}/baz/{id2}")
public class Test1 {}
@Path("/bar/{id}/bar/{id2}")
public class Test2 {}
</pre>
</div></div><p>Both classes match /bar/1/baz/2 requests and both have the same number of literal characters and capturing groups but Test1 will be selected as it has 1 Path capturing groups with the arbitrary regular expression (id) as opposed to 0 in Test2.</p><h2 id="JAX-RSBasics-Selectingbetweenmultipleresourcemethods">Selecting between multiple resource methods</h2><p>Once the resource class has been selected, the next step is to choose a resource method. If multiple methods can be matched then the same rules which are used for selecting resource classes are applied. Additionally, one more rule is used.</p><p>4. Prefer a resource method to a subresource locator method</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("/")
+<pre class="brush: java; gutter: false; theme: Default">@Path("/")
public class Test1 {
@Path("/bar")
@@ -518,7 +518,7 @@ public class Order {
}
</pre>
</div></div><p>Both getOrderFromSubresource() and getOrder() methods can be used to serve a /bar request. However, getOrder() wins.</p><h2 id="JAX-RSBasics-Resourcemethodsandmediatypes">Resource methods and media types</h2><p>Consider this resource class with 2 resource methods :</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("/")
+<pre class="brush: java; gutter: false; theme: Default">@Path("/")
public class Test1 {
@Path("/bar")
@@ -536,7 +536,7 @@ public class Test1 {
}
</pre>
</div></div><p>Both methods match /bar requests. If in a given request both Content-Type and Accept are set to application/xml then getOrderXML will be selected. If both Content-Type and Accept are set to application/json then getOrderJSON will be chosen instead.</p><p>For this specific example, in both cases either JAXB or JSON message body readers and writers will be selected to deserialize the input stream into OrderDetails and serialize Order into the output stream. Message body providers can have @Produces and @Consumes set too, and they have to match those on a chosen resource method.</p><p>The above code can be replaced with this one :</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("/")
+<pre class="brush: java; gutter: false; theme: Default">@Path("/")
public class Test1 {
@Path("/bar")
@@ -548,7 +548,7 @@ public class Test1 {
}
</pre>
</div></div><h2 id="JAX-RSBasics-Customselectionbetweenmultipleresourcesoroperations">Custom selection between multiple resources or operations</h2><p>The JAX-RS selection algorithm has been designed with a lot of attention being paid to various possible cases, as far as the selection between multiple matching resource classes or methods is concerned.</p><p>However, in some cases, users have reported the algorithm being somewhat restrictive in the way multiple resource classes are selected. For example, by default, after a given resource class has been matched and if this class has no matching resource method, then the algorithm stops executing, without attempting to check the remaining matching resource classes.</p><p>Starting from CXF 2.2.5 it is possible to register a custom <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/ext/ResourceComparator.java">ResourceComparator</a> implementation us
ing a jaxrs:server/jaxrs:resourceComparator element, 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;"><!-- JAX-RS endpoint declaration fragment -->
+<pre class="brush: java; gutter: false; theme: Default"><!-- JAX-RS endpoint declaration fragment -->
<jaxrs:server address="/">
<!-- Usual elements, like serviceBeans or providers, etc -->
@@ -559,8 +559,8 @@ public class Test1 {
</jaxrs:server>
</pre>
-</div></div><p>Custom implementations can check the names of the resource classes or methods being compared and given the current request URI they can make sure that the required class or method is chosen by returning either -1 or 1, as needed. If 0 is returned then the runtime will proceed with executing the default selection algorithm. At the moment the easiest way to get to the details such as the current request URI is to create an instance of the CXF JAXRS UriInfoImpl using a constructor accepting a Message.</p><p>Note that by the time a custom ResourceComparator is called the provided resource classes or methods have already been successfully matched by the runtime.</p><p>For example, the optional HTTP request and URI parameters (query, matrix, headers, cookies) and form parameters do not affect the selection algorithm.<br clear="none"> A custom ResourceComparator can be used when this limitation is considered to be problematic. For example, the following shows one such implem
entation:</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 java.io.UnsupportedEncodingException;
+</div></div><p>Custom implementations can check the names of the resource classes or methods being compared and given the current request URI they can make sure that the required class or method is chosen by returning either -1 or 1, as needed. If 0 is returned then the runtime will proceed with executing the default selection algorithm. At the moment the easiest way to get to the details such as the current request URI is to create an instance of the CXF JAXRS UriInfoImpl using a constructor accepting a Message.</p><p>Note that by the time a custom ResourceComparator is called the provided resource classes or methods have already been successfully matched by the runtime.</p><p>For example, the optional HTTP request and URI parameters (query, matrix, headers, cookies) and form parameters do not affect the selection algorithm.<br clear="none">A custom ResourceComparator can be used when this limitation is considered to be problematic. For example, the following shows one such impleme
ntation:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">import java.io.UnsupportedEncodingException;
import java.net.URLDecoder;
import java.util.HashSet;
import java.util.List;
@@ -665,7 +665,7 @@ public class QueryResourceInfoComperator
}
</pre>
</div></div><p>Now consider this code:</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("/paramTest")
+<pre class="brush: java; gutter: false; theme: Default">@Path("/paramTest")
public class MySimpleService {
@GET
@@ -682,8 +682,8 @@ public class MySimpleService {
}
</pre>
-</div></div><p>Using the custom comparator will lead to getFoo() method accepting a single query parameter selected when a request URI has only one query parameter, and getFoo() method accepting multiple query parameters selected when a request URI has at least two query parameters. Further customizations may also be possible.</p><h1 id="JAX-RSBasics-Contextannotations">Context annotations</h1><p>A number of context types can be injected as parameters, in fields or through dedicated methods.<br clear="none"> UriInfo, SecurityContext, HttpHeaders, Providers, Request, ContextResolver, Servlet types (HttpServletRequest, HttpServletResponse, ServletContext, ServletConfig) can be injected.</p><p>A CXF-specific composite context interface, <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/ext/MessageContext.java">MessageContext</a> is also supported which makes it easier to deal with all the supported
JAX-RS contexts (and indeed with future ones) and also lets us check the current message's properties.</p><p>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("/customer")
+</div></div><p>Using the custom comparator will lead to getFoo() method accepting a single query parameter selected when a request URI has only one query parameter, and getFoo() method accepting multiple query parameters selected when a request URI has at least two query parameters. Further customizations may also be possible.</p><h1 id="JAX-RSBasics-Contextannotations">Context annotations</h1><p>A number of context types can be injected as parameters, in fields or through dedicated methods.<br clear="none">UriInfo, SecurityContext, HttpHeaders, Providers, Request, ContextResolver, Servlet types (HttpServletRequest, HttpServletResponse, ServletContext, ServletConfig) can be injected.</p><p>A CXF-specific composite context interface, <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/ext/MessageContext.java">MessageContext</a> is also supported which makes it easier to deal with all the supported
JAX-RS contexts (and indeed with future ones) and also lets us check the current message's properties.</p><p>Example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">@Path("/customer")
public class CustomerService {
@Context
@@ -705,7 +705,7 @@ public class CustomerService {
</pre>
</div></div><p>Note that all types of supported JAX-RS providers such as MessageBodyWriter, MessageBodyReader, ExceptionMapper and ContextResolver, as well as the list of body providers which can be provided by Providers can have contexts injected too. The only exception is that no parameter level injection is supported for providers due to methods of JAXRS providers being fixed.</p><p>Note that Providers and ContextResolver are likely to be of interest to message body providers rather than to the actual application code. You can also inject all the context types into @Resource annotated fields.</p><h2 id="JAX-RSBasics-CustomContexts">Custom Contexts</h2><p>Registering a custom <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/ext/ContextProvider.java">ContextProvider</a> implementation such as <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/extensions
/search/src/main/java/org/apache/cxf/jaxrs/ext/search/SearchContextProvider.java">SearchContextProvider</a> lets attach Context annotations to arbitrary classes which can be helpful when some of the information representing the current request needs to be optimized or specialized, 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;">package resources;
+<pre class="brush: java; gutter: false; theme: Default">package resources;
import org.apache.cxf.jaxrs.ext.search.SearchContext;
@Path("/")
public class RootResource {
@@ -715,7 +715,7 @@ public class RootResource {
}
</pre>
</div></div><p>and</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>
+<pre class="brush: java; gutter: false; theme: Default"><jaxrs:server>
<serviceBeans>
<bean class="resources.RootResource"/>
</serviceBeans>
@@ -725,7 +725,7 @@ public class RootResource {
</jaxrs:server>
</pre>
</div></div><p>Custom Context implementations may get all the information about the HTTP request from the current CXF message.</p><h1 id="JAX-RSBasics-URIcalculationusingUriInfoandUriBuilder">URI calculation using UriInfo and UriBuilder</h1><p>Mapping of a particular URI to a service that returns some resource is straightforward using the @Path annotation. However RESTful services are often connected: one service returns data that is used as the key in another service. Listing entities and accessing a particular entity is a typical 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("/customers")
+<pre class="brush: java; gutter: false; theme: Default">@Path("/customers")
public class CustomerService {
@GET
@@ -742,7 +742,7 @@ public class CustomerService {
}
</pre>
</div></div><p>For this service we can assume that the returned list of customers exposes only basic attributes and more details is returned using the second method which uses the customer id as the key. Something like this:</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;">GET http://foobar.com/api/customers
+<pre class="brush: java; gutter: false; theme: Default">GET http://foobar.com/api/customers
<customers>
<customer id="1005">John Doe</customer>
@@ -759,7 +759,7 @@ GET http://foobar.com/api/customers/1005
</customer>
</pre>
</div></div><p>How does a client of this service know how to get from list of customers to given customer? A trivial approach would be to expect the client to compute the proper URI. But wouldn't it be better to have the services provide full URIs in the response that can be used directly? This way the client would be more decoupled from the service itself (which may change URI format over time). A client could be provided the following on response, 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;">GET http://foobar.com/api/customers
+<pre class="brush: java; gutter: false; theme: Default">GET http://foobar.com/api/customers
<customers-list>
<customer id="1005" url="http://foobar.com/api/customers/1005">John Doe</customer>
@@ -768,7 +768,7 @@ GET http://foobar.com/api/customers/1005
</customers-list>
</pre>
</div></div><p>The problem for the service is how to determine these URIs when the paths come from @Path annotations. It gets more complicated as we consider paths with templates (variables) on multiple levels or sub-resources introducing dynamic routing to different URIs.</p><p>The core part of the solution is to inject the <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.1/javax/ws/rs/core/UriInfo.html" rel="nofollow">UriInfo</a> object into method "getCustomers". This helper object allows for extracting useful information about the current URI context, but more importantly allows for getting the <a shape="rect" class="external-link" href="https://jax-rs.github.io/apidocs/2.1/javax/ws/rs/core/UriBuilder.html" rel="nofollow">UriBuilder</a> object. UriBuilder has multiple appender methods for building the URI for each object; in our case to the stem URI we can append path in multiple ways, providing it as a string (which we actually want to avoid here)
or a resource (class or method) to extract the @Path value. Finally UriBuilder must have values bound to its template variables to render the actual URI. This case in action looks like this:</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("/customers")
+<pre class="brush: java; gutter: false; theme: Default">@Path("/customers")
public class CustomerService {
@GET
@@ -793,7 +793,7 @@ public class CustomerService {
}
</pre>
</div></div><h1 id="JAX-RSBasics-Annotationinheritance">Annotation inheritance</h1><p>Most of the JAX-RS annotations can be inherited from either an interface or a superclass. 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;">public interface CustomerService {
+<pre class="brush: java; gutter: false; theme: Default">public interface CustomerService {
@PUT
@Path("/customers/{id}")
@@ -820,7 +820,7 @@ public class Customers implements Custom
}
</pre>
</div></div><p>Similarly, annotations can be inherited from super-classes. In CXF, the resource class will inherit the class-level annotations from both its implemented interfaces and any class it extends.</p><h1 id="JAX-RSBasics-Sub-resourcelocators.">Sub-resource locators.</h1><p>A method of a resource class that is annotated with @Path becomes a sub-resource locator when no annotation with an HttpMethod designator like @GET is present. Sub-resource locators are used to further resolve the object that will handle the request. They can delegate to other sub-resource locators, including themselves.</p><p>In the example below, getOrder method is a sub-resource locator:</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("/customerservice/")
+<pre class="brush: java; gutter: false; theme: Default">@Path("/customerservice/")
public class CustomerService {
@Path("/orders/{orderId}/")
@@ -861,7 +861,7 @@ public class Order {
}
</pre>
[... 61 lines stripped ...]