@@ -135,81 +143,81 @@ Apache CXF -- JAX-RS Data Bindings

For example:

-@XmlRootElement(name = "Customer")
-public class Customer {
-    private String name;
-    private long id;
+

In the example below, the Customer object returned by getCustomer is marshaled using JAXB data binding:

-@Path("/customerservice/")
-public class CustomerService {
+

The wire representation of Customer object is:

-<Customer>
-    <id>123</id>
-    <name>John</name>
-</Customer>
-

The simplest way to work with the collections is to define a type representing a collection. For example:

-@XmlRootElement(name = "Customers")
-public class Customers {
-    private Collection<Customer> customers;
+

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.

@@ -223,18 +231,18 @@ Apache CXF -- JAX-RS Data Bindings

The default JAXB provider can be configured in a number of ways. For example, here's how to set up marshall properties :

-<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>
-<util:map id="propertiesMap">
-<entry key="jaxb.formatted.output">
-   <value type="java.lang.Boolean">true</value>
-</entry>
-</util:map>
-/<beans>
-

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 this example and "Customizing media types for message body providers" and "Schema Validation" sections for more information.

@@ -260,16 +268,16 @@ If Moxy is used to handle beans without

Following code returns a Customer object that is marshaled to JSON format:

-@Path("/customerservice/")
-public class CustomerService {
-    @Produces("application/json")
+

Jettison

@@ -281,16 +289,16 @@ If Moxy is used to handle beans without

The default JSON provider can be configured in a number of ways. For example, here's how to set up namespace-to-prefix mappings :

-<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>
-<util:map id="jsonNamespaceMap" map-class="java.util.Hashtable">
-<entry key="http://www.example.org/books" value="b"/>
-</util:map>
-/<beans>
-

Note 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.

@@ -304,38 +312,38 @@ If Moxy is used to handle beans without

Note that 'serializeAsArray' and 'arrayKeys' can be combined to produce so called natural convention sequences. For example, given the following two class definitions :

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 :

@@ -366,33 +374,33 @@ If Moxy is used to handle beans without

If you prefer working with Jackson JSON providers then register either JacksonJsonProvider:

-<jaxrs:providers>
-   <bean class="org.codehaus.jackson.jaxrs.JacksonJsonProvider"/>
-</jaxrs:providers>
-

or JacksonJaxbJsonProvider (when working with JAXB beans):

-<jaxrs:providers>
-   <bean class="org.codehaus.jackson.jaxrs.JacksonJaxbJsonProvider"/>
-</jaxrs:providers>
-

and add this Maven dependency:

-<dependency>
-  <groupId>org.codehaus.jackson</groupId>
-  <artifactId>jackson-jaxrs</artifactId>
-  <version>1.9.0</version>
-</dependency>
-

Common JAXB and JSON configuration

@@ -404,17 +412,17 @@ If Moxy is used to handle beans without

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 :

-<bean id="jaxb" class="org.apache.cxf.jaxrs.provider.JAXBElementProvider">
-      <property name="singleJaxbContext" value="true"/>
-      <property name="extraClass">
-         <list>
-           <value>org.apache.cxf.jaxrs.resources.SuperBook</value>
-           <value>org.apache.cxf.jaxrs.resources.SuperBook</value>  
-         </list>
-      </property>
-</bean>
-

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.

@@ -451,20 +459,20 @@ One can override it by setting a 'collec

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 :

-<!-- Configure JAXB Provider -->
-<bean id="jaxbProvider"
-class="org.apache.cxf.jaxrs.provider.JAXBElementProvider">
-  <property name="collectionWrapperMap">
-  <map>
-    <entry>
-      <key><value>com.foo.bar.MyObject</value></key>
-      <value>MyObjects</value>
-    </entry>
-   </map>
-   </property>
-</bean> 
-

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).

@@ -492,25 +500,25 @@ Typically one would delegate to a super

-<bean id="jaxbProvider" class="org.apache.cxf.jaxrs.provider.JAXBElementProvider">
-  <property name="outTransformElements">
-    <map>
-      <!-- change "book" to "thebook" -->
-      <entry key="book" value="thebook"/>
+

"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.

@@ -520,25 +528,25 @@ Typically one would delegate to a super

-<bean id="jaxbProvider" class="org.apache.cxf.jaxrs.provider.JAXBElementProvider">
-  <property name="outAppendElements">
-    <map>
-      <!-- append "book" before "thebook" -->
-      <entry key="book" value="thebook"/>
+

"inAppendElements" map property : can be used to append new simple or qualified elements to the input; see the "outAppendElements" property description for an example.

@@ -548,17 +556,17 @@ Typically one would delegate to a super

-<bean id="jaxbProvider" class="org.apache.cxf.jaxrs.provider.JAXBElementProvider">
-  <property name="outDropElements">
-    <list>
-      <!-- ignore drop and {http://numbers}number elements -->
-      <value>{http://numbers}number</value>
-      <value>index</value>
-    </list>
-  </property>
-</bean> 
-

"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.

@@ -578,68 +586,68 @@ Typically one would delegate to a super

Additionally it is possible to configure JAXBElementProvider or JSONProvider with contextual properties or DocumentDepthProperties:

JSON With Padding (JSONP)

One option for supporting "JSON With Padding" (JSONP) is to extend the default JSONProvider and override its writeTo method as follows:

Similar approach can work when Jackson is used.

@@ -649,48 +657,48 @@ class JsonpProvider

-<jaxrs:server id="bookJsonp" address="/jsonp">
-    <jaxrs:serviceBeans>
-      <ref bean="serviceBean" />
-    </jaxrs:serviceBeans>		  
-
-    <jaxrs:inInterceptors>
-       <bean class="org.apache.cxf.jaxrs.provider.jsonp.JsonpInInterceptor"/>
-    </jaxrs:inInterceptors>
-    <jaxrs:outInterceptors>
-       <bean class="org.apache.cxf.jaxrs.provider.jsonp.JsonpPreStreamInterceptor"/>
-       <bean class="org.apache.cxf.jaxrs.provider.jsonp.JsonpPostStreamInterceptor"/>
-    </jaxrs:outInterceptors> 
-</jaxrs:server>
-

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:

Jettison

Common JAXB and JSON configuration

JSON With Padding (JSONP)

Form payloads

Support for catalogs

CXF RuntimeDelegate