cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache CXF Documentation > JAX-RS Data Bindings
Date Thu, 13 Sep 2012 15:26:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/1/_/styles/combined.css?spaceKey=CXF20DOC&amp;forWysiwyg=true" type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/CXF20DOC/JAX-RS+Data+Bindings">JAX-RS Data Bindings</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~mazzag">Glen Mazza</a>
    </h4>
        <div id="versionComment">
        <b>Comment:</b>
        wikipedia link to jsonp added<br />
    </div>
        <br/>
                         <h4>Changes (2)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >{code} <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >h1. JSON With Padding <span class="diff-added-words"style="background-color: #dfd;">(JSONP)</span> <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" >One option for supporting <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">a</span> &quot;JSON With Padding&quot; <span class="diff-changed-words">(<span class="diff-added-chars"style="background-color: #dfd;">[</span>JSONP<span class="diff-added-chars"style="background-color: #dfd;">|http://en.wikipedia.org/wiki/JSONP]</span>)</span> is to extend the default JSONProvider and override its writeTo method as follows: <br></td></tr>
            <tr><td class="diff-unchanged" >{code:java} <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <p><span style="font-size:2em;font-weight:bold"> JAX-RS : Data Bindings </span></p>

<div>
<ul>
    <li><a href='#JAX-RSDataBindings-JAXBsupport'>JAXB support</a></li>
<ul>
    <li><a href='#JAX-RSDataBindings-ConfiguringJAXBprovider'>Configuring JAXB provider</a></li>
    <li><a href='#JAX-RSDataBindings-JAXBandMoxy'>JAXB and Moxy</a></li>
</ul>
    <li><a href='#JAX-RSDataBindings-JSONsupport'>JSON support</a></li>
<ul>
    <li><a href='#JAX-RSDataBindings-Jettison'>Jettison</a></li>
<ul>
    <li><a href='#JAX-RSDataBindings-ConfiguringJSONprovider'>Configuring JSON provider</a></li>
    <li><a href='#JAX-RSDataBindings-DealingwithJSONarrayserializationissues'>Dealing with JSON array serialization issues</a></li>
    <li><a href='#JAX-RSDataBindings-BadgerFishconvention'>BadgerFish convention</a></li>
    <li><a href='#JAX-RSDataBindings-WrappingandUnwrappingJSONsequences'>Wrapping and Unwrapping JSON sequences</a></li>
    <li><a href='#JAX-RSDataBindings-TypeConverters'>TypeConverters</a></li>
</ul>
    <li><a href='#JAX-RSDataBindings-Jackson'>Jackson</a></li>
</ul>
    <li><a href='#JAX-RSDataBindings-CommonJAXBandJSONconfiguration'>Common JAXB and JSON configuration</a></li>
<ul>
    <li><a href='#JAX-RSDataBindings-SingleJAXBContextandextrauserclasses'>Single JAXBContext and extra user classes</a></li>
    <li><a href='#JAX-RSDataBindings-AutomaticJAXBElementconversionduringserialization'>Automatic JAXBElement conversion during serialization</a></li>
    <li><a href='#JAX-RSDataBindings-HandlingJAXBbeanswithoutXmlRootElementannotations'>Handling JAXB beans without XmlRootElement annotations</a></li>
    <li><a href='#JAX-RSDataBindings-Handlingexplicitcollections'>Handling explicit collections</a></li>
</ul>
    <li><a href='#JAX-RSDataBindings-CustomizingJAXBXMLandJSONinputandoutput'>Customizing JAXB XML and JSON input and output</a></li>
    <li><a href='#JAX-RSDataBindings-ControllingLargeJAXBXMLandJSONinputpayloads'>Controlling Large JAXB XML and JSON input payloads</a></li>
    <li><a href='#JAX-RSDataBindings-JSONWithPadding%28JSONP%29'>JSON With Padding (JSONP)</a></li>
    <li><a href='#JAX-RSDataBindings-Formpayloads'>Form payloads</a></li>
    <li><a href='#JAX-RSDataBindings-Atom'>Atom</a></li>
    <li><a href='#JAX-RSDataBindings-AegisDataBinding'>Aegis Data Binding</a></li>
    <li><a href='#JAX-RSDataBindings-XMLBeans'>XMLBeans</a></li>
    <li><a href='#JAX-RSDataBindings-CXFDataBindingsasJAXRSproviders'>CXF DataBindings as JAX-RS providers</a></li>
    <li><a href='#JAX-RSDataBindings-JAXRSDataBinding'>JAXRS DataBinding</a></li>
    <li><a href='#JAX-RSDataBindings-Schemavalidation'>Schema validation</a></li>
<ul>
    <li><a href='#JAX-RSDataBindings-Supportforcatalogs'>Support for catalogs</a></li>
    <li><a href='#JAX-RSDataBindings-Outputvalidation'>Output validation</a></li>
</ul>
    <li><a href='#JAX-RSDataBindings-FastInfoset'>Fast Infoset</a></li>
</ul></div>

<h1><a name="JAX-RSDataBindings-JAXBsupport"></a>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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
@XmlRootElement(name = <span class="code-quote">"Customer"</span>)
<span class="code-keyword">public</span> class Customer {
    <span class="code-keyword">private</span> <span class="code-object">String</span> name;
    <span class="code-keyword">private</span> <span class="code-object">long</span> id;

    <span class="code-keyword">public</span> Customer() {
    }

    <span class="code-keyword">public</span> void setName(<span class="code-object">String</span> n) {
        name = n;
    }

    <span class="code-keyword">public</span> <span class="code-object">String</span> getName() {
        <span class="code-keyword">return</span> name;
    }

    <span class="code-keyword">public</span> void setId(<span class="code-object">long</span> i) {
        id = i;
    }

    <span class="code-keyword">public</span> <span class="code-object">long</span> getId() {
        <span class="code-keyword">return</span> id;
    }
}
</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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
@Path(<span class="code-quote">"/customerservice/"</span>)
<span class="code-keyword">public</span> class CustomerService {
    @GET
    @Path(<span class="code-quote">"/customers/{customerId}/"</span>)
    <span class="code-keyword">public</span> Customer getCustomer(@PathParam(<span class="code-quote">"customerId"</span>) <span class="code-object">String</span> id) {
        ....
    }
}
</pre>
</div></div>
<p>The wire representation of Customer object is:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;Customer&gt;</span>
    <span class="code-tag">&lt;id&gt;</span>123<span class="code-tag">&lt;/id&gt;</span>
    <span class="code-tag">&lt;name&gt;</span>John<span class="code-tag">&lt;/name&gt;</span>
<span class="code-tag">&lt;/Customer&gt;</span>
</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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
@XmlRootElement(name = <span class="code-quote">"Customers"</span>)
<span class="code-keyword">public</span> class Customers {
    <span class="code-keyword">private</span> Collection&lt;Customer&gt; customers;

    <span class="code-keyword">public</span> Collection&lt;Customer&gt; getCustomer() {
        <span class="code-keyword">return</span> customers;
    }

    <span class="code-keyword">public</span> void setCustomer(Collection&lt;Customer&gt; c) {
        <span class="code-keyword">this</span>.customers = c;
    }
}
@Path(<span class="code-quote">"/customerservice/"</span>)
<span class="code-keyword">public</span> class CustomerService {
    @GET
    @Path(<span class="code-quote">"/customers/"</span>)
    <span class="code-keyword">public</span> Customers getCustomers() {
        ....
    }
}
</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><a name="JAX-RSDataBindings-ConfiguringJAXBprovider"></a>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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;beans <span class="code-keyword">xmlns:util</span>=<span class="code-quote">"http://www.springframework.org/schema/util"</span>&gt;</span>
<span class="code-tag">&lt;bean id=<span class="code-quote">"jaxbProvider"</span> class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.JAXBElementProvider"</span>&gt;</span>
<span class="code-tag">&lt;property name=<span class="code-quote">"marshallerProperties"</span> ref=<span class="code-quote">"propertiesMap"</span>/&gt;</span>
<span class="code-tag">&lt;/bean&gt;</span>
<span class="code-tag">&lt;util:map id=<span class="code-quote">"propertiesMap"</span>&gt;</span>
<span class="code-tag">&lt;entry key=<span class="code-quote">"jaxb.formatted.output"</span>&gt;</span>
   <span class="code-tag">&lt;value type=<span class="code-quote">"java.lang.Boolean"</span>&gt;</span>true<span class="code-tag">&lt;/value&gt;</span>
<span class="code-tag">&lt;/entry&gt;</span>
<span class="code-tag">&lt;/util:map&gt;</span>
/<span class="code-tag">&lt;beans&gt;</span>
</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 &#64;Consume and &#64;Produce media types can be injected, see <a href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/resources/jaxrs/WEB-INF/beans.xml" class="external-link" rel="nofollow">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 for 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><a name="JAX-RSDataBindings-JAXBandMoxy"></a>JAXB and Moxy</h2>

<p>For JAXBElementProvider to support <a href="http://www.eclipse.org/eclipselink/moxy.php" class="external-link" rel="nofollow">Moxy</a> a custom Moxy-aware JAX-RS ContextProvider implementation needs to be registered. <br/>
If Moxy is used to handle beans without JAXB annotations then setting a 'skipJaxbChecks' property on JAXBElementProvider to 'true' will be needed. </p>

<h1><a name="JAX-RSDataBindings-JSONsupport"></a>JSON support</h1>

<p>Following code returns a Customer object that is marshaled to JSON format:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
@Path(<span class="code-quote">"/customerservice/"</span>)
<span class="code-keyword">public</span> class CustomerService {
    @Produces(<span class="code-quote">"application/json"</span>)
    @GET
    @Path(<span class="code-quote">"/customers/{customerId}/"</span>)
    <span class="code-keyword">public</span> Customer getCustomer(@PathParam(<span class="code-quote">"customerId"</span>) <span class="code-object">String</span> id) {
        ....
    }
</pre>
</div></div>

<h2><a name="JAX-RSDataBindings-Jettison"></a>Jettison</h2>

<h3><a name="JAX-RSDataBindings-ConfiguringJSONprovider"></a>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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;beans <span class="code-keyword">xmlns:util</span>=<span class="code-quote">"http://www.springframework.org/schema/util"</span>&gt;</span>
<span class="code-tag">&lt;bean id=<span class="code-quote">"jaxbProvider"</span> class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.json.JSONProvider"</span>&gt;</span>
<span class="code-tag">&lt;property name=<span class="code-quote">"namespaceMap"</span> ref=<span class="code-quote">"jsonNamespaceMap"</span>/&gt;</span>
<span class="code-tag">&lt;/bean&gt;</span>
<span class="code-tag">&lt;util:map id=<span class="code-quote">"jsonNamespaceMap"</span> map-class=<span class="code-quote">"java.util.Hashtable"</span>&gt;</span>
<span class="code-tag">&lt;entry key=<span class="code-quote">"http://www.example.org/books"</span> value=<span class="code-quote">"b"</span>/&gt;</span>
<span class="code-tag">&lt;/util:map&gt;</span>
/<span class="code-tag">&lt;beans&gt;</span>
</pre>
</div></div>

<p><b>Note</b> 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 &#64;Consume and &#64;Produce media types can be injected, see <a href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/resources/jaxrs/WEB-INF/beans.xml" class="external-link" rel="nofollow">this example</a> and "Customizing media types for message body providers" and "Schema Validation" sections for more information. </p>

<h3><a name="JAX-RSDataBindings-DealingwithJSONarrayserializationissues"></a>Dealing with JSON array serialization issues </h3>

<p>There is a well known problem in the JSON community which shows itself in the wrong serialization of 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 href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/resources/jaxrs/WEB-INF/beans.xml" class="external-link" rel="nofollow">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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
@XmlRootElement()
@XmlType(name = <span class="code-quote">"", propOrder = {"</span>title<span class="code-quote">", "</span>comments" })
<span class="code-keyword">public</span> <span class="code-keyword">static</span> class Post {
    <span class="code-keyword">private</span> <span class="code-object">String</span> title;
    <span class="code-keyword">private</span> List&lt;Comment&gt; comments = <span class="code-keyword">new</span> ArrayList&lt;Comment&gt;();
    <span class="code-keyword">public</span> void setTitle(<span class="code-object">String</span> title) {
        <span class="code-keyword">this</span>.title = title;
    }
    <span class="code-keyword">public</span> <span class="code-object">String</span> getTitle() {
        <span class="code-keyword">return</span> title;
    }
    <span class="code-keyword">public</span> void setComments(List&lt;Comment&gt; comments) {
        <span class="code-keyword">this</span>.comments = comments;
    }
    <span class="code-keyword">public</span> List&lt;Comment&gt; getComments() {
        <span class="code-keyword">return</span> comments;
    }
}
   
<span class="code-keyword">public</span> <span class="code-keyword">static</span> class Comment {
     <span class="code-keyword">private</span> <span class="code-object">String</span> title;

     <span class="code-keyword">public</span> void setTitle(<span class="code-object">String</span> title) {
        <span class="code-keyword">this</span>.title = title;
     }

     <span class="code-keyword">public</span> <span class="code-object">String</span> getTitle() {
         <span class="code-keyword">return</span> title;
     }
} 
</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>&gt; {"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>

<h3><a name="JAX-RSDataBindings-BadgerFishconvention"></a>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><a name="JAX-RSDataBindings-WrappingandUnwrappingJSONsequences"></a>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 property 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><a name="JAX-RSDataBindings-TypeConverters"></a>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><a name="JAX-RSDataBindings-Jackson"></a>Jackson</h2>

<p>If you prefer working with Jackson JSON providers then register either JacksonJsonProvider:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;jaxrs:providers&gt;</span>
   <span class="code-tag">&lt;bean class=<span class="code-quote">"org.codehaus.jackson.jaxrs.JacksonJsonProvider"</span>/&gt;</span>
<span class="code-tag">&lt;/jaxrs:providers&gt;</span>
</pre>
</div></div>

<p>or JacksonJaxbJsonProvider (when working with JAXB beans):</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;jaxrs:providers&gt;</span>
   <span class="code-tag">&lt;bean class=<span class="code-quote">"org.codehaus.jackson.jaxrs.JacksonJaxbJsonProvider"</span>/&gt;</span>
<span class="code-tag">&lt;/jaxrs:providers&gt;</span>
</pre>
</div></div>


<p>and add this Maven dependency:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;dependency&gt;</span>
  <span class="code-tag">&lt;groupId&gt;</span>org.codehaus.jackson<span class="code-tag">&lt;/groupId&gt;</span>
  <span class="code-tag">&lt;artifactId&gt;</span>jackson-jaxrs<span class="code-tag">&lt;/artifactId&gt;</span>
  <span class="code-tag">&lt;version&gt;</span>1.9.0<span class="code-tag">&lt;/version&gt;</span>
<span class="code-tag">&lt;/dependency&gt;</span>
</pre>
</div></div>

<h1><a name="JAX-RSDataBindings-CommonJAXBandJSONconfiguration"></a>Common JAXB and JSON configuration</h1>

<p>In this section it's expected that Jettison is used to handle JSON.</p>

<h2><a name="JAX-RSDataBindings-SingleJAXBContextandextrauserclasses"></a>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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;bean id=<span class="code-quote">"jaxb"</span> class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.JAXBElementProvider"</span>&gt;</span>
      <span class="code-tag">&lt;property name=<span class="code-quote">"singleJaxbContext"</span> value=<span class="code-quote">"true"</span>/&gt;</span>
      <span class="code-tag">&lt;property name=<span class="code-quote">"extraClass"</span>&gt;</span>
         <span class="code-tag">&lt;list&gt;</span>
           <span class="code-tag">&lt;value&gt;</span>org.apache.cxf.jaxrs.resources.SuperBook<span class="code-tag">&lt;/value&gt;</span>
           <span class="code-tag">&lt;value&gt;</span>org.apache.cxf.jaxrs.resources.SuperBook<span class="code-tag">&lt;/value&gt;</span>  
         <span class="code-tag">&lt;/list&gt;</span>
      <span class="code-tag">&lt;/property&gt;</span>
<span class="code-tag">&lt;/bean&gt;</span>
</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 written.</p>

<h2><a name="JAX-RSDataBindings-AutomaticJAXBElementconversionduringserialization"></a>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 additional 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><a name="JAX-RSDataBindings-HandlingJAXBbeanswithoutXmlRootElementannotations"></a>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/>
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><a name="JAX-RSDataBindings-Handlingexplicitcollections"></a>Handling explicit collections</h2>

<p>JAXB and JSON providers can handle explicit collections like List, Set or base Collection.<br/>
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/>
One can override it by setting a 'collectionWrapperName' string property, like 'Books' or '{<a href="http://books" class="external-link" rel="nofollow">http://books</a>}Book'. </p>

<p>There's also a 'collectionWrapperMap' property 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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag"><span class="code-comment">&lt;!-- Configure JAXB Provider --&gt;</span></span>
&lt;bean id=<span class="code-quote">"jaxbProvider"</span>
class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.JAXBElementProvider"</span>&gt;
  <span class="code-tag">&lt;property name=<span class="code-quote">"collectionWrapperMap"</span>&gt;</span>
  <span class="code-tag">&lt;map&gt;</span>
    <span class="code-tag">&lt;entry&gt;</span>
      <span class="code-tag">&lt;key&gt;</span><span class="code-tag">&lt;value&gt;</span>com.foo.bar.MyObject<span class="code-tag">&lt;/value&gt;</span><span class="code-tag">&lt;/key&gt;</span>
      <span class="code-tag">&lt;value&gt;</span>MyObjects<span class="code-tag">&lt;/value&gt;</span>
    <span class="code-tag">&lt;/entry&gt;</span>
   <span class="code-tag">&lt;/map&gt;</span>
   <span class="code-tag">&lt;/property&gt;</span>
<span class="code-tag">&lt;/bean&gt;</span> 
</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><a name="JAX-RSDataBindings-CustomizingJAXBXMLandJSONinputandoutput"></a>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/>
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/>
handler from RequestHandler or ResponseHandler filters or input/output CXF interceptors. For example, see <a href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/XmlStreamWriterProvider.java" class="external-link" rel="nofollow">XMLStreamWriterProvider</a> and <a href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/CustomXmlStreamWriter.java" class="external-link" rel="nofollow">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/>
Typically one would delegate to a super class first and then wrap the returned writer in a custom writer, see <a href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/CustomXmlStreamWriter.java" class="external-link" rel="nofollow">CustomXmlStreamWriter</a> for an example.</p>

<p>One can also use XSLTJaxbProvider to produce or modify the incoming XML. In fact, XSLTJaxbProvider can be used to adapt formats like JSON for legacy consumers.</p>

<p>Please also see this <a href="http://soa.dzone.com/articles/pragmatic-web-services-apache" class="external-link" 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 href="/confluence/display/CXF20DOC/TransformationFeature" title="TransformationFeature">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" type="square">
	<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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;bean id=<span class="code-quote">"jaxbProvider"</span> class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.JAXBElementProvider"</span>&gt;</span>
  <span class="code-tag">&lt;property name=<span class="code-quote">"outTransformElements"</span>&gt;</span>
    <span class="code-tag">&lt;map&gt;</span>
      <span class="code-tag"><span class="code-comment">&lt;!-- change <span class="code-quote">"book"</span> to <span class="code-quote">"thebook"</span> --&gt;</span></span>
      <span class="code-tag">&lt;entry key=<span class="code-quote">"book"</span> value=<span class="code-quote">"thebook"</span>/&gt;</span>
      
      <span class="code-tag"><span class="code-comment">&lt;!-- drop the namespace from <span class="code-quote">"book"</span> --&gt;</span></span>
      <span class="code-tag">&lt;entry key=<span class="code-quote">"{http://books}book"</span> value=<span class="code-quote">"book"</span>/&gt;</span> 
      
      <span class="code-tag"><span class="code-comment">&lt;!-- qualify <span class="code-quote">"book"</span> with <span class="code-quote">"http://books"</span> --&gt;</span></span>
      <span class="code-tag">&lt;entry key=<span class="code-quote">"book"</span> value=<span class="code-quote">"{http://books}thebook"</span>/&gt;</span> 
      
      <span class="code-tag"><span class="code-comment">&lt;!--  change namespace to <span class="code-quote">"http://books"</span> for all the elements with the <span class="code-quote">"http://book"</span> namespace --&gt;</span></span>
      <span class="code-tag">&lt;entry key=<span class="code-quote">"{http://book}*"</span> value=<span class="code-quote">"{http://books}*"</span>/&gt;</span> 
    <span class="code-tag">&lt;/map&gt;</span>
  <span class="code-tag">&lt;/property&gt;</span>
<span class="code-tag">&lt;/bean&gt;</span> 
</pre>
</div></div>

<ul class="alternate" type="square">
	<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" type="square">
	<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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;bean id=<span class="code-quote">"jaxbProvider"</span> class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.JAXBElementProvider"</span>&gt;</span>
  <span class="code-tag">&lt;property name=<span class="code-quote">"outAppendElements"</span>&gt;</span>
    <span class="code-tag">&lt;map&gt;</span>
      <span class="code-tag"><span class="code-comment">&lt;!-- append <span class="code-quote">"book"</span> before <span class="code-quote">"thebook"</span> --&gt;</span></span>
      <span class="code-tag">&lt;entry key=<span class="code-quote">"book"</span> value=<span class="code-quote">"thebook"</span>/&gt;</span>
      
      <span class="code-tag"><span class="code-comment">&lt;!-- qualify <span class="code-quote">"book"</span> with <span class="code-quote">"http://books"</span> --&gt;</span></span>
      <span class="code-tag">&lt;entry key=<span class="code-quote">"{http://books}book"</span> value=<span class="code-quote">"book"</span>/&gt;</span> 
      
      <span class="code-tag"><span class="code-comment">&lt;!-- drop the namespace from the <span class="code-quote">"book"</span> --&gt;</span></span>
      <span class="code-tag">&lt;entry key=<span class="code-quote">"book"</span> value=<span class="code-quote">"{http://books}thebook"</span>/&gt;</span> 
      
      <span class="code-tag"><span class="code-comment">&lt;!--  change namespace to <span class="code-quote">"http://book"</span> for all the elements with the <span class="code-quote">"http://books"</span> namespace --&gt;</span></span>
      <span class="code-tag">&lt;entry key=<span class="code-quote">"{http://book}*"</span> value=<span class="code-quote">"{http://books}*"</span>/&gt;</span> 
    <span class="code-tag">&lt;/map&gt;</span>
  <span class="code-tag">&lt;/property&gt;</span>
<span class="code-tag">&lt;/bean&gt;</span> 
</pre>
</div></div>

<ul class="alternate" type="square">
	<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" type="square">
	<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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;bean id=<span class="code-quote">"jaxbProvider"</span> class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.JAXBElementProvider"</span>&gt;</span>
  <span class="code-tag">&lt;property name=<span class="code-quote">"outDropElements"</span>&gt;</span>
    <span class="code-tag">&lt;list&gt;</span>
      <span class="code-tag"><span class="code-comment">&lt;!-- ignore drop and {http://numbers}number elements --&gt;</span></span>
      <span class="code-tag">&lt;value&gt;</span>{http://numbers}number<span class="code-tag">&lt;/value&gt;</span>
      <span class="code-tag">&lt;value&gt;</span>index<span class="code-tag">&lt;/value&gt;</span>
    <span class="code-tag">&lt;/list&gt;</span>
  <span class="code-tag">&lt;/property&gt;</span>
<span class="code-tag">&lt;/bean&gt;</span> 
</pre>
</div></div>

<ul class="alternate" type="square">
	<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" type="square">
	<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 "<tt>a:b},{c:d</tt>" 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:<tt>a:b},{c:d</tt>}}".</p>

<h1><a name="JAX-RSDataBindings-ControllingLargeJAXBXMLandJSONinputpayloads"></a>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 href="https://cwiki.apache.org/confluence/display/CXF20DOC/Security#Security-XML" class="external-link" rel="nofollow">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 href="http://svn.apache.org/repos/asf/cxf/trunk/api/src/main/java/org/apache/cxf/staxutils/DocumentDepthProperties.java" class="external-link" rel="nofollow">DocumentDepthProperties</a>:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">

<span class="code-tag">&lt;bean id=<span class="code-quote">"depthProperties"</span> class=<span class="code-quote">"org.apache.cxf.staxutils.DocumentDepthProperties"</span>&gt;</span>
  <span class="code-tag">&lt;property name=<span class="code-quote">"innerElementCountThreshold"</span> value=<span class="code-quote">"500"</span>/&gt;</span>
<span class="code-tag">&lt;/bean&gt;</span> 

<span class="code-tag">&lt;bean id=<span class="code-quote">"jaxbProvider"</span> class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.JAXBElementProvider"</span>&gt;</span>
  <span class="code-tag">&lt;property name=<span class="code-quote">"depthProperties"</span> ref=<span class="code-quote">"depthProperties"</span>/&gt;</span>
<span class="code-tag">&lt;/bean&gt;</span> 

<span class="code-tag">&lt;bean id=<span class="code-quote">"jsonProvider"</span> class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.json.JSONProvider"</span>&gt;</span>
  <span class="code-tag">&lt;property name=<span class="code-quote">"depthProperties"</span> ref=<span class="code-quote">"depthProperties"</span>/&gt;</span>
<span class="code-tag">&lt;/bean&gt;</span> 

<span class="code-tag">&lt;jaxrs:server id=<span class="code-quote">"endpoint1"</span>&gt;</span>
  <span class="code-tag">&lt;jaxrs:serviceBeans&gt;</span>
    <span class="code-tag">&lt;bean class=<span class="code-quote">"my.package.RootResource"</span>/&gt;</span>
  <span class="code-tag">&lt;/jaxrs:serviceBeans&gt;</span>
  <span class="code-tag">&lt;jaxrs:providers&gt;</span>
    <span class="code-tag">&lt;ref bean=<span class="code-quote">"jaxbProvider"</span>/&gt;</span>
    <span class="code-tag">&lt;ref bean=<span class="code-quote">"jsonProvider"</span>/&gt;</span>
  <span class="code-tag">&lt;/jaxrs:providers&gt;</span>
<span class="code-tag">&lt;/jaxrs:server&gt;</span>

<span class="code-tag">&lt;jaxrs:server id=<span class="code-quote">"endpoint2"</span>&gt;</span>
  <span class="code-tag">&lt;jaxrs:serviceBeans&gt;</span>
    <span class="code-tag">&lt;bean class=<span class="code-quote">"my.package.RootResource"</span>/&gt;</span>
  <span class="code-tag">&lt;/jaxrs:serviceBeans&gt;</span>
  <span class="code-tag">&lt;jaxrs:properties&gt;</span>
    &lt;entry key=<span class="code-quote">"depthInnerElementCountThreshold"</span> value=<span class="code-quote">"500"</span>/
  <span class="code-tag">&lt;/jaxrs:properties&gt;</span>
<span class="code-tag">&lt;/jaxrs:server&gt;</span>


</pre>
</div></div>

<h1><a name="JAX-RSDataBindings-JSONWithPadding%28JSONP%29"></a>JSON With Padding (JSONP)</h1>

<p>One option for supporting "JSON With Padding" (<a href="http://en.wikipedia.org/wiki/JSONP" class="external-link" rel="nofollow">JSONP</a>) is to extend the default JSONProvider and override its writeTo method as follows:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">

@Produces(<span class="code-quote">"application/javascript"</span>)
class JsonpProvider <span class="code-keyword">extends</span> JSONProvider {
		
    @Override
    <span class="code-keyword">public</span> void writeTo(<span class="code-object">Object</span> obj, <span class="code-object">Class</span>&lt;?&gt; cls, Type genericType, Annotation[] anns, MediaType m, MultivaluedMap&lt;<span class="code-object">String</span>, <span class="code-object">Object</span>&gt; headers,
	OutputStream os) <span class="code-keyword">throws</span> IOException {
	<span class="code-object">String</span> prefix = getContext().getHttpServletRequest().getParameter(<span class="code-quote">"_jsonp"</span>);
	<span class="code-object">boolean</span> hasPrefix = !isEmpty(prefix);
	<span class="code-keyword">if</span>(hasPrefix) {
	    os.write(prefix.getBytes(HttpUtils.getSetEncoding(m, headers, <span class="code-quote">"UTF-8"</span>)));
	    os.write('(');
	}
	<span class="code-keyword">super</span>.writeTo(obj, cls, genericType, anns, m, headers, os);
	<span class="code-keyword">if</span>(hasPrefix) {
		os.write(')');
	}
    }
}
</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 href="http://josh.media.berkeley.edu/?p=78" class="external-link" 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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;jaxrs:server id=<span class="code-quote">"bookJsonp"</span> address=<span class="code-quote">"/jsonp"</span>&gt;</span>
    <span class="code-tag">&lt;jaxrs:serviceBeans&gt;</span>
      <span class="code-tag">&lt;ref bean=<span class="code-quote">"serviceBean"</span> /&gt;</span>
    <span class="code-tag">&lt;/jaxrs:serviceBeans&gt;</span>		  

    <span class="code-tag">&lt;jaxrs:inInterceptors&gt;</span>
       <span class="code-tag">&lt;bean class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.jsonp.JsonpInInterceptor"</span>/&gt;</span>
    <span class="code-tag">&lt;/jaxrs:inInterceptors&gt;</span>
    <span class="code-tag">&lt;jaxrs:outInterceptors&gt;</span>
       <span class="code-tag">&lt;bean class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.jsonp.JsonpPreStreamInterceptor"</span>/&gt;</span>
       <span class="code-tag">&lt;bean class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.jsonp.JsonpPostStreamInterceptor"</span>/&gt;</span>
    <span class="code-tag">&lt;/jaxrs:outInterceptors&gt;</span> 
<span class="code-tag">&lt;/jaxrs:server&gt;</span>
</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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;jaxrs:server id=<span class="code-quote">"bookJsonp"</span> address=<span class="code-quote">"/jsonp"</span>&gt;</span>
    <span class="code-tag">&lt;jaxrs:serviceBeans&gt;</span>
      <span class="code-tag">&lt;ref bean=<span class="code-quote">"serviceBean"</span> /&gt;</span>
    <span class="code-tag">&lt;/jaxrs:serviceBeans&gt;</span>		  

    <span class="code-tag">&lt;jaxrs:inInterceptors&gt;</span>
       <span class="code-tag">&lt;bean class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.jsonp.JsonpInInterceptor"</span>&gt;</span>
          <span class="code-tag">&lt;property name=<span class="code-quote">"callbackParam"</span> value=<span class="code-quote">"myjsonp"</span>/&gt;</span>
       <span class="code-tag">&lt;/bean&gt;</span> 
    <span class="code-tag">&lt;/jaxrs:inInterceptors&gt;</span>
    <span class="code-tag">&lt;jaxrs:outInterceptors&gt;</span>
       <span class="code-tag">&lt;bean class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.jsonp.JsonpPreStreamInterceptor"</span>&gt;</span>
           <span class="code-tag">&lt;property name=<span class="code-quote">"mediaType"</span> value=<span class="code-quote">"text/x+javascript"</span>/&gt;</span>
       <span class="code-tag">&lt;/bean&gt;</span>
       <span class="code-tag">&lt;bean class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.jsonp.JsonpPostStreamInterceptor"</span>&gt;</span>
           <span class="code-tag"><span class="code-comment">&lt;!-- default is ');' --&gt;</span></span>
           <span class="code-tag">&lt;property name=<span class="code-quote">"paddingEnd"</span> value=<span class="code-quote">")"</span>/&gt;</span>
       <span class="code-tag">&lt;/bean&gt;</span>
    <span class="code-tag">&lt;/jaxrs:outInterceptors&gt;</span> 
<span class="code-tag">&lt;/jaxrs:server&gt;</span>
</pre>
</div></div>

<h1><a name="JAX-RSDataBindings-Formpayloads"></a>Form payloads</h1>

<p>Form payload is a sequence of name and value pairs, example, "name=Barry&amp;age=20".<br/>
One can capture the form data by using either JAX-RS FormParam annotation or MultivaluedMap, for example:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">

<span class="code-keyword">import</span> javax.ws.rs.FormParam;
<span class="code-keyword">import</span> javax.ws.rs.MultivaluedMap;

@Path(<span class="code-quote">"resource"</span>)
<span class="code-keyword">public</span> class FormResource {

   @POST
   @Path(<span class="code-quote">"/form1"</span>)
   @Consumes(<span class="code-quote">"application/x-www-form-urlencoded"</span>)
   <span class="code-keyword">public</span> void form1(@FormParam(<span class="code-quote">"name"</span>) <span class="code-object">String</span> name, @FormParam(<span class="code-quote">"age"</span>) <span class="code-object">int</span> age) {
   }

   @POST
   @Path(<span class="code-quote">"/form2"</span>)
   @Consumes(<span class="code-quote">"application/x-www-form-urlencoded"</span>)
   <span class="code-keyword">public</span> void form1(MultivaluedMap&lt;<span class="code-object">String</span>, <span class="code-object">String</span>&gt; params) {
       <span class="code-object">String</span> name = params.getFirst(<span class="code-quote">"name"</span>);
       <span class="code-object">String</span> age = params.getFirst(<span class="code-quote">"age"</span>);
   }

}
</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><a name="JAX-RSDataBindings-Atom"></a>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 AtomEntryProvider support a 'formattedOutput' (pretty-printing) property.</p>

<p>2. Register an <a 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" class="external-link" rel="nofollow">AtomPojoProvider</a> injected with either <a 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" class="external-link" rel="nofollow">AtomElementWriter</a> or <a 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" class="external-link" rel="nofollow">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&lt;Feed, Book&gt; will be responsible for converting Book instances into Feeds while ChapterAtomElementWriter&lt;Entry, Chapter&gt; 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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
@Path(<span class="code-quote">"books"</span>)
<span class="code-keyword">public</span> class BooksRootResource {

 <span class="code-keyword">private</span> Books books;

 @GET
 @Produces({<span class="code-quote">"application/xml"</span>, <span class="code-quote">"application/json"</span>, <span class="code-quote">"application/atom+xml;type=feed"</span>})
 <span class="code-keyword">public</span> Books getCollectionOfBooks() {
     <span class="code-keyword">return</span> books;
 } 

 @GET
 @Produces({<span class="code-quote">"application/xml"</span>, <span class="code-quote">"application/json"</span>, <span class="code-quote">"application/atom+xml;type=entry"</span>})
 @Path(<span class="code-quote">"{id}"</span>)
 <span class="code-keyword">public</span> Book getBook(@PathParam(<span class="code-quote">"id"</span>) <span class="code-object">Long</span> id) {
     <span class="code-keyword">return</span> books.get(id);
 }

}
</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 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" class="external-link" rel="nofollow">AbstractFeedBuilder</a> or <a 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" class="external-link" rel="nofollow">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><a name="JAX-RSDataBindings-AegisDataBinding"></a>Aegis Data Binding</h1>

<p>Use org.apache.cxf.provider.AegisElementProvider to start doing Aegis with JAX-RS<br/>
org.apache.cxf.provider.AegisJSONProvider can be used to output JSON with the help of Aegis.<br/>
Similarly to the default JSONProvider this Aegis-based JSON provider can have "namespaceMap", "serializeAsArray", "arrayKeys", "dropRootElement" and "writeXsiType" properties set.</p>

<h1><a name="JAX-RSDataBindings-XMLBeans"></a>XMLBeans</h1>

<p>Use org.apache.cxf.provider.XmlBeansElementProvider to start doing XmlBeans with JAX-RS</p>

<h1><a name="JAX-RSDataBindings-CXFDataBindingsasJAXRSproviders"></a>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 href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/provider/DataBindingProvider.java" class="external-link" rel="nofollow">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 and 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 href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/provider/DataBindingJSONProvider.java" class="external-link" rel="nofollow">DataBindingJSONProvider</a>.<br/>
Please see <a href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/resources/jaxrs_databinding/WEB-INF/beans.xml" class="external-link" rel="nofollow">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 href="/confluence/display/CXF20DOC/Annotations" title="Annotations">DataBinding</a> annotation is also supported. </p>

<h1><a name="JAX-RSDataBindings-JAXRSDataBinding"></a>JAXRS DataBinding</h1>

<p><b>Available starting from CXF 2.3.2 and CXF 2.4.0</b></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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
  <span class="code-tag">&lt;jaxrs:server id=<span class="code-quote">"hello_rest"</span> address=<span class="code-quote">"/hello-rest"</span>&gt;</span>
    <span class="code-tag">&lt;jaxrs:serviceBeans&gt;</span>
      <span class="code-tag">&lt;bean class=<span class="code-quote">"org.apache.cxf.systest.jaxrs.jaxws.HelloWorldImpl"</span>/&gt;</span>
    <span class="code-tag">&lt;/jaxrs:serviceBeans&gt;</span>

    <span class="code-tag">&lt;jaxrs:providers&gt;</span>
      <span class="code-tag">&lt;ref bean=<span class="code-quote">"jaxbProviderSoap"</span>/&gt;</span>
    <span class="code-tag">&lt;/jaxrs:providers&gt;</span>
  <span class="code-tag">&lt;/jaxrs:server&gt;</span>

  &lt;jaxws:endpoint <span class="code-keyword">xmlns:s</span>=<span class="code-quote">"http://hello.com"</span>
      serviceName=<span class="code-quote">"s:HelloWorld"</span>
      endpointName=<span class="code-quote">"s:HelloWorldPort"</span>
      id=<span class="code-quote">"hello_soap-databinding"</span>
      implementor=<span class="code-quote">"org.apache.cxf.systest.jaxrs.jaxws.HelloWorldImpl"</span>
      address=<span class="code-quote">"/hello-soap-databinding"</span>&gt;
      
      <span class="code-tag">&lt;jaxws:dataBinding&gt;</span>
          <span class="code-tag">&lt;ref bean=<span class="code-quote">"jaxrs-data-binding"</span>/&gt;</span>
      <span class="code-tag">&lt;/jaxws:dataBinding&gt;</span>
      
  <span class="code-tag">&lt;/jaxws:endpoint&gt;</span>        
 
  <span class="code-tag">&lt;bean id=<span class="code-quote">"jaxrs-data-binding"</span> class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.JAXRSDataBinding"</span>&gt;</span>
      <span class="code-tag">&lt;property name=<span class="code-quote">"provider"</span> ref=<span class="code-quote">"jaxbProviderSoap"</span>/&gt;</span>
  <span class="code-tag">&lt;/bean&gt;</span>

  <span class="code-tag">&lt;bean id=<span class="code-quote">"jaxbProviderSoap"</span> class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.JAXBElementProvider"</span>/&gt;</span>
</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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">

<span class="code-keyword">public</span> class PortableXMLProvider <span class="code-keyword">implements</span> MessageBodyReader, MessageBodyWriter {

    <span class="code-keyword">public</span> <span class="code-object">Object</span> readFrom(<span class="code-object">Class</span>&lt;<span class="code-object">Object</span>&gt; type, Type genericType, Annotation[] anns, MediaType mt, 
                           MultivaluedMap&lt;<span class="code-object">String</span>, <span class="code-object">String</span>&gt; headers, InputStream is) 
                           <span class="code-keyword">throws</span> IOException {

        XMLStreamReader reader = createReaderUsingStandardStaxApi(is);
        <span class="code-keyword">return</span> readFromStream(reader);  

    }

    <span class="code-keyword">public</span> void writeTo(<span class="code-object">Object</span> obj, <span class="code-object">Class</span>&lt;?&gt; cls, Type genericType, Annotation[] anns,  
                        MediaType m, MultivaluedMap&lt;<span class="code-object">String</span>, <span class="code-object">Object</span>&gt; headers, OutputStream os)
                        <span class="code-keyword">throws</span> IOException {
        XMLStreamWriter writer = createWriterUsingStandardStaxApi(os);
        writeToStream(writer);  
    }

    <span class="code-comment">// add more parameters <span class="code-keyword">if</span> needed
</span>    <span class="code-keyword">protected</span> <span class="code-object">Object</span> readFromStream(XMLStreamReader reader) {
        <span class="code-comment">// read from XMLStreamReader
</span>    }
    
    <span class="code-comment">// add more parameters <span class="code-keyword">if</span> needed
</span>    <span class="code-keyword">protected</span> void writeToStream(XMLStreamWriter writer) {
        <span class="code-comment">// write to XMLStreamWriter
</span>    }

    
}

<span class="code-keyword">public</span> class CXFCustomXMLProvider <span class="code-keyword">extends</span> PortableXMLProvider {

    @Override
    <span class="code-keyword">public</span> <span class="code-object">Object</span> readFrom(<span class="code-object">Class</span>&lt;<span class="code-object">Object</span>&gt; type, Type genericType, Annotation[] anns, MediaType mt, 
                           MultivaluedMap&lt;<span class="code-object">String</span>, <span class="code-object">String</span>&gt; headers, InputStream is) 
                           <span class="code-keyword">throws</span> IOException {

        XMLStreamReader reader = getStaxHandlerFromCurrentMessage(XMLStreamReader.class);
        <span class="code-keyword">return</span> readFromStream(reader);  

    }

    @Override
    <span class="code-keyword">public</span> void writeTo(<span class="code-object">Object</span> obj, <span class="code-object">Class</span>&lt;?&gt; cls, Type genericType, Annotation[] anns,  
                        MediaType m, MultivaluedMap&lt;<span class="code-object">String</span>, <span class="code-object">Object</span>&gt; headers, OutputStream os)
                        <span class="code-keyword">throws</span> IOException {
        XMLStreamWriter writer = getStaxHandlerFromCurrentMessage(XMLStreamWriter.class);
        writeToStream(writer);  
    }


    <span class="code-keyword">protected</span> &lt;T&gt; T getStaxHandlerFromCurrentMessage(<span class="code-object">Class</span>&lt;T&gt; staxCls) {
        Message m = PhaseInterceptorChain.getCurrentMessage();
        <span class="code-keyword">if</span> (m != <span class="code-keyword">null</span>) {
            <span class="code-keyword">return</span> staxCls.<span class="code-keyword">cast</span>(m.getContent(staxCls));
        }
        <span class="code-keyword">return</span> <span class="code-keyword">null</span>;
    }
}
</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><a name="JAX-RSDataBindings-Schemavalidation"></a>Schema validation</h1>

<p>Schema validation can be enabled in one of the following ways:</p>

<p>1. Using jaxrs:schemaLocations element</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;beans&gt;</span>
<span class="code-tag">&lt;jaxrs:server address=<span class="code-quote">"/"</span> serviceClass=<span class="code-quote">"org.apache.cxf.systest.jaxrs.BookStore"</span>&gt;</span>
  <span class="code-tag">&lt;jaxrs:schemaLocations&gt;</span>
     <span class="code-tag">&lt;jaxrs:schemaLocation&gt;</span>classpath:/schemas/a.xsd<span class="code-tag">&lt;/jaxrs:schemaLocation&gt;</span>
     <span class="code-tag">&lt;jaxrs:schemaLocation&gt;</span>classpath:/schemas/b.xsd<span class="code-tag">&lt;/jaxrs:schemaLocation&gt;</span>
  <span class="code-tag">&lt;/jaxrs:schemaLocations&gt;</span>
<span class="code-tag">&lt;/jaxrs:server&gt;</span>
<span class="code-tag">&lt;/beans&gt;</span>
</pre>
</div></div>

<p>Using this option is handy when you have multiple bindings involved which support the schema validation. In this case<br/>
individual MessageBodyReader implementations which have a method setSchemas(List&lt;Sring&gt; 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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;beans <span class="code-keyword">xmlns:util</span>=<span class="code-quote">"http://www.springframework.org/schema/util"</span>&gt;</span>
<span class="code-tag">&lt;jaxrs:server address=<span class="code-quote">"/"</span> serviceClass=<span class="code-quote">"org.apache.cxf.systest.jaxrs.BookStore"</span>&gt;</span>
 <span class="code-tag">&lt;jaxrs:providers&gt;</span>
   <span class="code-tag">&lt;ref bean=<span class="code-quote">"jaxbProvider"</span>/&gt;</span>
 <span class="code-tag">&lt;/jaxrs:providers&gt;</span>
<span class="code-tag">&lt;/jaxrs:server&gt;</span>

<span class="code-tag">&lt;bean id=<span class="code-quote">"jaxbProvider"</span> class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.JAXBElementProvider"</span>&gt;</span>
   <span class="code-tag">&lt;property name=<span class="code-quote">"schemaLocations"</span> ref=<span class="code-quote">"schemaHolder"</span>/&gt;</span>
<span class="code-tag">&lt;/bean&gt;</span>
  
<span class="code-tag">&lt;util:list id=<span class="code-quote">"theSchemas"</span>&gt;</span>
  <span class="code-tag">&lt;value&gt;</span>classpath:/WEB-INF/schemas/bookid.xsd<span class="code-tag">&lt;/value&gt;</span>
  <span class="code-tag">&lt;value&gt;</span>classpath:/org/apache/cxf/systest/jaxrs/resources/book.xsd<span class="code-tag">&lt;/value&gt;</span>
<span class="code-tag">&lt;/util:list&gt;</span>
<span class="code-tag">&lt;/beans&gt;</span>
</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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;beans <span class="code-keyword">xmlns:util</span>=<span class="code-quote">"http://www.springframework.org/schema/util"</span>&gt;</span>
 <span class="code-tag">&lt;jaxrs:server address=<span class="code-quote">"/"</span> serviceClass=<span class="code-quote">"org.apache.cxf.systest.jaxrs.BookStore"</span>&gt;</span>
  <span class="code-tag">&lt;jaxrs:providers&gt;</span>
   <span class="code-tag">&lt;ref bean=<span class="code-quote">"jaxbProvider"</span>/&gt;</span>
   <span class="code-tag">&lt;ref bean=<span class="code-quote">"jsonProvider"</span>/&gt;</span>
  <span class="code-tag">&lt;/jaxrs:providers&gt;</span>
 <span class="code-tag">&lt;/jaxrs:server&gt;</span>

<span class="code-tag">&lt;bean id=<span class="code-quote">"jaxbProvider"</span> class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.JAXBElementProvider"</span>&gt;</span>
   <span class="code-tag">&lt;property name=<span class="code-quote">"schemaHandler"</span> ref=<span class="code-quote">"schemaHolder"</span>/&gt;</span>
<span class="code-tag">&lt;/bean&gt;</span>

<span class="code-tag">&lt;bean id=<span class="code-quote">"jsonProvider"</span> class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.json.JSONProvider"</span>&gt;</span>
   <span class="code-tag">&lt;property name=<span class="code-quote">"schemaHandler"</span> ref=<span class="code-quote">"schemaHolder"</span>/&gt;</span>
<span class="code-tag">&lt;/bean&gt;</span>
  
<span class="code-tag">&lt;bean id=<span class="code-quote">"schemaHolder"</span> class=<span class="code-quote">"org.apache.cxf.jaxrs.utils.schemas.SchemaHandler"</span>&gt;</span>
   <span class="code-tag">&lt;property name=<span class="code-quote">"schemas"</span> ref=<span class="code-quote">"theSchemas"</span>/&gt;</span>
<span class="code-tag">&lt;/bean&gt;</span>
  
<span class="code-tag">&lt;util:list id=<span class="code-quote">"theSchemas"</span>&gt;</span>
  <span class="code-tag">&lt;value&gt;</span>classpath:/WEB-INF/schemas/bookid.xsd<span class="code-tag">&lt;/value&gt;</span>
  <span class="code-tag">&lt;value&gt;</span>classpath:/org/apache/cxf/systest/jaxrs/resources/book.xsd<span class="code-tag">&lt;/value&gt;</span>
<span class="code-tag">&lt;/util:list&gt;</span>
<span class="code-tag">&lt;/beans&gt;</span>
</pre>
</div></div>

<h2><a name="JAX-RSDataBindings-Supportforcatalogs"></a>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/>
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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;bean id=<span class="code-quote">"jaxbProvider"</span> class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.JAXBElementProvider"</span>&gt;</span>
   <span class="code-tag">&lt;property name=<span class="code-quote">"catalogLocation"</span> value=<span class="code-quote">"classpath:/schemas/mycatalog.xml"</span>/&gt;</span>
<span class="code-tag">&lt;/bean&gt;</span>

</pre>
</div></div>

<p>where mycatalog.xml may look like this:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;catalog xmlns=<span class="code-quote">"urn:oasis:names:tc:entity:<span class="code-keyword">xmlns:xml:catalog"</span</span>> prefer=<span class="code-quote">"system"</span>&gt;</span>
    <span class="code-tag">&lt;system systemId=<span class="code-quote">"http://schemas/bookid.xsd"</span> uri=<span class="code-quote">"classpath:WEB-INF/schemas/bookid.xsd"</span>/&gt;</span>
<span class="code-tag">&lt;/catalog&gt;</span>
</pre>
</div></div>


<h2><a name="JAX-RSDataBindings-Outputvalidation"></a>Output validation</h2>

<p>By default, after a valid schema has been located, only JAXB Unmarshaller will use it to validate the input.<br/>
Starting from CXF 2.3.4 and 2.4, the following properties can be used to enable the output validation:</p>
<ul class="alternate" type="square">
	<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><a name="JAX-RSDataBindings-FastInfoset"></a>Fast Infoset</h1>

<p>You can enable the <a href="https://fi.dev.java.net/standardization.html" class="external-link" 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/>
for example :</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">

<span class="code-tag">&lt;jaxrs:server id=<span class="code-quote">"restservice3"</span> address=<span class="code-quote">"/rest3"</span>&gt;</span>

 <span class="code-tag">&lt;jaxrs:serviceBeans&gt;</span>
  <span class="code-tag">&lt;ref bean=<span class="code-quote">"bookstore"</span>/&gt;</span>
 <span class="code-tag">&lt;/jaxrs:serviceBeans&gt;</span>

 <span class="code-tag">&lt;jaxrs:providers&gt;</span>
  <span class="code-tag">&lt;ref bean=<span class="code-quote">"jaxbProvider"</span>/&gt;</span>
 <span class="code-tag">&lt;/jaxrs:providers&gt;</span>

 <span class="code-tag">&lt;jaxrs:outInterceptors&gt;</span>
  <span class="code-tag">&lt;ref bean=<span class="code-quote">"fastInfosetOutInterceptor"</span>/&gt;</span>
 <span class="code-tag">&lt;/jaxrs:outInterceptors&gt;</span>

 <span class="code-tag">&lt;jaxrs:inInterceptors&gt;</span>
  <span class="code-tag">&lt;ref bean=<span class="code-quote">"fastInfosetInInterceptor"</span>/&gt;</span>
 <span class="code-tag">&lt;/jaxrs:inInterceptors&gt;</span>

 <span class="code-tag">&lt;jaxrs:properties&gt;</span>
  <span class="code-tag">&lt;entry key=<span class="code-quote">"org.apache.cxf.endpoint.private"</span> value=<span class="code-quote">"true"</span>/&gt;</span>
 <span class="code-tag">&lt;/jaxrs:properties&gt;</span>
<span class="code-tag">&lt;/jaxrs:server&gt;</span>

<span class="code-tag">&lt;util:list id=<span class="code-quote">"fastinfosetType"</span>&gt;</span>
  <span class="code-tag">&lt;value&gt;</span>application/fastinfoset<span class="code-tag">&lt;/value&gt;</span>
<span class="code-tag">&lt;/util:list&gt;</span>

<span class="code-tag">&lt;bean id=<span class="code-quote">"jaxbProvider"</span> class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.JAXBElementProvider"</span>&gt;</span>
  <span class="code-tag">&lt;property name=<span class="code-quote">"produceMediaTypes"</span> ref=<span class="code-quote">"fastinfosetType"</span>/&gt;</span>
  <span class="code-tag">&lt;property name=<span class="code-quote">"consumeMediaTypes"</span> ref=<span class="code-quote">"fastinfosetType"</span>/&gt;</span>
<span class="code-tag">&lt;/bean&gt;</span>
<span class="code-tag">&lt;bean id=<span class="code-quote">"fastInfosetOutInterceptor"</span> class=<span class="code-quote">"org.apache.cxf.interceptor.FIStaxOutInterceptor"</span>/&gt;</span>
<span class="code-tag">&lt;bean id=<span class="code-quote">"fastInfosetInInterceptor"</span> class=<span class="code-quote">"org.apache.cxf.interceptor.FIStaxInInterceptor"</span>/&gt;</span>
</pre>
</div></div>

<p>Note that explicitly registering the interceptors is not required anymore given that CXF FastInfoset and Feature annotations are also currently supported.</p>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action" class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/CXF20DOC/JAX-RS+Data+Bindings">View Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=24190800&revisedVersion=34&originalVersion=33">View Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/CXF20DOC/JAX-RS+Data+Bindings?showComments=true&amp;showCommentArea=true#addcomment">Add Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message