cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [CONF] Apache CXF Documentation > JAX-RS
Date Wed, 03 Oct 2012 13:02:00 GMT
    <base href="">
            <link rel="stylesheet" href="/confluence/s/2042/9/1/_/styles/combined.css?spaceKey=CXF20DOC&amp;forWysiwyg=true"
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="">JAX-RS</a></h2>
    <h4>Page <b>edited</b> by             <a href="">Sergey
                         <h4>Changes (3)</h4>
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >JAX-RS 2.0 is backward compatible
with JAX-RS 1.1. Please see [JAX-RS Basics] for more information. <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h4.
from CXF 2.6.x to CXF 2.7.0  <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">Please
also check the [CXF 2.7 Migration Guide|]
for the information about all the changes affecting the JAX-RS users <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The
following CXF specific classes are not available in CXF 2.7.0: org.apache.cxf.jaxrs.client.ResponseReader,
org.apache.cxf.jaxrs.client.ServerWebApplicationException, org.apache.cxf.jaxrs.client.ClientWebApplicationException.
<br> <br>The following CXF specific extensions have been deprecated and will be
eventually removed: <br> <br>org.apache.cxf.jaxrs.ext.ParamHandler - please use and instead. <br>org.apache.cxf.jaxrs.ext.RequestHandler
and org.apache.cxf.jaxrs.ext.ResponseHandler - please use
and  and instead. <br> <br>Note
that no @Deprecated annotation has been attached to the deprecated classes in order to minimize
the &#39;noise&#39; in the runtime code while these classes are still maintained.
<br> <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h3. Migrating from JAX-RS 1.0 to 1.1
<br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <p><span style="font-size:2em;font-weight:bold"> JAX-RS (JSR-311) </span></p>

    <li><a href='#JAX-RS-Introduction'>Introduction</a></li>
    <li><a href='#JAX-RS-Projectsetupandconfiguration'>Project setup and configuration</a></li>
    <li><a href='#JAX-RS-Migration'>Migration</a></li>
    <li><a href='#JAX-RS-MigratingfromJAXRS1.1to2.0'>Migrating from JAX-RS 1.1
to 2.0</a></li>
    <li><a href='#JAX-RS-MigratingfromJAXRS1.0to1.1'>Migrating from JAX-RS 1.0
to 1.1</a></li>
    <li><a href='#JAX-RS-Mavendependencies'>Maven dependencies</a></li>
    <li><a href='#JAX-RS-CXF2.7.0'>CXF 2.7.0</a></li>
    <li><a href='#JAX-RS-CXF2.6.x'>CXF 2.6.x</a></li>
    <li><a href='#JAX-RS-CXF2.5.xCXF2.3.x'>CXF 2.5.x - CXF 2.3.x</a></li>
    <li><a href='#JAX-RS-Settinguptheclasspath'>Setting up the classpath</a></li>
    <li><a href='#JAX-RS-CXFJAXRSbundle'>CXF JAX-RS bundle</a></li>
    <li><a href='#JAX-RS-WhatisNew'>What is New</a></li>
    <li><a href='#JAX-RS-GettingStartedwithJAXRS'>Getting Started with JAX-RS</a></li>
    <li><a href='#JAX-RS-UnderstandingtheBasics'>Understanding the Basics</a></li>
    <li><a href='#JAX-RS-SupportforDataBindings'>Support for Data Bindings</a></li>
    <li><a href='#JAX-RS-HowRequestURIisMatched'>How Request URI is Matched</a></li>
    <li><a href='#JAX-RS-ClientAPI'>Client API</a></li>
    <li><a href='#JAX-RS-Filters%2CInterceptorsandInvokers'>Filters, Interceptors
and Invokers</a></li>
    <li><a href='#JAX-RS-ServicelistingsandWADLsupport'>Service listings and WADL
    <li><a href='#JAX-RS-ConfiguringJAXRSservices'>Configuring JAX-RS services</a></li>
    <li><a href='#JAX-RS-Testing'>Testing</a></li>
    <li><a href='#JAX-RS-Debugging'>Debugging</a></li>
    <li><a href='#JAX-RS-Logging'>Logging</a></li>
    <li><a href='#JAX-RS-AdvancedFeatures'>Advanced Features</a></li>
    <li><a href='#JAX-RS-Multiparts'>Multiparts</a></li>
    <li><a href='#JAX-RS-SecureJAXRSservices'>Secure JAX-RS services</a></li>
    <li><a href='#JAX-RS-FailoverandLoadDistributionFeatures'>Failover and Load
Distribution Features</a></li>
    <li><a href='#JAX-RS-Redirection'>Redirection</a></li>
    <li><a href='#JAX-RS-XSLTandXPath'>XSLT and XPath</a></li>
    <li><a href='#JAX-RS-ComplexSearchQueries'>Complex Search Queries</a></li>
    <li><a href='#JAX-RS-ModelViewControllersupport'>Model-View-Controller support</a></li>
    <li><a href='#JAX-RS-CombiningJAXWSandJAXRS'>Combining JAX-WS and JAX-RS</a></li>
    <li><a href='#JAX-RS-IntegrationwithDistributedOSGi'>Integration with Distributed
    <li><a href='#JAX-RS-OtherAdvancedFeatures'>Other Advanced Features</a></li>
    <li><a href='#JAX-RS-MavenPlugins'>Maven Plugins</a></li>
    <li><a href='#JAX-RS-Deployment'>Deployment</a></li>
    <li><a href='#JAX-RS-RESTfulResources'>RESTful Resources</a></li>
    <li><a href='#JAX-RS-Howtocontribute'>How to contribute</a></li>

<h1><a name="JAX-RS-Introduction"></a>Introduction</h1>

<p><a href="" class="external-link" 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 the Java API for RESTful Web Services: JAX-RS 2.0 (<a href=""
class="external-link" rel="nofollow">JSR-339</a>) and JAX-RS 1.1 (<a href=""
class="external-link" rel="nofollow">JSR-311</a>). </p>

<p>CXF 2.7.0 supports most of the new features introduced in JAX-RS 2.0 (excluding the
client API for now - but note that CXF client API has been retrofitted to support new filters,
interceptors, exception classes and Response API, plus the asynchronous client invoker API).</p>

<p>CXF 2.6.x, 2.5.x, 2.4.x and 2.3.x supports <a href=""
class="external-link" rel="nofollow">JSR-311 API 1.1</a> and is JAX-RS TCK 1.1 compliant.<br/>
The JAX-RS 1.1 specification may be found <a href=""
class="external-link" rel="nofollow">here</a></p>

<p>CXF 2.2.x supports <a href=""
class="external-link" rel="nofollow">JSR-311 API 1.0 </a> and is JAX-RS TCK 1.0.
The JAX-RS 1.0 specification may be found <a href=""
class="external-link" rel="nofollow">here</a></p>

<p>CXF 2.1.x supports <a href=""
class="external-link" rel="nofollow">JSR-311 API 0.8</a>. </p>

<p>JAX-RS related demos are located under the <a href=""
class="external-link" rel="nofollow">samples/jax_rs </a> directory.</p>

<p>This documentation will refer to JAX-RS 2.0 (JSR-339) API.</p>

<p>Outstanding JAX-RS JIRA issues can be found <a href=";jqlQuery=project+%3D+CXF+AND+resolution+%3D+Unresolved+AND+component+%3D+JAX-RS+ORDER+BY+priority+DESC&amp;mode=hide"
class="external-link" rel="nofollow">here</a>.</p>

<h1><a name="JAX-RS-Projectsetupandconfiguration"></a>Project setup and

<h2><a name="JAX-RS-Migration"></a>Migration</h2>

<h3><a name="JAX-RS-MigratingfromJAXRS1.1to2.0"></a>Migrating 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 href="/confluence/display/CXF20DOC/JAX-RS+Basics"
title="JAX-RS Basics">JAX&#45;RS Basics</a> for more information.</p>

<p>Please also check the <a href=""
class="external-link" rel="nofollow">CXF 2.7 Migration Guide</a> for the information
about all the changes affecting the JAX-RS users</p>

<h3><a name="JAX-RS-MigratingfromJAXRS1.0to1.1"></a>Migrating from JAX-RS
1.0 to 1.1</h3>

<p>Existing JAX-RS 1.0 applications should run in CXF starting from 2.3.x without any
There have been just a few minor modifications at the JAX-RS API level:</p>
<ul class="alternate" type="square">
	<li>The <a href=""
class="external-link" rel="nofollow"><tt>@ApplicationPath</tt> annotation </a>
has been added for JAX-RS Application subclasses</li>
	<li>The <tt>Request</tt> interface has been updated with a new no-argument
<tt>evaluatePreconditions</tt> method - existing applications which are already
using the <tt>Request</tt> interface may need to be recompiled</li>

<h2><a name="JAX-RS-Mavendependencies"></a>Maven dependencies</h2>

<p>The cxf-rt-frontend-jaxrs dependency is required:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
   <span class="code-tag">&lt;dependency&gt;</span>
      <span class="code-tag">&lt;groupId&gt;</span>org.apache.cxf<span
      <span class="code-tag">&lt;artifactId&gt;</span>cxf-rt-frontend-jaxrs<span
      <span class="code-tag">&lt;version&gt;</span>${cxf.version}<span
   <span class="code-tag">&lt;/dependency&gt;</span>

<p>This will in turn pull in other <a href=""
class="external-link" rel="nofollow">CXF modules</a> such <tt>cxf-api</tt>,
<tt>cxf-rt-core</tt>, <tt>cxf-rt-transports-http</tt> and <tt>cxf-rt-bindings-xml</tt>
as well as <a href=""
class="external-link" rel="nofollow">the following 3rd-party dependencies</a>.</p>

<p>Here is a list of the additional dependencies:</p>

<h3><a name="JAX-RS-CXF2.7.0"></a>CXF 2.7.0</h3>

<p><tt></tt> replaces <tt></tt>.
This is very close to JSR-339 Public Release API level. Users can expect very minor differences
in the Final Release of API.  </p>

<h3><a name="JAX-RS-CXF2.6.x"></a>CXF 2.6.x</h3>

<p>Please check the <a href=""
class="external-link" rel="nofollow">CXF 2.6 Migration Guide</a> for the information
about all the changes affecting the JAX-RS users. Typically adding the frontend jaxrs dependency
should be enough.</p>

<p>1. <tt></tt> </p>

<p>Optional providers (including the default JSONProvider) are located in this module:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
   <span class="code-tag">&lt;dependency&gt;</span>
      <span class="code-tag">&lt;groupId&gt;</span>org.apache.cxf<span
      <span class="code-tag">&lt;artifactId&gt;</span>cxf-rt-rs-extension-providers<span
      <span class="code-tag">&lt;version&gt;</span>2.6.0<span class="code-tag">&lt;/version&gt;</span>
   <span class="code-tag">&lt;/dependency&gt;</span>

<p>The Search extension is now located in</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
   <span class="code-tag">&lt;dependency&gt;</span>
      <span class="code-tag">&lt;groupId&gt;</span>org.apache.cxf<span
      <span class="code-tag">&lt;artifactId&gt;</span>cxf-rt-rs-extension-search<span
      <span class="code-tag">&lt;version&gt;</span>2.6.0<span class="code-tag">&lt;/version&gt;</span>
   <span class="code-tag">&lt;/dependency&gt;</span>

<h3><a name="JAX-RS-CXF2.5.xCXF2.3.x"></a>CXF 2.5.x - CXF 2.3.x</h3>

<p>1. <tt></tt> </p>

<p>2. org.apache.abdera groupId: abdera-core, abdera-parser and abdera-extensions-json
artifacts, version 1.1. <b>Note that starting from CXF 2.3.0 the Abdera dependencies
are optional</b>.</p>

<p>3. <tt>org.springframework/spring-core/3.0.5-RELEASE</tt> (and other
core Spring dependencies)</p>

<p>4. <tt>org.codehaus.jettison/jettison/1.3.2</tt></p>

<p><b>Note that starting from CXF 2.4.x the <tt>cxf-rt-databindings-aegis</tt>
and <tt>org.apache.xmlbeans/xmlbeans/2.4.0</tt> dependencies are optional</b>.
If you are not working with the CXF distributions containing these dependencies but using
Maven to pull in either the CXF JAX-RS Bundle or the <tt>cxf-rt-frontend-jaxrs</tt>
frontend then please make sure one of the following dependencies are also included:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
   <span class="code-tag">&lt;dependency&gt;</span>
      <span class="code-tag">&lt;groupId&gt;</span>org.apache.cxf<span
      <span class="code-tag">&lt;artifactId&gt;</span>cxf-rt-databinding-aegis<span
      <span class="code-tag"><span class="code-comment">&lt;!-- 2.4.4 or 2.5.0
      <span class="code-tag">&lt;version&gt;</span>${cxf.version}<span
   <span class="code-tag">&lt;/dependency&gt;</span>
   <span class="code-tag">&lt;dependency&gt;</span>
      <span class="code-tag">&lt;groupId&gt;</span>org.apache.xmlbeans<span
      <span class="code-tag">&lt;artifactId&gt;</span>xmlbeans<span
      <span class="code-tag">&lt;version&gt;</span>2.4.0<span class="code-tag">&lt;/version&gt;</span>
   <span class="code-tag">&lt;/dependency&gt;</span>

<p><b>Starting from CXF 2.4.0</b> the wsdl4j transitive dependency is only
required for running the CXF JAX-RS client code due to one of the HTTP transport extensions
indirectly depending on wsdl4j. When running the server endpoints only, you can add the wsdl4j
exclusion to either cxf-frontend-jaxrs or cxf-bundle-jaxrs dependency: </p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;exclusion&gt;</span>
 <span class="code-tag">&lt;groupId&gt;</span>wsdl4j<span class="code-tag">&lt;/groupId&gt;</span>
 <span class="code-tag">&lt;artifactId&gt;</span>wsdl4j<span class="code-tag">&lt;/artifactId&gt;</span>
<span class="code-tag">&lt;/exclusion&gt;</span>

<p>Please check the <a href=""
class="external-link" rel="nofollow">pom.xml</a> for the list of cxf components used
by the JAX-RS implementation. Snapshots are available from <a href=""
class="external-link" rel="nofollow"></a>.</p>

<h2><a name="JAX-RS-Settinguptheclasspath"></a>Setting up the classpath</h2>

<p>If Maven is not used then the following JARs will need to be available at the runtime

<p>For CXF 2.7.x:</p>


<p>For CXF 2.6.x:</p>


<p>For CXF 2.5.x-2.4.x:</p>

<ul class="alternate" type="square">

<ul class="alternate" type="square">

<ul class="alternate" type="square">

<ul class="alternate" type="square">
	<li>wsdl4j-1.6.2.jar (only needed at the client side)</li>

<h2><a name="JAX-RS-CXFJAXRSbundle"></a>CXF JAX-RS bundle</h2>

<p>A standalone <a href=""
class="external-link" rel="nofollow">JAX-RS bundle</a> is now 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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
   <span class="code-tag">&lt;dependency&gt;</span>
      <span class="code-tag">&lt;groupId&gt;</span>org.apache.cxf<span
      <span class="code-tag">&lt;artifactId&gt;</span>cxf-bundle-jaxrs<span
      <span class="code-tag">&lt;version&gt;</span>${cxf.version}<span
      <span class="code-tag">&lt;exclusions&gt;</span>
          <span class="code-tag">&lt;exclusion&gt;</span>
            <span class="code-tag">&lt;groupId&gt;</span>org.eclipse.jetty<span
            <span class="code-tag">&lt;artifactId&gt;</span>jetty-server<span
          <span class="code-tag">&lt;/exclusion&gt;</span>
      <span class="code-tag">&lt;/exclusions&gt;</span> 

   <span class="code-tag">&lt;/dependency&gt;</span>

<h1><a name="JAX-RS-WhatisNew"></a>What is New</h1>

	<li>Initial support for JAX-RS 2.0, please see <a href="/confluence/display/CXF20DOC/JAX-RS+Basics"
title="JAX-RS Basics">JAX&#45;RS Basics</a> for more information</li>
	<li>Initial support for MAC token in OAuth2, please see <a href=""
class="external-link" rel="nofollow">JAX-RS OAuth2</a> for more information.</li>
	<li>Kerberos Support, please see <a href=""
class="external-link" rel="nofollow">JAXRS Kerberos</a> for more information.</li>

<h1><a name="JAX-RS-GettingStartedwithJAXRS"></a>Getting Started with JAX-RS</h1>

<h2><a name="JAX-RS-UnderstandingtheBasics"></a>Understanding the Basics</h2>

<p>You are encouraged to read <a href="" class="external-link"
rel="nofollow">JSR-339</a> specification to find out 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 href="/confluence/display/CXF20DOC/JAX-RS+Basics" title="JAX-RS
Basics">JAX&#45;RS Basics</a> page for more information.</p>

<h2><a name="JAX-RS-SupportforDataBindings"></a>Support for Data Bindings</h2>

<p>JAX-RS MessageBodyReader and MessageBodyWriter can be used to create data bindings
for reading and writing data in a number of different formats. Compliant JAX-RS implementations
are expected to support JAXB-annotated beans, JAXP Source objects, InputStreams, etc.</p>

<p>In addition, CXF JAX-RS lets users reuse existing CXF DataBindings for working with
JAXB, XBeans, Aegis and SDO.     </p>

<p>Please see the <a href="/confluence/display/CXF20DOC/JAX-RS+Data+Bindings" title="JAX-RS
Data Bindings">JAX&#45;RS Data Bindings</a> page for more information. </p>

<h2><a name="JAX-RS-HowRequestURIisMatched"></a>How Request URI is Matched</h2>

<p>Lets assume you have a web application called 'rest'. 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 &#64;Path("/") should be available, in the latter case - at least
&#64;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 &#64;Path with at least "/test/bar" for the above requests to be matched.

<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><a name="JAX-RS-ClientAPI"></a>Client API</h2>

<p>JAX-RS 1.1 does not provide for a standard approach toward consuming pure HTTP-based
services thus CXF JAX-RS provides a comprehensive support for developing RESTful clients by
introducing 3 flavors of the client API: proxy-based, HTTP-centric and XML-centric.</p>

<p>Please see the <a href="/confluence/display/CXF20DOC/JAX-RS+Client+API" title="JAX-RS
Client API">JAX&#45;RS Client API</a> page for more information.</p>

<h2><a name="JAX-RS-Filters%2CInterceptorsandInvokers"></a>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 href="/confluence/display/CXF20DOC/JAX-RS+Filters" title="JAX-RS
Filters">JAX&#45;RS Filters</a> page for more information.</p>

<h2><a name="JAX-RS-ServicelistingsandWADLsupport"></a>Service listings
and WADL support</h2>

<p>CXF JAX-RS supports <a href="" class="external-link"
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 href="/confluence/display/CXF20DOC/JAXRS+Services+Description"
title="JAXRS Services Description">JAXRS Services Description</a> page for more information.

<h2><a name="JAX-RS-ConfiguringJAXRSservices"></a>Configuring JAX-RS services</h2>

<p>JAX-RS services can be configured programmatically, using Blueprint, Spring or CXFNonSpringJAXRSServlet.</p>

<p>Please see the <a href="/confluence/display/CXF20DOC/JAXRS+Services+Configuration"
title="JAXRS Services Configuration">JAXRS Services Configuration</a> page for more

<h2><a name="JAX-RS-Testing"></a>Testing</h2>

<p>JAX-RS services can be easily tested using the embedded Jetty or CXF Local Transport.<br/>
Please see the <a href=""
class="external-link" rel="nofollow">JAXRS Testing</a> page for more information.</p>

<h2><a name="JAX-RS-Debugging"></a>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><tt>&gt; GET /resource.xml</tt><br/>
<tt>&gt; GET /resource.en</tt></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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">

  <span class="code-tag">&lt;jaxrs:server id=<span class="code-quote">"customerService"</span>
address=<span class="code-quote">"/"</span>&gt;</span>
    <span class="code-tag">&lt;jaxrs:serviceBeans&gt;</span>
      <span class="code-tag">&lt;bean class=<span class="code-quote">"org.apache.cxf.jaxrs.systests.CustomerService"</span>
    <span class="code-tag">&lt;/jaxrs:serviceBeans&gt;</span>
    <span class="code-tag">&lt;jaxrs:extensionMappings&gt;</span>
      <span class="code-tag">&lt;entry key=<span class="code-quote">"json"</span>
value=<span class="code-quote">"application/json"</span>/&gt;</span>
      <span class="code-tag">&lt;entry key=<span class="code-quote">"xml"</span>
value=<span class="code-quote">"application/xml"</span>/&gt;</span>
    <span class="code-tag">&lt;/jaxrs:extensionMappings&gt;</span>
    <span class="code-tag">&lt;jaxrs:languageMappings&gt;</span>
       <span class="code-tag">&lt;entry key=<span class="code-quote">"en"</span>
value=<span class="code-quote">"en-gb"</span>/&gt;</span>  
    <span class="code-tag">&lt;/jaxrs:languageMappings&gt;</span>
  <span class="code-tag">&lt;/jaxrs:server&gt;</span>

<p>CXF also supports a _type query as an alternative to appending extensions like '.xml'
to request URIs:</p>

<p>{{ &gt; GET /resource?_type=xml}}</p>

<p>Overriding a request method is also easy:</p>

<p><tt>&gt; GET /resource?_method=POST</tt></p>

<p>Alternatively, one can specify an HTTP header X-HTTP-Method-Override:</p>

<p><tt>&gt; POST /books</tt><br/>
<tt>&gt; X-HTTP-Method-Override : PATCH</tt></p>

<p>For example, at the moment the http-centric client API does not support arbitrary
HTTP verbs except for those supported <br/>
by Java HTTPUrlConnection. When needed, X-HTTP-Method-Override can be set to overcome this

<p>Finally, a "_ctype" query allows for overriding Content-Type.</p>

<p>Please see the <a href="/confluence/display/CXF20DOC/Debugging+and+Logging" title="Debugging
and Logging">Debugging and Logging</a> page for more information on how to debug
and log service calls in CXF.</p>

<h2><a name="JAX-RS-Logging"></a>Logging</h2>

<p>Many of the existing CXF features can be applied either to <tt>jaxrs:server</tt>
or <tt>jaxrs:client</tt>. For example, to enable logging of requests and responses,
simply do:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
&lt;beans <span class="code-keyword">xmlns:cxf</span>=<span class="code-quote">""</span>

<span class="code-tag">&lt;jaxrs:server&gt;</span>
<span class="code-tag">&lt;jaxrs:features&gt;</span>
     <span class="code-tag">&lt;cxf:logging/&gt;</span>
<span class="code-tag">&lt;/jaxrs:features&gt;</span>
<span class="code-tag">&lt;jaxrs:server&gt;</span>
<span class="code-tag">&lt;/beans&gt;</span>

<p>Please make sure the <tt><a href="" class="external-link"
rel="nofollow"></a></tt> 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 href="/confluence/display/CXF20DOC/Debugging+and+Logging" title="Debugging
and Logging">Debugging and Logging</a> page for more information.</p>

<h1><a name="JAX-RS-AdvancedFeatures"></a>Advanced Features</h1>

<h2><a name="JAX-RS-Multiparts"></a>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 href="/confluence/display/CXF20DOC/JAX-RS+Multiparts" title="JAX-RS
Multiparts">JAX&#45;RS Multiparts</a> page for more information. </p>

<h2><a name="JAX-RS-SecureJAXRSservices"></a>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 href="/confluence/display/CXF20DOC/Secure+JAX-RS+Services" title="Secure
JAX-RS Services">Secure JAX&#45;RS Services</a> page for more information.</p>

<p>Please also check <a href=""
class="external-link" rel="nofollow">JAX-RS XML Security</a>, <a href="/confluence/display/CXF20DOC/JAX-RS+SAML"
title="JAX-RS SAML">JAX&#45;RS SAML</a> and <a href="/confluence/display/CXF20DOC/JAX-RS+OAuth2"
title="JAX-RS OAuth2">JAX&#45;RS OAuth2</a> pages for more information about
the advanced security topics.</p>

<h2><a name="JAX-RS-FailoverandLoadDistributionFeatures"></a>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/>
Please see the <a href="/confluence/display/CXF20DOC/JAX-RS+Failover" title="JAX-RS Failover">JAX&#45;RS
Failover</a> page for more information.  </p>

<h2><a name="JAX-RS-Redirection"></a>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>Please see the <a href="/confluence/display/CXF20DOC/JAX-RS+Redirection" title="JAX-RS
Redirection">JAX&#45;RS Redirection</a> page for more information.</p>

<h2><a name="JAX-RS-XSLTandXPath"></a>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 href="/confluence/display/CXF20DOC/JAX-RS+Advanced+XML" title="JAX-RS
Advanced XML">JAX&#45;RS Advanced XML</a> page for more information.</p>

<h2><a name="JAX-RS-ComplexSearchQueries"></a>Complex Search Queries</h2>

<p>Using <a href="" class="external-link"
rel="nofollow">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&amp;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 href=""
class="external-link" rel="nofollow">Feed Item Query Language</a>(FIQL).</p>

<p>Please see the <a href="/confluence/display/CXF20DOC/JAX-RS+Advanced+Features"
title="JAX-RS Advanced Features">JAX&#45;RS Advanced Features</a> page for more

<h2><a name="JAX-RS-ModelViewControllersupport"></a>Model-View-Controller

Please see <a href=""
class="external-link" rel="nofollow">this blog entry</a> on how <tt>XSLTJaxbProvider</tt>
can be used to generate complex (X)HTML views.</p>


<p>With the introduction of the <tt>RequestDispatcherProvider</tt> (see
above) it is now possible for JAXRS service responses be redirected to JSP pages for further
processing. Please see this <a href=""
class="external-link" rel="nofollow">beans.xml</a> for an example.</p>

<p>In addition to 'resourcePath' and 'dispatcherName' properties, one can set a 'scope'
property which has two possible values, 'request' and 'session' with 'request' being the default
value. It affects the way the JSP code can retrieve parameters passed to it by the RequestDispatcherProvider.
If it is a 'request' scope then all the parameters are set as the attributes on the current
HTTP request.  If session scope then they're set as the attributes on the current HTTP session.</p>

<p><tt>RequestDispatcherProvider</tt> sets the following parameters :</p>

<ul class="alternate" type="square">
	<li>JAXRS method response object.  The name of this parameter is either a simple class
name of this object (lower case) or a value retrieved from a beanNames map property using
the fully qualified class name of this object.</li>
	<li>All the path, query and matrix parameters which have been initialized during the
method execution</li>
	<li>"absolute.path", "base.path" and "relative.path" obtained from the current UriInfo</li>

<h2><a name="JAX-RS-CombiningJAXWSandJAXRS"></a>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 href="/confluence/display/CXF20DOC/JAX-RS+and+JAX-WS" title="JAX-RS
and JAX-WS">JAX&#45;RS and JAX&#45;WS</a> page for more information.</p>

<h2><a name="JAX-RS-IntegrationwithDistributedOSGi"></a>Integration with
Distributed OSGi</h2>

<p>Distributed OSGi RI is a CXF <a href=""
class="external-link" rel="nofollow">subproject</a>. DOSGi mandates how registered
Java interfaces can be exposed<br/>
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 possible to expose Java interfaces as RESTful services and consume such services using
a proxy-based client API.</p>

<p>Please see the <a href=""
class="external-link" rel="nofollow">DOSGI Reference page</a> (''
properties) and a <a href=""
class="external-link" rel="nofollow">greeter_rest</a> sample for more information.
Note that this demo can be run exactly as a SOAP-based <a href=""
class="external-link" rel="nofollow">greeter</a> demo as it registers and consumes
a similar (but) JAX-RS annotated <a href=""
class="external-link" rel="nofollow">GreeterService</a>. In addition, this demo shows
how one can register and consume a given interface (<a href=""
class="external-link" rel="nofollow">GreeterService2</a>) without using explicit
JAX-RS annotations but providing an out-of-band <a href=""
class="external-link" rel="nofollow">user model description</a>.</p>

<h2><a name="JAX-RS-OtherAdvancedFeatures"></a>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 href="/confluence/display/CXF20DOC/JAX-RS+Advanced+Features"
title="JAX-RS Advanced Features">JAX&#45;RS Advanced Features</a> page for more

<h1><a name="JAX-RS-MavenPlugins"></a>Maven Plugins</h1>

<p>Please see the <a href="/confluence/display/CXF20DOC/JAX-RS+Maven+Plugins" title="JAX-RS
Maven Plugins">JAX&#45;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><a name="JAX-RS-Deployment"></a>Deployment</h1>

<p>CXF JAX-RS applications packaged as WAR archives can be deployed into standalone
Servlet containers such as Tomcat or Jetty.<br/>
Please see the <a href=""
class="external-link" rel="nofollow">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><a name="JAX-RS-RESTfulResources"></a>RESTful Resources</h1>
	<li><a href=""
class="external-link" rel="nofollow">JSR-000311 JAX-RS: The JavaTM API for RESTful Web
	<li><a href="" class="external-link"
rel="nofollow">Architectural Styles and the Design of Network-based Software Architectures</a></li>
	<li><a href="" class="external-link"
rel="nofollow">Representational State Transfer - Wikipedia </a></li>
	<li><a href="" class="external-link" 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 href="" class="external-link" rel="nofollow">RESTful
Java with JAX-RS</a> <em>by Bill Burke</em> (O'Reilly Media, November 2009)</li>
	<li><a href="" class="external-link" rel="nofollow">Java
Web Services: Up and Running </a> <em>by Martin Kalin</em> (O'Reilly Media,
February 2009)</li>
	<li><a href="" class="external-link" 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 href=""
class="external-link" rel="nofollow">RESTful Web Services</a> <em>by Sameer
Tyagi</em> (Oracle , August 2006)</li>
	<li><a href="" class="external-link"
rel="nofollow">RESTful Web Services - "Unofficial homepage for a book about simple web
services."</a> <em>Unknown</em></li>
	<li><a href="" class="external-link"
rel="nofollow">How I Explained REST to My Wife</a> <em>by Ryan Tomayko</em>
(<a href="" class="external-link" rel="nofollow"></a>,
December 2004)</li>

<h1><a name="JAX-RS-Howtocontribute"></a>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 href=";mode=hide&amp;pid=12310511&amp;sorter/order=DESC&amp;sorter/field=priority&amp;resolution=-1&amp;component=12311911"
class="external-link" rel="nofollow">issue list</a> and see if you are interested
in fixing one of the issues.</p>

<p>If you decide to go ahead then the fastest way to start is to </p>
	<li>do the fast trunk build using '<tt>mvn install -Pfastinstall</tt>'</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>

<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/>
<tt>&gt; mvn install</tt> </p>

<p>You can also check out the general <a href=""
class="external-link" rel="nofollow">Getting Involved</a> web page for more information
on contributing.</p>

        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href=""
class="grey">Change Notification Preferences</a>
        <a href="">View Online</a>
        <a href="">View
        <a href=";showCommentArea=true#addcomment">Add

View raw message