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, 09 Feb 2011 13:31:00 GMT
    <base href="">
            <link rel="stylesheet" href="/confluence/s/2036/9/1/_/styles/combined.css?spaceKey=CXF20DOC&amp;forWysiwyg=true" type="text/css">
<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 Beryozkin</a>
                         <h4>Changes (2)</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" >h2. CXF JAX-RS bundle <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >A standalone [JAX-RS bundle|] is now available which may be of interest to users doing <span class="diff-added-words"style="background-color: #dfd;">the</span> JAX-RS work only. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">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: <br> <br>{code:xml} <br>   &lt;dependency&gt; <br>      &lt;groupId&gt;org.apache.cxf&lt;/groupId&gt; <br>      &lt;artifactId&gt;cxf-bundle-jaxrs&lt;/artifactId&gt; <br>      &lt;!-- 2.3.2 or 2.4.0 --&gt; <br>      &lt;version&gt;${cxf.version}&lt;/version&gt; <br>      &lt;exclusions&gt; <br>          &lt;exclusion&gt; <br>            &lt;groupId&gt;org.eclipse.jetty&lt;/groupId&gt; <br>            &lt;artifactId&gt;jetty-server&lt;/artifactId&gt; <br>            &lt;!-- 7.2.2.v20101205 --&gt;  <br>            &lt;version&gt;${cxf.jetty.version}&lt;/version&gt; <br>          &lt;/exclusion&gt; <br>      &lt;/exclusions&gt;  <br> <br>   &lt;/dependency&gt; <br>{code} <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h1. What is New <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-Mavendependencies'>Maven dependencies</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-BasicFeatures'>Basic Features</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-ClientAPI'>Client API</a></li>
    <li><a href='#JAX-RS-Multiparts'>Multiparts</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-Debugging'>Debugging</a></li>
    <li><a href='#JAX-RS-Logging'>Logging</a></li>
    <li><a href='#JAX-RS-Filters%2CInterceptorsandInvokers'>Filters, Interceptors and Invokers</a></li>
    <li><a href='#JAX-RS-SupportFeatures'>Support Features</a></li>
    <li><a href='#JAX-RS-SecureJAXRSservices'>Secure JAX-RS services</a></li>
    <li><a href='#JAX-RS-Redirection'>Redirection</a></li>
    <li><a href='#JAX-RS-ModelViewControllersupport'>Model-View-Controller support</a></li>
    <li><a href='#JAX-RS-ServicelistingsandWADLsupport'>Service listings and WADL support</a></li>
    <li><a href='#JAX-RS-ConfiguringJAXRSservices'>Configuring JAX-RS services</a></li>
    <li><a href='#JAX-RS-MatchingtheRequestURI'>Matching the Request URI</a></li>
    <li><a href='#JAX-RS-CombiningJAXWSandJAXRS'>Combining JAX-WS and JAX-RS</a></li>
    <li><a href='#JAX-RS-JAXRSandSpringAOP'>JAX-RS and Spring AOP</a></li>
    <li><a href='#JAX-RS-IntegrationwithDistributedOSGi'>Integration with Distributed OSGi</a></li>
    <li><a href='#JAX-RS-OtherAdvancedFeatures'>Other Advanced Features</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 JAX-RS (<a href="" class="external-link" rel="nofollow">JSR-311</a>), the Java API for RESTful Web Services. JAX-RS standardizes the way RESTful services can be developed in Java. </p>

<p>CXF 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. compliant.<br/>
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 JSR-311 API 1.1.</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 configuration</h1>

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

<p><b>Migrating from 1.0 to 1.1</b></p>

<p>Existing JAX-RS 1.0 applications should run in CXF 2.3.x without any problems.<br/>
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>

<p><b>Migrating from JAX-RS 0.8 to 1.0</b></p>

<p>The following major changes in 1.0 will most likely affect users migrating from 0.8:</p>

<ul class="alternate" type="square">
	<li><tt>@ProduceMime</tt> and <tt>@ConsumeMime</tt> have been replaced with <tt>@Produces</tt> and <tt>@Consumes</tt> respectively</li>
	<li><tt>HttpHeaders</tt> has had some of its methods returning a string representation of <tt>Locale</tt> updated to return the <tt>Locale</tt> object itself instead</li>

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

<p>To incorporate JAX-RS, you will need:</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 class="code-tag">&lt;/groupId&gt;</span>
      <span class="code-tag">&lt;artifactId&gt;</span>cxf-rt-frontend-jaxrs<span class="code-tag">&lt;/artifactId&gt;</span>
      <span class="code-tag">&lt;version&gt;</span>2.3.0<span class="code-tag">&lt;/version&gt;</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>1. <tt></tt> (or 1.0 for CXF 2.2.x)</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.2</tt></p>

<p><b>Note that starting from CXF 2.3.2-SNAPSHOT and 2.4.0-SNAPSHOT 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 is also included as needed :</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 class="code-tag">&lt;/groupId&gt;</span>
      <span class="code-tag">&lt;artifactId&gt;</span>cxf-rt-databinding-aegis<span class="code-tag">&lt;/artifactId&gt;</span>
      <span class="code-tag"><span class="code-comment">&lt;!-- 2.3.2 or 2.4.0 --&gt;</span></span>
      <span class="code-tag">&lt;version&gt;</span>${cxf.version}<span class="code-tag">&lt;/version&gt;</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 class="code-tag">&lt;/groupId&gt;</span>
      <span class="code-tag">&lt;artifactId&gt;</span>xmlbeans<span class="code-tag">&lt;/artifactId&gt;</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>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 classpath.</p>

<p>For CXF 2.3.0:</p>

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

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

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

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

<p>For CXF 2.2.x the dependencies are similar :</p>

<ul class="alternate" type="square">
	<li>do not add stax2-api-3.0.1.jar</li>
	<li>add wstx-asl-3.2.8.jar instead of woodstox-core-asl-4.0.3.jar</li>
	<li>add saaj-api-1.3.jar</li>

<p>If Spring configuration is used then add <tt>spring.jar</tt> from the Spring distribution or the spring jars available in the CXF distribution. When creating client proxies from concrete classes the <tt>cglib-nodep-2.1_3.jar</tt> needs to be added. You do not need to add JAXB libraries if you do not use JAXB. If you depend on Jetty then you will also need to add Jetty 7 or Jetty 6 JARs shipped with CXF 2.3.0 and 2.2.12 respectively.</p>

<p>We are working on reducing the set of required dependencies.<br/>
Please see the configuration sections below on how the spring dependency can be dropped.</p>

<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 class="code-tag">&lt;/groupId&gt;</span>
      <span class="code-tag">&lt;artifactId&gt;</span>cxf-bundle-jaxrs<span class="code-tag">&lt;/artifactId&gt;</span>
      <span class="code-tag"><span class="code-comment">&lt;!-- 2.3.2 or 2.4.0 --&gt;</span></span>
      <span class="code-tag">&lt;version&gt;</span>${cxf.version}<span class="code-tag">&lt;/version&gt;</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 class="code-tag">&lt;/groupId&gt;</span>
            <span class="code-tag">&lt;artifactId&gt;</span>jetty-server<span class="code-tag">&lt;/artifactId&gt;</span>
            <span class="code-tag"><span class="code-comment">&lt;!-- 7.2.2.v20101205 --&gt;</span></span> 
            <span class="code-tag">&lt;version&gt;</span>${cxf.jetty.version}<span class="code-tag">&lt;/version&gt;</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>

<ul class="alternate" type="square">
	<li>Many of the CXF <a href="/confluence/display/CXF20DOC/Annotations" title="Annotations">Custom Annotations</a> are now also recognized by CXF JAX-RS endpoints and client proxies.</li>

<p><tt>InInterceptors</tt>, <tt>OutInterceptors</tt>, <tt>InFaultInterceptors</tt>, <tt>OutFaultInterceptors</tt>, <tt>Logging</tt>, <tt>DataBinding</tt>, <tt>GZIP} and {{FastInfoset</tt>, <tt>EndpointProperties</tt> and <tt>EndpointProperty</tt> annotations are currently supported.</p>

<ul class="alternate" type="square">
	<li><tt>JAXBElementProvider</tt> can be configured to create a single <tt>JAXBContext</tt> which may also include some extra user classes. 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.</li>

<ul class="alternate" type="square">
	<li><tt>JAXRSDataBinding</tt> can be used to wrap JAX-RS providers for reading and writing XML payloads wrapped in SOAP envelopes.<br/>
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.    </li>

<h1><a name="JAX-RS-BasicFeatures"></a>Basic Features</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">JAX-RS spec </a>  <a href="" class="external-link" rel="nofollow">(html version) </a> 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.  </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-ClientAPI"></a>Client API</h2>

<p>JAX-RS 1.0 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-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-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 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> /&gt;</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;/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 limitation.</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> 
 xsi:schemaLocation=<span class="code-quote">""</span>&gt;
<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>

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

<h1><a name="JAX-RS-SupportFeatures"></a>Support Features</h1>

<h2><a name="JAX-RS-SecureJAXRSservices"></a>Secure JAX-RS services</h2>

<p>A demo called <tt>samples\jax_rs\basic_https</tt> shows how to do communications using HTTPS.</p>

<p>It is often containers like Tomcat or frameworks like Spring Security which handle user authentication. Sometimes however you might want to do custom authentication instead. The easiest way to do this is to register a custom invoker or <tt>RequestHandler</tt> filter which will extract a user name and password like this (it will work only for Basic Authentication requests):</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> class AuthenticationHandler <span class="code-keyword">implements</span> RequestHandler {

    <span class="code-keyword">public</span> Response handleRequest(Message m, ClassResourceInfo resourceClass) {
        AuthorizationPolicy policy = (AuthorizationPolicy)m.get(AuthorizationPolicy.class);
        <span class="code-comment">// alternatively :
</span>        <span class="code-comment">// HttpHeaders headers = <span class="code-keyword">new</span> HttpHeadersImpl(m);
</span>        <span class="code-comment">// access the headers as needed  
        <span class="code-comment">// authenticate the user
        <span class="code-keyword">return</span> <span class="code-keyword">null</span>;


<p>A demo called <tt>samples\jax_rs\spring_security</tt> shows how to provide the authentication and authorization with the help of Spring Security.</p>

<p>Please see the <a href="/confluence/display/CXF20DOC/Security" title="Security">Security</a> section on how CXF Security interceptors can help. Check this <a href="" class="external-link" rel="nofollow">blog entry</a> for more information on how CXF JAX-RS wraps the CXF security interceptors with helper filters.</p>

<p>Also see the "JAXRS and Spring AOP" section for some general advice.</p>

<p><b>SecurityManager and IllegalAccessExceptions</b></p>

<p>If <tt>java.lang.SecurityManager</tt> is installed then you'll likely need to configure the trusted JAX-RS codebase with a 'suppressAccessChecks' permission for the injection of JAXRS context or parameter fields to succeed. For example, you may want to update a Tomcat <a href="" class="external-link" rel="nofollow">catalina.policy</a> with the following permission :</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
grant codeBase <span class="code-quote">"file:${catalina.home}/webapps/yourwebapp/lib/cxf.jar"</span> {
    permission java.lang.reflect.ReflectPermission <span class="code-quote">"suppressAccessChecks"</span>;

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

<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-ModelViewControllersupport"></a>Model-View-Controller support</h2>

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-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. </p>

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

<p>JAX-RS services can be configured programmatically from Spring or using 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 information.</p>

<h2><a name="JAX-RS-MatchingtheRequestURI"></a>Matching the Request URI</h2>

<p>There's a number of variables involved here. </p>

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

<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-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-JAXRSandSpringAOP"></a>JAX-RS and Spring AOP</h2>

<p>CXF JAX-RS is capable of working with AOP interceptors applied to resource classes from Spring.<br/>
For example:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">

&lt;beans xsi:schemaLocation=""&gt;
  <span class="code-tag">&lt;import resource=<span class="code-quote">"classpath:META-INF/cxf/cxf.xml"</span>/&gt;</span>
  <span class="code-tag">&lt;import resource=<span class="code-quote">"classpath:META-INF/cxf/cxf-extension-jaxrs-binding.xml"</span>/&gt;</span>
  <span class="code-tag">&lt;import resource=<span class="code-quote">"classpath:META-INF/cxf/cxf-servlet.xml"</span>/&gt;</span>

  <span class="code-tag">&lt;jaxrs:server id=<span class="code-quote">"bookservice"</span> address=<span class="code-quote">"/"</span>&gt;</span>
	<span class="code-tag">&lt;jaxrs:serviceBeans&gt;</span>
          <span class="code-tag">&lt;ref bean=<span class="code-quote">"bookstore"</span>/&gt;</span>
          <span class="code-tag">&lt;ref bean=<span class="code-quote">"bookstoreInterface"</span>/&gt;</span>
        <span class="code-tag">&lt;/jaxrs:serviceBeans&gt;</span>
   <span class="code-tag">&lt;/jaxrs:server&gt;</span>
   <span class="code-tag">&lt;bean id=<span class="code-quote">"bookstore"</span> class=<span class="code-quote">"org.apache.cxf.systest.jaxrs.BookStore"</span>/&gt;</span>
   <span class="code-tag">&lt;bean id=<span class="code-quote">"bookstoreInterface"</span> class=<span class="code-quote">"org.apache.cxf.systest.jaxrs.BookStoreWithInterface"</span>/&gt;</span>

   <span class="code-tag">&lt;aop:config&gt;</span>
	<span class="code-tag">&lt;aop:aspect id=<span class="code-quote">"loggingAspect"</span> ref=<span class="code-quote">"simpleLogger"</span>&gt;</span>
          <span class="code-tag">&lt;aop:before method=<span class="code-quote">"logBefore"</span> pointcut=<span class="code-quote">"execution(* org.apache.cxf.systest.jaxrs.BookStore*.*(..))"</span>/&gt;</span>
          <span class="code-tag">&lt;aop:after-returning method=<span class="code-quote">"logAfter"</span> pointcut=<span class="code-quote">"execution(* org.apache.cxf.systest.jaxrs.BookStore*.*(..))"</span>/&gt;</span>
        <span class="code-tag">&lt;/aop:aspect&gt;</span>
   <span class="code-tag">&lt;/aop:config&gt;</span>
   <span class="code-tag">&lt;bean id=<span class="code-quote">"simpleLogger"</span> class=<span class="code-quote">"org.apache.cxf.systest.jaxrs.SimpleLoggingAspect"</span>/&gt;</span>
<span class="code-tag">&lt;/beans&gt;</span>


<p>Note that some AOP configuration is applied to two JAX-RS resource classes. By default Spring uses JDK dynamic proxies if a class to be proxified implements at least one interface or CGLIB proxies otherwise. </p>

<p>For example, here's how org.apache.cxf.systest.jaxrs.BookStoreWithInterface looks like: </p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">

<span class="code-keyword">public</span> <span class="code-keyword">interface</span> BookInterface {
    @Path(<span class="code-quote">"/thosebooks/{bookId}/"</span>)
    @Produces(<span class="code-quote">"application/xml"</span>)
    Book getThatBook(<span class="code-object">Long</span> id) <span class="code-keyword">throws</span> BookNotFoundFault;

<span class="code-keyword">public</span> class BookStoreWithInterface <span class="code-keyword">extends</span> BookStoreStorage <span class="code-keyword">implements</span> BookInterface {

    <span class="code-keyword">public</span> Book getThatBook(@PathParam(<span class="code-quote">"bookId"</span>) <span class="code-object">Long</span> id) <span class="code-keyword">throws</span> BookNotFoundFault {
        <span class="code-keyword">return</span> doGetBook(id);

    @Path(<span class="code-quote">"/thebook"</span>)
    <span class="code-keyword">public</span> Book getTheBook(@PathParam(<span class="code-quote">"bookId"</span>) <span class="code-object">Long</span> id) <span class="code-keyword">throws</span> BookNotFoundFault {
        <span class="code-keyword">return</span> doGetBook(id);

<p>In this case Spring will use a JDK dynamic proxy to wrap a BookStoreWithInterface class. As such it is important that the method which needs to be invoked such as getThatBook(...) will be part of the interface. </p>

<p>The other method, getTheBook() can not be dispatched to by a JAX-RS runtime as it's not possible to discover it through a JDK proxy. If this method also needs to be invoked then this method should either be added to the interface or CGLIB proxies have to be explicitly enabled (consult Spring AOP documentation for more details). For example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;aop:config proxy-target-class=<span class="code-quote">"true"</span>/&gt;</span>

<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 information.</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 Services</a></li>
	<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 Changes</a>
        <a href=";showCommentArea=true#addcomment">Add Comment</a>

View raw message