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 15:35: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 (27)</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" >Please see the [JAX-RS Client API] page for more information. <br> <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h1. Support for Multiparts <br> <br>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.  <br> <br>Please see the [JAX-RS Multiparts] page for more information.  <br> <br> <br>h1. XPath and XSLT <br> <br>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>h2. XPath support <br> <br>XPath is supported on the server and client sides with the help of [XMLSource|http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/xml/XMLSource.java] utility class. Please see above how http-centric WebClients can use XPath, here is an example for the server side : <br> <br>{code:java} <br>@Path(&quot;/root&quot;) <br>public class Root { <br>   @POST <br>   public void post(XMLSource source) { <br>       String value = source.getProperty(&quot;/books/book/@name&quot;); <br>   }     <br>} <br>{code}  <br> <br>Users have an option to hide XPath expressions, by registering an [XPathProvider|http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/provider/XPathProvider.java], either on client or server sides. For example : <br> <br>{code:java} <br>XPathProvider provider = new XPathProvider(); <br>provider.setGlobalExpression(&quot;/books/book[position() = 1]&quot;); <br>WebClient wc = WebClient.create(&quot;http://aggregated/data&quot;, Collections.singletonList(provider)); <br>Book b = wc.get(Book.class); <br>{code} <br> <br>h2. XSLT support <br> <br>XSLT is currently supported by [XSLTJaxbProvider|http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/provider/XSLTJaxbProvider.java]. 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. <br> <br>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 &quot;application/xml&quot; formats only while the other one handles &quot;application/json&quot; writes only. <br> <br>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. <br> <br>For example, given this resource method definition : <br> <br>{code:java} <br>@Path(&quot;/root&quot;) <br>public class Root { <br>   @GET <br>   @Path(&quot;{id}&quot;)  <br>   public Book get(@PathParam(&quot;id&quot;) String id, @QueryParam(&quot;name&quot;) String name) { <br>       return getBook(id, name); <br>   }     <br>} <br>{code} <br> <br>an XSLT template processing the JAXB-driven serialization of a Book instance will have parameters with name &#39;id&#39; and &#39;name&#39; injected. <br> <br>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 : <br> <br>{code:java} <br>WebClient client = WebClient.create(&quot;http://books&quot;); <br>client.path(&quot;/store/1&quot;).get(); <br>{code} <br> <br>it is not possible to deduce that &#39;1&#39; represents a template parameter in the &quot;/store/1&quot; expression. However, one can use the following code instead if &#39;1&#39; needs to be available to XSLT templates : <br> <br>{code:java} <br>WebClient client = WebClient.create(&quot;http://books&quot;); <br>client.path(&quot;/store/{id}&quot;, 1).get(); <br>{code} <br> <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h1. Support for Complex Search Queries <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >h2. Checking HTTP security headers <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >It is often containers like Tomcat or frameworks like Spring Security which deal with ensuring a current user is authenticated. <span class="diff-added-words"style="background-color: #dfd;">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) :</span> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">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 <br>which will extract a user name and password like this (note it will work only for basic authentication requests only) : <br></td></tr>
            <tr><td class="diff-unchanged" > <br>{code:java} <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >        // HttpHeaders headers = new HttpHeadersImpl(m); <br>        // access the headers as needed   <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;"> <br>        // authenticate the user <br> <br></td></tr>
            <tr><td class="diff-unchanged" >        return null; <br>    } <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >{code} <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h1. XPath and XSLT <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;">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></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h1. Redirection <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;">h2. XPath support <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">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.  <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;">XPath is supported on the server and client sides with the help of [XMLSource|http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/xml/XMLSource.java] utility class. Please see above how http-centric WebClients can use XPath, here is an example for the server side : <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">Please see the [JAX-RS Redirection] page for more information. <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;">{code:java} <br>@Path(&quot;/root&quot;) <br>public class Root { <br>   @POST <br>   public void post(XMLSource source) { <br>       String value = source.getProperty(&quot;/books/book/@name&quot;); <br>   }     <br>} <br>{code}  <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;">Users have an option to hide XPath expressions, by registering an [XPathProvider|http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/provider/XPathProvider.java], either on client or server sides. For example : <br> <br>{code:java} <br>XPathProvider provider = new XPathProvider(); <br>provider.setGlobalExpression(&quot;/books/book[position() = 1]&quot;); <br>WebClient wc = WebClient.create(&quot;http://aggregated/data&quot;, Collections.singletonList(provider)); <br>Book b = wc.get(Book.class); <br>{code} <br> <br>h2. XSLT support <br> <br>XSLT is currently supported by [XSLTJaxbProvider|http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/provider/XSLTJaxbProvider.java]. 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. <br> <br>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 &quot;application/xml&quot; formats only while the other one handles &quot;application/json&quot; writes only. <br> <br>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. <br> <br>For example, given this resource method definition : <br> <br>{code:java} <br>@Path(&quot;/root&quot;) <br>public class Root { <br>   @GET <br>   @Path(&quot;{id}&quot;)  <br>   public Book get(@PathParam(&quot;id&quot;) String id, @QueryParam(&quot;name&quot;) String name) { <br>       return getBook(id, name); <br>   }     <br>} <br>{code} <br> <br>an XSLT template processing the JAXB-driven serialization of a Book instance will have parameters with name &#39;id&#39; and &#39;name&#39; injected. <br> <br>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 : <br> <br>{code:java} <br>WebClient client = WebClient.create(&quot;http://books&quot;); <br>client.path(&quot;/store/1&quot;).get(); <br>{code} <br> <br>it is not possible to deduce that &#39;1&#39; represents a template parameter in the &quot;/store/1&quot; expression. However, one can use the following code instead if &#39;1&#39; needs to be available to XSLT templates : <br> <br>{code:java} <br>WebClient client = WebClient.create(&quot;http://books&quot;); <br>client.path(&quot;/store/{id}&quot;, 1).get(); <br>{code} <br> <br>h1. Redirection <br> <br>CXF 2.2.5 supports redirecting to other servlet resources for a given request and/or response be completed.  <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h2. With RequestDispatcherProvider <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >h1. Model-View-Controller support <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h2. XSLT <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">*XSLT* <br></td></tr>
            <tr><td class="diff-unchanged" >Please see [this blog entry|http://sberyozkin.blogspot.com/2009/05/mvc-xml-way-with-cxf-jax-rs.html] on how XSLTJaxbProvider can be used to generate complex (X)HTML views. <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h2. JSP <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">*JSP* <br></td></tr>
            <tr><td class="diff-unchanged" > <br>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 [beans.xml|http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/resources/jaxrs_dispatch/WEB-INF/beans.xml].  <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >- &quot;absolute.path&quot;, &quot;base.path&quot; and &quot;relative.path&quot; obtained from the current UriInfo   <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h1. Support for Multiparts <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h1. Service listings and WADL support <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;">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.  <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">CXF JAX-RS supports [WADL|http://www.w3.org/Submission/wadl]. CXF JAX-RS service endpoints can be listed in the service listings page and users can check the WADL documents.   <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" >Please see the <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">[JAX-RS Multiparts]</span> <span class="diff-added-words"style="background-color: #dfd;">[JAXRS Services Description]</span> page for more information. <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;">h1. Service listings and WADL support <br> <br></td></tr>
            <tr><td class="diff-unchanged" >CXF JAX-RS now supports the auto-generation of [WADL|http://www.w3.org/Submission/wadl] for JAX-RS endpoints.  <br>Note that JAX-RS subresources are supposed to be late-resolved, so using annotated interfaces for subresources and a staticSubresourceResolution=true property will let the whole resource tree/graph be described in a generated instance. Schemas will be generated for JAXB-annotated types. <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >If no JAXB is used then you can attach an [XmlName|http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/xml/XMLName.java] annotation to method input or output types. Alternatively, you can register an instance of [ElementQNameResolver|http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/wadl/ElementQNameResolver.java] with the WADLGenerator which will be used for creating wadl:representation/@element values. <br> <br></td></tr>
            <tr><td class="diff-changed-lines" ><span class="diff-changed-words">h<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">1</span><span class="diff-added-chars"style="background-color: #dfd;">2</span>.</span> Hiding links to JAXRS endpoints from the services page <br></td></tr>
            <tr><td class="diff-unchanged" > <br>In some cases you may not want the users to see the links to some of your JAXRS endpoints. For example, if you have an AtomPullServer endpoint collecting the log entries for a number of application endpoints, you may not want to the AtomPullServer endpoint being listed among the endpoints which the users are actually interested in. If so then adding an &quot;org.apache.cxf.endpoint.private&quot; boolean property with the value &quot;true&quot; will do the trick; note the same property can be used by jaxws endpoints. <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h1. Code Generation <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h2. Generating the client code from WADL <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;">h2. Generating the client code at runtime <br> <br></td></tr>
            <tr><td class="diff-unchanged" >If you register an org.apache.cxf.jaxrs.ext.codegen.CodeGeneratorProvider with a jaxrs endpoint and issue a &#39;_code&#39; query to it then you will get back an XHTML page containing the link to a zipped client source code which you can download and start customizing.  <br> <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>
<ul>
    <li><a href='#JAX-RS-WithRequestDispatcherProvider'>With RequestDispatcherProvider</a></li>
    <li><a href='#JAX-RS-WithCXFServlet'>With CXFServlet</a></li>
    <li><a href='#JAX-RS-CustomRedirection'>Custom Redirection</a></li>
</ul>
    <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>
<ul>
    <li><a href='#JAX-RS-DocumentingresourceclassesandmethodsinWADL'>Documenting resource classes and methods in WADL</a></li>
    <li><a href='#JAX-RS-CustomWADLproviders'>Custom WADL providers</a></li>
<ul>
    <li><a href='#JAX-RS-RepresentingexternalschemasandnonJAXBtypes'>Representing external schemas and non JAXB types</a></li>
</ul>
    <li><a href='#JAX-RS-HidinglinkstoJAXRSendpointsfromtheservicespage'>Hiding links to JAXRS endpoints from the services page</a></li>
    <li><a href='#JAX-RS-GeneratingtheclientcodefromWADL'>Generating the client code from WADL</a></li>
</ul>
    <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>
<ul>
    <li><a href='#JAX-RS-Dealingwithcontexts'>Dealing with contexts</a></li>
</ul>
    <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>

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


<h2><a name="JAX-RS-WithRequestDispatcherProvider"></a>With RequestDispatcherProvider</h2>

<p><a href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/provider/RequestDispatcherProvider.java" class="external-link" rel="nofollow">RequestDispatcherProvider</a> is a JAXRS MessageBodyWriter which can redirect to JSP pages, named or default servlets. It can be used to serve all the responses from a given resource class or restricted to serving a limited set of classes only using a classResources map property. Note that this classResources property can also be used to specify the name of the key which JSP pages or other downstream servlets will use to access a response object.</p>

<p>At the moment, this provider is statically configured to support text/html content types, but it can be easily configured to support other content types if needed.  </p>

<p>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>. As you can see, it is possible to redirect to either to static resources such as book.html (possibly for providing some default response) or dynamic resources such as JSP pages. It is also possible to redirect to named servlets. </p>

<p>Note that the only required property is a 'requestPath' one and its value should start with a forward slash but it does not have to point to an existing web application resource such as book.html; it can also have values like "/other/services/", possibly in a combination with a 'dispatcherName' property.</p>

<p>Finally, a servletContextPath property can be used to have some other ServletContext (as opposed to the current one) be used for RequestDispatcher look-ups. If set then the current ServletContext.getContext(servletContextPath) will be used to get the needed ServletContext.</p>



<h2><a name="JAX-RS-WithCXFServlet"></a>With CXFServlet</h2>

<p>Please see the "Redirection" section on the <a href="http://cwiki.apache.org/confluence/display/CXF20DOC/Servlet+Transport" class="external-link" rel="nofollow">Servlet Transport</a> page.</p>

<p>Note that both CXFServlet and JAXRS RequestDispatcher provider can work together effectively on executing the redirection requests as described at that page.</p>

<p>If you have CXFServlet listening on "/" (thus effectively catching all the requests) and also would like to use RequestDispatcher, then make sure that a 'dispatcherName' property is also set, for example :</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;bean id=<span class="code-quote">"dispatchProvider"</span> class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.RequestDispatcherProvider"</span>&gt;</span>
    <span class="code-tag">&lt;property name=<span class="code-quote">"dispatcherName"</span> value=<span class="code-quote">"jsp"</span>/&gt;</span>
    <span class="code-tag">&lt;property name=<span class="code-quote">"resourcePath"</span> value=<span class="code-quote">"/WEB-INF/jsp/test.jsp"</span>/&gt;</span>
    <span class="code-tag">&lt;property name=<span class="code-quote">"scope"</span> value=<span class="code-quote">"request"</span>/&gt;</span>
<span class="code-tag">&lt;/bean&gt;</span> 
</pre>
</div></div>

<p>If resources which are redirected to can be made public (i.e, moved out of /WEB-INF) then alternative option (instead of adding a 'dispatcherName' property to RequestDispatcherProvider and still have CXFServlet listening on '/') is to configure both RequestDispatcherProvider and CXFServlet to redirect to resources such as "/jsp/test.jsp".</p>

<h2><a name="JAX-RS-CustomRedirection"></a>Custom Redirection</h2>

<p>One can borrow some of the code from RequestDispatcherProvider and do the custom redirection from CXF in interceptors or custom invokers, if you will try to do it then you will also need to set an AbstractHTTPDestination.REQUEST_REDIRECTED property with a 'true' value on a current input message.</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/pages/createpage.action?spaceKey=CXF20DOC&amp;title=JAXRS+Services+Description&amp;linkCreation=true&amp;fromPageId=70366" class="createlink">JAXRS Services Description</a> page for more information.</p>

<p>CXF JAX-RS now supports the auto-generation of <a href="http://www.w3.org/Submission/wadl" class="external-link" rel="nofollow">WADL</a> for JAX-RS endpoints. <br/>
Note that JAX-RS subresources are supposed to be late-resolved, so using annotated interfaces for subresources and a staticSubresourceResolution=true property will let the whole resource tree/graph be described in a generated instance. Schemas will be generated for JAXB-annotated types.</p>

<p>WADL instances for RESTful endpoints are available from {base endpointaddress}/services, in addition to SOAP endpoints if any. Note that you can override the location at which listings are provided (in case you would like '/services' be available to your resources) using<br/>
'service-list-path' servlet parameter, ex :</p>

<p>&gt; 'service-list-path' = '/listings'</p>

<p>Going to the service listings page is not the only way to see the wadl instances, generally one can get it using a ?_wadl query.</p>

<p>For example, given</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
Base address : 'http://localhost:8080'
WAR name : 'store'
CXFServlet : '/books/*'
jaxrs:server/@address = '/orders'
jaxrs:server/@staticSubresourceResoulution = 'true'
</pre>
</div></div>

<p>and 2 root resource classes registered with this endpoint, say</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
@Path(<span class="code-quote">"/fiction"</span>) 
<span class="code-keyword">public</span> class FictionBookOrders {
}
@Path(<span class="code-quote">"/sport"</span>) 
<span class="code-keyword">public</span> class SportBookOrders {
}
</pre>
</div></div>

<p>then</p>

<p>&gt; <a href="http://localhost:8080/store/books/orders?_wadl" class="external-link" rel="nofollow">http://localhost:8080/store/books/orders?_wadl</a></p>

<p>will give you the description of all the root resource classes registered<br/>
with a given jaxrs:server endpoint, including all the subresources. While</p>

<p>&gt; <a href="http://localhost:8080/store/books/orders/fiction?_wadl" class="external-link" rel="nofollow">http://localhost:8080/store/books/orders/fiction?_wadl</a><br/>
&gt; <a href="http://localhost:8080/store/books/orders/sport?_wadl" class="external-link" rel="nofollow">http://localhost:8080/store/books/orders/sport?_wadl</a></p>

<p>will give you all the info for FictionBookOrders and SportBookOrders respectively.</p>

<p>If you have many jaxrs:endpoints then visiting</p>

<p>&gt; <a href="http://localhost:8080/store/books" class="external-link" rel="nofollow">http://localhost:8080/store/books</a> <br/>
&gt; <a href="http://localhost:8080/store/books/services" class="external-link" rel="nofollow">http://localhost:8080/store/books/services</a> </p>

<p>will let you see all the WADL links.</p>

<p>Note that the media type for a ?_wadl response is set to 'application/vnd.sun.wadl+xml' which is something Firefox does not really<br/>
like unless some wadl plugin is registered. If an HTTP Accept header is set to 'application/xml' then Firefox will show it with no problems. Doing<br/>
'?_wadl&amp;_type=xml' will ensure a WADL generator will see Accept being set set to 'application/xml'.</p>

<h2><a name="JAX-RS-DocumentingresourceclassesandmethodsinWADL"></a>Documenting resource classes and methods in WADL</h2>

<p>WADL documents can include <a href="http://www.w3.org/Submission/wadl/#x3-80002.3" class="external-link" rel="nofollow">doc</a> fragments. Users may want to use <a href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/Description.java" class="external-link" rel="nofollow">Description</a> annotations which can be attached to resource classes and methods.</p>

<h2><a name="JAX-RS-CustomWADLproviders"></a>Custom WADL providers</h2>

<p>One can register a custom WADLGenerator as a jaxrs:provider. The custom generator can extend the default <br/>
org.apache.cxf.jaxrs.model.wadl.WADLGenerator or register a default one with one of the following properties set.</p>

<ul class="alternate" type="square">
	<li>wadlNamespace : default is "http://wadl.dev.java.net/2009/02", the earlier one is "http://research.sun.com/wadl/2006/10".</li>
	<li>singleResourceMultipleMethods : default is 'true', for example, if a resource class has multiple methods supported at the same path such as "/" (GET, POST, etc) then WADL will list them all as the child nodes of a single resource element.</li>
	<li>useSingleSlashResource : default is false, for example, if you have a root resource class with a path "root" and a resource method with a path "" or "/" then a WADL resource representing the root will not have a child resource representing this resource method (it would do if a resource method had a more specific path such as "bar").</li>
</ul>


<h3><a name="JAX-RS-RepresentingexternalschemasandnonJAXBtypes"></a>Representing external schemas and non JAXB types</h3>

<p>By default, the WADL grammar section will be properly generated if resource methods accept or return JAXB types. </p>

<p>Even when you do use JAXB, the JAXB types may have been generated from the external schema so having WADLGenerator attempting to recreate the original schema may not work well. To have a generated WADL referencing the original schema(s) please set a 'schemaLocations' list property (programmatically or from Spring) :</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
WadlGenerator wg = <span class="code-keyword">new</span> WadlGenerator();
wg.setSchemaLocations(Collections.singletonList(<span class="code-quote">"classpath:/book.xsd"</span>));
</pre>
</div></div> 

<p>In this case the grammar section will have the 'book.xsd' schema inlined. If this schema imports other schemas then the imports with relative URIs will be replaced by the absolute URIs based on the current endpoint's base address. For example, if the endpoint address is "http://somehost/bar" and the 'book.xsd' imports "foo/book1.xsd" then the published WADL will contain an "http://somehost/bar/foo/book1.xsd". At the moment a custom RequestHandler filter will have to be registered to serve resources such as "http://somehost/bar/foo/book1.xsd" which can 'calculate' which resource is required get the absolute request URI and comparing it with the base URI, possibly with the help of the injected JAXRS UriInfo context. Alternatively, resources such as book1.xsd may be served by CXFServlet itself (see the Redirection with CXFServlet)  </p>

<p>TODO : add ignoreImports flag so that users can list root and imported schemas in "schemaLocations" and have them all inlined.</p>

<p>Note that the root schema such as "book.xsd" is inlined - you can have it referenced only by setting an 'externalLinks' list property. This will very well when the "book.xsd" is indeed available at some external URI, but this property can be used to avoid the local schemas being inlined. Moreover, using JAXB will not be required. The result will look like this :</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;wadl:grammars&gt;</span>
<span class="code-tag">&lt;wadl:include href=<span class="code-quote">"http://books.xsd"</span>/&gt;</span>
<span class="code-tag">&lt;/wadl:grammars&gt;</span>
</pre>
</div></div> 

<p>Note that "schemaLocations" and "externalLinks" properties differ in that the schemas referenced by the former one are inlined.</p>

<p>You can also customize the way schema elements are referenced. When WADLGenerator creates WADL representation elements (representing resource method input or output types) it will be able to link to schema elements provided a given type is actually a JAXB one, so the result may look like this :</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
&lt;!-- 
  thebook2 element is declared in a schema inlined in or referenced from the grammar section
  prefix1 is bound to that schema's target namespace and is declared at the wadl:application element 
--&gt;
<span class="code-tag">&lt;representation mediaType=<span class="code-quote">"application/xml"</span> element=<span class="code-quote">"prefix1:thebook2"</span>/&gt;</span>
</pre>
</div></div>

<p>If no JAXB is used then you can attach an <a href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/xml/XMLName.java" class="external-link" rel="nofollow">XmlName</a> annotation to method input or output types. Alternatively, you can register an instance of <a href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/wadl/ElementQNameResolver.java" class="external-link" rel="nofollow">ElementQNameResolver</a> with the WADLGenerator which will be used for creating wadl:representation/@element values.</p>

<h2><a name="JAX-RS-HidinglinkstoJAXRSendpointsfromtheservicespage"></a>Hiding links to JAXRS endpoints from the services page </h2>

<p>In some cases you may not want the users to see the links to some of your JAXRS endpoints. For example, if you have an AtomPullServer endpoint collecting the log entries for a number of application endpoints, you may not want to the AtomPullServer endpoint being listed among the endpoints which the users are actually interested in. If so then adding an "org.apache.cxf.endpoint.private" boolean property with the value "true" will do the trick; note the same property can be used by jaxws endpoints.</p>

<h2><a name="JAX-RS-GeneratingtheclientcodefromWADL"></a>Generating the client code from WADL</h2>

<p>If you register an org.apache.cxf.jaxrs.ext.codegen.CodeGeneratorProvider with a jaxrs endpoint and issue a '_code' query to it then you will get back an XHTML page containing the link to a zipped client source code which you can download and start customizing. </p>

<p>Internally, before the code gets generated, WADL will be generated first. The archive will include JAXB generated classes from a WADL grammar section plus the proxy based client code for accessing root and sub resources. The WebClient based code can not be generated just yet but one can request that only a WADL grammar section is processed by adding a '_codeType=grammar' query and easily adding a WebClient-based code. </p>

<p>Here is how to get the archive programmatically :</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
WebClient wc = WebClient.create(<span class="code-quote">"http:<span class="code-comment">//localhost:9080/petstore"</span>);
</span>XMLSource source = wc.query(<span class="code-quote">"_code"</span>).query(<span class="code-quote">"_os"</span>, getOs()).get(XMLSource.class);
<span class="code-object">String</span> link = source.getValue(<span class="code-quote">"ns:html/ns:body/ns:ul/ns:a/@href"</span>,  
              Collections.singletonMap(<span class="code-quote">"ns"</span>,<span class="code-quote">"http:<span class="code-comment">//www.w3.org/1999/xhtml"</span>));
</span><span class="code-comment">// download a zip file          
</span>WebClient wcZip = WebClient.create(link);
InputStream is = wcZip.accept(<span class="code-quote">"application/zip"</span>).get(InputStream.class);
<span class="code-comment">// unzip and compile it</span>
</pre>
</div></div>

<p>Please see a <a href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/JAXRSClientServerResourceCreatedSpringProviderTest.java" class="external-link" rel="nofollow">testPetStore</a> test for more details.</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>Here's a beans.xml showing how to have a single service class supporting both SOAP and REST-based invocations at the same time with the help of JAX-WS and JAX-RS : </p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;?xml version=<span class="code-quote">"1.0"</span> encoding=<span class="code-quote">"UTF-8"</span>?&gt;</span>
&lt;beans xmlns=<span class="code-quote">"http://www.springframework.org/schema/beans"</span>
  <span class="code-keyword">xmlns:xsi</span>=<span class="code-quote">"http://www.w3.org/2001/XMLSchema-instance"</span>
  <span class="code-keyword">xmlns:jaxrs</span>=<span class="code-quote">"http://cxf.apache.org/jaxrs"</span>
  <span class="code-keyword">xmlns:jaxws</span>=<span class="code-quote">"http://cxf.apache.org/jaxws"</span>
  xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://cxf.apache.org/jaxrs
http://cxf.apache.org/schemas/jaxrs.xsd
http://cxf.apache.org/jaxws
http://cxf.apache.org/schemas/jaxws.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"><span class="code-comment">&lt;!-- JAX-RS --&gt;</span></span>
  <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;ref bean=<span class="code-quote">"customerService"</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"><span class="code-comment">&lt;!-- JAX-WS --&gt;</span></span>
  &lt;jaxws:endpoint implementor=<span class="code-quote">"#customerService"</span>
    address=<span class="code-quote">"/CustomerWorld"</span> wsdlLocation=<span class="code-quote">"..."</span>/&gt;
  
  <span class="code-tag">&lt;bean id=<span class="code-quote">"customerService"</span> class=<span class="code-quote">"demo.jaxrs.server.CustomerService"</span> /&gt;</span>
<span class="code-tag">&lt;/beans&gt;</span>
</pre>
</div></div>

<p>Either contract-first or Java-first approach can be used for JAX-WS. JAX-RS annotations can be added to the existing service class. Some custom providers may need to be created, depending on the complexity of the method signatures.</p>

<p>When a WSDL-first approach is used then a document-literal-wrapped style may or may not be a good fit as the code generator unwraps all the types into a signature, for example :</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> class CustomerService {
   <span class="code-keyword">public</span> void doIt(<span class="code-object">String</span> a, <span class="code-object">String</span> b) {...};
}
</pre>
</div></div>  

<p>By default JAX-RS may not be able to handle such methods as it requires that only a single parameter can be available in a signature that is not annotated by one of the JAX-RS annotations like @PathParam. So if <br/>
a 'String a' parameter can be mapped to a @Path template variable or one of the query segments then this signature won't need to be changed :</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
@Path(<span class="code-quote">"/customers/{a}"</span>)
<span class="code-keyword">public</span> class CustomerService {
   <span class="code-keyword">public</span> void doIt(@PathParam(<span class="code-quote">"a"</span>) <span class="code-object">String</span> a, <span class="code-object">String</span> b) {...};
}
</pre>
</div></div>  

<p>Note that CXF Continuations API is supported for both JAXWS and JAXRS services.</p>

<h2><a name="JAX-RS-Dealingwithcontexts"></a>Dealing with contexts</h2>

<p>When combining JAXWS and JAXRS, one may need to access some context information as part of processing a given request. At the moment, CXF JAXRS does not offer a context implementation which can be used to access a request-specific information common for both JAXWS and JAXRS requests, in cases when the same methods are used to handle both JAXWS and JAXRS requests. Please use a JAXWS WebServiceContext and JAXRS contexts or CXF JAXRS composite MessageContext :</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
@Path(<span class="code-quote">"/customers"</span>)
@WebService
<span class="code-keyword">public</span> class CustomerService {

   @Resource WebServiceContext jaxwsContext;
   @Resource MessageContext jaxrsContext;

   @WebMethod
   @POST
   <span class="code-keyword">public</span> void doIt(<span class="code-object">String</span> b) {
       isUserInRole();
   };

   <span class="code-keyword">private</span> void isUserInRole() <span class="code-keyword">throws</span> WebApplicationException {
       <span class="code-keyword">if</span> (jaxwsContext.getSecurityContext() != <span class="code-keyword">null</span>) {
           <span class="code-comment">// soap invocation
</span>           jaxwsContext.getSecurityContext().isUserInRole(theRole);
       } <span class="code-keyword">else</span> {
           <span class="code-comment">// http-only jaxrs one
</span>           jaxrsContext.getSecurityContext().isUserInRole(theRole);
       }  
   }
}
</pre>
</div></div>  

<p>Note that injected context instances (jaxwsContext and jaxrsContext) are in fact thread-local proxies hence they will not be equal to null even if they do not represent a given request. For example, jaxrsContext will not be equal to null even if it's not a JAXWS invocation which is being processed at the moment.</p>

<p>However, if say a (JAXWS or JAXRS) SecurityContext needs to be accessed then it will be set in, say, jaxwsContext only if it's a JAXWS/SOAP invocation. For this reason it can be handy using a composite CXF JAXRS MessageContext when accessing a JAXRS-specific context information when combining JAXWS and JAXRS as one can easily check if it's actually a JAXRS request by simply checking an individual context like SecurityContext or UriInfo for null.</p>

<p>Using individual contexts like JAXRS SecurityContext might be less attractive :</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
@WebService
<span class="code-keyword">public</span> class CustomerService {
   @Resource WebServiceContext jaxwsContext;
   <span class="code-comment">// @Resource can be applied too
</span>   @Context SecurityContext jaxrsSecurityContext;  
}
</pre>
</div></div>

<p>as some methods of SecurityContext return boolean values so only throwing a runtime exception can reliably indicate that this context is actually not in scope.</p>

<p>Note that if you do not share the same service methods between JAXRS and JAXWS invocations then you can directly access corresponding contexts : </p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
@Path(<span class="code-quote">"/customers"</span>)
@WebService
<span class="code-keyword">public</span> class CustomerService {

   @Resource WebServiceContext jaxwsContext;
   @Resource MessageContext jaxrsContext;

   @WebMethod
   <span class="code-keyword">public</span> void doItSoap(<span class="code-object">String</span> b) {
       isUserInRole(jaxwsContext.getSecurityContext().getPrincipal());
   };

   @POST
   <span class="code-keyword">public</span> void doItSoap(<span class="code-object">String</span> b) {
       isUserInRole(jaxwsContext.getSecurityContext().getPrincipal());
   }

   <span class="code-keyword">private</span> void isUserInRole(Principal p) <span class="code-keyword">throws</span> WebApplicationException {
       ...  
   }
}
</pre>
</div></div>

<p>Another option is to avoid the use of contexts in the service code and deal with them in CXF interceptors or JAXRS filters. Sometimes it's possible to avoid the use of contexts altogether. For example, Spring Security can be used to secure a given service at an individual method level.     </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=197&originalVersion=196">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