Page Comparison

A common way to use the REST protocol is to transmit a Java Bean’s content in the message body. For this option to work, we need to have a method that will allow us to marshal the Java object to and from a suitable data format.

These data formats (suitable for encoding Java objects), are supported by the REST DSL:

JSON

JSON (JavaScript object notation) is a lightweight data format that can easily be mapped to and from Java objects. The JSON syntax is compact, lightly typed, and easy for humans to read and write. For all of these reasons, JSON has become popular as a message format for REST services.

...

{
    "id" : 1234,
    "name" : "Jane Doe"
}

JAXB

JAXB (Java Architecture for XML Binding) is an XML-based data format we can use for mapping to and from Java objects. Thus, to marshal the XML to a Java object, you need to annotate the Java class that you want to use.

...

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<User>
  <Id>1234</Id>
  <Name>Jane Doe</Name>
</User>

Integration of JSON and JAXB with REST DSL

We could write the necessary code to convert the message body to and from a Java object, but the REST DSL can perform this conversion automatically. The integration of JSON and JAXB with the REST DSL offers these advantages:

• Marshalling to and from Java objects is performed automatically (with the correct configuration).

• REST DSL will automatically detect the data format (either JSON or JAXB) and perform the correct conversion.

• REST DSL has an abstraction layer so that our code is not specific to a particular JSON or JAXB implementation. This allows us to switch the implementation with minimum impact to your application.

Supported Data Formats

Apache Camel provides a number of different implementations of the JSON and JAXB data formats. The following data formats are currently supported by the REST DSL:

• JSON

  • Jackson data format (camel-jackson) (this is the default)

  • GSon data format (camel-gson)

  • XStream data format (camel-xstream)

• JAXB

  • JAXB data format (camel-jaxb)

Enable Object Marshalling

To enable object marshalling in the REST DSL, we must be cognizant of these points:

1. Enable binding mode, by setting the bindingMode option.

2. Identify the Java type to be converted to (or From), on each of our incoming message using the type option (required), and also on any outgoing message using the outType option (optional).

3. In order to convert your Java object to/from the JAXB data format, we must annotate the class with the correct JAXB annotations.

4. We will need to specify the underlying data format implementation(s), using the jsonDataFormat option and/or the xmlDataFormat option (use the restConfiguration builder).

5. When our route generates a return value in JAXB format, it is anticipated that we will set the Out message of the exchange body to be an instance of a class with JAXB annotations (ie. JAXB element).

6. We will need to add the required dependencies to your POM file. For example, using the Maven build system with the Jackson data format, we would add the following dependency:

<?xml version="1.0" encoding="UTF-8"?>
<project ...>
  ...
  <dependencies>
    ...
    <!-- use for json binding --> <dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-jackson</artifactId> </dependency>
    ...
  </dependencies>
</project>

REST DSL Route with JSON Binding

<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           ...>
  ...
  <!-- a bean for user services -->
  <bean id="userService" class="org.apache.camel.example.rest.UserService"/>

  <camelContext xmlns="http://camel.apache.org/schema/blueprint">

    <restConfiguration component="servlet"
                       bindingMode="json"
                       contextPath="/camel-example-servlet-rest-blueprint/rest"
                       port="8181">
      <dataFormatProperty key="prettyPrint" value="true"/>
    </restConfiguration>

    <!-- defines the REST services using the  base path, /user -->
    <rest path="/user" consumes="application/json" produces="application/json">
      <description>User rest service</description>

      <!-- this is a rest GET to view a user with the given id -->
      <get uri="/{id}" outType="org.apache.camel.example.rest.User">
        <description>Find user by id</description>
        <to uri="bean:userService?method=getUser(${header.id})"/>
      </get>

      <!-- this is a rest PUT to create/update a user -->
      <put type="org.apache.camel.example.rest.User">
        <description>Updates or create a user</description>
        <to uri="bean:userService?method=updateUser"/>
      </put>

      <!-- this is a rest GET to find all users -->
      <get uri="/findAll" outType="org.apache.camel.example.rest.User[]">
        <description>Find all users</description>
        <to uri="bean:userService?method=listUsers"/>
      </get>

    </rest>