JSON
JSON is a Data Format to marshal and unmarshal Java objects to and from JSON.
For JSON to object marshalling, Camel provides integration with three popular JSON libraries:
- The XStream library and Jettsion
- The Jackson library
- Camel 2.10: The GSon library
By default Camel uses the XStream library.
Direct, bi-directional JSON <=> XML conversions
As of Camel 2.10, Camel supports direct, bi-directional JSON <=> XML conversions via the camel-xmljson data format, which is documented separately.
Using JSON data format with the XStream library
// lets turn Object messages into json then send to MQSeries from("activemq:My.Queue"). marshal().json(). to("mqseries:Another.Queue");
Using JSON data format with the Jackson library
// lets turn Object messages into json then send to MQSeries from("activemq:My.Queue"). marshal().json(JsonLibrary.Jackson). to("mqseries:Another.Queue");
Using JSON data format with the GSON library
// lets turn Object messages into json then send to MQSeries from("activemq:My.Queue"). marshal().json(JsonLibrary.Gson). to("mqseries:Another.Queue");
Using JSON in Spring DSL
When using Data Format in Spring DSL you need to declare the data formats first. This is done in the DataFormats XML tag.
<dataFormats> <!-- here we define a Json data format with the id jack and that it should use the TestPojo as the class type when doing unmarshal. The unmarshalTypeName is optional, if not provided Camel will use a Map as the type --> <json id="jack" library="Jackson" unmarshalTypeName="org.apache.camel.component.jackson.TestPojo"/> </dataFormats>
And then you can refer to this id in the route:
<route> <from uri="direct:back"/> <unmarshal ref="jack"/> <to uri="mock:reverse"/> </route>
Excluding POJO fields from marshalling
As of Camel 2.10
When marshalling a POJO to JSON you might want to exclude certain fields from the JSON output. With Jackson you can use JSON views to accomplish this. First create one or more marker classes.
Use the marker classes with the @JsonView
annotation to include/exclude certain fields. The annotation also works on getters.
Finally use the Camel JacksonDataFormat
to marshall the above POJO to JSON.
Note that the weight field is missing in the resulting JSON:
{"age":30, "weight":70}
The GSON library supports a similar feature through the notion of ExclusionStrategies:
The GsonDataFormat
accepts an ExclusionStrategy
in its constructor:
The line above will exclude fields annotated with @ExcludeAge
when marshalling to JSON.
Configuring field naming policy
Available as of Camel 2.11
The GSON library supports specifying policies and strategies for mapping from json to POJO fields. A common naming convention is to map json fields using lower case with underscores.
We may have this JSON string
{ "id" : 123, "first_name" : "Donald" "last_name" : "Duck" }
Which we want to map to a POJO that has getter/setters as
public class PersonPojo { private int id; private String firstName; private String lastName; public int getId() { return id; } public void setId(int id) { this.id = id; } public String getFirstName() { return firstName; } public void setFirstName(String firstName) { this.firstName = firstName; } public String getLastName() { return lastName; } public void setLastName(String lastName) { this.lastName = lastName; } }
Then we can configure the org.apache.camel.component.gson.GsonDataFormat
in a Spring XML files as shown below. Notice we use fieldNamingPolicy
property to set the field mapping. This property is an enum from GSon com.google.gson.FieldNamingPolicy
which has a number of pre defined mappings. If you need full control you can use the property FieldNamingStrategy
and implement a custom com.google.gson.FieldNamingStrategy
where you can control the mapping.
<!-- define the gson data format, where we configure the data format using the properties --> <bean id="gson" class="org.apache.camel.component.gson.GsonDataFormat"> <!-- we want to unmarshal to person pojo --> <property name="unmarshalType" value="org.apache.camel.component.gson.PersonPojo"/> <!-- we want to map fields to use lower case and underscores --> <property name="fieldNamingPolicy" value="LOWER_CASE_WITH_UNDERSCORES"/> </bean>
And use it in Camel routes by referring to its bean id as shown:
<camelContext xmlns="http://camel.apache.org/schema/spring"> <route> <from uri="direct:inPojo"/> <marshal ref="gson"/> </route> <route> <from uri="direct:backPojo"/> <unmarshal ref="gson"/> </route> </camelContext>
Include/Exclude fields using the jsonView
attribute with JacksonDataFormat
Available as of Camel 2.12
As an example of using this attribute you can instead of:
JacksonDataFormat ageViewFormat = new JacksonDataFormat(TestPojoView.class, Views.Age.class); from("direct:inPojoAgeView"). marshal(ageViewFormat);
Directly specify your JSON view inside the Java DSL as:
from("direct:inPojoAgeView"). marshal().json(TestPojoView.class, Views.Age.class);
And the same in XML DSL:
<from uri="direct:inPojoAgeView"/> <marshal> <json library="Jackson" unmarshalTypeName="org.apache.camel.component.jackson.TestPojoView" jsonView="org.apache.camel.component.jackson.Views$Age"/> </marshal>
Setting serialization include option for Jackson marshal
Available as of Camel 2.13.3/2.14
If you want to marshal a pojo to JSON, and the pojo has some fields with null values. And you want to skip these null values, then you need to set either an annotation on the pojo,
@JsonInclude(Include.NON_NULL) public class MyPojo { ... }
But this requires you to include that annotation in your pojo source code. You can also configure the Camel JsonDataFormat to set the include option, as shown below:
JacksonDataFormat format = new JacksonDataFormat(); format.setInclude("NON_NULL");
Or from XML DSL you configure this as
<dataFormats> <json id="json" library="Jackson" include="NOT_NULL"/> </dataFormats>
Unmarshalling from json to POJO with dynamic class name
Available as of Camel 2.14
If you use jackson to unmarshal json to POJO, then you can now specify a header in the message that indicate which class name to unmarshal to.
The header has key CamelJacksonUnmarshalType
if that header is present in the message, then Jackson will use that as FQN for the POJO class to unmarshal the json payload as. Notice that behavior is enabled out of the box from Camel 2.14 onwards.
For JMS end users there is the JMSType header from the JMS spec that indicates that also. To enable support for JMSType you would need to turn that on, on the jackson data format as shown:
JacksonDataFormat format = new JacksonDataFormat(); format.setAllowJmsType(true);
Or from XML DSL you configure this as
<dataFormats> <json id="json" library="Jackson" allowJmsType="true"/> </dataFormats>
Unmarshalling from json to List<Map> or List<pojo>
Available as of Camel 2.14
If you are using Jackson to unmarshal json to a list of map/pojo, you can now specify this by setting useList="true"
or use the org.apache.camel.component.jackson.ListJacksonDataFormat
. For example with Java you can do as shown below:
JacksonDataFormat format = new ListJacksonDataFormat(); // or JacksonDataFormat format = new JacksonDataFormat(); format.useList(); // and you can specify the pojo class type also format.setUnmarshalType(MyPojo.class);
And if you use XML DSL then you configure to use list using useList
attribute as shown below:
<dataFormats> <json id="json" library="Jackson" useList="true"/> </dataFormats>
And you can specify the pojo type also
<dataFormats> <json id="json" library="Jackson" useList="true" unmarshalTypeName="com.foo.MyPojo"/> </dataFormats>
Dependencies for XStream
To use JSON in your camel routes you need to add the a dependency on camel-xstream which implements this data format.
If you use maven you could just add the following to your pom.xml, substituting the version number for the latest & greatest release (see the download page for the latest versions).
<dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-xstream</artifactId> <version>2.9.2</version> </dependency>
Dependencies for Jackson
To use JSON in your camel routes you need to add the a dependency on camel-jackson which implements this data format.
If you use maven you could just add the following to your pom.xml, substituting the version number for the latest & greatest release (see the download page for the latest versions).
<dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-jackson</artifactId> <version>2.9.2</version> </dependency>
Dependencies for GSON
To use JSON in your camel routes you need to add the a dependency on camel-gson which implements this data format.
If you use maven you could just add the following to your pom.xml, substituting the version number for the latest & greatest release (see the download page for the latest versions).
<dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-gson</artifactId> <version>2.10.0</version> </dependency>