Modified: websites/production/cxf/content/docs/jax-rs-data-bindings.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-data-bindings.html (original)
+++ websites/production/cxf/content/docs/jax-rs-data-bindings.html Wed Sep 13
15:05:52 2017
@@ -32,9 +32,9 @@
<link type="text/css" rel="stylesheet"
href="/resources/highlighter/styles/shThemeCXF.css">
<script src='/resources/highlighter/scripts/shCore.js'></script>
-<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
-<script src='/resources/highlighter/scripts/shBrushXml.js'></script>
<script src='/resources/highlighter/scripts/shBrushBash.js'></script>
+<script src='/resources/highlighter/scripts/shBrushXml.js'></script>
+<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
<script>
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -122,11 +122,11 @@ Apache CXF -- JAX-RS Data Bindings
 </p><p> </p><p> </p><p> </p><p><style
type="text/css">/*<![CDATA[*/
-div.rbtoc1505311211084 {padding: 0px;}
-div.rbtoc1505311211084 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1505311211084 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1505314944398 {padding: 0px;}
+div.rbtoc1505314944398 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1505314944398 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1505311211084">
+/*]]>*/</style></p><div class="toc-macro rbtoc1505314944398">
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSDataBindings-JAXBsupport">JAXB support</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSDataBindings-ConfiguringJAXBprovider">Configuring JAXB
provider</a></li><li><a shape="rect"
href="#JAX-RSDataBindings-JAXBandMoxy">JAXB and Moxy</a></li></ul>
</li><li><a shape="rect" href="#JAX-RSDataBindings-JSONsupport">JSON
support</a>
@@ -139,7 +139,7 @@ div.rbtoc1505311211084 li {margin-left:
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSDataBindings-Supportforcatalogs">Support for
catalogs</a></li><li><a shape="rect"
href="#JAX-RSDataBindings-Outputvalidation">Output validation</a></li></ul>
</li><li><a shape="rect" href="#JAX-RSDataBindings-BeanValidation">Bean
Validation</a></li><li><a shape="rect"
href="#JAX-RSDataBindings-FastInfoset">Fast Infoset</a></li></ul>
</div><h1 id="JAX-RSDataBindings-JAXBsupport">JAXB support</h1><p>The request
and response can be marshalled and unmarshalled to/from Java object using
JAXB.</p><p>There's a number of ways to tell to the JAXB provider how objects
can be serialized. The simplest way is to mark a given type with
@XmlRootElement annotation.</p><p>For example:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">@XmlRootElement(name = "Customer")
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@XmlRootElement(name = "Customer")
public class Customer {
private String name;
private long id;
@@ -165,7 +165,7 @@ public class Customer {
}
</pre>
</div></div><p>In the example below, the Customer object returned by
getCustomer is marshaled using JAXB data binding:</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">@Path("/customerservice/")
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Path("/customerservice/")
public class CustomerService {
@GET
@Path("/customers/{customerId}/")
@@ -175,13 +175,13 @@ public class CustomerService {
}
</pre>
</div></div><p>The wire representation of Customer object is:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><Customer>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><Customer>
<id>123</id>
<name>John</name>
</Customer>
</pre>
</div></div><p>The simplest way to work with the collections is to define a
type representing a collection. For example:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">@XmlRootElement(name = "Customers")
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@XmlRootElement(name = "Customers")
public class Customers {
private Collection<Customer> customers;
@@ -203,7 +203,7 @@ public class CustomerService {
}
</pre>
</div></div><p>Alternatively to using @XmlRootElement and Collection wrappers,
one can provide an Object factory which will tell JAXB how to marshal a given
type (in case of Collections - its template type). Another option is to
return/accept a JAXBElement directly from/in a given method.</p><p>Another
option is to register one or more JAX-RS ContextResolver providers capable of
creating JAXBContexts for a number of different types. The default
JAXBElementProvider will check these resolvers first before attempting to
create a JAXBContext on its own.</p><p>Finally, JAXBProvider provides a support
for serializing response types and deserializing parameters of methods
annotated with @XmlJavaTypeAdapter annotations.</p><h2
id="JAX-RSDataBindings-ConfiguringJAXBprovider">Configuring JAXB
provider</h2><p>The default JAXB provider can be configured in a number of
ways. For example, here's how to set up marshall properties :</p><div
class="code panel pdl" style="border-width: 1px;"><div cla
ss="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><beans
xmlns:util="http://www.springframework.org/schema/util">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans
xmlns:util="http://www.springframework.org/schema/util">
<bean id="jaxbProvider"
class="org.apache.cxf.jaxrs.provider.JAXBElementProvider">
<property name="marshallerProperties" ref="propertiesMap"/>
</bean>
@@ -215,7 +215,7 @@ public class CustomerService {
/<beans>
</pre>
</div></div><p>Individual marshal properties can be injected as simple
properties. At the moment, Marshaller.JAXB_SCHEMA_LOCATION can be injected as
"schemaLocation" property. Schema validation can be enabled and custom @Consume
and @Produce media types can be injected, see <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/resources/jaxrs/WEB-INF/beans.xml";>this
example</a> and "Customizing media types for message body providers" and
"Schema Validation" sections for more information.</p><p>One issue which one
may need to be aware of it is that an exception may occur during the JAXB
serialization process, after some content has already been processed and
written to the output stream. By default, the output goes directly to the
output HTTP stream so if an exception occurs midway through the process then
the output will likely be malformed. If you set 'enableBuffering' property to
'true' then a JAXB provider will write to the
efficient CXF CachedOutputStream instead and if an exception occurs then no
text which has already been written will make it to the outside world and it
will be only this exception that will be reported to the client.</p><p>When
enabling buffering, you can also control how the data being serialized will be
buffered. By default, an instance of CXF CachedOutputStream will be used. If
you set an "enableStreaming" property on the JAXBElementProvider then it will
be a CXF CachingXMLEventWriter that will cache the serialization
events.</p><p>If you would like your own custom provider to write to a cached
stream then you can either set an "org.apache.cxf.output.buffering" property to
'true' on a jaxrs endpoint or "enableBuffering" property on the provider. If
this provider deals with XML and has a "getEnableStreaming" method returning
'true' then CachingXMLEventWriter will be used, in all other cases
CachedOutputStream will be used.</p><p>Please note that if you don't have
wrapper types fo
r your methods and the classloader you are using does not allow you to call
defineClass(), you may need to set
'-Dcom.sun.xml.bind.v2.bytecode.ClassTailor.noOptimize'</p><p>JAXB Marshaller,
Unmarshaller and context properties can be configured for both JAXB and JSON
providers. Both providers can also be configured to skip the isReadable() and
isWriteable() checks to do with asserting that a given instance is likely to be
successfully read/written by setting a 'skipChecks' property to true. This can
be useful when it is known that only valid JAXB instances are read or
written.</p><p>Starting from CXF 2.4.3 it is possible to have specific prefixes
associated with XML namespaces. This might be needed to make the legacy
consumers able to consume the resulting XML. Use a "namespacePrefixes" map
property (namespace is a key, corresponding prefix is a value).</p><h2
id="JAX-RSDataBindings-JAXBandMoxy">JAXB and Moxy</h2><p>For
JAXBElementProvider to support <a shape="rect" class="external-l
ink" href="http://www.eclipse.org/eclipselink/moxy.php";
rel="nofollow">Moxy</a> a custom Moxy-aware JAX-RS ContextProvider
implementation needs to be registered in jaxrs:providers. For example:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">import javax.xml.bind.JAXBContext;
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBException;
import javax.ws.rs.ext.ContextResolver;
import org.eclipse.persistence.jaxb.JAXBContextFactory;
@@ -235,7 +235,7 @@ public class MoxyJaxbContextResolved imp
}
</pre>
</div></div><p>Alternatively, add a "jaxb.properties" file with the entry
"javax.xml.bind.context.factory=org.eclipse.persistence.jaxb.JAXBContextFactory"
to a package where JAXB beans are located.</p><p>If Moxy is used to handle
beans without JAXB annotations then setting a 'skipJaxbChecks' property on
JAXBElementProvider to 'true' will be needed.</p><p>Use JAXBElementProvider
"namespaceMapperPropertyName" and "xmlPiPropertyName" properties if you need to
customize namespace prefixes or add XML processing instructions with Moxy.
JSONProvider will also recognize "namespaceMapperPropertyName" in cases when
the namespaces are not ignored.</p><h1 id="JAX-RSDataBindings-JSONsupport">JSON
support</h1><p>Following code returns a Customer object that is marshaled to
JSON format:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">@Path("/customerservice/")
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Path("/customerservice/")
public class CustomerService {
@Produces("application/json")
@GET
@@ -245,7 +245,7 @@ public class CustomerService {
}
</pre>
</div></div><h2 id="JAX-RSDataBindings-Jettison">Jettison</h2><h3
id="JAX-RSDataBindings-ConfiguringJSONprovider">Configuring JSON
provider</h3><p>Default JSON provider relies on Jettison 1.3 and it expects the
types it deals with to follow the same techniques as described above in the
JAXB support section for them to be handled properly.</p><p>The default JSON
provider can be configured in a number of ways. For example, here's how to set
up namespace-to-prefix mappings :</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><beans
xmlns:util="http://www.springframework.org/schema/util">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans
xmlns:util="http://www.springframework.org/schema/util">
<bean id="jaxbProvider"
class="org.apache.cxf.jaxrs.provider.json.JSONProvider">
<property name="namespaceMap" ref="jsonNamespaceMap"/>
</bean>
@@ -255,7 +255,7 @@ public class CustomerService {
/<beans>
</pre>
</div></div><p><strong>Note</strong> that starting from CXF 2.3.0 it may not
be needed to set up a custom namespace map on the write side with JSONProvider
making a 'best' effort to retrieve them during the JAXB Marshaller calls.
Starting from CXF 2.6.1 and 2.5.4 setting the namespace maps will additionally
configure a Marshaller namespace mapper.</p><p>Schema validation can be enabled
and custom @Consume and @Produce media types can be injected, see <a
shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/resources/jaxrs/WEB-INF/beans.xml";>this
example</a> and "Customizing media types for message body providers" and
"Schema Validation" sections for more information.</p><p><strong>Note</strong>
that JSONProvider is Jettison based and supports only JAXB annotated beans. You
should use Jackson provider to process POJOs without JAXB annotations.</p><h3
id="JAX-RSDataBindings-DealingwithJettisonarrayserializationissues">Dealing
with J
ettison array serialization issues</h3><p>By default, Jettison wrongly
serializes List objects containing a single value only. To work around this
issue, one needs to enable a 'serializeAsArray' feature on a JSONProvider, with
the additional option of specifying the individual fields which needs to be
processed accordingly using an 'arrayKeys' property. Please see <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/resources/jaxrs/WEB-INF/beans.xml";>this
example</a> for more information.</p><p>Note that 'serializeAsArray' and
'arrayKeys' can be combined to produce so called natural convention sequences.
For example, given the following two class definitions :</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">@XmlRootElement()
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@XmlRootElement()
@XmlType(name = "", propOrder = {"title", "comments" })
public static class Post {
private String title;
@@ -287,24 +287,24 @@ public static class Comment {
}
</pre>
</div></div><p>an instance of Post class can be serialized like this if a
JSONProvider has had its 'serializeAsArray' property set to 'true' and
'arrayKeys' list property set to contain 'comments' value :</p><p>>
{"post":{"title":"post","comments":[{"title":"comment1"},{"title":"comment2"}]}}</p><p>One
other property which might help during the serialization is a boolean
"ignoreMixedContent" property which lets to bypass a Jettison issue to do with
outputting '$' properties when dealing with empty strings typically encountered
in mixed content trees.</p><p>You may request that JSONProvider ignores an
'xsi:type' attribute which is serialized in some cases by setting a
"writeXsiType" boolean property with a 'false' value.</p><p>You may also
request that JSONProvider ignores all the namespaces during the serialization
process by setting an "ignoreNamespaces" boolean property with a 'true'
value.</p><p>Starting from CXF 2.7.6 (and Jettison 1.3.4):</p><ul
class="alternate"><li>'writeN
ullAsString' property can be used to affect the way Jettison writes out null
values, if this property is set to 'false' then Jettison will write null values
without wrapping them in double quotes.</li><li>new 'dropElementsInXmlStream'
can be set to false and be used with outDropElements property to affect the
serialization directly at the Jettison level</li></ul><h3
id="JAX-RSDataBindings-BadgerFishconvention">BadgerFish
convention</h3><p>Starting from CXF 2.2.5 it is possible to configure
JSONProvider to support a BadgerFish convention. By default a "mapped"
convention is supported, set a JSONProvider "convention" property with the
value "badgerfish" if you'd like to work with the BadgerFish convention.</p><h3
id="JAX-RSDataBindings-WrappingandUnwrappingJSONsequences">Wrapping and
Unwrapping JSON sequences</h3><p>A "wrapperName" string property can be used to
append a dropped root element name to an incoming JSON sequence for it to be
deserialized properly. A "wrapperMap" map prope
rty can be used to nominate wrapper names for individual class names. In both
cases, a 'supportUnwrapped' boolean property also has to be set.</p><p>A
boolean "dropRootName" property can be used to tell JSONProvider that a root
element needs to be dropped.</p><h3
id="JAX-RSDataBindings-TypeConverters">TypeConverters</h3><p>Jettison 1.2
supports the registration of org.codehaus.jettison.mapped.TypeConverter
implementations which can be used to convert types to JSON primitives. The
"typeConverter" property can be used to register a converter with JSONProvider
instance. The "convertTypesToStrings" property can be used to configure
JSONProvider to convert all the types to strings.</p><h2
id="JAX-RSDataBindings-Jackson">Jackson</h2><p>If you prefer working with
Jackson JSON providers then register either JacksonJsonProvider:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><jaxrs:providers>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><jaxrs:providers>
<bean class="org.codehaus.jackson.jaxrs.JacksonJsonProvider"/>
</jaxrs:providers>
</pre>
</div></div><p>or JacksonJaxbJsonProvider (when working with JAXB
beans):</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><jaxrs:providers>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><jaxrs:providers>
<bean class="org.codehaus.jackson.jaxrs.JacksonJaxbJsonProvider"/>
</jaxrs:providers>
</pre>
</div></div><p>and add this Maven dependency:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><dependency>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><dependency>
<groupId>org.codehaus.jackson</groupId>
<artifactId>jackson-jaxrs</artifactId>
<version>1.9.0</version>
</dependency>
</pre>
</div></div><h1 id="JAX-RSDataBindings-CommonJAXBandJSONconfiguration">Common
JAXB and JSON configuration</h1><p>In this section it's expected that Jettison
is used to handle JSON.</p><h2
id="JAX-RSDataBindings-SingleJAXBContextandextrauserclasses">Single JAXBContext
and extra user classes</h2><p>By default JAXBContexts are created on demand.
Starting from CXF 2.3.2 and 2.4.0 it is possible to configure JAXB-based
providers to support the creation of a single JAXBContext, example :</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><bean id="jaxb"
class="org.apache.cxf.jaxrs.provider.JAXBElementProvider">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><bean id="jaxb"
class="org.apache.cxf.jaxrs.provider.JAXBElementProvider">
<property name="singleJaxbContext" value="true"/>
<property name="extraClass">
<list>
@@ -315,7 +315,7 @@ public static class Comment {
</bean>
</pre>
</div></div><p>Please note that if an extraClass property is set then the
JAXBContext (single as in the above example or the one created dynamically on a
per-class or per-package basis) will also include the extra user classes thus
making it possible to avoid setting an XmlSeeAlso JAXB annotation or dealing
with JAXB jaxb.index or ObjectFactory resources. This property is identical to
a CXF JAXBDataBinding 'extraClass' property.</p><p>Trying to create a single
JAXBContext is also an optimization step. Having a single JAXBContext for
classes the JAX-RS runtime can statically discover by checking all the root
resources and their sub-resources (assuming the jaxrs:server endpoint has been
configured to do the static resolution of the sub-resources) does not preclude
JAX-RS Responses wrapping JAXB beans being used as well.</p><p>One may want to
use the "singleJaxbContext" property in combination with the "skipChecks"
property if it is known that only valid JAXB beans will be read or writ
ten.</p><p>Also note that setting only "extraClass", without setting
"singleJaxbContext" property will also work in cases when no package JAXB
contexts are created (specifically when no ObjectFactory or jaxb.index have
been found). Starting from CXF 2.7.2 and 2.6.4 it will also work well for
package contexts.</p><p>However, when possible, prefer always setting both
"singleJaxbContext" and "extraClass" properties. Starting from CXF 2.7.2 this
will also work well for package-level contexts - add
"useSingleContextForPackages" property to get the created single context always
used as a package context.</p><h2
id="JAX-RSDataBindings-AutomaticJAXBElementconversionduringserialization">Automatic
JAXBElement conversion during serialization</h2><p>In some cases, wrapping
object instances into JAXBElements may affect the way XML is produced. For
example, given Base and Derived classes, returning an instance of Derived
class, with Base one being a method response type, would produce an addition
al xsi:type attribute if this instance is wrapped into JAXBElement. One can
set a "jaxbElementClassNames" list property which can contain class names like
"org.foo.Base", etc.</p><h2
id="JAX-RSDataBindings-HandlingJAXBbeanswithoutXmlRootElementannotations">Handling
JAXB beans without XmlRootElement annotations</h2><p>A "jaxbElementClassNames"
list property mentioned in the previous section can affect the serialization of
objects of types with XmlRootElement annotations.<br clear="none"> In some
cases no XmlRootElement annotations are available on types and adding them
manually may not be an option; likewise having explicit JAXBElements in method
signatures may also be seen as too intrusive.</p><p>In such cases, one might
want to use a "jaxbElementClassMap" map property which contains class name to
simple or expanded QName pairs. This will also lead to the automatic
JAXBElement conversion durring the serialization. Finally,
'marshalAsJaxbElement' boolean property can be used when all
the instances need to be wrapped - provided that simple class names of these
instances can be used as element names.</p><p>When deserializing, one can
either update an existing ObjectFactory with methods returning JAXBElements or
simply set an 'unmarshalFromJaxbElement' property on either JAXB or JSON
provider.</p><h2 id="JAX-RSDataBindings-Handlingexplicitcollections">Handling
explicit collections</h2><p>JAXB and JSON providers can handle explicit
collections like List, Set or base Collection.<br clear="none"> By default they
will try to deduce the name of the collection root element from a collection
member class. For example, given a Book.class whose @XmlRootElement value is
'Book', the name of the collection name will be 'Books'.<br clear="none"> One
can override it by setting a 'collectionWrapperName' string property, like
'Books' or '{<a shape="rect" class="external-link" href="http://books";
rel="nofollow">http://books</a>}Book'.</p><p>There's also a
'collectionWrapperMap' pr
operty available for use in more advanced cases, when collections of different
types are used, for example, when mixed collections of objects descended from
abstract classes having no @XmlRootElement tags are returned :</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><!-- Configure JAXB Provider -->
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><!-- Configure JAXB Provider -->
<bean id="jaxbProvider"
class="org.apache.cxf.jaxrs.provider.JAXBElementProvider">
<property name="collectionWrapperMap">
@@ -329,7 +329,7 @@ class="org.apache.cxf.jaxrs.provider.JAX
</bean>
</pre>
</div></div><p>JSONProvider can only serialize explicit collections at the
moment. If needed, it can be told to drop a collection element name using a
boolean 'dropCollectionWrapperElementName'. For example, a
'dropCollectionWrapperElementName' and 'serializeAsArray' properties can be
used to make the Dojo JSON RestStore consume the resulting JSON sequence (in
CXF 2.2.5).</p><h1
id="JAX-RSDataBindings-CustomizingJAXBXMLandJSONinputandoutput">Customizing
JAXB XML and JSON input and output</h1><p>Sometimes you may want to adapt an
incoming XML request or outgoing XML response. For example, your application
has changed but a lot of legacy clients have not been updated yet.<br
clear="none"> When dealing with XML, the easiest and fastest option is to
register a custom STAX XMLStreamWriter or XMLStreamReader and modify XML as
needed. You can register a custom STAX <br clear="none"> handler from
RequestHandler or ResponseHandler filters or input/output CXF interceptors. For
example, see <a
shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/XmlStreamWriterProvider.java";>XMLStreamWriterProvider</a>
and <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/CustomXmlStreamWriter.java";>CustomXmlStreamWriter</a>.</p><p>Another
option is to register a custom JAXB or JSON provider extending CXF
JAXBElementProvider or JSONProvider and overriding a method like
createStreamWriter(). <br clear="none"> Typically one would delegate to a super
class first and then wrap the returned writer in a custom writer, see <a
shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/CustomXmlStreamWriter.java";>CustomXmlStreamWriter</a>
for an example.</p><p>One can also use XSLTJaxbProvider to produce or modify
the incoming XML. In fa
ct, XSLTJaxbProvider can be used to adapt formats like JSON for legacy
consumers.</p><p>Please also see this <a shape="rect" class="external-link"
href="http://soa.dzone.com/articles/pragmatic-web-services-apache";
rel="nofollow">overview</a> of various related features available in
CXF.</p><p>In CXF 2.2.5, a new feature has been introduced whose goal is to
generalize and simplify in a number of cases the way both JAXB and JSON can be
customized.</p><p>Note that starting from CXF 2.4.0 the new <a shape="rect"
href="transformationfeature.html">Transformation Feature</a> can be used
instead.</p><p>The following configuration properties have been added to the
base JAXB/JSON AbstractJAXBProvider :</p><ul
class="alternate"><li>"outTransformElements" map property: can be used to
change the output element names and change or drop namespaces; keys are the
elements to be changed, values are the new element names.
Examples:</li></ul><div class="code panel pdl" style="border-width: 1px;"><div c
lass="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><bean id="jaxbProvider"
class="org.apache.cxf.jaxrs.provider.JAXBElementProvider">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><bean id="jaxbProvider"
class="org.apache.cxf.jaxrs.provider.JAXBElementProvider">
<property name="outTransformElements">
<map>
<!-- change "book" to "thebook" -->
@@ -348,7 +348,7 @@ class="org.apache.cxf.jaxrs.provider.JAX
</bean>
</pre>
</div></div><ul class="alternate"><li>"inTransformElements" map property: can
be used to change the input element names and change or drop namespaces; see
the "outTransfromElements" property description for an example.</li></ul><ul
class="alternate"><li>"outAppendElements" map property: can be used to append
new simple or qualified elements to the output; keys are the new elements,
values are the elements the new ones will be appended before.
Examples:</li></ul><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><bean id="jaxbProvider"
class="org.apache.cxf.jaxrs.provider.JAXBElementProvider">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><bean id="jaxbProvider"
class="org.apache.cxf.jaxrs.provider.JAXBElementProvider">
<property name="outAppendElements">
<map>
<!-- append "book" before "thebook" -->
@@ -367,7 +367,7 @@ class="org.apache.cxf.jaxrs.provider.JAX
</bean>
</pre>
</div></div><ul class="alternate"><li>"inAppendElements" map property : can be
used to append new simple or qualified elements to the input; see the
"outAppendElements" property description for an example.</li></ul><ul
class="alternate"><li>"outDropElements" list property : can be used to drop
elements during the serialization; note that children elements if any of a
given dropped element are not affected. Examples:</li></ul><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><bean id="jaxbProvider"
class="org.apache.cxf.jaxrs.provider.JAXBElementProvider">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><bean id="jaxbProvider"
class="org.apache.cxf.jaxrs.provider.JAXBElementProvider">
<property name="outDropElements">
<list>
<!-- ignore drop and {http://numbers}number elements -->
@@ -378,7 +378,7 @@ class="org.apache.cxf.jaxrs.provider.JAX
</bean>
</pre>
</div></div><ul class="alternate"><li>"inDropElements" list property : can be
used to drop elements during the deserialization; note that children elements
if any of a given dropped element are not affected. Please see the
"outDropElements" property description for an example.</li></ul><ul
class="alternate"><li>"attributesAsElements" boolean property : can be used to
have attributes serialized as elements.</li></ul><p>The combination of
"attributesAsElements" and "outDropElements" properties can be used to have
certain attributes ignored in the output by turning then into elements first
and then blocking them.</p><p>This feature might be used in a number of cases.
For example, one may have rootless JSON array collections such as
"<code>a:b},{c:d</code>" deserialized into a bean by using a "wrapperName"
JSONProvider property with a value like "list" which identifies a bean field
and an "inAppendMap" property with a name of the bean (ex, "book") being
appended before the "list", thus
effectively turning the original JSON sequence into
"{book:{list:<code>a:b},{c:d</code>}}".</p><h1
id="JAX-RSDataBindings-ControllingLargeJAXBXMLandJSONinputpayloads">Controlling
Large JAXB XML and JSON input payloads</h1><p>Starting from CXF 2.6.0 it is
possible to control the depth of large XML and JSON payloads on the
per-endpoint basis in order to limit the risk of the denial of service attacks.
Please see <a shape="rect"
href="https://cwiki.apache.org/confluence/display/CXF20DOC/Security#Security-XML";>this
section</a> on how to use a new DepthRestrictingInterceptor in order to
control XML payloads which are read either by JAXBElementProvider or
SourceProvider (which supports JAXP Source and DOM Document
types).</p><p>Additionally it is possible to configure JAXBElementProvider or
JSONProvider with contextual properties or <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/api/src/main/java/org/apache/cxf/staxutils/DocumentDepthProperties.java";
>DocumentDepthProperties</a>:</p><div class="code panel pdl"
>style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><bean id="depthProperties"
class="org.apache.cxf.staxutils.DocumentDepthProperties">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><bean id="depthProperties"
class="org.apache.cxf.staxutils.DocumentDepthProperties">
<property name="innerElementCountThreshold" value="500"/>
</bean>
@@ -412,12 +412,12 @@ class="org.apache.cxf.jaxrs.provider.JAX
</pre>
</div></div><h1 id="JAX-RSDataBindings-JSR-353JSONProcessing">JSR-353 JSON
Processing</h1><p>As per JAX-RS 2.0 specification, the support of <a
shape="rect" class="external-link" href="http://jcp.org/en/jsr/detail?id=353";
rel="nofollow">JSR-353 Java API for JSON Processing</a> is mandatory
requirement and implies the presence of message body reader(s)/writer(s) for
following types: <a shape="rect" class="external-link"
href="http://docs.oracle.com/javaee/7/api/javax/json/JsonStructure.html";
rel="nofollow">JsonStructure</a>, <a shape="rect" class="external-link"
href="http://docs.oracle.com/javaee/7/api/javax/json/JsonArray.html";
rel="nofollow">JsonArray</a> and <a shape="rect" class="external-link"
href="http://docs.oracle.com/javaee/7/api/javax/json/JsonObject.html";
rel="nofollow">JsonObject</a>. The Apache CXF provides such a support in a form
of <strong>JsrJsonpProvider</strong> provider distributed by Apache CXF JAX-RS
Extensions Providers module<strong> (cxf-rt-rs-extension-pro
viders).</strong></p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><jaxrs:providers>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><jaxrs:providers>
<bean
class="org.apache.cxf.jaxrs.provider.jsrjsonp.JsrJsonpProvider"/>
</jaxrs:providers>
</pre>
</div></div><p>Adding <strong>JsrJsonpProvider</strong> provider alone (or in
a combination with other providers) allows JAX-RS resources to natively use <a
shape="rect" class="external-link"
href="http://docs.oracle.com/javaee/7/api/javax/json/JsonStructure.html";
rel="nofollow">JsonStructure</a>, <a shape="rect" class="external-link"
href="http://docs.oracle.com/javaee/7/api/javax/json/JsonArray.html";
rel="nofollow">JsonArray</a>, <a shape="rect" class="external-link"
href="http://docs.oracle.com/javaee/7/api/javax/json/JsonObject.html";
rel="nofollow">JsonObject</a> as input parameters or return values. For
example:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">@GET
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@GET
@Path("/books")
@Produces(MediaType.APPLICATION_JSON)
public JsonArray getBooks() {
@@ -438,7 +438,7 @@ public Response addBook(@Context final U
// Implementation here
}</pre>
</div></div><p>The <strong>JsrJsonpProvider</strong> provider could be used on
server side or on a client side. By default, the provider uses <a shape="rect"
class="external-link" href="https://jsonp.java.net/"; rel="nofollow">JSR-353
Java API for JSON Processing reference implementation</a> to read/write message
bodies.</p><h1 id="JAX-RSDataBindings-SimpleJsonMapObjectsupport">Simple
JsonMapObject
support</h1><p>org.apache.cxf.jaxrs.provider.json.JsonMapObjectProvider is
available starting from CXF 3.0.3 and CXF 3.1.0. This provider can read or
write JSON into/from org.apache.cxf.jaxrs.provider.json.JsonMapObject which is
a simple Map wrapper.</p><p>JsonMapObject can detect duplicate JSON sibling
properties which can be useful in certain applications.</p><h1
id="JAX-RSDataBindings-JSONWithPadding(JSONP)">JSON With Padding
(JSONP)</h1><p>One option for supporting "JSON With Padding" (<a shape="rect"
class="external-link" href="http://en.wikipedia.org/wiki/JSONP";
rel="nofollow">JSONP<
/a>) is to extend the default JSONProvider and override its writeTo method as
follows:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">@Produces("application/javascript")
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Produces("application/javascript")
class JsonpProvider extends JSONProvider {
@Override
@@ -458,7 +458,7 @@ class JsonpProvider extends JSONProvider
}
</pre>
</div></div><p>Similar approach can work when Jackson is
used.</p><p>Alternatively, a custom servlet filter can be used to support
JSONP. Please read the <a shape="rect" class="external-link"
href="http://josh.media.berkeley.edu/?p=78"; rel="nofollow">Supporting JSONP</a>
blog post for more information.</p><p>Starting from CXF 2.3.4 and 2.4.0, JSONP
can be supported with the help of CXF in/out interceptors:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><jaxrs:server id="bookJsonp" address="/jsonp">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><jaxrs:server id="bookJsonp" address="/jsonp">
<jaxrs:serviceBeans>
<ref bean="serviceBean" />
</jaxrs:serviceBeans>
@@ -473,7 +473,7 @@ class JsonpProvider extends JSONProvider
</jaxrs:server>
</pre>
</div></div><p>JsonpInInterceptor checks if a JSONP callback query parameter
is available (default is _jsonp) and if yes then it saves its value on the
current exchange for out interceptors to know if they have to write the
paddings or not. The name of the expected callback parameter can be customized.
JsonpPreStreamInterceptor and JsonpPostStreamInterceptor ensure the actual JSON
stream is 'padded' properly. JsonpPreStreamInterceptor will also set
Content-Type to "application/x+javascript" by default but this can be
changed:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><jaxrs:server id="bookJsonp" address="/jsonp">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><jaxrs:server id="bookJsonp" address="/jsonp">
<jaxrs:serviceBeans>
<ref bean="serviceBean" />
</jaxrs:serviceBeans>
@@ -495,7 +495,7 @@ class JsonpProvider extends JSONProvider
</jaxrs:server>
</pre>
</div></div><h1 id="JAX-RSDataBindings-Formpayloads">Form payloads</h1><p>Form
payload is a sequence of name and value pairs, example,
"name=Barry&age=20".<br clear="none"> One can capture the form data by
using either JAX-RS FormParam annotation or MultivaluedMap, for
example:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">import javax.ws.rs.FormParam;
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import javax.ws.rs.FormParam;
import javax.ws.rs.MultivaluedMap;
@Path("resource")
@@ -518,7 +518,7 @@ public class FormResource {
}
</pre>
</div></div><p>Note that it is possible to control the maximum number of the
expected form parameters by setting a "maxFormParameterCount" contextual
property (set within the jaxrs:properties). The client will receive HTTP 413 if
the limit is reached.</p><h1 id="JAX-RSDataBindings-Atom">Atom</h1><p>CXF JAXRS
offers users 3 options for dealing with Atom</p><p>1. Register Apache Abdera
based Feed and/or Entry providers
(org.apache.cxf.jaxrs.ext.provider.atom.AtomFeedProvider and
org.apache.cxf.jaxrs.ext.provider.atom.AtomEntryProvider) with a jaxrs endpoint
and have resource methods explicitly dealing with Abdera Feed or Entry classes.
This is the most advanced option in that it lets users build Feeds or Entries
in the way which suits most. Note that Abdera has not been actively mantained
recently but practically speaking it is very good for working with most of the
cases one may have to deal with when developing Atom-based
applications.</p><p>Both AtomFeedProvider and AtomEntryProvid
er support a 'formattedOutput' (pretty-printing) property.</p><p>2. Register
an <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/extensions/providers/src/main/java/org/apache/cxf/jaxrs/ext/provider/atom/AtomPojoProvider.java";>AtomPojoProvider</a>
injected with either <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/extensions/providers/src/main/java/org/apache/cxf/jaxrs/ext/provider/atom/AtomElementWriter.java";>AtomElementWriter</a>
or <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/extensions/providers/src/main/java/org/apache/cxf/jaxrs/ext/provider/atom/AtomElementReader.java";>AtomElementReader</a>
implementations parameterized by either Abdera Feed or Entry and type of
object which will have to be converted to/read from Feed/Entry.</p><p>For
example, BookAtomElementWriter<Feed, Book> will be responsible for
converting Book instances into Feeds wh
ile ChapterAtomElementWriter<Entry, Chapter> will be responsible for
converting Chapter instances into Entries.</p><p>AtomElementWriter and
AtomElementReader are injected using 'atomWriters' and 'atomReaders' map
properties, where the keys are class names of the objects to be converted
to/read from Feed or Entries, ex
"org.apache.cxf.systest.jaxrs.Book".</p><p>AtomPojoProvider offers users a way
to have no Abdera Feed/Entry classes referenced from the 'main' application
code, example :</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">@Path("books")
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Path("books")
public class BooksRootResource {
private Books books;
@@ -539,7 +539,7 @@ public class BooksRootResource {
}
</pre>
</div></div><p>Note that when an object such as Books is about to be converted
to/read from Feed (which in our case is essentially a collection of entries
each of them representing an individual Book) the AtomPojoProvider needs to
know about the collection getters and/or setters so that it can create
individual Entries. The "collectionGetters" and "collectionSetters" map
properties with keys being the names of collection classes and values being the
method names need to be used for providing this information, example a pair
"org.apache.cxf.systest.jaxrs.Books:getBooks" tells AtomPojoProvider that when
creating a Books Feed, the objects representing individual entries can be
retrieved from Book with the help of "getBooks". If these properties are not
set then AtomPojoProvider will try to get a method adding the simple class name
to either 'get' or 'set', for example, an
"org.apache.cxf.systest.jaxrs.Books:getBooks" pair is redundant if the Books
class has a getBooks method.</p><p>3.
This option is nearly identical to the option 2, except that users configure
AtomPojoProvider with concrete implementations of either <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/extensions/providers/src/main/java/org/apache/cxf/jaxrs/ext/provider/atom/AbstractFeedBuilder.java";>AbstractFeedBuilder</a>
or <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/extensions/providers/src/main/java/org/apache/cxf/jaxrs/ext/provider/atom/AbstractEntryBuilder.java";>AbstractEntryBuilder</a>.</p><p>The
difference is that in this case users have no explicit dependencies in their
code on Atom-aware libraries such as Abdera - it may make it easier to
experiment with various Atom libraries.</p><h1
id="JAX-RSDataBindings-AegisDataBinding">Aegis Data Binding</h1><p>Use
org.apache.cxf.provider.AegisElementProvider to start doing Aegis with
JAX-RS<br clear="none"> org.apache.cxf.provider.AegisJSONProvider can be used
to output JSON with the help of Aegis.<br clear="none"> Similarly to the
default JSONProvider this Aegis-based JSON provider can have "namespaceMap",
"serializeAsArray", "arrayKeys", "dropRootElement" and "writeXsiType"
properties set.</p><h1 id="JAX-RSDataBindings-XMLBeans">XMLBeans</h1><p>Use
org.apache.cxf.provider.XmlBeansElementProvider to start doing XmlBeans with
JAX-RS</p><h1 id="JAX-RSDataBindings-CXFDataBindingsasJAX-RSproviders">CXF
DataBindings as JAX-RS providers</h1><p>Starting from CXF 2.2.3 it is possible
to register a CXF DataBinding bean using a jaxrs:databinding element and it
will be wrappped as a JAXRS MessageBodyReader/Writer <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/provider/DataBindingProvider.java";>DataBindingProvider</a>
capable of dealing with XML-based content. It can be of special interest to
users combining JAX-RS and JAXWS. Thus CXF JAXB, JIBX, Aegis, SDO a
nd XMLBeans DataBindings can be plugged in.</p><p>DataBindingProvider can also
be registered as a jaxrs:provider with its dataBinding property being set as
needed.</p><p>JSON support is also provided for all these databindings by <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/provider/DataBindingJSONProvider.java";>DataBindingJSONProvider</a>.<br
clear="none"> Please see <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/resources/jaxrs_databinding/WEB-INF/beans.xml";>this
configuration file</a> for some examples.</p><p>Similarly to the default
JSONProvider the DataBindingJSONProvider JSON provider can have "namespaceMap",
"serializeAsArray", "arrayKeys", "dropRootElement" and "writeXsiType"
properties set. Additionally it may also have an "ignoreMixedContent" property
set.</p><p>Starting from CXF 2.4.0 and CXF 2.3.2 a CXF <a shape="rec
t" href="annotations.html">DataBinding</a> annotation is also
supported.</p><h1 id="JAX-RSDataBindings-JAXRSDataBinding">JAXRS
DataBinding</h1><p><strong>Available starting from CXF 2.3.2 and CXF
2.4.0</strong></p><p>org.apache.cxf.jaxrs.provider.JAXRSDataBinding is a CXF
DataBinding implementation which wraps JAX-RS providers and can be used by CXF
JAX-WS endpoints thus making it possible to use JAX-RS providers for reading
and writing XML payloads during SOAP and RESTful invocations. Example :</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"> <jaxrs:server id="hello_rest"
address="/hello-rest">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> <jaxrs:server id="hello_rest"
address="/hello-rest">
<jaxrs:serviceBeans>
<bean class="org.apache.cxf.systest.jaxrs.jaxws.HelloWorldImpl"/>
</jaxrs:serviceBeans>
@@ -569,7 +569,7 @@ public class BooksRootResource {
<bean id="jaxbProviderSoap"
class="org.apache.cxf.jaxrs.provider.JAXBElementProvider"/>
</pre>
</div></div><p>This option is similar to the one involving wrapping CXF
DataBindings as JAX-RS providers and using them for handling the data for the
JAX-RS endpoints. This time though it is SOAP endpoints which are relying on
the JAX-RS providers to handle the data properly.</p><p>If you would like to
write your own custom XML provider and have it wrapped by the JAXRSDataBinding
then custom MessageBodyReader and MessageBodyWriter implementations should be
ready to accept null InputStream and OutputStream parameters and retrieve
XMLStreamReader and XMLStreamWriter instances from the current CXF Message. To
make the custom provider as portable as possible, one may want to follow the
following approach :</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">public class PortableXMLProvider implements
MessageBodyReader, MessageBodyWriter {
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public class PortableXMLProvider implements
MessageBodyReader, MessageBodyWriter {
public Object readFrom(Class<Object> type, Type genericType,
Annotation[] anns, MediaType mt,
MultivaluedMap<String, String> headers,
InputStream is)
@@ -631,7 +631,7 @@ public class CXFCustomXMLProvider extend
}
</pre>
</div></div><p>Please note that if you need the advanced DataBinding support
for your JAX-WS endpoints (such as the schema validation with the schemas being
available in the WSDL documents - likely to be supported, un-wrapping the XML
payloads into multiple method parameters) then you are recommended to use one
of the CXF DataBindings supported by CXF JAX-WS endpoints directly.</p><p>If
all the resource methods have a single parameter such as a valid JAXB class and
a response type which is not expected to be wrapped then it is likely this
approach will work.</p><p>When using a CXF JAX-RS JAXBElementProvider, you may
need to tune it to properly handle JAXB classes without XmlRootElement
annotations and optionally create a single JAXBContext, something that CXF
JAXBDataBinding does automatically. Also note that JAXBElementProvider is not
aware that in some cases the local name of the first method parameter is "arg0"
for SOAP requests and the local name of the SOAP response is expected
to be "return". You may need to use JAX-WS WebParam and WebResult annotations
to create different names; alternatively, you can use JAXBElementProvider's
inTransformElements and outTransformElements properties, for example, to have
'arg0' converted to a bean name such as 'User' and 'User' converted to
'return'.</p><h1 id="JAX-RSDataBindings-Schemavalidation">Schema
validation</h1><p><strong>New</strong>: starting from CXF 3.0.0-milestone2 it
is possible to point only to classpath folders containing multiple schema
resources.</p><p>Schema validation can be enabled in one of the following
ways:</p><p>1. Using jaxrs:schemaLocations element</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><beans>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans>
<jaxrs:server address="/"
serviceClass="org.apache.cxf.systest.jaxrs.BookStore">
<jaxrs:schemaLocations>
<jaxrs:schemaLocation>classpath:/schemas/a.xsd</jaxrs:schemaLocation>
@@ -645,7 +645,7 @@ public class CXFCustomXMLProvider extend
</beans>
</pre>
</div></div><p>Using this option is handy when you have multiple bindings
involved which support the schema validation. In this case<br clear="none">
individual MessageBodyReader implementations which have a method
setSchemas(List<Sring> schemaLocations) have it called and locations to
schema resources injected. Default JAXBElementProvider and JSONProvider which
rely on JAXB can be enabled to do the validation this way. In the above example
two schema documents are provided, with b.xsd schema importing a.xsd</p><p>2.
Configuring providers individually</p><p>JAXB and JSON providers can be
configured explicitly, for example:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><beans
xmlns:util="http://www.springframework.org/schema/util">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans
xmlns:util="http://www.springframework.org/schema/util">
<jaxrs:server address="/"
serviceClass="org.apache.cxf.systest.jaxrs.BookStore">
<jaxrs:providers>
<ref bean="jaxbProvider"/>
@@ -663,7 +663,7 @@ public class CXFCustomXMLProvider extend
</beans>
</pre>
</div></div><p>If you have both JAXB and JSON providers validating the input
data then you can get schemas shared between them, for example:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><beans
xmlns:util="http://www.springframework.org/schema/util">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans
xmlns:util="http://www.springframework.org/schema/util">
<jaxrs:server address="/"
serviceClass="org.apache.cxf.systest.jaxrs.BookStore">
<jaxrs:providers>
<ref bean="jaxbProvider"/>
@@ -690,18 +690,18 @@ public class CXFCustomXMLProvider extend
</beans>
</pre>
</div></div><p>3. Using SchemaValidation annotation </p><p>Starting from
CXF 3.0.0 it is possible to use org.apache.cxf.annotations.SchemaValidation
with JAX-RS root resources. Set its optional "schemas" property.</p><h2
id="JAX-RSDataBindings-Supportforcatalogs">Support for
catalogs</h2><p>Available starting from CXF 2.5.5, 2.6.2</p><p>XML Catalogs can
be used for the main schema (which is used to validate the data) to get the
imported or included schema resources resolved locally.<br clear="none"> By
default, a "META-INF/jax-rs-catalog.xml" will be checked however the catalog
location can be set either on JAXBElementProvider or JSONProvider:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><bean id="jaxbProvider"
class="org.apache.cxf.jaxrs.provider.JAXBElementProvider">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><bean id="jaxbProvider"
class="org.apache.cxf.jaxrs.provider.JAXBElementProvider">
<property name="catalogLocation"
value="classpath:/schemas/mycatalog.xml"/>
</bean>
</pre>
</div></div><p>where mycatalog.xml may look like this:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><catalog
xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" prefer="system">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><catalog
xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" prefer="system">
<system systemId="http://schemas/bookid.xsd";
uri="classpath:WEB-INF/schemas/bookid.xsd"/>
</catalog>
</pre>
</div></div><h2 id="JAX-RSDataBindings-Outputvalidation">Output
validation</h2><p>By default, after a valid schema has been located, only JAXB
Unmarshaller will use it to validate the input.<br clear="none"> Starting from
CXF 2.3.4 and 2.4, the following properties can be used to enable the output
validation:</p><ul
class="alternate"><li>validateOutput</li><li>validateBeforeWrite</li></ul><p>Setting
the 'validateOutput' property will ensure that JAXBMarshaller will validate
the output while writing the data. The 'validateBeforeWrite' property can be
set to ensure the validation is done before data are written to the output
stream.</p><h1 id="JAX-RSDataBindings-BeanValidation">Bean
Validation</h1><p>Bean Validation can be used to complement the schema
validation or as an alternative form of validation, please see <a shape="rect"
href="http://cxf.apache.org/docs/validationfeature.html";>this page</a> for more
information.</p><h1 id="JAX-RSDataBindings-FastInfoset">Fast Infoset</h1><p>Y
ou can enable the <a shape="rect" class="external-link"
href="https://fi.dev.java.net/standardization.html";
rel="nofollow">FastInfoset</a> by explicitly registering CXF FastInfoset
interceptors with a JAXRS endpoint and configuring JAXBElementProvider to
support an "application/fastinfoset" media type :<br clear="none"> for example
:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><jaxrs:server id="restservice3" address="/rest3">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><jaxrs:server id="restservice3" address="/rest3">
<jaxrs:serviceBeans>
<ref bean="bookstore"/>
Modified: websites/production/cxf/content/docs/jax-rs-deployment.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-deployment.html (original)
+++ websites/production/cxf/content/docs/jax-rs-deployment.html Wed Sep 13
15:05:52 2017
@@ -120,11 +120,11 @@ Apache CXF -- JAX-RS Deployment
 </p><p> </p><p> </p><p> </p><p> </p><p><style
type="text/css">/*<![CDATA[*/
-div.rbtoc1505311267847 {padding: 0px;}
-div.rbtoc1505311267847 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1505311267847 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1505314981146 {padding: 0px;}
+div.rbtoc1505314981146 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1505314981146 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1505311267847">
+/*]]>*/</style></p><div class="toc-macro rbtoc1505314981146">
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSDeployment-SpringBoot">Spring Boot</a></li><li><a shape="rect"
href="#JAX-RSDeployment-ServletContainers">Servlet Containers</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSDeployment-Tomcat">Tomcat</a></li></ul>
</li><li><a shape="rect"
href="#JAX-RSDeployment-ApplicationServers">Application Servers</a>
@@ -135,19 +135,19 @@ div.rbtoc1505311267847 li {margin-left:
</li></ul>
</li></ul>
</div><p>This page provides the tips on how to deploy CXF JAX-RS applications
packaged as WAR archives or OSGI bundles into Java EE application servers and
OSGI containers.</p><h1 id="JAX-RSDeployment-SpringBoot">Spring
Boot</h1><p>Please see CXF <a shape="rect"
href="springboot.html">SpringBoot</a> documenation. </p><p>Please
see <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/jaxrs_spring_boot";
rel="nofollow">JAX-RS Spring Boot</a> and <a shape="rect"
class="external-link"
href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/jaxrs_spring_boot_scan";
rel="nofollow">JAX-RS Spring Boot Scan</a> demos.</p><h1
id="JAX-RSDeployment-ServletContainers">Servlet Containers</h1><h2
id="JAX-RSDeployment-Tomcat">Tomcat</h2><p>1. System
"org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH"<br clear="none"> and
"org.apache.catalina.conne
ctor.CoyoteAdapter.ALLOW_BACKSLASH" properties may have to be set to "true" to
support URIs containing encoded forward or backward slashes.<br clear="none">
2. When using mod_jk - ensure that the JkOptions setting has
+ForwardURICompatUnparsed set. <br clear="none"> 3. Windows: upgrade
isapi_redirect.dll if you see URI containing encoded spaces being decoded by
Tomcat.</p><h1 id="JAX-RSDeployment-ApplicationServers">Application
Servers</h1><h2
id="JAX-RSDeployment-Glassfish">Glassfish</h2><p><strong>Verified with
Glassfish Server Open Source Edition 3.1.1</strong></p><p>1. Make sure a
cxf-rt-transport-http-jetty dependency is excluded during the war
build</p><p>2. If a custom JAX-RS <a shape="rect" class="external-link"
href="http://jsr311.java.net/nonav/releases/1.1/index.html";
rel="nofollow">Application</a> is included then<br clear="none"> use a <a
shape="rect"
href="http://cxf.apache.org/docs/jaxrs-services-configuration.html#JAXRSServicesConfiguration-ConfiguringJAXRSservicesin
containerwithoutSpring">CXFNonSpringJaxrsServlet</a> to reference the
Application implementation class and either <br clear="none"> 2.1 Disable the
Jersey scanning the custom web applications. Setting the following system
property may help:<br clear="none">
"-Dcom.sun.enterprise.overrideablejavaxpackages=javax.ws.rs,javax.ws.rs.core,javax.ws.rs.ext"</p><p>2.2
Remove jersey-gf-server.jar from $GLASSFISH_HOME/glassfish/modules</p><h2
id="JAX-RSDeployment-JBoss">JBoss</h2><p><strong>Verified with JBoss AS
7.1.0.CR1b</strong></p><p>1. If a custom JAX-RS <a shape="rect"
class="external-link"
href="http://jsr311.java.net/nonav/releases/1.1/index.html";
rel="nofollow">Application</a> is included then<br clear="none"> use a <a
shape="rect"
href="http://cxf.apache.org/docs/jaxrs-services-configuration.html#JAXRSServicesConfiguration-ConfiguringJAXRSservicesincontainerwithoutSpring";>CXFNonSpringJaxrsServlet</a>
to reference the Application implementation class and either</p><p>1.1 Disable
the
RestEasy scanning the custom web applications (TODO: specify how this actually
can be done)<br clear="none"> 1.2 Modify
$JBOSS_HOME/standalone/configuration/standalone.xml by commenting out a
"org.jboss.as.jaxrs" extension and a "urn:jboss:domain:jaxrs:1.0"
sybsystem.</p><p>2. JBoss does not support URI path slashes by default: <a
shape="rect" class="external-link" href="http://securitytracker.com/id/1018110";
rel="nofollow">http://securitytracker.com/id/1018110</a></p><h2
id="JAX-RSDeployment-WebLogic">WebLogic</h2><p><strong>Verified with WebLogic
Server 12c (12.1.1)</strong></p><h3
id="JAX-RSDeployment-SpecifyingaWebLogicspecificJSPservlet">Specifying a
WebLogic specific JSP servlet</h3><p>If you configure CXFServlet to redirect to
custom JSP pages then you need to add the following declaration to
web.xml:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><servlet>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><servlet>
<servlet-name>jsp</servlet-name>
<servlet-class>weblogic.servlet.JSPServlet</servlet-class>
</servlet>
</pre>
</div></div><h3 id="JAX-RSDeployment-CXFRuntimeDelegate">CXF
RuntimeDelegate</h3><p>Add a "prefer-application-packages" block in
weblogic.xml, including the package "javax.ws.rs.*", for CXF RuntimeDelegate be
visible after the application has been redeployed</p><h3
id="JAX-RSDeployment-SelectingWoodstoxasthedefaultparser">Selecting Woodstox as
the default parser</h3><p>WebLogic requires the following update to the
proprietary deployment descriptor weblogic.xml:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"> <container-descriptor>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> <container-descriptor>
<!-- SNIP -->
<prefer-web-inf-classes>true</prefer-web-inf-classes>
</container-descriptor>
</pre>
</div></div><p>This instructs WebLogic's classloaders to look FIRST in the
JARS from the application's WEB-INF/lib directory for Service Provider
Implementations (in this case, to find
META-INF/services/javax.xml.stream.XMLInputFactory in the Woodstox JAR) rather
than to the system classloader.<br clear="none"> Please see this <a
shape="rect" class="external-link"
href="https://forums.oracle.com/forums/message.jspa?messageID=9953045";
rel="nofollow">thread</a> for more information.</p><h3
id="JAX-RSDeployment-DowngradingServletversion">Downgrading Servlet
version</h3><p>It was reported that downgrading a web-app descriptor version in
web.xml can help disable the native (Jersey) scanning:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"> <!-- From: -->
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> <!-- From: -->
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/j2ee";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
@@ -160,7 +160,7 @@ div.rbtoc1505311267847 li {margin-left:
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
</web-app></pre>
</div></div><h3 id="JAX-RSDeployment-Removingmyfaces-shared-impljar">Removing
myfaces-shared-impl jar</h3><p>It was reported if myfaces-shared-impl-4.1.0.jar
is shipped in a web application lib folder then removing it helps, with the
following descriptor being effective:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><weblogic-web-app>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><weblogic-web-app>
<context-root>/emessaging</context-root>
<container-descriptor>
<prefer-web-inf-classes>false</prefer-web-inf-classes>
Modified: websites/production/cxf/content/docs/jax-rs-failover.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-failover.html (original)
+++ websites/production/cxf/content/docs/jax-rs-failover.html Wed Sep 13
15:05:52 2017
@@ -32,8 +32,8 @@
<link type="text/css" rel="stylesheet"
href="/resources/highlighter/styles/shThemeCXF.css">
<script src='/resources/highlighter/scripts/shCore.js'></script>
-<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
<script src='/resources/highlighter/scripts/shBrushXml.js'></script>
+<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
<script>
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -121,18 +121,18 @@ Apache CXF -- JAX-RS Failover
 </p><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1505311228113 {padding: 0px;}
-div.rbtoc1505311228113 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1505311228113 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1505314843926 {padding: 0px;}
+div.rbtoc1505314843926 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1505314843926 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1505311228113">
+/*]]>*/</style></p><div class="toc-macro rbtoc1505314843926">
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSFailover-Failover">Failover</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSFailover-Spring">Spring</a></li><li><a shape="rect"
href="#JAX-RSFailover-Code">Code</a></li></ul>
</li><li><a shape="rect"
href="#JAX-RSFailover-CircuitBreakersFailover">Circuit Breakers Failover</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSFailover-Spring.1">Spring</a></li><li><a shape="rect"
href="#JAX-RSFailover-Code.1">Code</a></li></ul>
</li><li><a shape="rect" href="#JAX-RSFailover-LoadDistribution">Load
Distribution</a></li></ul>
</div><p>Starting from CXF 2.4.1, CXF JAX-RS clients can be configured for
them to become failover-capable.<br clear="none"> Core CXF Failover and Load
Distribution features are supported.</p><h1
id="JAX-RSFailover-Failover">Failover</h1><p>Proxies and WebClients can be
configured to failover to alternate addresses in case of connection-related
failures.<br clear="none"> Sequential and Random strategies are supported and
implementers can build more sophisticated failover features by retrieving<br
clear="none"> alternate addresses from locators and other
intermediaries.</p><h2 id="JAX-RSFailover-Spring">Spring</h2><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xmlns:jaxrs="http://cxf.apache.org/jaxrs";
xmlns:clustering="http://cxf.apache.org/clustering";
@@ -191,7 +191,7 @@ factory-method="createWebClient">
</beans>
</pre>
</div></div><h2 id="JAX-RSFailover-Code">Code</h2><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">org.apache.cxf.jaxrs.features.clustering.FailoverFeature
feature =
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">org.apache.cxf.jaxrs.features.clustering.FailoverFeature
feature =
new org.apache.cxf.jaxrs.features.clustering.FailoverFeature();
List<String> alternateAddresses = new ArrayList<String>();
// addresses are alternate addresses provided at start-up
@@ -214,7 +214,7 @@ bean.create(BookStore.class);
bean.createWebClient();
</pre>
</div></div><h1 id="JAX-RSFailover-CircuitBreakersFailover">Circuit Breakers
Failover</h1><p>The recent addition to CXF failover features is the
implementation based on circuit breakers, more precisely Apache Zest (<a
shape="rect" class="external-link"
href="https://zest.apache.org/";>https://zest.apache.org/</a>) library. It is
available starting from CXF 3.2.0.</p><p>The configuration is very similar to
the regular failover strategy, the only difference is usage of<strong>
clustering:circuit-breaker-failover</strong> element.</p><h2
id="JAX-RSFailover-Spring.1">Spring</h2><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xmlns:jaxrs="http://cxf.apache.org/jaxrs";
xmlns:clustering="http://cxf.apache.org/clustering";
@@ -272,7 +272,7 @@ factory-method="createWebClient">
</bean>
</beans></pre>
</div></div><p>Circuit breakers have recommended themselves as a proven
strategy to handle and monitor the failures related to external service calls,
giving the external systems a time to recover by preventing endless retries or
time-outing. For that reason, two configuration parameters could be
tuned:</p><ul><li><strong>threshold</strong>: the error threshold to open the
circuit breaker</li><li><strong>timeout</strong>: the timeout to wait before
trying the next invocation</li></ul><h2
id="JAX-RSFailover-Code.1">Code</h2><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">org.apache.cxf.jaxrs.features.clustering.CircuitBreakerFailoverFeature
feature =
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">org.apache.cxf.jaxrs.features.clustering.CircuitBreakerFailoverFeature
feature =
new
org.apache.cxf.jaxrs.features.clustering.CircuitBreakerFailoverFeature(1,
60000);
List<String> alternateAddresses = new ArrayList<String>();
// addresses are alternate addresses provided at start-up
@@ -294,7 +294,7 @@ bean.create(BookStore.class);
// create web client
bean.createWebClient();</pre>
</div></div><h1 id="JAX-RSFailover-LoadDistribution">Load
Distribution</h1><p>CXF Load Distribution feature is a failover feature which
can iterate where alternate addresses not only in case of failures but also
after a successful invocation has been done.</p><p>Example:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xmlns:jaxrs="http://cxf.apache.org/jaxrs";
xmlns:clustering="http://cxf.apache.org/clustering";
@@ -329,7 +329,7 @@ http://www.springframework.org/schema/ut
</jaxrs:client>
</pre>
</div></div><p>the selector can be set from code like this:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">org.apache.cxf.jaxrs.features.clustering.FailoverFeature
feature =
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">org.apache.cxf.jaxrs.features.clustering.FailoverFeature
feature =
new org.apache.cxf.jaxrs.features.clustering.FailoverFeature();
feature.setSelector(new
org.apache.cxf.clustering.LoadDistributorTargetSelector());
</pre>
Modified: websites/production/cxf/content/docs/jax-rs-filters.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-filters.html (original)
+++ websites/production/cxf/content/docs/jax-rs-filters.html Wed Sep 13
15:05:52 2017
@@ -32,8 +32,8 @@
<link type="text/css" rel="stylesheet"
href="/resources/highlighter/styles/shThemeCXF.css">
<script src='/resources/highlighter/scripts/shCore.js'></script>
-<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
<script src='/resources/highlighter/scripts/shBrushXml.js'></script>
+<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
<script>
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -121,18 +121,18 @@ Apache CXF -- JAX-RS Filters
 </p><p> </p><p> </p><p> </p><p> </p><p><style
type="text/css">/*<![CDATA[*/
-div.rbtoc1505311226316 {padding: 0px;}
-div.rbtoc1505311226316 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1505311226316 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1505314873441 {padding: 0px;}
+div.rbtoc1505314873441 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1505314873441 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1505311226316">
+/*]]>*/</style></p><div class="toc-macro rbtoc1505314873441">
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSFilters-Filters">Filters</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSFilters-DifferencebetweenJAXRSfiltersandCXFinterceptors">Difference
between JAXRS filters and CXF interceptors</a></li></ul>
</li><li><a shape="rect"
href="#JAX-RSFilters-Overridingrequestandresponseproperties">Overriding request
and response properties</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSFilters-OverridingHTTPmethod">Overriding HTTP
method</a></li><li><a shape="rect"
href="#JAX-RSFilters-OverridingrequestURI,queryandheaders">Overriding request
URI, query and headers</a></li><li><a shape="rect"
href="#JAX-RSFilters-Overridingresponsestatuscodeandheaders">Overriding
response status code and headers</a></li></ul>
</li><li><a shape="rect"
href="#JAX-RSFilters-IgnoringJAXRSMessageBodyWriters">Ignoring JAXRS
MessageBodyWriters</a></li><li><a shape="rect"
href="#JAX-RSFilters-Custominvokers">Custom invokers</a></li></ul>
</div><h1 id="JAX-RSFilters-Filters">Filters</h1><p>Often it's necessary to
pre- or post-process some requests according to a number of requirements.<br
clear="none"> For example, a request like</p><p>GET /resource?_type=xml is
supported by a CXF specific RequestPreprocessor code which modifies an input
message <br clear="none"> by updating one of its headers.</p><p>A standard
mechanism for updating the request or response properties is to use JAX-RS 2.0
ContainerRequestFilter or
ContainerResponseFilter.</p><p>ContainerRequestFilters with a @PreMatching
annotation are run before the JAX-RS resource selection process starts.
PreMatching filters should be used to modify request URI or headers or input
stream. Post-matching filters are run just before a selected resource method is
executed.</p><p>Multiple ContainerRequestFilter and ContainerResponseFilter
filters can be ordered using a @Priority annotation.</p><p> </p><p>The
implementations can be registered like any other type of
providers :</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><beans>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans>
<jaxrs:server id="customerService" address="/">
<jaxrs:serviceBeans>
<bean class="org.CustomerService" />
@@ -148,7 +148,7 @@ div.rbtoc1505311226316 li {margin-left:
</beans>
</pre>
</div></div><h2
id="JAX-RSFilters-DifferencebetweenJAXRSfiltersandCXFinterceptors">Difference
between JAXRS filters and CXF interceptors</h2><p>JAXRS runtime flow is mainly
implemented by a pair of 'classical' CXF interceptors. JAXRSInInterceptor is
currently at Phase.UNMARSHAL (was at Phase.PRE_STREAM before CXF 2.2.2) phase
while JAXRSOutInterceptor is currently at Phase.MARSHAL phase.</p><p>JAXRS
filters can be thought of as additional handlers. JAXRSInInterceptor deals with
a chain of Pre and Post Match ContainerRequestFilters, just before the
invocation. JAXRSOutInterceptor deals with a chain of ContainerResponseFilters,
just after the invocation but before message body writers get their
chance.</p><p>Sometimes you may want to use CXF interceptors rather than
writing JAXRS filters. For example, suppose you combine JAXWS and JAXRS and you
need to log only inbound or outbound messages. You can reuse the existing CXF
interceptors :</p><div class="code panel pdl" style="border-widt
h: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><beans>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans>
<bean id="logInbound"
class="org.apache.cxf.interceptor.LoggingInInterceptor"/>
<bean id="logOutbound"
class="org.apache.cxf.interceptor.LoggingOutInterceptor"/>
@@ -173,12 +173,12 @@ div.rbtoc1505311226316 li {margin-left:
</beans>
</pre>
</div></div><p>Reusing other CXF interceptors/features such as GZIP handlers
can be useful too.</p><h1
id="JAX-RSFilters-Overridingrequestandresponseproperties">Overriding request
and response properties</h1><p>Now and then one needs to overwrite various
request and response properties like HTTP method or request URI, <br
clear="none"> response headers or status codes and even the request or response
body. JAX-RS Response may be used to specify custom status and response headers
but it might be intrusive to add it to method signatures.</p><p>Using filters
and interceptors makes it possible to override all the needed request/response
properties.</p><h2 id="JAX-RSFilters-OverridingHTTPmethod">Overriding HTTP
method</h2><p>Use @PreMatching ContainerRequestFilter or register a custom CXF
in intrerceptor filter which will replace the current method value keyed by <br
clear="none"> Message.HTTP_REQUEST_METHOD in a given Message.</p><h2
id="JAX-RSFilters-OverridingrequestURI,queryandheader
s">Overriding request URI, query and headers</h2><p>One can do it either from
@PreMatching ContainerRequestFilter or CXF input interceptor (registered at the
early phase like USER_STREAM), for example :</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">String s = m.get(Message.REQUEST_URI);
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">String s = m.get(Message.REQUEST_URI);
s += "/data/";
m.put(Message.REQUEST_URI, s);
</pre>
</div></div><p>If the updated Request URI has a new query string, then you
also need to update a Message.QUERY_STRING property.</p><p>Similarly, one can
update request HTTP headers, by modifying a Message.REQUEST_HEADERS Message
object which is a Map containing String and List of Strings entries.</p><h2
id="JAX-RSFilters-Overridingresponsestatuscodeandheaders">Overriding response
status code and headers</h2><p>It is assumed here a user prefers not to use
explicit Response objects in the application code.<br clear="none"> This can be
done either from ContainerResponseFilter or CXF output interceptor (phase like
MARSHALL will do), for example this code will work for both JAXRS and JAXWS
:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">import java.util.Map;
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import java.util.Map;
import java.util.TreeMap;
import org.apache.cxf.message.Message;
@@ -202,10 +202,10 @@ public class CustomOutInterceptor extend
}
</pre>
</div></div><p>At the moment it is not possible to override a response status
code from a CXF interceptor running before JAXRSOutInterceptor, like
CustomOutInterceptor above, which will be fixed.<br clear="none"> The only
option at the moment is to use a custom ResponseHandler which will replace the
current Response object with another one containing the required status.</p><h1
id="JAX-RSFilters-IgnoringJAXRSMessageBodyWriters">Ignoring JAXRS
MessageBodyWriters</h1><p>In some cases you may want to have a JAXRS Response
entity which a given filter has produced to be directly written to the output
stream. For example, a CXF JAXRS WADLGenerator filter produces an XML content
which does not have to be serialized by JAXRS MessageBodyWriters. If you do
need to have the writers ignored then set the following property on the current
exchange in the custom handler :</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">message.getExchange().put("ignore.message.writers",
true);
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">message.getExchange().put("ignore.message.writers",
true);
</pre>
</div></div><h1 id="JAX-RSFilters-Custominvokers">Custom
invokers</h1><p><strong>Note</strong> This feature is available starting from
CXF 2.2.2</p><p>Using custom JAXR-RS invokers is yet another way to pre or post
process a given invocation. For example, this <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/CustomJAXRSInvoker.java";>invoker</a>
does a security check before delegating to the default JAXRS invoker. A custom
invoker, like a request filter, has the access to all the information
accumulated during the processing of a given call, but additionally, it can
also check the actual method parameter values.</p><p>Custom invokers can be
registered like this :</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><beans>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans>
<jaxrs:server address="/">
<jaxrs:invoker>
