Author: buildbot Date: Sun Jan 4 10:47:19 2015 New Revision: 935000 Log: Production update by buildbot for cxf
Modified: websites/production/cxf/content/cache/docs.pageCache websites/production/cxf/content/docs/jax-rs.html Modified: websites/production/cxf/content/cache/docs.pageCache ============================================================================== Binary files - no diff available. Modified: websites/production/cxf/content/docs/jax-rs.html ============================================================================== --- websites/production/cxf/content/docs/jax-rs.html (original) +++ websites/production/cxf/content/docs/jax-rs.html Sun Jan 4 10:47:19 2015 @@ -118,11 +118,11 @@ Apache CXF -- JAX-RS <!-- Content --> <div class="wiki-content"> <div id="ConfluenceContent"><p> </p><p> <span class="inline-first-p" style="font-size:2em;font-weight:bold">JAX-RS (JSR-339)</span> </p><p> </p><p><style type="text/css">/*<![CDATA[*/ -div.rbtoc1419015878673 {padding: 0px;} -div.rbtoc1419015878673 ul {list-style: disc;margin-left: 0px;} -div.rbtoc1419015878673 li {margin-left: 0px;padding-left: 0px;} +div.rbtoc1420368412341 {padding: 0px;} +div.rbtoc1420368412341 ul {list-style: disc;margin-left: 0px;} +div.rbtoc1420368412341 li {margin-left: 0px;padding-left: 0px;} -/*]]>*/</style></p><div class="toc-macro rbtoc1419015878673"> +/*]]>*/</style></p><div class="toc-macro rbtoc1420368412341"> <ul class="toc-indentation"><li><a shape="rect" href="#JAX-RS-Introduction">Introduction</a></li><li><a shape="rect" href="#JAX-RS-JAX-RSCompliance">JAX-RS Compliance</a> <ul class="toc-indentation"><li><a shape="rect" href="#JAX-RS-1.1">1.1</a></li><li><a shape="rect" href="#JAX-RS-2.0Final">2.0 Final</a></li></ul> </li><li><a shape="rect" href="#JAX-RS-Projectsetupandconfiguration">Project setup and configuration</a> @@ -237,7 +237,7 @@ public void upload(@Multipart InputStrea </dependency> ]]></script> -</div></div><h1 id="JAX-RS-WhatisNew">What is New</h1><ul><li>Complete support for JAX-RS 2.0, please see <a shape="rect" href="jax-rs-basics.html">JAX-RS Basics</a> for more information</li><li>Bean Validation 1.1 Support, please see <a shape="rect" href="http://cxf.apache.org/docs/validationfeature.html">http://cxf.apache.org/docs/validationfeature.html</a> for more information</li><li>Swagger Feature</li></ul><h1 id="JAX-RS-GettingStartedwithJAX-RS">Getting Started with JAX-RS</h1><h2 id="JAX-RS-UnderstandingtheBasics">Understanding the Basics</h2><p>You are encouraged to read <a shape="rect" class="external-link" href="http://jcp.org/en/jsr/detail?id=339" rel="nofollow">JSR-339</a> specification to find out information not covered by this documentation. The specification introduces many terms such as root resources, resource methods, sub-resources and sub-resource locators, message body readers and writers. JAX-RS 2.0 additionally introduces filters, interceptors, new client API , features, new exception classes, server-side support for asynchronous invocations.</p><p>Please see the <a shape="rect" href="jax-rs-basics.html">JAX-RS Basics</a> page for more information.</p><h2 id="JAX-RS-SupportforDataBindings">Support for Data Bindings</h2><p>JAX-RS MessageBodyReader and MessageBodyWriter can be used to create data bindings for reading and writing data in a number of different formats. Compliant JAX-RS implementations are expected to support JAXB-annotated beans, JAXP Source objects, InputStreams, etc.</p><p>In addition, CXF JAX-RS lets users reuse existing CXF DataBindings for working with JAXB, XBeans, Aegis and SDO.</p><p>Please see the <a shape="rect" href="jax-rs-data-bindings.html">JAX-RS Data Bindings</a> page for more information.</p><h2 id="JAX-RS-HowRequestURIisMatched">How Request URI is Matched</h2><p>Lets assume you have a web application called 'rest'. CXFServlet's url-pattern is "/test/*". Finally, jaxrs:server's address is "/bar".</p><p>Reque sts like /rest/test/bar or /rest/test/bar/baz will be delivered to one of the resource classes in a given jaxrs:server endpoint. For the former request to be handled, a resource class with @Path("/") should be available, in the latter case - at least @Path("/") or a more specific @Path("/baz").</p><p>The same requirement can be expressed by having a CXFServlet with "/*" and jaxrs:server with "/test/bar".</p><p>When both CXFServlet and jaxrs:server use "/" then it's a root resource class which should provide a @Path with at least "/test/bar" for the above requests to be matched.</p><p>Generally, it can be a good idea to specify the URI segments which are more likely to change now and then with CXFServlets or jaxrs:server.</p><h2 id="JAX-RS-ClientAPI">Client API</h2><p>CXF 3.0.0 implements JAX-RS 2.0 Client API.</p><p>CXF 2.7.x or earlier provides a comprehensive support for developing RESTful clients by supporting 3 flavors of the client API: proxy-based, HTTP-centric and XML-centric . CXF-specific client API is supported alongside new JAX-RS 2.0 Client API in CXF 3.0.0.</p><p>Please see the <a shape="rect" href="jax-rs-client-api.html">JAX-RS Client API</a> page for more information.</p><h2 id="JAX-RS-BeanValidation">Bean Validation</h2><p>Bean Validation 1.1 is supported since CXF 3.0.0-milestone1. Please see the <a shape="rect" href="http://cxf.apache.org/docs/validationfeature.html">http://cxf.apache.org/docs/validationfeature.html</a> for more information.</p><h2 id="JAX-RS-Filters,InterceptorsandInvokers">Filters, Interceptors and Invokers</h2><p>It is possible to intercept and modify the inbound and outbound calls with the help of CXF JAX-RS filters and/or CXF interceptors. Additionally, custom invokers offer an option to intercept a call immediately before a service bean is invoked.</p><p>Please see the <a shape="rect" href="jax-rs-filters.html">JAX-RS Filters</a> page for more information.</p><p>Please see the <a shape="rect" href="jax-rs-basics.html">J AX-RS Basics</a> page for more information about new JAX-RS 2.0 filters and interceptors available in CXF 2.7.x and 3.0.0.</p><h2 id="JAX-RS-ServicelistingsandWADLsupport">Service listings and WADL support</h2><p><strong>New</strong>: Swagger feature has been introduced.</p><p>CXF JAX-RS supports <a shape="rect" class="external-link" href="http://www.w3.org/Submission/wadl" rel="nofollow">WADL</a>. CXF JAX-RS service endpoints can be listed in the service listings page and users can check the WADL documents.</p><p>Please see the <a shape="rect" href="jaxrs-services-description.html">JAXRS Services Description</a> page for more information.</p><h2 id="JAX-RS-ConfiguringJAX-RSservices">Configuring JAX-RS services</h2><p>JAX-RS services can be configured programmatically, using Blueprint, Spring or CXFNonSpringJAXRSServlet.</p><p>Please see the <a shape="rect" href="jaxrs-services-configuration.html">JAXRS Services Configuration</a> page for more information.</p><h2 id="JAX-RS-Testing" >Testing</h2><p>JAX-RS services can be easily tested using the embedded Jetty >or CXF Local Transport.<br clear="none"> Please see the <a shape="rect" >href="https://cwiki.apache.org/confluence/display/CXF20DOC/JAXRS+Testing">JAXRS > Testing</a> page for more information.</p><h2 >id="JAX-RS-Debugging">Debugging</h2><p>One may want to use a browser to test >how a given HTTP resource reacts to different HTTP Accept or Accept-Language >header values and request methods. For example, if a resource class supports >a "/resource" URI then one can test the resource class using one of the >following queries :</p><p><code>> GET /resource.xml</code> <br >clear="none"> <code>> GET /resource.en</code></p><p>The runtime will >replace '.xml' or '.en' with an appropriate header value. For it to know the >type or language value associated with a given URI suffix, some configuration >needs to be done. Here's an example of how it can be done with >Spring:</p><div class="code panel pdl" style="border-width: 1p x;"><div class="codeContent panelContent pdl"> +</div></div><h1 id="JAX-RS-WhatisNew">What is New</h1><ul><li>Complete support for JAX-RS 2.0, please see <a shape="rect" href="jax-rs-basics.html">JAX-RS Basics</a> for more information</li><li>Bean Validation 1.1 Support, please see <a shape="rect" href="http://cxf.apache.org/docs/validationfeature.html">http://cxf.apache.org/docs/validationfeature.html</a> for more information</li><li>Swagger Feature</li></ul><h1 id="JAX-RS-GettingStartedwithJAX-RS">Getting Started with JAX-RS</h1><h2 id="JAX-RS-UnderstandingtheBasics">Understanding the Basics</h2><p>You are encouraged to read <a shape="rect" class="external-link" href="http://jcp.org/en/jsr/detail?id=339" rel="nofollow">JSR-339</a> specification to find out information not covered by this documentation. The specification introduces many terms such as root resources, resource methods, sub-resources and sub-resource locators, message body readers and writers. JAX-RS 2.0 additionally introduces filters, interceptors, new client API , features, new exception classes, server-side support for asynchronous invocations.</p><p>Please see the <a shape="rect" href="jax-rs-basics.html">JAX-RS Basics</a> page for more information.</p><h2 id="JAX-RS-SupportforDataBindings">Support for Data Bindings</h2><p>JAX-RS MessageBodyReader and MessageBodyWriter can be used to create data bindings for reading and writing data in a number of different formats. Compliant JAX-RS implementations are expected to support JAXB-annotated beans, JAXP Source objects, InputStreams, etc.</p><p>In addition, CXF JAX-RS lets users reuse existing CXF DataBindings for working with JAXB, XBeans, Aegis and SDO.</p><p>Please see the <a shape="rect" href="jax-rs-data-bindings.html">JAX-RS Data Bindings</a> page for more information.</p><h2 id="JAX-RS-HowRequestURIisMatched">How Request URI is Matched</h2><p>Lets assume you have a web application called 'rest' (example, a 'rest.war' archive). CXFServlet's url-pattern is "/test/*". Finally, jaxrs:server' s address is "/bar".</p><p>Requests like /rest/test/bar or /rest/test/bar/baz will be delivered to one of the resource classes in a given jaxrs:server endpoint. For the former request to be handled, a resource class with @Path("/") should be available, in the latter case - at least @Path("/") or a more specific @Path("/baz").</p><p>The same requirement can be expressed by having a CXFServlet with "/*" and jaxrs:server with "/test/bar".</p><p>When both CXFServlet and jaxrs:server use "/" then it's a root resource class which should provide a @Path with at least "/test/bar" for the above requests to be matched.</p><p>Generally, it can be a good idea to specify the URI segments which are more likely to change now and then with CXFServlets or jaxrs:server.</p><h2 id="JAX-RS-ClientAPI">Client API</h2><p>CXF 3.0.0 implements JAX-RS 2.0 Client API.</p><p>CXF 2.7.x or earlier provides a comprehensive support for developing RESTful clients by supporting 3 flavors of the client API: proxy-bas ed, HTTP-centric and XML-centric. CXF-specific client API is supported alongside new JAX-RS 2.0 Client API in CXF 3.0.0.</p><p>Please see the <a shape="rect" href="jax-rs-client-api.html">JAX-RS Client API</a> page for more information.</p><h2 id="JAX-RS-BeanValidation">Bean Validation</h2><p>Bean Validation 1.1 is supported since CXF 3.0.0-milestone1. Please see the <a shape="rect" href="http://cxf.apache.org/docs/validationfeature.html">http://cxf.apache.org/docs/validationfeature.html</a> for more information.</p><h2 id="JAX-RS-Filters,InterceptorsandInvokers">Filters, Interceptors and Invokers</h2><p>It is possible to intercept and modify the inbound and outbound calls with the help of CXF JAX-RS filters and/or CXF interceptors. Additionally, custom invokers offer an option to intercept a call immediately before a service bean is invoked.</p><p>Please see the <a shape="rect" href="jax-rs-filters.html">JAX-RS Filters</a> page for more information.</p><p>Please see the <a shape="r ect" href="jax-rs-basics.html">JAX-RS Basics</a> page for more information about new JAX-RS 2.0 filters and interceptors available in CXF 2.7.x and 3.0.0.</p><h2 id="JAX-RS-ServicelistingsandWADLsupport">Service listings and WADL support</h2><p><strong>New</strong>: Swagger feature has been introduced.</p><p>CXF JAX-RS supports <a shape="rect" class="external-link" href="http://www.w3.org/Submission/wadl" rel="nofollow">WADL</a>. CXF JAX-RS service endpoints can be listed in the service listings page and users can check the WADL documents.</p><p>Please see the <a shape="rect" href="jaxrs-services-description.html">JAXRS Services Description</a> page for more information.</p><h2 id="JAX-RS-ConfiguringJAX-RSservices">Configuring JAX-RS services</h2><p>JAX-RS services can be configured programmatically, using Blueprint, Spring or CXFNonSpringJAXRSServlet.</p><p>Please see the <a shape="rect" href="jaxrs-services-configuration.html">JAXRS Services Configuration</a> page for more informa tion.</p><h2 id="JAX-RS-Testing">Testing</h2><p>JAX-RS services can be easily tested using the embedded Jetty or CXF Local Transport.<br clear="none"> Please see the <a shape="rect" href="https://cwiki.apache.org/confluence/display/CXF20DOC/JAXRS+Testing">JAXRS Testing</a> page for more information.</p><h2 id="JAX-RS-Debugging">Debugging</h2><p>One may want to use a browser to test how a given HTTP resource reacts to different HTTP Accept or Accept-Language header values and request methods. For example, if a resource class supports a "/resource" URI then one can test the resource class using one of the following queries :</p><p><code>> GET /resource.xml</code> <br clear="none"> <code>> GET /resource.en</code></p><p>The runtime will replace '.xml' or '.en' with an appropriate header value. For it to know the type or language value associated with a given URI suffix, some configuration needs to be done. Here's an example of how it can be done with Spring:</p><div class="code pa nel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> <script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ <jaxrs:server id="customerService" address="/"> <jaxrs:serviceBeans> <bean class="org.apache.cxf.jaxrs.systests.CustomerService" />