Author: buildbot Date: Mon Mar 9 17:47:06 2015 New Revision: 943038 Log: Production update by buildbot for cxf
Modified: websites/production/cxf/content/cache/docs.pageCache websites/production/cxf/content/docs/jax-rs-basics.html Modified: websites/production/cxf/content/cache/docs.pageCache ============================================================================== Binary files - no diff available. Modified: websites/production/cxf/content/docs/jax-rs-basics.html ============================================================================== --- websites/production/cxf/content/docs/jax-rs-basics.html (original) +++ websites/production/cxf/content/docs/jax-rs-basics.html Mon Mar 9 17:47:06 2015 @@ -117,24 +117,26 @@ Apache CXF -- JAX-RS Basics <td height="100%"> <!-- Content --> <div class="wiki-content"> -<div id="ConfluenceContent"><p><span class="inline-first-p" style="font-size:2em;font-weight:bold"> JAX-RS : Understanding the Basics </span></p><p></p><p> </p><p><style type="text/css">/*<![CDATA[*/ -div.rbtoc1419015821180 {padding: 0px;} -div.rbtoc1419015821180 ul {list-style: disc;margin-left: 0px;} -div.rbtoc1419015821180 li {margin-left: 0px;padding-left: 0px;} +<div id="ConfluenceContent"><p><span class="inline-first-p" style="font-size:2em;font-weight:bold">JAX-RS : Understanding the Basics</span> </p><p> </p><p><style type="text/css">/*<![CDATA[*/ +div.rbtoc1425923200952 {padding: 0px;} +div.rbtoc1425923200952 ul {list-style: disc;margin-left: 0px;} +div.rbtoc1425923200952 li {margin-left: 0px;padding-left: 0px;} -/*]]>*/</style></p><div class="toc-macro rbtoc1419015821180"> +/*]]>*/</style></p><div class="toc-macro rbtoc1425923200952"> <ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSBasics-WhatisNewinJAX-RS2.0">What is New in JAX-RS 2.0</a> <ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSBasics-Filters">Filters</a> <ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSBasics-Server">Server</a></li><li><a shape="rect" href="#JAX-RSBasics-Client">Client</a></li></ul> </li><li><a shape="rect" href="#JAX-RSBasics-Interceptors">Interceptors</a></li><li><a shape="rect" href="#JAX-RSBasics-DynamicFeatures">Dynamic Features</a></li><li><a shape="rect" href="#JAX-RSBasics-Exceptions">Exceptions</a></li><li><a shape="rect" href="#JAX-RSBasics-Suspendedinvocations">Suspended invocations</a></li><li><a shape="rect" href="#JAX-RSBasics-Parameterconverters">Parameter converters</a></li><li><a shape="rect" href="#JAX-RSBasics-Beanparameters">Bean parameters</a></li><li><a shape="rect" href="#JAX-RSBasics-ResourceInfo">ResourceInfo</a></li><li><a shape="rect" href="#JAX-RSBasics-Injectionintosubresources">Injection into subresources</a></li><li><a shape="rect" href="#JAX-RSBasics-Updatestothematchingalgorithm">Updates to the matching algorithm</a></li><li><a shape="rect" href="#JAX-RSBasics-Link">Link</a></li><li><a shape="rect" href="#JAX-RSBasics-ClientAPI">Client API</a></li></ul> -</li><li><a shape="rect" href="#JAX-RSBasics-Resourceclass">Resource class</a></li><li><a shape="rect" href="#JAX-RSBasics-@Path">@Path</a></li><li><a shape="rect" href="#JAX-RSBasics-HTTPMethod">HTTP Method</a></li><li><a shape="rect" href="#JAX-RSBasics-Returntypes">Return types</a></li><li><a shape="rect" href="#JAX-RSBasics-ResponseStreaming">Response Streaming </a> +</li><li><a shape="rect" href="#JAX-RSBasics-Resourceclass">Resource class</a></li><li><a shape="rect" href="#JAX-RSBasics-@Path">@Path</a></li><li><a shape="rect" href="#JAX-RSBasics-HTTPMethod">HTTP Method</a> +<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSBasics-DefaultHttpMethod">Default Http Method</a></li></ul> +</li><li><a shape="rect" href="#JAX-RSBasics-Returntypes">Return types</a></li><li><a shape="rect" href="#JAX-RSBasics-ResponseStreaming">Response Streaming </a> <ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSBasics-JAX-RSStreamingOutput">JAX-RS StreamingOutput</a></li><li><a shape="rect" href="#JAX-RSBasics-CXFStreamingResponse">CXF StreamingResponse</a></li></ul> </li><li><a shape="rect" href="#JAX-RSBasics-Exceptionhandling">Exception handling</a> <ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSBasics-MappingexceptionsthrownfromCXFinterceptors">Mapping exceptions thrown from CXF interceptors</a></li><li><a shape="rect" href="#JAX-RSBasics-CustomizingdefaultWebApplicationExceptionmapper">Customizing default WebApplicationException mapper</a></li></ul> </li><li><a shape="rect" href="#JAX-RSBasics-DealingwithParameters">Dealing with Parameters</a> <ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSBasics-Parameterbeans">Parameter beans</a></li></ul> </li><li><a shape="rect" href="#JAX-RSBasics-Resourcelifecycles">Resource lifecycles</a></li><li><a shape="rect" href="#JAX-RSBasics-Overviewoftheselectionalgorithm.">Overview of the selection algorithm.</a> -<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSBasics-Selectingbetweenmultipleresourceclasses">Selecting between multiple resource classes</a></li><li><a shape="rect" href="#JAX-RSBasics-Selectingbetweenmultipleresourcemethods">Selecting between multiple resource methods</a></li><li><a shape="rect" href="#JAX-RSBasics-Resourcemethodsandmediatypes">Resource methods and media types</a></li><li><a shape="rect" href="#JAX-RSBasics-Customselectionbetweenmultipleresources">Custom selection between multiple resources</a></li></ul> +<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSBasics-Selectingbetweenmultipleresourceclasses">Selecting between multiple resource classes</a></li><li><a shape="rect" href="#JAX-RSBasics-Selectingbetweenmultipleresourcemethods">Selecting between multiple resource methods</a></li><li><a shape="rect" href="#JAX-RSBasics-Resourcemethodsandmediatypes">Resource methods and media types</a></li><li><a shape="rect" href="#JAX-RSBasics-Customselectionbetweenmultipleresourcesoroperations">Custom selection between multiple resources or operations</a></li></ul> </li><li><a shape="rect" href="#JAX-RSBasics-Contextannotations">Context annotations</a> <ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSBasics-CustomContexts">Custom Contexts</a></li></ul> </li><li><a shape="rect" href="#JAX-RSBasics-URIcalculationusingUriInfoandUriBuilder">URI calculation using UriInfo and UriBuilder</a></li><li><a shape="rect" href="#JAX-RSBasics-Annotationinheritance">Annotation inheritance</a></li><li><a shape="rect" href="#JAX-RSBasics-Sub-resourcelocators.">Sub-resource locators.</a> @@ -253,7 +255,7 @@ import java.lang.annotation.Target; public @interface PATCH { } ]]></script> -</div></div><h1 id="JAX-RSBasics-Returntypes">Return types</h1><p>Either javax.ws.rs.core.Response or custom type can be returned. javax.ws.rs.core.Response can be used to set the HTTP response code, headers and entity. JAX-RS MessageBodyWriters (see below) are in charge of serializing the response entities, those which are returned directly or as part of javax.ws.rs.core.Response.</p><h1 id="JAX-RSBasics-ResponseStreaming">Response Streaming </h1><h2 id="JAX-RSBasics-JAX-RSStreamingOutput">JAX-RS StreamingOutput</h2><p><a shape="rect" class="external-link" href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/core/StreamingOutput.html" rel="nofollow">StreamingOutput</a> can be used to stream the data to the client, for example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +</div></div><h2 id="JAX-RSBasics-DefaultHttpMethod">Default Http Method</h2><p>CXF 3.0.4 introduces a new extension, a org.apache.cxf.jaxrs.ext.DefaultMethod annotation. It can be used to match arbitrary HTTP methods on a single resource method. This can be used in some advanced scenarious for integrating the CXF JAX-RS runtime into non-JAX-RS environments as well as in cases where it is awkward/difficult to have every HTTP method listed for a given path segment. CXF users need to be aware using this option will lead to a non-portable JAX-RS code.</p><p> </p><h1 id="JAX-RSBasics-Returntypes">Return types</h1><p>Either javax.ws.rs.core.Response or custom type can be returned. javax.ws.rs.core.Response can be used to set the HTTP response code, headers and entity. JAX-RS MessageBodyWriters (see below) are in charge of serializing the response entities, those which are returned directly or as part of javax.ws.rs.core.Response.</p><h1 id="JAX-RSBasics-ResponseStreaming">Response St reaming </h1><h2 id="JAX-RSBasics-JAX-RSStreamingOutput">JAX-RS StreamingOutput</h2><p><a shape="rect" class="external-link" href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/core/StreamingOutput.html" rel="nofollow">StreamingOutput</a> can be used to stream the data to the client, for example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> <script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[@GET @Path("/books/pdf") @Produces("application/pdf") @@ -533,7 +535,7 @@ public class Test1 { } ]]></script> -</div></div><h2 id="JAX-RSBasics-Customselectionbetweenmultipleresources">Custom selection between multiple resources</h2><p>The JAX-RS selection algorithm has been designed with a lot of attention being paid to various possible cases, as far as the selection between multiple matching resource classes or methods is concerned.</p><p>However, in some cases, users have reported the algorithm being somewhat restrictive in the way multiple resource classes are selected. For example, by default, after a given resource class has been matched and if this class has no matching resource method, then the algorithm stops executing, without attempting to check the remaining matching resource classes.</p><p>Starting from CXF 2.2.5 it is possible to register a custom <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/ResourceComparator.java">ResourceComparator</a> implementation using a jaxrs:server/jaxrs:r esourceComparator element, example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +</div></div><h2 id="JAX-RSBasics-Customselectionbetweenmultipleresourcesoroperations">Custom selection between multiple resources or operations</h2><p>The JAX-RS selection algorithm has been designed with a lot of attention being paid to various possible cases, as far as the selection between multiple matching resource classes or methods is concerned.</p><p>However, in some cases, users have reported the algorithm being somewhat restrictive in the way multiple resource classes are selected. For example, by default, after a given resource class has been matched and if this class has no matching resource method, then the algorithm stops executing, without attempting to check the remaining matching resource classes.</p><p>Starting from CXF 2.2.5 it is possible to register a custom <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/ResourceComparator.java">ResourceComparator</a> implementation us ing a jaxrs:server/jaxrs:resourceComparator element, example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> <script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<!-- JAX-RS endpoint declaration fragment --> <jaxrs:server address="/"> <!-- Usual elements, like serviceBeans or providers, etc -->