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 ...]
