Author: buildbot
Date: Thu Nov 21 13:48:12 2013
New Revision: 887534
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 Thu Nov 21 13:48:12 2013
@@ -130,11 +130,11 @@ Apache CXF -- JAX-RS
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div id="ConfluenceContent"><p><span style="font-size:2em;font-weight:bold">
JAX-RS (JSR-311) </span></p>
+<div id="ConfluenceContent"><p><span style="font-size:2em;font-weight:bold">
JAX-RS (JSR-339) </span></p>
<div>
-<ul><li><a shape="rect"
href="#JAX-RS-Introduction">Introduction</a></li><li><a shape="rect"
href="#JAX-RS-Projectsetupandconfiguration">Project setup and
configuration</a></li><ul><li><a shape="rect"
href="#JAX-RS-Migration">Migration</a></li><ul><li><a shape="rect"
href="#JAX-RS-MigratingfromJAXRS1.1to2.0">Migrating from JAX-RS 1.1 to
2.0</a></li><li><a shape="rect"
href="#JAX-RS-MigrationfromCXF2.7.xtoCXF3.0.0">Migration from CXF 2.7.x to CXF
3.0.0</a></li><li><a shape="rect"
href="#JAX-RS-MigrationfromCXF2.6.xtoCXF2.7.x">Migration from CXF 2.6.x to CXF
2.7.x</a></li></ul><li><a shape="rect" href="#JAX-RS-Mavendependencies">Maven
dependencies</a></li><ul><li><a shape="rect" href="#JAX-RS-CXF3.0.0">CXF
3.0.0</a></li><li><a shape="rect" href="#JAX-RS-CXF2.7.0">CXF
2.7.0</a></li><li><a shape="rect" href="#JAX-RS-CXF2.6.x">CXF
2.6.x</a></li></ul><li><a shape="rect"
href="#JAX-RS-Settinguptheclasspath">Setting up the classpath</a></li><li><a
shape="rect" href="#JAX-RS-CXFJAXRSbundle">
CXF JAX-RS bundle</a></li></ul><li><a shape="rect"
href="#JAX-RS-WhatisNew">What is New</a></li><li><a shape="rect"
href="#JAX-RS-GettingStartedwithJAXRS">Getting Started with
JAX-RS</a></li><ul><li><a shape="rect"
href="#JAX-RS-UnderstandingtheBasics">Understanding the Basics</a></li><li><a
shape="rect" href="#JAX-RS-SupportforDataBindings">Support for Data
Bindings</a></li><li><a shape="rect" href="#JAX-RS-HowRequestURIisMatched">How
Request URI is Matched</a></li><li><a shape="rect"
href="#JAX-RS-ClientAPI">Client API</a></li><li><a shape="rect"
href="#JAX-RS-Filters%2CInterceptorsandInvokers">Filters, Interceptors and
Invokers</a></li><li><a shape="rect"
href="#JAX-RS-ServicelistingsandWADLsupport">Service listings and WADL
support</a></li><li><a shape="rect"
href="#JAX-RS-ConfiguringJAXRSservices">Configuring JAX-RS
services</a></li><li><a shape="rect"
href="#JAX-RS-Testing">Testing</a></li><li><a shape="rect"
href="#JAX-RS-Debugging">Debugging</a></li><li><a shape="rect" href=
"#JAX-RS-Logging">Logging</a></li></ul><li><a shape="rect"
href="#JAX-RS-AdvancedFeatures">Advanced Features</a></li><ul><li><a
shape="rect" href="#JAX-RS-Multiparts">Multiparts</a></li><li><a shape="rect"
href="#JAX-RS-SecureJAXRSservices">Secure JAX-RS services</a></li><li><a
shape="rect" href="#JAX-RS-FailoverandLoadDistributionFeatures">Failover and
Load Distribution Features</a></li><li><a shape="rect"
href="#JAX-RS-Redirection">Redirection</a></li><li><a shape="rect"
href="#JAX-RS-XSLTandXPath">XSLT and XPath</a></li><li><a shape="rect"
href="#JAX-RS-ComplexSearchQueries">Complex Search Queries</a></li><li><a
shape="rect" href="#JAX-RS-ModelViewControllersupport">Model-View-Controller
support</a></li><li><a shape="rect"
href="#JAX-RS-CombiningJAXWSandJAXRS">Combining JAX-WS and
JAX-RS</a></li><li><a shape="rect"
href="#JAX-RS-IntegrationwithDistributedOSGi">Integration with Distributed
OSGi</a></li><li><a shape="rect" href="#JAX-RS-OtherAdvancedFeatures">Other
Advanced Feature
s</a></li></ul><li><a shape="rect" href="#JAX-RS-MavenPlugins">Maven
Plugins</a></li><li><a shape="rect"
href="#JAX-RS-Deployment">Deployment</a></li><li><a shape="rect"
href="#JAX-RS-Thirdpartyprojects">Third-party projects</a></li><li><a
shape="rect" href="#JAX-RS-References">References</a></li><li><a shape="rect"
href="#JAX-RS-Howtocontribute">How to contribute</a></li></ul></div>
+<ul><li><a shape="rect"
href="#JAX-RS-Introduction">Introduction</a></li><li><a shape="rect"
href="#JAX-RS-Projectsetupandconfiguration">Project setup and
configuration</a></li><ul><li><a shape="rect"
href="#JAX-RS-Migration">Migration</a></li><ul><li><a shape="rect"
href="#JAX-RS-FromJAXRS1.1to2.0">From JAX-RS 1.1 to 2.0</a></li><li><a
shape="rect" href="#JAX-RS-FromCXF2.7.xtoCXF3.0.0">From CXF 2.7.x to CXF
3.0.0</a></li><li><a shape="rect" href="#JAX-RS-FromCXF2.6.xtoCXF2.7.x">From
CXF 2.6.x to CXF 2.7.x</a></li></ul><li><a shape="rect"
href="#JAX-RS-Mavendependencies">Maven dependencies</a></li><ul><li><a
shape="rect" href="#JAX-RS-CXF3.0.0">CXF 3.0.0</a></li><li><a shape="rect"
href="#JAX-RS-CXF2.7.0">CXF 2.7.0</a></li><li><a shape="rect"
href="#JAX-RS-CXF2.6.x">CXF 2.6.x</a></li></ul><li><a shape="rect"
href="#JAX-RS-Settinguptheclasspath">Setting up the classpath</a></li><li><a
shape="rect" href="#JAX-RS-CXFJAXRSbundle">CXF JAX-RS
bundle</a></li></ul><li><a shape="rect" href="
#JAX-RS-WhatisNew">What is New</a></li><li><a shape="rect"
href="#JAX-RS-GettingStartedwithJAXRS">Getting Started with
JAX-RS</a></li><ul><li><a shape="rect"
href="#JAX-RS-UnderstandingtheBasics">Understanding the Basics</a></li><li><a
shape="rect" href="#JAX-RS-SupportforDataBindings">Support for Data
Bindings</a></li><li><a shape="rect" href="#JAX-RS-HowRequestURIisMatched">How
Request URI is Matched</a></li><li><a shape="rect"
href="#JAX-RS-ClientAPI">Client API</a></li><li><a shape="rect"
href="#JAX-RS-Filters%2CInterceptorsandInvokers">Filters, Interceptors and
Invokers</a></li><li><a shape="rect"
href="#JAX-RS-ServicelistingsandWADLsupport">Service listings and WADL
support</a></li><li><a shape="rect"
href="#JAX-RS-ConfiguringJAXRSservices">Configuring JAX-RS
services</a></li><li><a shape="rect"
href="#JAX-RS-Testing">Testing</a></li><li><a shape="rect"
href="#JAX-RS-Debugging">Debugging</a></li><li><a shape="rect"
href="#JAX-RS-Logging">Logging</a></li></ul><li><a shape="rect
" href="#JAX-RS-AdvancedFeatures">Advanced Features</a></li><ul><li><a
shape="rect" href="#JAX-RS-Multiparts">Multiparts</a></li><li><a shape="rect"
href="#JAX-RS-SecureJAXRSservices">Secure JAX-RS services</a></li><li><a
shape="rect" href="#JAX-RS-FailoverandLoadDistributionFeatures">Failover and
Load Distribution Features</a></li><li><a shape="rect"
href="#JAX-RS-Redirection">Redirection</a></li><li><a shape="rect"
href="#JAX-RS-XSLTandXPath">XSLT and XPath</a></li><li><a shape="rect"
href="#JAX-RS-ComplexSearchQueries">Complex Search Queries</a></li><li><a
shape="rect" href="#JAX-RS-ModelViewControllersupport">Model-View-Controller
support</a></li><li><a shape="rect"
href="#JAX-RS-CombiningJAXWSandJAXRS">Combining JAX-WS and
JAX-RS</a></li><li><a shape="rect"
href="#JAX-RS-IntegrationwithDistributedOSGi">Integration with Distributed
OSGi</a></li><li><a shape="rect" href="#JAX-RS-OtherAdvancedFeatures">Other
Advanced Features</a></li></ul><li><a shape="rect" href="#JAX-RS-MavenPlu
gins">Maven Plugins</a></li><li><a shape="rect"
href="#JAX-RS-Deployment">Deployment</a></li><li><a shape="rect"
href="#JAX-RS-Thirdpartyprojects">Third-party projects</a></li><li><a
shape="rect" href="#JAX-RS-References">References</a></li><li><a shape="rect"
href="#JAX-RS-Howtocontribute">How to contribute</a></li></ul></div>
<h1><a shape="rect" name="JAX-RS-Introduction"></a>Introduction</h1>
@@ -142,8 +142,7 @@ Apache CXF -- JAX-RS
<p>CXF supports the Java API for RESTful Web Services: JAX-RS 2.0 (<a
shape="rect" class="external-link" href="http://jcp.org/en/jsr/detail?id=339";
rel="nofollow">JSR-339</a>) and JAX-RS 1.1 (<a shape="rect"
class="external-link" href="http://jcp.org/en/jsr/detail?id=311";
rel="nofollow">JSR-311</a>). </p>
-<p>CXF 3.0.0 completely implements JAX-RS 2.0 including new Client API.
Existing JAX-RS 1.1 applications can be run with CXF 3.0.0.<br clear="none">
-CXF 3.0.0 has been fully tested against the first JAX-RS 2.0 TCK which became
available to Apache.</p>
+<p>CXF 3.0.0 completely implements JAX-RS 2.0 including new Client API and has
been fully tested against the first JAX-RS 2.0 TCK which became available to
Apache. Existing JAX-RS 1.1 applications can be run with CXF 3.0.0.</p>
<p>CXF 2.7.0 supports most of the new features introduced in JAX-RS 2.0
(excluding 2.0 Client API for now - but note that CXF client API has been
retrofitted to support new filters, interceptors, exception classes and
Response API, plus the asynchronous client invoker API).</p>
@@ -159,13 +158,59 @@ CXF 3.0.0 has been fully tested against
<h2><a shape="rect" name="JAX-RS-Migration"></a>Migration</h2>
-<h3><a shape="rect" name="JAX-RS-MigratingfromJAXRS1.1to2.0"></a>Migrating
from JAX-RS 1.1 to 2.0</h3>
+<h3><a shape="rect" name="JAX-RS-FromJAXRS1.1to2.0"></a>From JAX-RS 1.1 to
2.0</h3>
<p>JAX-RS 2.0 is backward compatible with JAX-RS 1.1. Please see <a
shape="rect" href="jax-rs-basics.html" title="JAX-RS Basics">JAX-RS Basics</a>
for more information about JAX-RS 2.0.</p>
-<h3><a shape="rect"
name="JAX-RS-MigrationfromCXF2.7.xtoCXF3.0.0"></a>Migration from CXF 2.7.x to
CXF 3.0.0</h3>
+<h3><a shape="rect" name="JAX-RS-FromCXF2.7.xtoCXF3.0.0"></a>From CXF 2.7.x to
CXF 3.0.0</h3>
-<h3><a shape="rect"
name="JAX-RS-MigrationfromCXF2.6.xtoCXF2.7.x"></a>Migration from CXF 2.6.x to
CXF 2.7.x</h3>
+<p>Please check the <a shape="rect"
href="http://cxf.apache.org/docs/30-migration-guide.html";>CXF 3.0.0 Migration
Guide</a> for the information about all the changes<br clear="none">
+in CXF 3.0.0. Here are more details on the changes specifically affecting
JAX-RS users:</p>
+
+<p>1. CXF RequestHandler and ResponseHandler filters have been removed.</p>
+
+<p>These legacy CXF filters are still supported in 2.7.x but no longer in
3.0.0. Please use <a shape="rect" class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/container/ContainerRequestFilter.html";
rel="nofollow">ContainerRequestFilter</a> and <a shape="rect"
class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/container/ContainerResponseFilter.html";
rel="nofollow">ContainerResponseFilter</a> instead. Also, <a shape="rect"
class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/ext/ReaderInterceptor.html";
rel="nofollow">ReaderInterceptor</a> and <a shape="rect" class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/ext/WriterInterceptor.html";
rel="nofollow">WriterInterceptor</a> can be used too. </p>
+
+<p>Note, CXF filters had org.apache.cxf.message.Message available in the
signature. If CXF Message is used in the existing CXF RequestHandler or
ResponseHandler then use
"org.apache.cxf.phase.PhaseInterceptorChain.getCurrentMessage()" or
"org.apache.cxf.jaxrs.util.JAXRSUtils.getCurrentMessage()" to get a Message
which has all the contextual information available. </p>
+
+<p>2. CXF org.apache.cxf.jaxrs.ext.form.Form has been dropped, please use
JAX-RS 2.0 <a shape="rect" class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/core/Form.html";
rel="nofollow">Form</a> instead. </p>
+
+<p>3. JAX-RS 2.0 introduces a controversial requirement that the default
built-in JAX-RS MessageBodyWriter and JAX-RS MessageBodyReader providers are
<b>preferred</b> to custom providers supporting the same types unless the
custom providers are precisely typed, for example, if you have a custom
InputStream reader properly implementing isReadable:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
+public class MyStreamProvider implements MessageBodyReader<Object> {
+ public boolean isReadable(Class<?> cls, ...) {
+ return InputStream.class.isAssignableFrom(cls) ||
Reader.class.isAssignableFrom(cls);
+ }
+ // other methods
+}
+{code:java}
+
+then the runtime will ignore it and choose a default InputStream/Reader reader
because MyStreamProvider is typed on Object. This was done to deal with the
cases where well-known JSON/etc providers are blindly supporting all types in
their isReadable methods by always returning 'true' and then failing when asked
to actually read the incoming stream into InputStream/etc directly.
+
+At CXF level, the users which depend on CXF MultipartProvider to provider
InputStream or String references to multipart attachments will be affected
unless they use @Multipart annotation. For example, if we have a multipart
payload with a single part/attachment only then the following code:
+
+{code:java}
+@POST
+@Consumes("multipart/form-data")
+public void upload(InputStream is) {
+}
+
+which in CXF 2.7.x or earlier will return a pointer to first/single individual
part, will actually return a stream representing the complete unprocessed
multipart payload. Adding a @Multipart marker will keep the existing code
working as expected:
+
+{code:java}
+@POST
+@Consumes("multipart/form-data")
+public void upload(@Multipart InputStream is) {
+}
+]]></script>
+</div></div>
+
+<p>4. If the custom code throws JAX-RS WebApplicationException with Response
containing a non-null entity then custom WebApplicationException mappers will
be bypassed - another problematic requirement, for example, the custom mappers
doing the logging will miss on such exceptions.<br clear="none">
+Set CXF "support.wae.spec.optimization" property to false to disable it. </p>
+
+<h3><a shape="rect" name="JAX-RS-FromCXF2.6.xtoCXF2.7.x"></a>From CXF 2.6.x to
CXF 2.7.x</h3>
<p>Please check the <a shape="rect"
href="http://cxf.apache.org/docs/27-migration-guide.html";>CXF 2.7 Migration
Guide</a> for the information about all the changes affecting the JAX-RS
users</p>
