cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache CXF Documentation > JAX-RS
Date Wed, 22 Dec 2010 16:14:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1810/9/1/_/styles/combined.css?spaceKey=CXF20DOC&amp;forWysiwyg=true"
type="text/css">
    </head>
<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="https://cwiki.apache.org/confluence/display/CXF20DOC/JAX-RS">JAX-RS</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~sergey_beryozkin">Sergey
Beryozkin</a>
    </h4>
        <br/>
                         <h4>Changes (1)</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" >XPath and XSLT 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. <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >Please see the <span class="diff-changed-words">[JAX<span
class="diff-added-chars"style="background-color: #dfd;">-</span>RS</span> Advanced
XML] page for more information. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>h2. XPath support <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
        </table>
</div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <span style="font-size:2em;font-weight:bold"> JAX-RS (JSR-311) </span>

<div>
<ul>
    <li><a href='#JAX-RS-Introduction'>Introduction</a></li>
    <li><a href='#JAX-RS-Migration'>Migration</a></li>
<ul>
    <li><a href='#JAX-RS-MigratingfromJAXRS0.8to1.0'>Migrating from JAX-RS 0.8
to 1.0</a></li>
    <li><a href='#JAX-RS-Migratingfrom1.0to1.1'>Migrating from 1.0 to 1.1</a></li>
</ul>
    <li><a href='#JAX-RS-Mavendependencies'>Maven dependencies</a></li>
    <li><a href='#JAX-RS-SettinguptheclasspathinEclipseorAnt'>Setting up the classpath
in Eclipse or Ant</a></li>
    <li><a href='#JAX-RS-CXFJAXRSbundle'>CXF JAX-RS bundle</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-SupportforMultiparts'>Support for Multiparts</a></li>
    <li><a href='#JAX-RS-XPathandXSLT'>XPath and XSLT</a></li>
<ul>
    <li><a href='#JAX-RS-XPathsupport'>XPath support</a></li>
    <li><a href='#JAX-RS-XSLTsupport'>XSLT support</a></li>
</ul>
    <li><a href='#JAX-RS-SupportforComplexSearchQueries'>Support for 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-AdvancedFeatures'>Advanced Features</a></li>
    <li><a href='#JAX-RS-SecureJAXRSservices'>Secure JAX-RS services</a></li>
<ul>
    <li><a href='#JAX-RS-CheckingHTTPsecurityheaders'>Checking HTTP security headers</a></li>
    <li><a href='#JAX-RS-SecurityManagerandIllegalAccessExceptions'>SecurityManager
and IllegalAccessExceptions</a></li>
</ul>
    <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-Howtocontribute'>How to contribute</a></li>
</ul></div>

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

<p>CXF supports JAX-RS (JSR-311), Java API for RESTful Web Services. JAX-RS standardizes
the way RESTful services can be developed in Java. </p>

<p>CXF 2.3.0 supports <a href="https://jsr311.dev.java.net/nonav/releases/1.1/index.html"
class="external-link" rel="nofollow">JSR-311 API 1.1</a>.<br/>
CXF 2.2.x supports <a href="https://jsr311.dev.java.net/nonav/releases/1.0/index.html"
class="external-link" rel="nofollow">JSR-311 API 1.0 </a>.<br/>
CXF 2.3.0 and CXF 2.2.x have passed JAX-RS TCK 1.1 and TCK 1.0 respectively.</p>

<p>CXF 2.1.x supports <a href="https://jsr311.dev.java.net/nonav/releases/0.8/index.html"
class="external-link" rel="nofollow">JSR-311 API 0.8</a>. </p>

<p>JAX-RS related demos are located under the samples/jax_rs directory.<br/>
This documentation will refer to <a href="https://jsr311.dev.java.net/nonav/releases/1.1/index.html"
class="external-link" rel="nofollow">JSR-311 API 1.1 </a>.</p>

<h1><a name="JAX-RS-Migration"></a>Migration</h1>
<h2><a name="JAX-RS-MigratingfromJAXRS0.8to1.0"></a>Migrating from JAX-RS
0.8 to 1.0</h2>

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

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


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

<p>Existing JAX-RS 1.0 applications should run in CXF 2.3.0 without any problems.<br/>
There have been just few minor modifications at the JAX-RS API level :</p>
<ul class="alternate" type="square">
	<li>@ApplicationPath has been introduced which JAX-RS Application implementations can
be annotated with;</li>
	<li>Request interface has been updated with a new evaluatePreconditions method with
no input parameters - the existing applications which are already using the Request interface
may need to be recompiled.</li>
</ul>



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

<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>
</pre>
</div></div>

<p>This will in turn pull in other CXF modules such cxf-api, cxf-rt-core, cxf-rt-transports-http
and cxf-rt-bindings-xml as well as <a href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/pom.xml"
class="external-link" rel="nofollow">the following 3rd-party dependencies</a>:</p>

<p>1. javax.ws.rs/jsr311-api/1.1 (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. Note that starting from CXF 2.3.0 the Abdera dependencies are optional.</p>

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

<p>4. org.codehaus.jettison/jettison/1.2</p>

<p>5. org.apache.xmlbeans/xmlbeans/2.4.0</p>

<p>Please check <a href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/pom.xml"
class="external-link" rel="nofollow">the pom.xml</a> for the list of cxf components
used by the JAX-RS implementation. Snapshots are available from <a href="http://repository.apache.org/snapshots/org/apache/cxf/apache-cxf/"
class="external-link" rel="nofollow">http://repository.apache.org/snapshots/org/apache/cxf/apache-cxf/</a></p>

<h1><a name="JAX-RS-SettinguptheclasspathinEclipseorAnt"></a>Setting up
the classpath in Eclipse or Ant</h1>

<p>If Maven is not used then the following jars need to be available at the runtime
classpath.</p>

<p>For CXF 2.3.0:</p>

<ul class="alternate" type="square">
	<li>cxf-2.3.0.jar</li>
	<li>jsr311-api-1.1.jar</li>
	<li>jaxb-impl-2.1.13.jar</li>
	<li>jaxb-api-2.1.jar</li>
</ul>


<ul class="alternate" type="square">
	<li>geronimo-annotation_1.0_spec-1.1.1.jar</li>
	<li>geronimo-activation_1.1_spec-1.1.jar</li>
	<li>geronimo-servlet_3.0_spec_1.0.jar</li>
	<li>commons-logging-1.1.1.jar</li>
</ul>


<ul class="alternate" type="square">
	<li>geronimo-stax_api_1.0_spec-1.0.1.jar</li>
	<li>woodstox-core-asl-4.0.8.jar</li>
	<li>stax2-api-3.0.1.jar</li>
</ul>


<ul class="alternate" type="square">
	<li>wsdl4j-1.6.2.jar</li>
	<li>XmlSchema-1.4.5.jar</li>
	<li>neethi-2.0.4.jar</li>
</ul>


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

<ul class="alternate" type="square">
	<li>cxf-2.2.12.jar</li>
	<li>jsr311-api-1.0.jar</li>
	<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>
</ul>


<p>If Spring configuration is used then add spring.jar from the Spring distribution
or the spring jars available in the CXF distribution. When creating client proxies from concrete
classes the cglib-nodep-2.1_3.jar 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 will work on reducing the set of required dependencies.<br/>
Please see the configuration sections below on how a spring dependency can be dropped.</p>

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

<p>A standalone <a href="http://svn.apache.org/repos/asf/cxf/trunk/distribution/bundle/jaxrs/pom.xml"
class="external-link" rel="nofollow">JAX-RS bundle</a> is now available which may
be of interest to users doing JAX-RS work only.</p>

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

<p>You are encouraged to read <a href="http://jcp.org/en/jsr/detail?id=311" class="external-link"
rel="nofollow">JAX-RS spec </a>  <a href="https://jsr311.dev.java.net/nonav/releases/1.1/spec/spec.html"
class="external-link" rel="nofollow">(html version) </a> to find out information
not covered by this documentation.</p>

<p>The JAX-RS introduces such terms as root resources, resource methods, sub-resources
and sub-resource locators, message body readers and writers, etc.  </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>

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

<p>JAX-RS MessageBodyReader and MessageBodyWriter can be used to create data bindings
for reading and writing the 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>

<h1><a name="JAX-RS-ClientAPI"></a>Client API</h1>

<p>JAX-RS 1.0 does not provide for the 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>

<h1><a name="JAX-RS-SupportforMultiparts"></a>Support for Multiparts</h1>

<p>Multiparts can be handled in a number of ways. CXF core runtimes provides an advanced
support for handling attachments and CXF JAX-RS builds upon it. </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>


<h1><a name="JAX-RS-XPathandXSLT"></a>XPath and XSLT</h1>

<p>XPath and XSLT 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/pages/createpage.action?spaceKey=CXF20DOC&amp;title=JAX-RS+Advanced+XML&amp;linkCreation=true&amp;fromPageId=70366"
class="createlink">JAX&#45;RS Advanced XML</a> page for more information.</p>

<h2><a name="JAX-RS-XPathsupport"></a>XPath support</h2>

<p>XPath is supported on the server and client sides with the help of <a href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/xml/XMLSource.java"
class="external-link" rel="nofollow">XMLSource</a> utility class. Please see above
how http-centric WebClients can use XPath, here is an example for the server side :</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
@Path(<span class="code-quote">"/root"</span>)
<span class="code-keyword">public</span> class Root {
   @POST
   <span class="code-keyword">public</span> void post(XMLSource source) {
       <span class="code-object">String</span> value = source.getProperty(<span
class="code-quote">"/books/book/@name"</span>);
   }    
}
</pre>
</div></div> 

<p>Users have an option to hide XPath expressions, by registering an <a href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/provider/XPathProvider.java"
class="external-link" rel="nofollow">XPathProvider</a>, either on client or server
sides. For example :</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
XPathProvider provider = <span class="code-keyword">new</span> XPathProvider();
provider.setGlobalExpression(<span class="code-quote">"/books/book[position() = 1]"</span>);
WebClient wc = WebClient.create(<span class="code-quote">"http:<span class="code-comment">//aggregated/data"</span>,
Collections.singletonList(provider));
</span>Book b = wc.get(Book.class);
</pre>
</div></div>

<h2><a name="JAX-RS-XSLTsupport"></a>XSLT support</h2>

<p>XSLT is currently supported by <a href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/provider/XSLTJaxbProvider.java"
class="external-link" rel="nofollow">XSLTJaxbProvider</a>. This provider works in
tandem with JAXB and can be used to produce pretty much any format, including non-XML ones.
Likewise, it can be used to extract XML data out of incoming XML fragments, either on the
client or server sides.</p>

<p>XSLTJaxbProvider can be configured to handle input or output data, scoped by media
types if needed. For example, one may configure it such that one template handles "application/xml"
formats only while the other one handles "application/json" writes only.</p>

<p>XSLTJaxbProvider uses an injected JAX-RS UriInfo to inject all the usual JAX-RS information
like template or query parameters into a given XSLT template.</p>

<p>For example, given this resource method definition :</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
@Path(<span class="code-quote">"/root"</span>)
<span class="code-keyword">public</span> class Root {
   @GET
   @Path(<span class="code-quote">"{id}"</span>) 
   <span class="code-keyword">public</span> Book get(@PathParam(<span class="code-quote">"id"</span>)
<span class="code-object">String</span> id, @QueryParam(<span class="code-quote">"name"</span>)
<span class="code-object">String</span> name) {
       <span class="code-keyword">return</span> getBook(id, name);
   }    
}
</pre>
</div></div>

<p>an XSLT template processing the JAXB-driven serialization of a Book instance will
have parameters with name 'id' and 'name' injected.</p>

<p>Note that when XSLTJaxbProvider is used on the client side, it may not always be
possible for template parameters be injected in cases when http-centric clients are used (as
opposed to proxies). For example :</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
WebClient client = WebClient.create(<span class="code-quote">"http:<span class="code-comment">//books"</span>);
</span>client.path(<span class="code-quote">"/store/1"</span>).get();
</pre>
</div></div>

<p>it is not possible to deduce that '1' represents a template parameter in the "/store/1"
expression. However, one can use the following code instead if '1' needs to be available to
XSLT templates :</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
WebClient client = WebClient.create(<span class="code-quote">"http:<span class="code-comment">//books"</span>);
</span>client.path(<span class="code-quote">"/store/{id}"</span>, 1).get();
</pre>
</div></div>


<h1><a name="JAX-RS-SupportforComplexSearchQueries"></a>Support for Complex
Search Queries</h1>

<p>Using <a href="http://cxf.apache.org/docs/jax-rs.html#JAX-RS-Parameterbeans" class="external-link"
rel="nofollow">query parameter beans</a> provides for a way to capture all the search
requirements which can be expressed by enumerating simple name/value pairs, 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 the available
local data.</p>

<p>CXF JAXRS (since 2.3) supports another option for users to do the advanced search
queries based on the <a href="http://tools.ietf.org/html/draft-nottingham-atompub-fiql-00"
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>

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

<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>&gt; GET /resource.xml<br/>
&gt; GET /resource.en</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 how to do it in 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>
</pre>
</div></div>

<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>&gt; GET /resource?_method=POST</p>

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

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

<p>For example, at the moment 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 the service calls in CXF.</p>

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

<p>Many of the existing CXF features can be applied either to jaxrs:server or jaxrs:client.
For example, to enable the 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">"http://cxf.apache.org/core"</span>

 xsi:schemaLocation=<span class="code-quote">"http://cxf.apache.org/core http://cxf.apache.org/schemas/core.xsd"</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>
</pre>
</div></div>

<p>Please make sure an "http://cxf.apache.org/core" 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 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-Filters%2CInterceptorsandInvokers"></a>Filters, Interceptors
and Invokers</h1>

<p>It is possible to intercept and affect 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-AdvancedFeatures"></a>Advanced Features</h1>

<p>CXF JAX-RS provides a number of advanced extensions such as the support for the JMS
transport, one-way invocations (HTTP and JMS), the suspended invocations (HTTP and JMS), making
existing code REST-aware by applying the 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-SecureJAXRSservices"></a>Secure JAX-RS services</h1>

<p>A demo called samples\jax_rs\basic_https shows you how to do communications using
HTTPS.<br/>
Spring Security can be quite easily applied too (see "JAXRS and Spring AOP" section for some
general advice).</p>

<h2><a name="JAX-RS-CheckingHTTPsecurityheaders"></a>Checking HTTP security
headers</h2>

<p>It is often containers like Tomcat or frameworks like Spring Security which deal
with ensuring a current user is authenticated. Sometimes you might want to deal with the authentication
manually. The easiest way to do it is to register a custom invoker or RequestHandler 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);
        policy.getUserName();
        policy.getPassword(); 
        <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>
        <span class="code-comment">// authenticate the user
</span>
        <span class="code-keyword">return</span> <span class="code-keyword">null</span>;
    }

}
</pre>
</div></div> 

<h2><a name="JAX-RS-SecurityManagerandIllegalAccessExceptions"></a>SecurityManager
and IllegalAccessExceptions</h2>

<p>If java.lang.SecurityManager is installed then you'll likely need to configure the
trusted JAXRS 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="http://tomcat.apache.org/tomcat-5.5-doc/security-manager-howto.html" 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>;
};
</pre>
</div></div>


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

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

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

<p><b>XSLT</b><br/>
Please see <a href="http://sberyozkin.blogspot.com/2009/05/mvc-xml-way-with-cxf-jax-rs.html"
class="external-link" rel="nofollow">this blog entry</a> on how XSLTJaxbProvider
can be used to generate complex (X)HTML views.</p>

<p><b>JSP</b></p>

<p>With the introduction of the RequestDispatcherProvider (see above) it is now possible
for JAXRS service responses be redirected to JSP pages for further processing. Please see
this <a href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/resources/jaxrs_dispatch/WEB-INF/beans.xml"
class="external-link" rel="nofollow">beans.xml</a>.</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 it is a session then they're set as the attributes on the current HTTP session.</p>

<p>RequestDispatcherProvider 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>
</ul>


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

<p>CXF JAX-RS supports <a href="http://www.w3.org/Submission/wadl" 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>

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

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

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

<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 be handled, a resource
class with &#64;Path("/") should be available, in the latter case - at least &#64;Path("/")
or 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 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>

<h1><a name="JAX-RS-CombiningJAXWSandJAXRS"></a>Combining JAX-WS and JAX-RS</h1>

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

<h1><a name="JAX-RS-JAXRSandSpringAOP"></a>JAX-RS and Spring AOP</h1>

<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=" http://www.springframework.org/schema/beans
  http://www.springframework.org/schema/beans/spring-beans.xsd
  http://www.springframework.org/schema/aop  
  http://www.springframework.org/schema/aop/spring-aop.xsd 
  http://cxf.apache.org/jaxrs 
  http://cxf.apache.org/schemas/jaxrs.xsd"&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>

</pre>
</div></div> 

<p>Note that some AOP configuration is applied to two JAX-RS resource classes. By default
Spring uses JDK dynamic proxies every time 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 {
    @GET
    @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);
    }
}
</pre>
</div></div>

<p>In this case Spring will use a JDK proxy to wrap a BookStoreWithInterface class.
As such it is important that a method which needs to be invoked such as getThatBook(...) is
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>
</pre>
</div></div>


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

<p>Distributed OSGi RI is a CXF <a href="http://cxf.apache.org/distributed-osgi.html"
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 <a href="http://cxf.apache.org/distributed-osgi-reference.html#DistributedOSGiReference-ServiceProviderproperties"
class="external-link" rel="nofollow">DOSGI Reference page</a> ('org.apache.cxf.rs'
properties) and a <a href="http://svn.apache.org/repos/asf/cxf/dosgi/trunk/samples/greeter_rest/"
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="http://cxf.apache.org/distributed-osgi-greeter-demo-walkthrough.html"
class="external-link" rel="nofollow">greeter</a> demo as it registers and consumes
a similar (but) JAX-RS annotated <a 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"
class="external-link" rel="nofollow">GreeterService</a>. In addition, this demo shows
how one can register and consume a given interface (<a 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"
class="external-link" rel="nofollow">GreeterService2</a>) without using explicit
JAX-RS annotations but providing an out-of-band <a href="http://svn.apache.org/repos/asf/cxf/dosgi/trunk/samples/greeter_rest/interface/src/main/resources/OSGI-INF/cxf/jaxrs/GreeterService2-model.xml"
class="external-link" rel="nofollow">user model description</a>.</p>

<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 this <a href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?reset=true&amp;mode=hide&amp;pid=12310511&amp;sorter/order=DESC&amp;sorter/field=priority&amp;resolution=-1&amp;component=12311911"
class="external-link" rel="nofollow">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>
<ul>
	<li>do the fast trunk build using 'mvn install -Pfastinstall'</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/>
&gt; mvn install </p>

    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/CXF20DOC/JAX-RS">View Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=70366&revisedVersion=202&originalVersion=201">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/CXF20DOC/JAX-RS?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message