Author: buildbot
Date: Fri Sep 14 13:56:56 2018
New Revision: 1035170
Log:
Production update by buildbot for cxf
Added:
websites/production/cxf/content/docs/jax-rs-claims.html
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/jax-rs.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
Added: websites/production/cxf/content/docs/jax-rs-claims.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-claims.html (added)
+++ websites/production/cxf/content/docs/jax-rs-claims.html Fri Sep 14 13:56:56
2018
@@ -0,0 +1,299 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<html>
+ <head>
+
+<link type="text/css" rel="stylesheet" href="/resources/site.css">
+<script src='/resources/space.js'></script>
+
+<meta http-equiv="Content-type" content="text/html;charset=UTF-8">
+<meta name="keywords" content="business integration, EAI, SOA, Service
Oriented Architecture, web services, SOAP, JBI, JMS, WSDL, XML, EDI, Electronic
Data Interchange, standards support, integration standards, application
integration, middleware, software, solutions, services, CXF, open source">
+<meta name="description" content="Apache CXF, Services Framework - JAX-RS
Claims">
+
+
+<link type="text/css" rel="stylesheet"
href="/resources/highlighter/styles/shCoreCXF.css">
+<link type="text/css" rel="stylesheet"
href="/resources/highlighter/styles/shThemeCXF.css">
+
+<script src='/resources/highlighter/scripts/shCore.js'></script>
+<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
+<script src='/resources/highlighter/scripts/shBrushXml.js'></script>
+<script>
+ SyntaxHighlighter.defaults['toolbar'] = false;
+ SyntaxHighlighter.all();
+</script>
+
+
+ <title>
+Apache CXF -- JAX-RS Claims
+ </title>
+ </head>
+<body onload="init()">
+
+
+<table width="100%" cellpadding="0" cellspacing="0">
+ <tr>
+ <td id="cell-0-0" colspan="2"> </td>
+ <td id="cell-0-1"> </td>
+ <td id="cell-0-2" colspan="2"> </td>
+ </tr>
+ <tr>
+ <td id="cell-1-0"> </td>
+ <td id="cell-1-1"> </td>
+ <td id="cell-1-2">
+ <!-- Banner -->
+<div class="banner" id="banner"><div><table border="0" cellpadding="0"
cellspacing="0" width="100%"><tr><td align="left" colspan="1" nowrap>
+<a shape="rect" href="http://cxf.apache.org/"; title="Apache CXF"><span
style="font-weight: bold; font-size: 170%; color: white">Apache CXF</span></a>
+</td><td align="right" colspan="1" nowrap>
+<a shape="rect" href="http://www.apache.org/"; title="The Apache Sofware
Foundation"><img border="0" alt="ASF Logo"
src="http://cxf.apache.org/images/asf-logo.png";></a>
+</td></tr></table></div></div>
+ <!-- Banner -->
+ <div id="top-menu">
+ <table border="0" cellpadding="1" cellspacing="0" width="100%">
+ <tr>
+ <td>
+ <div align="left">
+ <!-- Breadcrumbs -->
+<a href="index.html">Index</a> > <a
href="restful-services.html">RESTful Services</a> > <a
href="jax-rs.html">JAX-RS</a> > <a
href="jax-rs-claims.html">JAX-RS Claims</a>
+ <!-- Breadcrumbs -->
+ </div>
+ </td>
+ <td>
+ <div align="right">
+ <!-- Quicklinks -->
+<div id="quicklinks"><p><a shape="rect"
href="http://cxf.apache.org/download.html";>Download</a> | <a shape="rect"
href="http://cxf.apache.org/docs/index.html";>Documentation</a></p></div>
+ <!-- Quicklinks -->
+ </div>
+ </td>
+ </tr>
+ </table>
+ </div>
+ </td>
+ <td id="cell-1-3"> </td>
+ <td id="cell-1-4"> </td>
+ </tr>
+ <tr>
+ <td id="cell-2-0" colspan="2"> </td>
+ <td id="cell-2-1">
+ <table>
+ <tr valign="top">
+ <td height="100%">
+ <div id="wrapper-menu-page-right">
+ <div id="wrapper-menu-page-top">
+ <div id="wrapper-menu-page-bottom">
+ <div id="menu-page">
+ <!-- NavigationBar -->
+<div id="navigation"><ul class="alternate"><li><a shape="rect"
href="overview.html">Overview</a></li><li><a shape="rect"
href="how-tos.html">How-Tos</a></li><li><a shape="rect"
href="frontends.html">Frontends</a></li><li><a shape="rect"
href="databindings.html">DataBindings</a></li><li><a shape="rect"
href="transports.html">Transports</a></li><li><a shape="rect"
href="configuration.html">Configuration</a></li><li><a shape="rect"
href="debugging-and-logging.html">Debugging and Logging</a></li><li><a
shape="rect" href="tools.html">Tools</a></li><li><a shape="rect"
href="restful-services.html">RESTful Services</a></li><li><a shape="rect"
href="wsdl-bindings.html">WSDL Bindings</a></li><li><a shape="rect"
href="service-routing.html">Service Routing</a></li><li><a shape="rect"
href="dynamic-languages.html">Dynamic Languages</a></li><li><a shape="rect"
href="ws-support.html">WS-* Support</a></li><li><a shape="rect"
href="advanced-integration.html">Advanced Integration</a></li><li><a shape
="rect" href="deployment.html">Deployment</a></li><li><a shape="rect"
href="schemas-and-namespaces.html">Use of Schemas and
Namespaces</a></li></ul><hr><ul
class="alternate"><li><p>Search</p></li></ul><form
enctype="application/x-www-form-urlencoded" method="get" id="cse-search-box"
action="http://www.google.com/cse";>
+ <div>
+ <input type="hidden" name="cx" value="002890367768291051730:o99qiwa09y4">
+ <input type="hidden" name="ie" value="UTF-8">
+ <input type="text" name="q" size="21">
+ <input type="submit" name="sa" value="Search">
+ </div>
+</form>
+<script type="text/javascript"
src="http://www.google.com/cse/brand?form=cse-search-box&lang=en";></script><hr><ul
class="alternate"><li><a shape="rect"
href="http://cxf.apache.org/javadoc/latest/";>API 3.2.x (Javadoc)</a></li><li><a
shape="rect" href="http://cxf.apache.org/javadoc/latest-3.1.x/";>API 3.1.x
(Javadoc)</a></li><li><a shape="rect" href="http://cxf.apache.org/";>CXF
Website</a></li></ul><p> </p><p><a shape="rect" class="external-link"
href="http://www.apache.org/events/current-event.html";><span
class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image
confluence-external-resource"
src="http://www.apache.org/events/current-event-125x125.png";
data-image-src="http://www.apache.org/events/current-event-125x125.png";></span></a></p></div>
+ <!-- NavigationBar -->
+ </div>
+ </div>
+ </div>
+ </div>
+ </td>
+ <td height="100%">
+ <!-- Content -->
+ <div class="wiki-content">
+<div id="ConfluenceContent"><p> <span
style="font-size:2em;font-weight:bold">JAX-RS: Claims</span>
+
+
+<br clear="none"></p><p><style type="text/css">/*<![CDATA[*/
+div.rbtoc1536933375575 {padding: 0px;}
+div.rbtoc1536933375575 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1536933375575 li {margin-left: 0px;padding-left: 0px;}
+
+/*]]>*/</style></p><div class="toc-macro rbtoc1536933375575">
+<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSClaims-Introduction">Introduction</a></li><li><a shape="rect"
href="#JAX-RSClaims-Backwardscompatibilityconfigurationnote">Backwards
compatibility configuration note</a></li><li><a shape="rect"
href="#JAX-RSClaims-Mavendependencies">Maven dependencies</a>
+<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSClaims-Claimsannotations">Claims annotations</a></li></ul>
+</li></ul>
+</div><h1 id="JAX-RSClaims-Introduction">Introduction</h1><p>CXF JAX-RS offers
an extension letting users to enforce a new fine-grained Claims Based Access
Control (CBAC) based on <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/core/src/main/java/org/apache/cxf/security/claims/authorization/Claim.java";
rel="nofollow">Claim</a> and <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/core/src/main/java/org/apache/cxf/security/claims/authorization/Claims.java";
rel="nofollow">Claims</a> annotations as well as <a shape="rect"
class="external-link"
href="https://github.com/apache/cxf/blob/master/core/src/main/java/org/apache/cxf/security/claims/authorization/ClaimMode.java";
rel="nofollow">ClaimMode</a> enum class. It works with SAML tokens and with
JWT tokens (from the 3.3.0 release onwards).</p><p>See also <a shape="rect"
href="jax-rs-xml-security.html">JAX-RS XML Security</a>, <a shape="rect"
href="jax-rs-saml.html"
>JAX-RS SAML</a> and <a shape="rect" href="jax-rs-jose.html">JAX-RS
>JOSE</a>.</p><h1
>id="JAX-RSClaims-Backwardscompatibilityconfigurationnote">Backwards
>compatibility configuration note</h1><p>From Apache CXF 3.1.0, the
>WS-Security based configuration tags used to configure XML Signature or
>Encryption ("ws-security-*") have been changed to just start with
>"security-". Apart from this they are exactly the same. Older "ws-security-"
>values continue to be accepted in CXF 3.1.0. To use any of the configuration
>examples in this page with an older version of CXF, simply add a "ws-" prefix
>to the configuration tag.</p><p>The package for Claim, Claims and ClaimMode
>annotations has changed from "org.apache.cxf.rs.security.saml.authorization"
>to "org.apache.cxf.security.claims.authorization". Starting from CXF 2.7.1,
>the default name format for claims is
>"urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified" instead of "<a
>shape="rect" class="external-link" href="http://schemas.xmlsoap.org
/ws/2005/05/identity/claims"
rel="nofollow">http://schemas.xmlsoap.org/ws/2005/05/identity/claims</a>".</p><p>From
the 3.3.0 release, the Claims access control annotations/interceptors <a
shape="rect" class="external-link"
href="https://issues.apache.org/jira/browse/CXF-6727";>now work</a> with JWT
tokens (as well as SAML tokens). This resulted in the following package
changes:</p><ul><li>The package name of the ClaimsAuthorizingInterceptor has
changed: from
org.apache.cxf.rt.security.saml.interceptor.ClaimsAuthorizingInterceptor to
org.apache.cxf.rt.security.claims.interceptor.ClaimsAuthorizingInterceptor.</li><li>The
package name of the ClaimsAuthorizingFilter  has changed: from
org.apache.cxf.rs.security.saml.authorization.ClaimsAuthorizingFilter to
org.apache.cxf.rs.security.claims.ClaimsAuthorizingFilter</li></ul><h1
id="JAX-RSClaims-Mavendependencies">Maven dependencies</h1><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"><dependency>
+ <groupId>org.apache.cxf</groupId>
+ <artifactId>cxf-rt-rs-security-xml</artifactId>
+ <version>3.3.0</version>
+</dependency>
+</pre>
+</div></div><h2 id="JAX-RSClaims-Claimsannotations">Claims
annotations</h2><p>Here is a simple code fragment to secure a service object
using Claims annotations:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">import
org.apache.cxf.security.claims.authorization.Claim;
+import org.apache.cxf.security.claims.authorization.Claims;
+
+@Path("/bookstore")
+public class SecureClaimBookStore {
+
+ @POST
+ @Path("/books")
+ @Produces("application/xml")
+ @Consumes("application/xml")
+ @Claims({
+ @Claim({"admin" }),
+ @Claim(name = "http://claims/authentication-format";,
+ format = "http://claims/authentication";,
+ value = {"fingertip", "smartcard" })
+ })
+ public Book addBook(Book book) {
+ return book;
+ }
+
+}
+</pre>
+</div></div><p>SecureClaimBookStore.addBook(Book) can only be invoked if
Subject meets the following requirement: it needs to have a Claim with a value
"admin" and another Claim confirming that it got authenticated using either a
'fingertip' or 'smartcard' method. Note that @Claim({"admin"}) has no name and
format classifiers set - it relies on default name and format values, namely
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/role"; and
"urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"
("http://schemas.xmlsoap.org/ws/2005/05/identity/claims"; before CXF 2.7.1)
respectively. These default values may change in the future depending on which
claims are found to be used most often - but as you can see you can always
provide name and format values which will scope a given claim value.</p><p>Note
that in the above example, a Claim with the name
"http://claims/authentication-format"; has two values, 'fingertip' and
'smartcard'. By default, in order to meet this Claim, Subjec
t needs to have a Claim which has either a 'fingertip' or 'smartcard' value.
If it is expected that Subject needs to have a Claim which has both 'fingertip'
and 'smartcard' values, then the following change needs to be done:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">import
org.apache.cxf.security.claims.authorization.Claim;
+import org.apache.cxf.security.claims.authorization.Claims;
+
+@Path("/bookstore")
+public class SecureClaimBookStore {
+
+ @POST
+ @Path("/books")
+ @Produces("application/xml")
+ @Consumes("application/xml")
+ @Claims({
+ @Claim({"admin" }),
+ @Claim(name = "http://claims/authentication-format";,
+ format = "http://claims/authentication";,
+ value = {"fingertip", "smartcard" },
+ matchAll = true)
+ })
+ public Book addBook(Book book) {
+ return book;
+ }
+
+}
+</pre>
+</div></div><p>Claims can be specified using individual @Claim annotation,
they can be set at the class level and overridden at the method level and
finally a lax mode of check can be specified:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">import
org.apache.cxf.security.claims.authorization.Claim;
+import org.apache.cxf.security.claims.authorization.Claims;
+
+@Path("/bookstore")
+@Claim({"user"})
+public class SecureClaimBookStore {
+
+ @POST
+ @Path("/books")
+ @Produces("application/xml")
+ @Consumes("application/xml")
+ @Claims({
+ @Claim({"admin" }),
+ @Claim(name = "http://claims/authentication-format";,
+ format = "http://claims/authentication";,
+ value = {"fingertip", "smartcard" },
+ matchAll = true)
+ })
+ public Book addBook(Book book) {
+ return book;
+ }
+
+ @GET
+ @Claim(name = "http://claims/authentication-format";,
+ format = "http://claims/authentication";,
+ value = {"password" },
+ mode = ClaimMode.LAX)
+ public Book getBook() {
+ //...
+ }
+
+ @GET
+ public BookList getBookList() {
+ //...
+ }
+
+
+}
+</pre>
+</div></div><p>In the above example, getBookList() can be invoked if Subject
has a Claim with the value "user"; addBook() has it overridden - "admin" is
expected and the authentication format Claim too; getBook() can be invoked if
Subject has a Claim with the value "user" and it also must have the
authentication format Claim with the value "password" - or no such Claim at
all.</p><p>org.apache.cxf.rt.security.claims.interceptor.ClaimsAuthorizingInterceptor
("org.apache.cxf.rt.security.saml.interceptor.ClaimsAuthorizingInterceptor"
before CXF 3.3.0) enforces the CBAC rules. This filter can be overridden and
configured with the rules directly which can be useful if no Claim-related
annotations are expected in the code. Map nameAliases and formatAliases
properties are supported to make @Claim annotations look a bit simpler, 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">@Claim(name =
"auth-format", format = "authentication", value = {"password" })
+</pre>
+</div></div><p>where "auth-format" and "authentication" are aliases for
"http://claims/authentication-format"; and "http://claims/authentication";
respectively.</p><p>Given the above example, the question is how to extract the
information available in a received token (SAML/JWT) for the current request to
succeed in passing through the security filter enforcing the CBAC
rules.</p><p>The first and most important thing which needs to be done is to
verify that an assertion Subject can be mapped to a recognized identity
instance.</p><p>There is a number of ways a Subject can be validated.</p><p>If
STS is asked to validate the assertion then a successful response from IDP will
likely be good enough for CXF to trust the identity of the provider.<br
clear="none"> If the assertion signature is verified locally using the public
key of IDP then it could a good enough confirmation too.</p><p>Alternatively, a
custom validator, extending either
org.apache.ws.security.validate.SamlAssertionValidato
r or CXF SAML <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/xml/src/main/java/org/apache/cxf/rs/security/saml/authorization/SecurityContextProvider.java";
rel="nofollow">SecurityContextProvider</a> <a shape="rect"
class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/xml/src/main/java/org/apache/cxf/rs/security/saml/authorization/SecurityContextProviderImpl.java";
rel="nofollow">implementation</a> can be registered with the server side SAML
handler.</p><p>The latter option is preferred because not only one can validate
Subject - but also ensure that a resulting SecurityContext will return a user
Principal with a proper name - given that the actual Subject name available in
the assertion may need to be translated to a name recognized by the local
security stores or application. A combination of the assertion's Subject and
AttributeStatement elements may need to be checked to establish a real name.</p>
<p>In cases like this you may want to register a custom
SecurityContextProvider even if you have STS validating the assertion. Yet
another reason is to retrieve the information about roles for a given Subject
or map the assertion claims to roles for working with the RBAC to succeed, see
the next section for more information.</p><p>Have a look please at this server
configuration example:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"><bean
id="serviceBeanClaims"
class="org.apache.cxf.systest.jaxrs.security.saml.SecureClaimBookStore"/>
+<bean id="samlEnvHandler"
class="org.apache.cxf.rs.security.saml.SamlEnvelopedInHandler">
+ <property name="securityContextProvider">
+ <bean
class="org.apache.cxf.systest.jaxrs.security.saml.CustomSecurityContextProvider"/>
+ </property>
+</bean>
+
+<bean id="claimsHandler"
+
class="org.apache.cxf.rs.security.saml.authorization.ClaimsAuthorizingFilter">
+ <property name="securedObject" ref="serviceBeanClaims"/>
+</bean>
+
+<jaxrs:server address="/saml-claims">
+ <jaxrs:serviceBeans>
+ <ref bean="serviceBeanClaims"/>
+ </jaxrs:serviceBeans>
+ <jaxrs:providers>
+ <ref bean="samlEnvHandler"/>
+ <ref bean="claimsHandler"/>
+ </jaxrs:providers>
+</jaxrs:server>
+</pre>
+</div></div><p>An instance of
org.apache.cxf.rs.security.saml.authorization.ClaimsAuthorizingFilter (note
org.apache.cxf.rs.security.claims.ClaimsAuthorizingFilter from CXF 3.3.0) is
used to enforce CBAC. It's a simple JAX-RS filter wrapper around
ClaimsAuthorizingInterceptor. SamlEnvelopedInHandler processes and validates
SAML assertions and it also relies on a simple <a shape="rect"
class="external-link"
href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/java/org/apache/cxf/systest/jaxrs/security/saml/CustomSecurityContextProvider.java";
rel="nofollow">CustomSecurityContextProvider</a> to help it to figure out what
the actual Subject name is. A more involved implementation can do some
additional validation as well as override few more super class methods, more on
it next. The claims themselves have already been parsed and will be made
available to a resulting SecurityContext which ClaimsAuthorizingFilter will
rely upon.</p><p><br clear="none"></p></div>
+ </div>
+ <!-- Content -->
+ </td>
+ </tr>
+ </table>
+ </td>
+ <td id="cell-2-2" colspan="2"> </td>
+ </tr>
+ <tr>
+ <td id="cell-3-0"> </td>
+ <td id="cell-3-1"> </td>
+ <td id="cell-3-2">
+ <div id="footer">
+ <!-- Footer -->
+ <div id="site-footer">
+ <a href="http://cxf.apache.org/privacy-policy.html";>Privacy
Policy</a> -
+ (<a
href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=93323381";>edit
page</a>)
+ (<a
href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=93323381&showComments=true&showCommentArea=true#addcomment";>add
comment</a>)<br>
+ Apache CXF, CXF, Apache, the Apache feather logo are trademarks of The
Apache Software Foundation.<br>
+ All other marks mentioned may be trademarks or registered trademarks
of their respective owners.
+ </div>
+ <!-- Footer -->
+ </div>
+ </td>
+ <td id="cell-3-3"> </td>
+ <td id="cell-3-4"> </td>
+ </tr>
+ <tr>
+ <td id="cell-4-0" colspan="2"> </td>
+ <td id="cell-4-1"> </td>
+ <td id="cell-4-2" colspan="2"> </td>
+ </tr>
+</table>
+
+<script type="text/javascript">
+var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl."; :
"http://www.";);
+document.write(unescape("%3Cscript src='" + gaJsHost +
"google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
+</script>
+<script type="text/javascript">
+try {
+var pageTracker = _gat._getTracker("UA-4458903-1");
+pageTracker._trackPageview();
+} catch(err) {}</script>
+
+</body>
+</html>
+
Modified: websites/production/cxf/content/docs/jax-rs.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs.html (original)
+++ websites/production/cxf/content/docs/jax-rs.html Fri Sep 14 13:56:56 2018
@@ -117,15 +117,15 @@ Apache CXF -- JAX-RS
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div id="ConfluenceContent"><p> </p><p> <span
style="font-size:2em;font-weight:bold">JAX-RS</span>
+<div id="ConfluenceContent"><p><span
style="font-size:2em;font-weight:bold">JAX-RS</span>
- </p><p> </p><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1524513419665 {padding: 0px;}
-div.rbtoc1524513419665 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1524513419665 li {margin-left: 0px;padding-left: 0px;}
+ </p><p><br clear="none"></p><p><style type="text/css">/*<![CDATA[*/
+div.rbtoc1536933374529 {padding: 0px;}
+div.rbtoc1536933374529 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1536933374529 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1524513419665">
+/*]]>*/</style></p><div class="toc-macro rbtoc1536933374529">
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RS-Introduction">Introduction</a></li><li><a shape="rect"
href="#JAX-RS-JAX-RSCompliance">JAX-RS Compliance</a>
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RS-2.1Final">2.1
Final</a></li><li><a shape="rect" href="#JAX-RS-2.0Final">2.0
Final</a></li><li><a shape="rect" href="#JAX-RS-1.1">1.1</a></li></ul>
</li><li><a shape="rect" href="#JAX-RS-Projectsetupandconfiguration">Project
setup and configuration</a>
@@ -140,7 +140,7 @@ div.rbtoc1524513419665 li {margin-left:
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RS-Multiparts">Multiparts</a></li><li><a shape="rect"
href="#JAX-RS-SecureJAX-RSservices">Secure JAX-RS services</a></li><li><a
shape="rect" href="#JAX-RS-FailoverandLoadDistributionFeatures">Failover and
Load Distribution Features</a></li><li><a shape="rect"
href="#JAX-RS-Redirection">Redirection</a></li><li><a shape="rect"
href="#JAX-RS-XSLTandXPath">XSLT and XPath</a></li><li><a shape="rect"
href="#JAX-RS-ComplexSearchQueries">Complex Search Queries</a></li><li><a
shape="rect" href="#JAX-RS-Model-View-Controllersupport">Model-View-Controller
support</a></li><li><a shape="rect"
href="#JAX-RS-CombiningJAX-WSandJAX-RS">Combining JAX-WS and
JAX-RS</a></li><li><a shape="rect"
href="#JAX-RS-IntegrationwithDistributedOSGi">Integration with Distributed
OSGi</a></li><li><a shape="rect" href="#JAX-RS-ODataSupport">OData
Support</a></li><li><a shape="rect" href="#JAX-RS-OtherAdvancedFeatures">Other
Advanced Features</a></li></ul>
</li><li><a shape="rect" href="#JAX-RS-MavenPlugins">Maven
Plugins</a></li><li><a shape="rect"
href="#JAX-RS-Deployment">Deployment</a></li><li><a shape="rect"
href="#JAX-RS-Third-partyprojects">Third-party projects</a></li><li><a
shape="rect" href="#JAX-RS-References">References</a></li><li><a shape="rect"
href="#JAX-RS-Howtocontribute">How to contribute</a></li></ul>
</div><h1 id="JAX-RS-Introduction">Introduction</h1><p><a shape="rect"
class="external-link" href="http://en.wikipedia.org/wiki/JAX-RS";
rel="nofollow">JAX-RS</a>: Java API for RESTful Web Services is a Java
programming language API that provides support in creating web services
according to the Representational State Transfer (REST) architectural
style.</p><p>CXF supports JAX-RS 2.1 (<a shape="rect" class="external-link"
href="https://www.jcp.org/en/jsr/detail?id=370"; rel="nofollow">JSR-370</a>),
2.0 (<a shape="rect" class="external-link"
href="http://jcp.org/en/jsr/detail?id=339"; rel="nofollow">JSR-339</a>) and 1.1
(<a shape="rect" class="external-link"
href="http://jcp.org/en/jsr/detail?id=311";
rel="nofollow">JSR-311</a>).</p><p>CXF 3.2.0 supports JAX-RS 2.1. All existing
JAX-RS 2.0 and 1.1 applications can be run with CXF 3.2.0.</p><p>CXF 3.1.x and
3.0.x support JAX-RS 2.0.  Existing JAX-RS 1.1 applications can be run
with CXF 3.1.x/3.0.x.</p><p>See <a shape="rect" href
="jax-rs.html">below</a> for more information about the
compliance.</p><p>JAX-RS related demos are located under the <a shape="rect"
class="external-link"
href="http://svn.apache.org/viewvc/cxf/trunk/distribution/src/main/release/samples/jax_rs/";>samples/jax_rs
</a> directory.</p><p>Outstanding JAX-RS JIRA issues can be found <a
shape="rect" class="external-link"
href="https://issues.apache.org/jira/secure/IssueNavigator.jspa?reset=true&jqlQuery=project+%3D+CXF+AND+resolution+%3D+Unresolved+AND+component+%3D+JAX-RS+ORDER+BY+priority+DESC&mode=hide";>here</a>.</p><h1
id="JAX-RS-JAX-RSCompliance">JAX-RS Compliance</h1><p><span
class="confluence-anchor-link" id="JAX-RS-2_0_FINAL"></span></p><h2
id="JAX-RS-2.1Final">2.1 Final</h2><p>CXF 3.2.0 has been updated to implement
the JAX-RS 2.1 API’s as completely as possible.</p><p>If another TCK
licensee that uses CXF’s JAX-RS 2.1 implementation in their products
finds issues with CXF’s compliance, we are more than ha
ppy to fix bugs that are raised.</p><h2 id="JAX-RS-2.0Final">2.0
Final</h2><p>CXF 3.1.x and CXF 3.0.x have been updated to implement the JAX-RS
2.0 API’s as completely as possible without access to the final JAX-RS
2.0 TCK. <br clear="none">We have done extensive testing with JAX-RS 2.0 user
applications, samples, and the preliminary TCK to make sure CXF’s
implementation is as complete and compatible as we can make it. <br
clear="none">CXF makes and will continue making the best possible effort to
have JAX-RS 2.0 and new JAX-RS version implementations technically complete and
offering an environment for running the portable JAX-RS 2.0 applications.<br
clear="none">If the final 2.0 TCK is made available to Apache, we will make
sure CXF is updated to pass.<br clear="none">If another TCK licensee that uses
CXF’s JAX-RS 2.0 implementation in their products finds issues with
CXF’s compliance, we are more than happy to fix bugs that are
raised.</p><h2 id="JAX-RS-1.
1">1.1</h2><p>Apache CXF 2.6.x passes the final JAX-RS 1.1 TCK and is formally
1.1 compliant.</p><p>Please consult the <a shape="rect" class="external-link"
href="http://tomee.apache.org/apache-tomee.html";>TomEE</a> documentation on the
support of Java EE related JAX-RS 1.1 options in its Apache CXF-based JAX-RS
runtime.</p><p>CXF 2.7.x and CXF 3.0.0 will fully support and run JAX-RS 1.1
applications but will not pass the JAX-RS 1.1 TCK Signature tests due
to</p><p>CXF 2.7.x and CXF 3.0.0 depending on 2.0-m10 and 2.0 final versions of
JAX-RS 2.0 API.</p><p> </p><h1
id="JAX-RS-Projectsetupandconfiguration">Project setup and
configuration</h1><h2 id="JAX-RS-Migration">Migration</h2><h3
id="JAX-RS-FromJAX-RS2.0toJAX-RS2.1">From JAX-RS 2.0 to JAX-RS
2.1</h3><p>JAX-RS 2.1 is backward compatible with JAX-RS 2.0. Please see <a
shape="rect" href="jax-rs-basics.html">JAX-RS Basics</a> for more information
about JAX-RS 2.1.</p><p>All the existing JAX-RS 2.0 and 1.1 applications will
run
on CXF 3.2.0.</p><h3 id="JAX-RS-FromJAX-RS1.1to2.0">From JAX-RS 1.1 to
2.0</h3><p>JAX-RS 2.0 is backward compatible with JAX-RS 1.1. Please see <a
shape="rect" href="jax-rs-basics.html">JAX-RS Basics</a> for more information
about JAX-RS 2.0.</p><p>CXF 3.1.x and CXF 3.0.x are expected to support the
existing JAX-RS 1.1 applications.</p><h3
id="JAX-RS-FromCXF2.7.xtoCXF3.0.xor3.1.x">From CXF 2.7.x to CXF 3.0.x or
3.1.x</h3><p>Please check the <a shape="rect"
href="http://cxf.apache.org/docs/30-migration-guide.html";>CXF 3.0.0 Migration
Guide</a> for the information about all the changes<br clear="none"> in CXF
3.0.0. Here are more details on the changes specifically affecting JAX-RS
users:</p><p>1. CXF RequestHandler and ResponseHandler filters have been
removed.</p><p>These legacy CXF filters are still supported in 2.7.x but no
longer in 3.0.0. Please use <a shape="rect" class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/container/ContainerRequestFi
lter.html" rel="nofollow">ContainerRequestFilter</a> and <a shape="rect"
class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/container/ContainerResponseFilter.html";
rel="nofollow">ContainerResponseFilter</a> instead. Also, <a shape="rect"
class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/ext/ReaderInterceptor.html";
rel="nofollow">ReaderInterceptor</a> and <a shape="rect" class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/ext/WriterInterceptor.html";
rel="nofollow">WriterInterceptor</a> can be used too.</p><p>Note, CXF filters
had org.apache.cxf.message.Message available in the signature. If CXF Message
is used in the existing CXF RequestHandler or ResponseHandler then use
"org.apache.cxf.phase.PhaseInterceptorChain.getCurrentMessage()" or
"org.apache.cxf.jaxrs.util.JAXRSUtils.getCurrentMessage()" to get a Message
which has all the contextual information available.</p><p>For exa
mple, instead of</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 CustomRequestHandler implements
RequestHandler {
+<pre class="brush: java; gutter: false; theme: Default">public class
CustomRequestHandler implements RequestHandler {
public Response handleRequest(Message message, ClassResourceInfo cri) {
}
}
@@ -152,7 +152,7 @@ public class CustomResponseHandler imple
</pre>
</div></div><p>do</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 CustomRequestFilter implements
ContainerRequestFilter {
+<pre class="brush: java; gutter: false; theme: Default">public class
CustomRequestFilter implements ContainerRequestFilter {
public void filter(ContainerRequestContext context) {
Message message = JAXRSUtils.getCurrentMessage();
ClassResourceInfo cri =
message.getExchange().get(OperationResourceInfo.class).getClassResourceInfo();
@@ -176,17 +176,17 @@ public class CustomResponseFilter implem
</pre>
</div></div><p>The above is only needed to ease the migration of the existing
RequestHandler or ResponseHandler implementations. Prefer writing portable
JAX-RS 2.0 filter implementations if possible. CXF interceptors can be used to
do the CXF specific code if needed.</p><p>2. CXF
org.apache.cxf.jaxrs.ext.form.Form has been dropped, please use JAX-RS 2.0 <a
shape="rect" class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/core/Form.html";
rel="nofollow">Form</a> instead. For example, use:</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 javax.ws.rs.core.Form;
+<pre class="brush: java; gutter: false; theme: Default">import
javax.ws.rs.core.Form;
Form form = new Form().param("a", "b");
</pre>
</div></div><p>instead of</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import org.apache.cxf.jaxrs.ext.form.Form;
+<pre class="brush: java; gutter: false; theme: Default">import
org.apache.cxf.jaxrs.ext.form.Form;
Form form = new Form().set("a", "b");
</pre>
</div></div><p>3. CXF WebClient and proxy code has been moved to a new
cxf-rt-rs-client module. <br clear="none"> Also, jaxrs:client elements for
injecting proxies have had the namespace changed from from
"http://cxf.apache.org/jaxrs"; to
"http://cxf.apache.org/jaxrs-client";.</p><p>Please see <a shape="rect"
href="jax-rs-client-api.html">JAX-RS Client API</a> page for more
information.</p><p>4. WADL Auto Generator code has been moved to a new
cxf-rt-rs-service-description module.</p><p>5. CXF ParameterHandler has been
dropped. Please use <a shape="rect" class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/ext/ParamConverterProvider.html";
rel="nofollow">ParameterConverterProvider</a> instead, it can be used both on
the server and client sides.</p><p>6. JAX-RS 2.0 introduces a controversial
requirement that the default built-in JAX-RS MessageBodyWriter and JAX-RS
MessageBodyReader providers are <strong>preferred</strong> to custom providers
supporting
the same types unless the custom providers are precisely typed, for example,
if you have a custom InputStream reader properly implementing
isReadable:</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 MyStreamProvider implements
MessageBodyReader<Object> {
+<pre class="brush: java; gutter: false; theme: Default">public class
MyStreamProvider implements MessageBodyReader<Object> {
public boolean isReadable(Class<?> cls, ...) {
return InputStream.class.isAssignableFrom(cls) ||
Reader.class.isAssignableFrom(cls);
}
@@ -194,33 +194,33 @@ Form form = new Form().set("a", "b");
}
</pre>
</div></div><p>then the runtime will ignore it and choose a default
InputStream/Reader reader because MyStreamProvider is typed on Object. This was
done to deal with the cases where well-known JSON/etc providers are blindly
supporting all types in their isReadable methods by always returning 'true' and
then failing when asked to actually read the incoming stream into
InputStream/etc directly. In case of MyStreamProvider, it will need to be split
into MyInputStreamProvider and MyReaderProvider typed on InputStream and Reader
respectively.</p><p>At CXF level, the users which depend on CXF
MultipartProvider to have InputStream or String references to multipart
attachments will be affected unless they use @Multipart annotation. For
example, if we have a multipart payload with a single part/attachment only then
the following 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;">@POST
+<pre class="brush: java; gutter: false; theme: Default">@POST
@Consumes("multipart/form-data")
public void upload(InputStream is) {
}
</pre>
</div></div><p>which in CXF 2.7.x or earlier will return a pointer to
first/single individual part, will actually return a stream representing the
complete unprocessed multipart payload. Adding a @Multipart marker will keep
the existing code working as expected:</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;">@POST
+<pre class="brush: java; gutter: false; theme: Default">@POST
@Consumes("multipart/form-data")
public void upload(@Multipart InputStream is) {
}
</pre>
</div></div><p>Alternatively, setting a "support.type.as.multipart" contextual
property will do.</p><p>7. If the custom code throws JAX-RS
WebApplicationException with Response containing a non-null entity then custom
WebApplicationException mappers will be bypassed - another problematic
requirement, for example, the custom mappers doing the logging will miss on
such exceptions.<br clear="none"> Set CXF "support.wae.spec.optimization"
property to false to disable it.</p><p>8. In some cases the matching
sub-resource locators will be dropped to precisely meet the current JAX-RS
matching algorithm text, please see <a shape="rect" class="external-link"
href="https://issues.apache.org/jira/browse/CXF-5650";>CXF-5650</a> for more
information. Use a new "keep.subresource.candidates" property to support the
existing application if needed.</p><h3
id="JAX-RS-CXF3.1.2ProviderSortingChanges">CXF 3.1.2 Provider Sorting
Changes</h3><p>Starting from CXF 3.1.2 customMessageBodyReader (MBR), MessageB
odyWriter (MBW) and ExceptionMapper providers are sorted together with default
providers.</p><p>Before CXF 3.1.2 if a custom MBR or MBW matches the read or
write selection criteria, example, if MBR Consumes matches Content-Type and its
isReadable() returns true, then</p><p>the default providers are not even
checked. The specification however does let the custom providers be selected
only if no higher priority matching default provider is available.</p><p>For
example, suppose you have a custom StringReader which is not typed by String
but by Object. In this case the default provider which is typed by String wins.
To have the custom String provider winning one needs to type it by
String.</p><p>Check the specification or ask at the users list for more
details.</p><p> </p><h2 id="JAX-RS-Mavendependencies">Maven
dependencies</h2><h3 id="JAX-RS-CXF3.2.0">CXF 3.2.0</h3><p>The
cxf-rt-frontend-jaxrs dependency is required:</p><div class="code panel pdl"
style="border-width: 1px;"><div c
lass="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> <dependency>
+<pre class="brush: java; gutter: false; theme: Default"> <dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-frontend-jaxrs</artifactId>
<version>3.2.0</version>
</dependency>
</pre>
</div></div><p>This will in turn pull other <a shape="rect"
href="http://cxf.apache.org/project-status.html";>CXF modules</a> such
<code>cxf-core</code> and <code>cxf-rt-transports-http</code>, check <a
shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/frontend/jaxrs/pom.xml";
rel="nofollow">the pom</a> for more information.</p><p><code><a shape="rect"
class="external-link" href="http://javax.ws"; rel="nofollow">javax.ws</a>.rs/<a
shape="rect" class="external-link" href="http://javax.ws";
rel="nofollow">javax.ws</a>.rs-api/2.1</code> dependency provides JAX-RS 2.1
Final API.</p><h3 id="JAX-RS-CXF3.1.x">CXF 3.1.x</h3><p>The
cxf-rt-frontend-jaxrs dependency is required:</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;"> <dependency>
+<pre class="brush: java; gutter: false; theme: Default"> <dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-frontend-jaxrs</artifactId>
<version>3.1.12</version>
</dependency>
</pre>
</div></div><p>This will in turn pull other <a shape="rect"
href="http://cxf.apache.org/project-status.html";>CXF modules</a> such
<code>cxf-core</code> and <code>cxf-rt-transports-http</code>, check <a
shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/3.1.x-fixes/rt/frontend/jaxrs/pom.xml";
rel="nofollow">the pom</a> for more
information.</p><p><code>javax.ws.rs/javax.ws.rs-api/2.0</code> dependency
provides JAX-RS 2.0 Final
API.</p><pre>javax.annotation/javax.annotation-api/1.2 dependency is needed if
custom JAX-RS 2.0 filters or interceptors use a javax.annotation.Priority
annotation.</pre><p>Existing JAX-RS 1.1 applications can run in CXF 3.1.x and
CXF 3.0.x.</p><h2 id="JAX-RS-CXFJAX-RSbundle">CXF JAX-RS bundle</h2><p>Note CXF
JAX-RS bundle has been removed in CXF 3.0.0. Prefer depending on the JAX-RS
frontend directly. In CXF 3.0.0 a complete CXF all-inclusive <a shape="rect"
class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/osgi/bund
le/all/pom.xml">bundle</a> can still be used if really needed.</p><p>Only in
CXF 2.7.x or earlier:<br clear="none"> A standalone <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/branches/2.7.x-fixes/osgi/bundle/all/pom.xml";>JAX-RS
bundle</a> is available which may be of interest to users doing the JAX-RS
work only.</p><p>Please note that this bundle has a transitive Maven dependency
on the Jetty server modules. If you are using Maven and working with other
servlet containers such as Tomcat then please add the following
exclusion:</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;"> <dependency>
+<pre class="brush: java; gutter: false; theme: Default"> <dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-bundle-jaxrs</artifactId>
<version>${cxf.version}</version>
@@ -234,7 +234,7 @@ public void upload(@Multipart InputStrea
</dependency>
</pre>
</div></div><h1 id="JAX-RS-WhatisNew">What is New</h1><ul><li>Complete support
for JAX-RS 2.1, please see <a shape="rect" href="jax-rs-basics.html">JAX-RS
Basics</a> for more information</li><li><a shape="rect"
href="jax-rs-nio.html">JAX-RS NIO</a> extension based on the early JAX-RS 2.1
API prototype.</li><li><a shape="rect" href="jax-rs-rxjava.html">JAX-RS
RxJava</a> Observable support: as a standard JAX-RS 2.1 RxInvoker client
provider and returning it asynchronously from the resource methods (CXF
extension) </li><li><a shape="rect"
href="jax-rs-project-reactor-support.html">JAX-RS Project Reactor</a> Support
also based on the JAX-RS 2.1 RxInvoker paradigm</li><li>Complete support for
JAX-RS 2.0, please see <a shape="rect" href="jax-rs-basics.html">JAX-RS
Basics</a> for more information</li><li>Bean Validation 1.1 Support, please see
<a shape="rect"
href="http://cxf.apache.org/docs/validationfeature.html";>http://cxf.apache.org/docs/validationfeature.html</a>
for more informa
tion</li><li><a shape="rect"
href="http://cxf.apache.org/docs/swagger2feature.html";>Swagger Feature</a> for
generating <a shape="rect" class="external-link"
href="http://swagger.io/specification/"; rel="nofollow">Swagger API</a>
documentation from JAX-RS endpoints</li></ul><h1
id="JAX-RS-GettingStartedwithJAX-RS">Getting Started with JAX-RS</h1><h2
id="JAX-RS-UnderstandingtheBasics">Understanding the Basics</h2><p>You are
encouraged to read JAX-RS 2.1 <a shape="rect" class="external-link"
href="http://jcp.org/en/jsr/detail?id=370"; rel="nofollow">JSR-370</a>
specification to find out the information not covered by this documentation.
The specification enhances JAX-RS 2.0 by introducing a support for Reactive
Client API extensions, Server Sent Events (client and server), returning
CompletableFuture from the resource methods and the sub-resource classes (as
opposed to instances) from the sub-resource locators.</p><p>You are also
encouraged to read JAX-RS 2.0 <a shape="rect" class="exter
nal-link" href="http://jcp.org/en/jsr/detail?id=339";
rel="nofollow">JSR-339</a> specification to find out the information not
covered by this documentation. The specification introduces many terms such as
root resources, resource methods, sub-resources and sub-resource locators,
message body readers and writers. JAX-RS 2.0 additionally introduces filters,
interceptors, new client API, features, new exception classes, server-side
support for asynchronous invocations.</p><p>Please see the <a shape="rect"
href="jax-rs-basics.html">JAX-RS Basics</a> page for more information.</p><h2
id="JAX-RS-SupportforDataBindings">Support for Data Bindings</h2><p>JAX-RS
MessageBodyReader and MessageBodyWriter can be used to create data bindings for
reading and writing data in a number of different formats. Compliant JAX-RS
implementations are expected to support JAXB-annotated beans, JAXP Source
objects, InputStreams, etc.</p><p>In addition, CXF JAX-RS lets users reuse
existing CXF DataBindings for w
orking with JAXB, XBeans, Aegis and SDO.</p><p>Please see the <a shape="rect"
href="jax-rs-data-bindings.html">JAX-RS Data Bindings</a> page for more
information.</p><h2 id="JAX-RS-HowRequestURIisMatched">How Request URI is
Matched</h2><p>Lets assume you have a web application called 'rest' (example, a
'rest.war' archive). CXFServlet's url-pattern is "/test/*". Finally,
jaxrs:server's address is "/bar".</p><p>Requests like /rest/test/bar or
/rest/test/bar/baz will be delivered to one of the resource classes in a given
jaxrs:server endpoint. For the former request to be handled, a resource class
with @Path("/") should be available, in the latter case - at least @Path("/")
or a more specific @Path("/baz").</p><p>The same requirement can be expressed
by having a CXFServlet with "/*" and jaxrs:server with "/test/bar".</p><p>When
both CXFServlet and jaxrs:server use "/" then it's a root resource class which
should provide a @Path with at least "/test/bar" for the above requests to be
mat
ched.</p><p>Generally, it can be a good idea to specify the URI segments which
are more likely to change now and then with CXFServlets or jaxrs:server.</p><h2
id="JAX-RS-ClientAPI">Client API</h2><p>CXF 3.0.0 implements JAX-RS 2.0 Client
API.</p><p>CXF 2.7.x or earlier provides a comprehensive support for developing
RESTful clients by supporting 3 flavors of the client API: proxy-based,
HTTP-centric and XML-centric. CXF-specific client API is supported alongside
new JAX-RS 2.0 Client API in CXF 3.0.0.</p><p>Please see the <a shape="rect"
href="jax-rs-client-api.html">JAX-RS Client API</a> page for more
information.</p><h2 id="JAX-RS-BeanValidation">Bean Validation</h2><p>Bean
Validation 1.1 is supported since CXF 3.0.0-milestone1. Please see the <a
shape="rect"
href="http://cxf.apache.org/docs/validationfeature.html";>http://cxf.apache.org/docs/validationfeature.html</a>
for more information.</p><h2
id="JAX-RS-Filters,InterceptorsandInvokers">Filters, Interceptors and
Invokers</h2><p
>It is possible to intercept and modify the inbound and outbound calls with
>the help of CXF JAX-RS filters and/or CXF interceptors. Additionally, custom
>invokers offer an option to intercept a call immediately before a service
>bean is invoked.</p><p>Please see the <a shape="rect"
>href="jax-rs-filters.html">JAX-RS Filters</a> page for more
>information.</p><p>Please see the <a shape="rect"
>href="jax-rs-basics.html">JAX-RS Basics</a> page for more information about
>new JAX-RS 2.0 filters and interceptors available in CXF 2.7.x and
>3.0.0.</p><h2 id="JAX-RS-ServicelistingsandWADLsupport">Service listings and
>WADL support</h2><p><strong>New</strong>: Swagger feature has been
>introduced.</p><p>CXF JAX-RS supports <a shape="rect" class="external-link"
>href="http://www.w3.org/Submission/wadl"; rel="nofollow">WADL</a>. CXF JAX-RS
>service endpoints can be listed in the service listings page and users can
>check the WADL documents.</p><p>Please see the <a shape="rect"
>href="jaxrs-services-descrip
tion.html">JAXRS Services Description</a> page for more information.</p><h2
id="JAX-RS-ConfiguringJAX-RSservices">Configuring JAX-RS services</h2><p>JAX-RS
services can be configured programmatically, using Blueprint, Spring or
CXFNonSpringJAXRSServlet.</p><p>Please see the <a shape="rect"
href="jaxrs-services-configuration.html">JAXRS Services Configuration</a> page
for more information.</p><h2 id="JAX-RS-Testing">Testing</h2><p>JAX-RS services
can be easily tested using the embedded Jetty or CXF Local Transport.<br
clear="none"> Please see the <a shape="rect"
href="https://cwiki.apache.org/confluence/display/CXF20DOC/JAXRS+Testing";>JAXRS
Testing</a> page for more information.</p><h2
id="JAX-RS-Debugging">Debugging</h2><p>One may want to use a browser to test
how a given HTTP resource reacts to different HTTP Accept or Accept-Language
header values and request methods. For example, if a resource class supports a
"/resource" URI then one can test the resource class using one of the
following queries :</p><p><code>> GET /resource.xml</code> <br
clear="none"> <code>> GET /resource.en</code></p><p>The runtime will replace
'.xml' or '.en' with an appropriate header value. For it to know the type or
language value associated with a given URI suffix, some configuration needs to
be done. Here's an example of how it can be done with Spring:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> <jaxrs:server id="customerService" address="/">
+<pre class="brush: java; gutter: false; theme: Default"> <jaxrs:server
id="customerService" address="/">
<jaxrs:serviceBeans>
<bean class="org.apache.cxf.jaxrs.systests.CustomerService" />
</jaxrs:serviceBeans>
@@ -248,7 +248,7 @@ public void upload(@Multipart InputStrea
</jaxrs:server>
</pre>
</div></div><p>CXF also supports a _type query as an alternative to appending
extensions like '.xml' to request URIs:</p><p>{{ > GET
/resource?_type=xml}}</p><p>Overriding a request method is also
easy:</p><p><code>> GET /resource?_method=POST</code></p><p>Alternatively,
one can specify an HTTP header X-HTTP-Method-Override:</p><p><code>> POST
/books</code> <br clear="none"> <code>> X-HTTP-Method-Override :
PATCH</code></p><p>For example, at the moment the http-centric client API does
not support arbitrary HTTP verbs except for those supported <br clear="none">
by Java HTTPUrlConnection. When needed, X-HTTP-Method-Override can be set to
overcome this limitation.</p><p>Finally, a "_ctype" query allows for overriding
Content-Type.</p><p>Please see the <a shape="rect"
href="debugging-and-logging.html">Debugging and Logging</a> page for more
information on how to debug and log service calls in CXF.</p><h2
id="JAX-RS-Logging">Logging</h2><p>Many of the existing CXF features c
an be applied either to <code>jaxrs:server</code> or
<code>jaxrs:client</code>. For example, to enable logging of requests and
responses, simply do:</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;"><beans xmlns:cxf="http://cxf.apache.org/core";
+<pre class="brush: java; gutter: false; theme: Default"><beans
xmlns:cxf="http://cxf.apache.org/core";
xsi:schemaLocation="http://cxf.apache.org/core
http://cxf.apache.org/schemas/core.xsd">
<jaxrs:server>
@@ -258,7 +258,7 @@ public void upload(@Multipart InputStrea
<jaxrs:server>
</beans>
</pre>
-</div></div><p>Please make sure the <code> <a shape="rect"
href="http://cxf.apache.org/core";>http://cxf.apache.org/core</a> </code>
namespace is in scope.</p><p>Starting from CXF 2.3.0 it is also possible to
convert log events into Atom entries and either push them to receivers or make
them available for polling.</p><p>Please see the <a shape="rect"
href="debugging-and-logging.html">Debugging and Logging</a> page for more
information.</p><h1 id="JAX-RS-AdvancedFeatures">Advanced Features</h1><h2
id="JAX-RS-Multiparts">Multiparts</h2><p>Multiparts can be handled in a number
of ways. The CXF core runtime provides advanced support for handling
attachments which CXF JAX-RS builds upon.</p><p>Please see the <a shape="rect"
href="jax-rs-multiparts.html">JAX-RS Multiparts</a> page for more
information.</p><h2 id="JAX-RS-SecureJAX-RSservices">Secure JAX-RS
services</h2><p>Transport level HTTPS security can be used to protect messages
exchanged between CXF JAX-RS endpoints and providers.</p>
<p>Authentication and authorization can be enforced in a number of
ways.</p><p>Please see the <a shape="rect"
href="secure-jax-rs-services.html">Secure JAX-RS Services</a> page for more
information.</p><p>Please also check <a shape="rect"
href="http://cxf.apache.org/docs/jax-rs-xml-security.html";>JAX-RS XML
Security</a>, <a shape="rect" href="jax-rs-saml.html">JAX-RS SAML</a> and <a
shape="rect" href="jax-rs-oauth2.html">JAX-RS OAuth2</a> pages for more
information about the advanced security topics.</p><h2
id="JAX-RS-FailoverandLoadDistributionFeatures">Failover and Load Distribution
Features</h2><p>Starting from CXF 2.4.1, CXF JAX-RS proxy and WebClient
consumers can be backed up by failover and load distribution features.<br
clear="none"> Please see the <a shape="rect" href="jax-rs-failover.html">JAX-RS
Failover</a> page for more information.</p><h2
id="JAX-RS-Redirection">Redirection</h2><p>Starting from CXF 2.2.5 it is
possible to redirect the request or response call to other
servlet resources by configuring CXFServlet or using CXF JAX-RS
RequestDispatcherProvider.</p><p>Please see the <a shape="rect"
href="jax-rs-redirection.html">JAX-RS Redirection</a> page for more
information.</p><h2 id="JAX-RS-XSLTandXPath">XSLT and XPath</h2><p>XSLT and
XPath are promoted and treated as first-class citizens in CXF JAX-RS. These
technologies can be very powerful when generating complex data or retrieving
data of interest out of complex XML fragments.</p><p>Please see the <a
shape="rect" href="jax-rs-advanced-xml.html">JAX-RS Advanced XML</a> page for
more information.</p><h2 id="JAX-RS-ComplexSearchQueries">Complex Search
Queries</h2><p>Using <a shape="rect"
href="http://cxf.apache.org/docs/jax-rs.html#JAX-RS-Parameterbeans";>query
parameter beans</a> provides a way to capture search requirements that can be
expressed by enumerating name/value pairs, for example, a query such as
'?name=CXF&version=2.3' can be captured by a bean containing setName and
setVersion m
ethods. This 'template' bean can be used in the code to compare it against all
available local data.</p><p>Versions 2.3 and later of CXF JAXRS support another
option for doing advanced search queries using the <a shape="rect"
class="external-link"
href="http://tools.ietf.org/html/draft-nottingham-atompub-fiql-00";
rel="nofollow">Feed Item Query Language</a>(FIQL).</p><p>Please see the <a
shape="rect" href="jax-rs-search.html">JAX-RS Search</a> page for more
information.</p><h2
id="JAX-RS-Model-View-Controllersupport">Model-View-Controller
support</h2><p><strong>XSLT</strong> <br clear="none"> Please see the <a
shape="rect" href="jax-rs-advanced-xml.html">JAX-RS Advanced XML</a> page for
more information. on how <code>XSLTJaxbProvider</code> can be used to generate
complex (X)HTML views.</p><p><strong>JSP</strong></p><p>With the introduction
of <code>RequestDispatcherProvider</code> it is now possible for JAXRS service
responses be redirected to JSP pages for further processing. Pleas
e see the <a shape="rect" href="jax-rs-redirection.html">JAX-RS
Redirection</a> page for more information.</p><h2
id="JAX-RS-CombiningJAX-WSandJAX-RS">Combining JAX-WS and JAX-RS</h2><p>CXF
JAX-RS tries to make it easy for SOAP developers to experiment with JAX-RS and
combine both JAX-WS and JAX-RS in the same service bean when
needed.</p><p>Please see the <a shape="rect"
href="jax-rs-and-jax-ws.html">JAX-RS and JAX-WS</a> page for more
information.</p><h2 id="JAX-RS-IntegrationwithDistributedOSGi">Integration with
Distributed OSGi</h2><p>Distributed OSGi RI is a CXF <a shape="rect"
href="http://cxf.apache.org/distributed-osgi.html";>subproject</a>. DOSGi
mandates how registered Java interfaces can be exposed<br clear="none"> and
consumed as remote services. DOSGi single and multi bundle distributions
contain all the OSGI bundles required for a CXF endpoint be successfully
published.</p><p>CXF JAX-RS implementations has been integrated with DOSGi RI
1.1-SNAPSHOT which makes it possib
le to expose Java interfaces as RESTful services and consume such services
using a proxy-based client API.</p><p>Please see the <a shape="rect"
href="http://cxf.apache.org/distributed-osgi-reference.html#DistributedOSGiReference-ServiceProviderproperties";>DOSGI
Reference page</a> ('org.apache.cxf.rs' properties) and a <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/dosgi/trunk/samples/greeter_rest/";>greeter_rest</a>
sample for more information. Note that this demo can be run exactly as a
SOAP-based <a shape="rect"
href="http://cxf.apache.org/distributed-osgi-greeter-demo-walkthrough.html";>greeter</a>
demo as it registers and consumes a similar (but) JAX-RS annotated <a
shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/dosgi/trunk/samples/greeter_rest/interface/src/main/java/org/apache/cxf/dosgi/samples/greeter/rest/GreeterService.java";>GreeterService</a>.
In addition, this demo shows how one can register and consume a given
interface (<a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/dosgi/trunk/samples/greeter_rest/interface/src/main/java/org/apache/cxf/dosgi/samples/greeter/rest/GreeterService2.java";>GreeterService2</a>)
without using explicit JAX-RS annotations but providing an out-of-band <a
shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/dosgi/trunk/samples/greeter_rest/interface/src/main/resources/OSGI-INF/cxf/jaxrs/GreeterService2-model.xml";>user
model description</a>.</p><h2 id="JAX-RS-ODataSupport">OData
Support</h2><p>CXF JAX-RS endpoints can support <a shape="rect"
class="external-link" href="http://www.odata.org/"; rel="nofollow">OData</a> in
two ways by relying on <a shape="rect" class="external-link"
href="https://olingo.apache.org/";>Apache Olingo</a>.</p><p>First, the OData
"$filter" query is supported by the <a shape="rect"
href="http://cxf.apache.org/docs/jax-rs-search.html#JAX-RSSearch-OpenDataProtocol";>Search
extension</a> whe
re an endpoint with the application specific API can respond to the filter
queries, for example, return a collection of books matching the fillter search
criteria.</p><p>Second, CXF JAX-RS can be used to interpose over the Olingo, as
is <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/odata";
rel="nofollow">demoed here</a>. Effectively such a CXF endpoint becomes an
OData server: all it does <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/odata/src/main/java/odata/server/JaxrsODataService.java";
rel="nofollow">it delegates to Olingo</a>. The idea is to be able to add CXF
specific features and interceptors in front of Olingo.</p><h2
id="JAX-RS-OtherAdvancedFeatures">Other Advanced Features</h2><p>CXF JAX-RS
provides a number of advanced extensions such as the support for the JMS
transport, one-way invocations (HTTP and JMS)
, suspended invocations (HTTP and JMS), making existing code REST-aware by
applying external user models, etc.</p><p>Please see the <a shape="rect"
href="jax-rs-advanced-features.html">JAX-RS Advanced Features</a> page for more
information.</p><h1 id="JAX-RS-MavenPlugins">Maven Plugins</h1><p>Please see
the <a shape="rect" href="jax-rs-maven-plugins.html">JAX-RS Maven Plugins</a>
page for more information about the Maven plugins and archetypes which can help
with creating CXF JAX-RS applications.</p><h1
id="JAX-RS-Deployment">Deployment</h1><p>CXF JAX-RS applications packaged as
WAR archives can be deployed into standalone Servlet containers such as Tomcat
or Jetty.<br clear="none"> Please see the <a shape="rect"
href="https://cwiki.apache.org/confluence/display/CXF20DOC/JAX-RS+Deployment";>JAX-RS
Deployment</a> page for the tips on how to deploy the CXF JAX-RS applications
into various Java EE and OSGI application servers successfully.</p><h1
id="JAX-RS-Third-partyprojects">Third-pa
rty projects</h1><ul><li>REST Utilities: <a shape="rect" class="external-link"
href="https://github.com/taimos/RESTUtils";
rel="nofollow">RESTUtils</a></li></ul><h1
id="JAX-RS-References">References</h1><ul><li><a shape="rect"
class="external-link"
href="http://jcp.org/aboutJava/communityprocess/final/jsr311/index.html";
rel="nofollow">JSR-000311 JAX-RS: The JavaTM API for RESTful Web
Services</a></li><li><a shape="rect" class="external-link"
href="http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm";
rel="nofollow">Architectural Styles and the Design of Network-based Software
Architectures</a></li><li><a shape="rect" class="external-link"
href="http://en.wikipedia.org/wiki/Representational_State_Transfer";
rel="nofollow">Representational State Transfer - Wikipedia </a></li><li><a
shape="rect" class="external-link"
href="http://oreilly.com/catalog/9780596801694/"; rel="nofollow">RESTful Web
Services Cookbook - Solutions for Improving Scalability and Simplicity</a>
<em>by Subbu All
amarajuy</em> (O'Reilly Media, February 2010)</li><li><a shape="rect"
class="external-link" href="http://oreilly.com/catalog/9780596158057/";
rel="nofollow">RESTful Java with JAX-RS</a> <em>by Bill Burke</em> (O'Reilly
Media, November 2009)</li><li><a shape="rect" class="external-link"
href="http://oreilly.com/catalog/9780596521134/"; rel="nofollow">Java Web
Services: Up and Running </a> <em>by Martin Kalin</em> (O'Reilly Media,
February 2009)</li><li><a shape="rect" class="external-link"
href="http://oreilly.com/catalog/9780596529260/"; rel="nofollow">RESTful Web
Services - Web services for the real world</a> <em>by Leonard Richardson, Sam
Ruby</em> (O'Reilly Media, May 2007)</li><li><a shape="rect"
class="external-link"
href="http://www.oracle.com/technetwork/articles/javase/index-137171.html";
rel="nofollow">RESTful Web Services</a> <em>by Sameer Tyagi</em> (Oracle ,
August 2006)</li><li><a shape="rect" class="external-link"
href="http://www.crummy.com/writing/RESTful-Web-Services/";
rel="nofollow">RESTful Web Services - "Unofficial homepage for a book about
simple web services."</a> <em>Unknown</em></li><li><a shape="rect"
class="external-link" href="http://tomayko.com/writings/rest-to-my-wife";
rel="nofollow">How I Explained REST to My Wife</a> <em>by Ryan Tomayko</em> (<a
shape="rect" class="external-link" href="http://tomayko.com";
rel="nofollow">http://tomayko.com</a>, December 2004)</li></ul><h1
id="JAX-RS-Howtocontribute">How to contribute</h1><p>CXF JAX-RS implementation
sits on top of the core CXF runtime and is quite self-contained and isolated
from other CXF modules such as jaxws and simple frontends.</p><p>Please check
the <a shape="rect" class="external-link"
href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?reset=true&mode=hide&pid=12310511&sorter/order=DESC&sorter/field=priority&resolution=-1&component=12311911";>issue
list</a> and see if you are interested in fixing one of the issues.</p><p>If
you decide to go ah
ead then the fastest way to start is to</p><ul><li>do the fast trunk build
using '<code>mvn install -Pfastinstall</code>'</li><li>setup the workspace 'mvn
-Psetup.eclipse' which will create a workspace in a 'workspace' folder, next to
'trunk'</li><li>import cxf modules from the trunk into the workspace and start
working with the cxf-frontend-jaxrs module</li></ul><p>If you are about to
submit a patch after building a trunk/rt/frontend/jaxrs, then please also run
JAX-RS system tests in trunk/systests/jaxrs :<br clear="none"> <code>> mvn
install</code></p><p>You can also check out the general <a shape="rect"
href="http://cxf.apache.org/getting-involved.html";>Getting Involved</a> web
page for more information on contributing.</p></div>
+</div></div><p>Please make sure the <code> <a shape="rect"
href="http://cxf.apache.org/core";>http://cxf.apache.org/core</a> </code>
namespace is in scope.</p><p>Starting from CXF 2.3.0 it is also possible to
convert log events into Atom entries and either push them to receivers or make
them available for polling.</p><p>Please see the <a shape="rect"
href="debugging-and-logging.html">Debugging and Logging</a> page for more
information.</p><h1 id="JAX-RS-AdvancedFeatures">Advanced Features</h1><h2
id="JAX-RS-Multiparts">Multiparts</h2><p>Multiparts can be handled in a number
of ways. The CXF core runtime provides advanced support for handling
attachments which CXF JAX-RS builds upon.</p><p>Please see the <a shape="rect"
href="jax-rs-multiparts.html">JAX-RS Multiparts</a> page for more
information.</p><h2 id="JAX-RS-SecureJAX-RSservices">Secure JAX-RS
services</h2><p>Transport level HTTPS security can be used to protect messages
exchanged between CXF JAX-RS endpoints and providers.</p>
<p>Authentication and authorization can be enforced in a number of
ways.</p><p>Please see the <a shape="rect"
href="secure-jax-rs-services.html">Secure JAX-RS Services</a> page for more
information.</p><p>Please also check <a shape="rect"
href="http://cxf.apache.org/docs/jax-rs-xml-security.html";>JAX-RS XML
Security</a>, <a shape="rect" href="jax-rs-saml.html">JAX-RS SAML,</a> <a
shape="rect" href="jax-rs-claims.html">JAX-RS Claims</a> and <a shape="rect"
href="jax-rs-oauth2.html">JAX-RS OAuth2</a> pages for more information about
the advanced security topics.</p><h2
id="JAX-RS-FailoverandLoadDistributionFeatures">Failover and Load Distribution
Features</h2><p>Starting from CXF 2.4.1, CXF JAX-RS proxy and WebClient
consumers can be backed up by failover and load distribution features.<br
clear="none"> Please see the <a shape="rect" href="jax-rs-failover.html">JAX-RS
Failover</a> page for more information.</p><h2
id="JAX-RS-Redirection">Redirection</h2><p>Starting from CXF 2.2.5 it i
s possible to redirect the request or response call to other servlet resources
by configuring CXFServlet or using CXF JAX-RS
RequestDispatcherProvider.</p><p>Please see the <a shape="rect"
href="jax-rs-redirection.html">JAX-RS Redirection</a> page for more
information.</p><h2 id="JAX-RS-XSLTandXPath">XSLT and XPath</h2><p>XSLT and
XPath are promoted and treated as first-class citizens in CXF JAX-RS. These
technologies can be very powerful when generating complex data or retrieving
data of interest out of complex XML fragments.</p><p>Please see the <a
shape="rect" href="jax-rs-advanced-xml.html">JAX-RS Advanced XML</a> page for
more information.</p><h2 id="JAX-RS-ComplexSearchQueries">Complex Search
Queries</h2><p>Using <a shape="rect"
href="http://cxf.apache.org/docs/jax-rs.html#JAX-RS-Parameterbeans";>query
parameter beans</a> provides a way to capture search requirements that can be
expressed by enumerating name/value pairs, for example, a query such as
'?name=CXF&version=2.3'
can be captured by a bean containing setName and setVersion methods. This
'template' bean can be used in the code to compare it against all available
local data.</p><p>Versions 2.3 and later of CXF JAXRS support another option
for doing advanced search queries using the <a shape="rect"
class="external-link"
href="http://tools.ietf.org/html/draft-nottingham-atompub-fiql-00";
rel="nofollow">Feed Item Query Language</a>(FIQL).</p><p>Please see the <a
shape="rect" href="jax-rs-search.html">JAX-RS Search</a> page for more
information.</p><h2
id="JAX-RS-Model-View-Controllersupport">Model-View-Controller
support</h2><p><strong>XSLT</strong> <br clear="none"> Please see the <a
shape="rect" href="jax-rs-advanced-xml.html">JAX-RS Advanced XML</a> page for
more information. on how <code>XSLTJaxbProvider</code> can be used to generate
complex (X)HTML views.</p><p><strong>JSP</strong></p><p>With the introduction
of <code>RequestDispatcherProvider</code> it is now possible for JAXRS service
respo
nses be redirected to JSP pages for further processing. Please see the <a
shape="rect" href="jax-rs-redirection.html">JAX-RS Redirection</a> page for
more information.</p><h2 id="JAX-RS-CombiningJAX-WSandJAX-RS">Combining JAX-WS
and JAX-RS</h2><p>CXF JAX-RS tries to make it easy for SOAP developers to
experiment with JAX-RS and combine both JAX-WS and JAX-RS in the same service
bean when needed.</p><p>Please see the <a shape="rect"
href="jax-rs-and-jax-ws.html">JAX-RS and JAX-WS</a> page for more
information.</p><h2 id="JAX-RS-IntegrationwithDistributedOSGi">Integration with
Distributed OSGi</h2><p>Distributed OSGi RI is a CXF <a shape="rect"
href="http://cxf.apache.org/distributed-osgi.html";>subproject</a>. DOSGi
mandates how registered Java interfaces can be exposed<br clear="none"> and
consumed as remote services. DOSGi single and multi bundle distributions
contain all the OSGI bundles required for a CXF endpoint be successfully
published.</p><p>CXF JAX-RS implementations has bee
n integrated with DOSGi RI 1.1-SNAPSHOT which makes it possible to expose Java
interfaces as RESTful services and consume such services using a proxy-based
client API.</p><p>Please see the <a shape="rect"
href="http://cxf.apache.org/distributed-osgi-reference.html#DistributedOSGiReference-ServiceProviderproperties";>DOSGI
Reference page</a> ('org.apache.cxf.rs' properties) and a <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/dosgi/trunk/samples/greeter_rest/";>greeter_rest</a>
sample for more information. Note that this demo can be run exactly as a
SOAP-based <a shape="rect"
href="http://cxf.apache.org/distributed-osgi-greeter-demo-walkthrough.html";>greeter</a>
demo as it registers and consumes a similar (but) JAX-RS annotated <a
shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/dosgi/trunk/samples/greeter_rest/interface/src/main/java/org/apache/cxf/dosgi/samples/greeter/rest/GreeterService.java";>GreeterService</a>.
In additi
on, this demo shows how one can register and consume a given interface (<a
shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/dosgi/trunk/samples/greeter_rest/interface/src/main/java/org/apache/cxf/dosgi/samples/greeter/rest/GreeterService2.java";>GreeterService2</a>)
without using explicit JAX-RS annotations but providing an out-of-band <a
shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/dosgi/trunk/samples/greeter_rest/interface/src/main/resources/OSGI-INF/cxf/jaxrs/GreeterService2-model.xml";>user
model description</a>.</p><h2 id="JAX-RS-ODataSupport">OData
Support</h2><p>CXF JAX-RS endpoints can support <a shape="rect"
class="external-link" href="http://www.odata.org/"; rel="nofollow">OData</a> in
two ways by relying on <a shape="rect" class="external-link"
href="https://olingo.apache.org/";>Apache Olingo</a>.</p><p>First, the OData
"$filter" query is supported by the <a shape="rect"
href="http://cxf.apache.org/docs/jax-rs-search
.html#JAX-RSSearch-OpenDataProtocol">Search extension</a> where an endpoint
with the application specific API can respond to the filter queries, for
example, return a collection of books matching the fillter search
criteria.</p><p>Second, CXF JAX-RS can be used to interpose over the Olingo, as
is <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/odata";
rel="nofollow">demoed here</a>. Effectively such a CXF endpoint becomes an
OData server: all it does <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/odata/src/main/java/odata/server/JaxrsODataService.java";
rel="nofollow">it delegates to Olingo</a>. The idea is to be able to add CXF
specific features and interceptors in front of Olingo.</p><h2
id="JAX-RS-OtherAdvancedFeatures">Other Advanced Features</h2><p>CXF JAX-RS
provides a number of advanced extensions such as the supp
ort for the JMS transport, one-way invocations (HTTP and JMS), suspended
invocations (HTTP and JMS), making existing code REST-aware by applying
external user models, etc.</p><p>Please see the <a shape="rect"
href="jax-rs-advanced-features.html">JAX-RS Advanced Features</a> page for more
information.</p><h1 id="JAX-RS-MavenPlugins">Maven Plugins</h1><p>Please see
the <a shape="rect" href="jax-rs-maven-plugins.html">JAX-RS Maven Plugins</a>
page for more information about the Maven plugins and archetypes which can help
with creating CXF JAX-RS applications.</p><h1
id="JAX-RS-Deployment">Deployment</h1><p>CXF JAX-RS applications packaged as
WAR archives can be deployed into standalone Servlet containers such as Tomcat
or Jetty.<br clear="none"> Please see the <a shape="rect"
href="https://cwiki.apache.org/confluence/display/CXF20DOC/JAX-RS+Deployment";>JAX-RS
Deployment</a> page for the tips on how to deploy the CXF JAX-RS applications
into various Java EE and OSGI application servers
successfully.</p><h1 id="JAX-RS-Third-partyprojects">Third-party
projects</h1><ul><li>REST Utilities: <a shape="rect" class="external-link"
href="https://github.com/taimos/RESTUtils";
rel="nofollow">RESTUtils</a></li></ul><h1
id="JAX-RS-References">References</h1><ul><li><a shape="rect"
class="external-link"
href="http://jcp.org/aboutJava/communityprocess/final/jsr311/index.html";
rel="nofollow">JSR-000311 JAX-RS: The JavaTM API for RESTful Web
Services</a></li><li><a shape="rect" class="external-link"
href="http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm";
rel="nofollow">Architectural Styles and the Design of Network-based Software
Architectures</a></li><li><a shape="rect" class="external-link"
href="http://en.wikipedia.org/wiki/Representational_State_Transfer";
rel="nofollow">Representational State Transfer - Wikipedia </a></li><li><a
shape="rect" class="external-link"
href="http://oreilly.com/catalog/9780596801694/"; rel="nofollow">RESTful Web
Services Cookbook - Solutions
for Improving Scalability and Simplicity</a> <em>by Subbu Allamarajuy</em>
(O'Reilly Media, February 2010)</li><li><a shape="rect" class="external-link"
href="http://oreilly.com/catalog/9780596158057/"; rel="nofollow">RESTful Java
with JAX-RS</a> <em>by Bill Burke</em> (O'Reilly Media, November
2009)</li><li><a shape="rect" class="external-link"
href="http://oreilly.com/catalog/9780596521134/"; rel="nofollow">Java Web
Services: Up and Running </a> <em>by Martin Kalin</em> (O'Reilly Media,
February 2009)</li><li><a shape="rect" class="external-link"
href="http://oreilly.com/catalog/9780596529260/"; rel="nofollow">RESTful Web
Services - Web services for the real world</a> <em>by Leonard Richardson, Sam
Ruby</em> (O'Reilly Media, May 2007)</li><li><a shape="rect"
class="external-link"
href="http://www.oracle.com/technetwork/articles/javase/index-137171.html";
rel="nofollow">RESTful Web Services</a> <em>by Sameer Tyagi</em> (Oracle ,
August 2006)</li><li><a shape="rect" class="external-link
" href="http://www.crummy.com/writing/RESTful-Web-Services/";
rel="nofollow">RESTful Web Services - "Unofficial homepage for a book about
simple web services."</a> <em>Unknown</em></li><li><a shape="rect"
class="external-link" href="http://tomayko.com/writings/rest-to-my-wife";
rel="nofollow">How I Explained REST to My Wife</a> <em>by Ryan Tomayko</em> (<a
shape="rect" class="external-link" href="http://tomayko.com";
rel="nofollow">http://tomayko.com</a>, December 2004)</li></ul><h1
id="JAX-RS-Howtocontribute">How to contribute</h1><p>CXF JAX-RS implementation
sits on top of the core CXF runtime and is quite self-contained and isolated
from other CXF modules such as jaxws and simple frontends.</p><p>Please check
the <a shape="rect" class="external-link"
href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?reset=true&mode=hide&pid=12310511&sorter/order=DESC&sorter/field=priority&resolution=-1&component=12311911";>issue
list</a> and see if you are interes
ted in fixing one of the issues.</p><p>If you decide to go ahead then the
fastest way to start is to</p><ul><li>do the fast trunk build using '<code>mvn
install -Pfastinstall</code>'</li><li>setup the workspace 'mvn -Psetup.eclipse'
which will create a workspace in a 'workspace' folder, next to
'trunk'</li><li>import cxf modules from the trunk into the workspace and start
working with the cxf-frontend-jaxrs module</li></ul><p>If you are about to
submit a patch after building a trunk/rt/frontend/jaxrs, then please also run
JAX-RS system tests in trunk/systests/jaxrs :<br clear="none"> <code>> mvn
install</code></p><p>You can also check out the general <a shape="rect"
href="http://cxf.apache.org/getting-involved.html";>Getting Involved</a> web
page for more information on contributing.</p></div>
</div>
<!-- Content -->
</td>
![http://cxf.apache.org/images/asf-logo.png"](http://cxf.apache.org/images/asf-logo.png"){kind=link}
![http://www.apache.org/events/current-event-125x125.png"](http://www.apache.org/events/current-event-125x125.png"){kind=link}