Chapter 184. JSon Jackson DataFormat

Available as of Camel version 2.0

Jackson is a Data Format which uses the Jackson Library

from("activemq:My.Queue").
  marshal().json(JsonLibrary.Jackson).
  to("mqseries:Another.Queue");

184.1. Jackson Options

The JSon Jackson dataformat supports 19 options, which are listed below.

Name	Default	Java Type	Description
objectMapper		`String`	Lookup and use the existing ObjectMapper with the given id when using Jackson.
useDefaultObjectMapper	`true`	`Boolean`	Whether to lookup and use default Jackson ObjectMapper from the registry.
prettyPrint	`false`	`Boolean`	To enable pretty printing output nicely formatted. Is by default false.
library	`XStream`	`JsonLibrary`	Which json library to use.
unmarshalTypeName		`String`	Class name of the java type to use when unarmshalling
jsonView		`Class`	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. This option is to refer to the class which has JsonView annotations
include		`String`	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, you can set this option to NON_NULL
allowJmsType	`false`	`Boolean`	Used for JMS users to allow the JMSType header from the JMS spec to specify a FQN classname to use to unmarshal to.
collectionTypeName		`String`	Refers to a custom collection type to lookup in the registry to use. This option should rarely be used, but allows to use different collection types than java.util.Collection based as default.
useList	`false`	`Boolean`	To unarmshal to a List of Map or a List of Pojo.
enableJaxbAnnotationModule	`false`	`Boolean`	Whether to enable the JAXB annotations module when using jackson. When enabled then JAXB annotations can be used by Jackson.
moduleClassNames		`String`	To use custom Jackson modules com.fasterxml.jackson.databind.Module specified as a String with FQN class names. Multiple classes can be separated by comma.
moduleRefs		`String`	To use custom Jackson modules referred from the Camel registry. Multiple modules can be separated by comma.
enableFeatures		`String`	Set of features to enable on the Jackson com.fasterxml.jackson.databind.ObjectMapper. The features should be a name that matches a enum from com.fasterxml.jackson.databind.SerializationFeature, com.fasterxml.jackson.databind.DeserializationFeature, or com.fasterxml.jackson.databind.MapperFeature Multiple features can be separated by comma
disableFeatures		`String`	Set of features to disable on the Jackson com.fasterxml.jackson.databind.ObjectMapper. The features should be a name that matches a enum from com.fasterxml.jackson.databind.SerializationFeature, com.fasterxml.jackson.databind.DeserializationFeature, or com.fasterxml.jackson.databind.MapperFeature Multiple features can be separated by comma
permissions		`String`	Adds permissions that controls which Java packages and classes XStream is allowed to use during unmarshal from xml/json to Java beans. A permission must be configured either here or globally using a JVM system property. The permission can be specified in a syntax where a plus sign is allow, and minus sign is deny. Wildcards is supported by using . as prefix. For example to allow com.foo and all subpackages then specfy com.foo.. Multiple permissions can be configured separated by comma, such as com.foo.,-com.foo.bar.MySecretBean. The following default permission is always included: -,java.lang.,java.util. unless its overridden by specifying a JVM system property with they key org.apache.camel.xstream.permissions.
allowUnmarshallType	`false`	`Boolean`	If enabled then Jackson is allowed to attempt to use the CamelJacksonUnmarshalType header during the unmarshalling. This should only be enabled when desired to be used.
timezone		`String`	If set then Jackson will use the Timezone when marshalling/unmarshalling. This option will have no effect on the others Json DataFormat, like gson, fastjson and xstream.
contentTypeHeader	`true`	`Boolean`	Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc.

184.2. Spring Boot Auto-Configuration

The component supports 20 options, which are listed below.

Name	Description	Default	Type
camel.dataformat.json-jackson.allow-jms-type	Used for JMS users to allow the JMSType header from the JMS spec to specify a FQN classname to use to unmarshal to.	false	Boolean
camel.dataformat.json-jackson.allow-unmarshall-type	If enabled then Jackson is allowed to attempt to use the CamelJacksonUnmarshalType header during the unmarshalling. This should only be enabled when desired to be used.	false	Boolean
camel.dataformat.json-jackson.collection-type-name	Refers to a custom collection type to lookup in the registry to use. This option should rarely be used, but allows to use different collection types than java.util.Collection based as default.		String
camel.dataformat.json-jackson.content-type-header	Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc.	false	Boolean
camel.dataformat.json-jackson.disable-features	Set of features to disable on the Jackson com.fasterxml.jackson.databind.ObjectMapper. The features should be a name that matches a enum from com.fasterxml.jackson.databind.SerializationFeature, com.fasterxml.jackson.databind.DeserializationFeature, or com.fasterxml.jackson.databind.MapperFeature Multiple features can be separated by comma		String
camel.dataformat.json-jackson.enable-features	Set of features to enable on the Jackson com.fasterxml.jackson.databind.ObjectMapper. The features should be a name that matches a enum from com.fasterxml.jackson.databind.SerializationFeature, com.fasterxml.jackson.databind.DeserializationFeature, or com.fasterxml.jackson.databind.MapperFeature Multiple features can be separated by comma		String
camel.dataformat.json-jackson.enable-jaxb-annotation-module	Whether to enable the JAXB annotations module when using jackson. When enabled then JAXB annotations can be used by Jackson.	false	Boolean
camel.dataformat.json-jackson.enabled	Enable json-jackson dataformat	true	Boolean
camel.dataformat.json-jackson.include	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, you can set this option to NON_NULL		String
camel.dataformat.json-jackson.json-view	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. This option is to refer to the class which has JsonView annotations		Class
camel.dataformat.json-jackson.library	Which json library to use.		JsonLibrary
camel.dataformat.json-jackson.module-class-names	To use custom Jackson modules com.fasterxml.jackson.databind.Module specified as a String with FQN class names. Multiple classes can be separated by comma.		String
camel.dataformat.json-jackson.module-refs	To use custom Jackson modules referred from the Camel registry. Multiple modules can be separated by comma.		String
camel.dataformat.json-jackson.object-mapper	Lookup and use the existing ObjectMapper with the given id when using Jackson.		String
camel.dataformat.json-jackson.permissions	Adds permissions that controls which Java packages and classes XStream is allowed to use during unmarshal from xml/json to Java beans. A permission must be configured either here or globally using a JVM system property. The permission can be specified in a syntax where a plus sign is allow, and minus sign is deny. Wildcards is supported by using . as prefix. For example to allow com.foo and all subpackages then specfy com.foo.. Multiple permissions can be configured separated by comma, such as com.foo.,-com.foo.bar.MySecretBean. The following default permission is always included: -,java.lang.,java.util. unless its overridden by specifying a JVM system property with they key org.apache.camel.xstream.permissions.		String
camel.dataformat.json-jackson.pretty-print	To enable pretty printing output nicely formatted. Is by default false.	false	Boolean
camel.dataformat.json-jackson.timezone	If set then Jackson will use the Timezone when marshalling/unmarshalling. This option will have no effect on the others Json DataFormat, like gson, fastjson and xstream.		String
camel.dataformat.json-jackson.unmarshal-type-name	Class name of the java type to use when unarmshalling		String
camel.dataformat.json-jackson.use-default-object-mapper	Whether to lookup and use default Jackson ObjectMapper from the registry.	true	Boolean
camel.dataformat.json-jackson.use-list	To unarmshal to a List of Map or a List of Pojo.	false	Boolean

184.3. Using custom ObjectMapper

You can configure JacksonDataFormat to use a custom ObjectMapper in case you need more control of the mapping configuration.

If you setup a single ObjectMapper in the registry, then Camel will automatic lookup and use this ObjectMapper. For example if you use Spring Boot, then Spring Boot can provide a default ObjectMapper for you if you have Spring MVC enabled. And this would allow Camel to detect that there is one bean of ObjectMapper class type in the Spring Boot bean registry and then use it. When this happens you should set a INFO logging from Camel.

184.4. Dependencies

To use Jackson in your camel routes you need to add the 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>x.x.x</version>
  <!-- use the same version as your Camel core version -->
</dependency>

184.5. Jackson ObjectMapper

184.5.1. What is object mapping?

Jackson provides a mechanism for serializing Java objects, using the com.fasterxml.jackson.databind.ObjectMapper class. For example, you can serialize a MyClass java object using ObjectMapper, as follows:

ObjectMapper objectMapper = new ObjectMapper();
MyClass myobject = new MyClass("foo", "bar");
objectMapper.writeValue(new File("myobject.json"), myobject);

The object, myobject, gets serialized to JSON format and written to the file, myobject.json (Jackson also supports conversion to XML and YAML formats).

To deserialize the JSON contents of the file, myobject.json, you can invoke the ObjectMapper as follows:

ObjectMapper objectMapper = new ObjectMapper();
MyClass myobject = objectMapper.readValue(new File("myobject.json"), MyClass.class);

Note that the receiver needs to know the type of the class in advance and must specify the type, MyClass.class, as the second argument to readValue().

184.5.2. What is polymorphic object mapping?

In some cases, it is impossible for the receiver of a serialized object to know the object’s type in advance. For example, this applies to the case of a polymorphic object array. Consider the abstract type, Shape, and its subtypes, Triangle, Square (and so on):

package com.example;
...
public abstract class Shape {
}

public class Triangle extends Shape {
  ...
}

public class Square extends Shape {
  ...
}

public class ListOfShape {
  public List<Shape> shapes;
  ...
}

You can instantiate and serialize an array list of shapes (ListOfShape) as follows:

ObjectMapper objectMapper = new ObjectMapper();

ListOfShape shapeList = new ListOfShape();
shapeList.shapes = new ArrayList<Shape>();
shapeList.shapes.add(new Triangle());
shapeList.shapes.add(new Square());

String serialized = objectMapper.writeValueAsString(shapeList);

But there is now a problem on the receiver side. You can tell the receiver to expect a ListOfShape object, by specifying this type as the second argument to readValue():

MyClass myobject = objectMapper.readValue(serialized, ListOfShape.class);
ObjectMapper objectMapper = new ObjectMapper();

However, there is no way that the receiver can know that the first element of the list is Triangle and the second element is Square. To get around this problem, you need to enable polymorphic object mapping as described in the next section.

184.5.3. How to enable polymorphic object mapping

Polymorphic object mapping is a mechanism that makes it possible to serialize and deserialize arrays of abstract classes, by providing additional metadata in the serialized array, which identifies the type of the objects in the array.

Important

Polymorphic object mapping poses an inherent security risk, because the mechanism allows the sender to choose which class to instantiate, which can form the basis of an attack by the sender. Red Hat’s distribution of the FasterXML Jackson library features a whitelist mechanism, which provides an extra level of protection against this threat. You must ensure that you are using Red Hat’s distribution of the jackson-databind library (provided with Fuse versions 7.7 and later) in order to get this additional layer of protection. For more details, see Section 184.5.5, “Security risk from polymorphic deserialization”.

To make it possible for the receiver to deserialize the objects in an array, it is necessary to provide type metadata in the serialized data. By default, Jackson does not encode any type metadata for serialized objects, so you need to write some additional code to enable this feature.

To enable polymorphic object mapping, perform the following steps (using ListOfShape as an example):

For each of the classes that can be elements of the list (subclasses of Shape), annotate the class with @JsonTypeInfo, as follows:
```
@JsonTypeInfo(use=JsonTypeInfo.Id.CLASS, include=JsonTypeInfo.As.PROPERTY)
public class Triangle extends Shape {
  ...
}
```

When the Triangle class is serialized to JSON format, it has the following format:

{"@class":"com.example.Triangle", "property1":"value1", "property2":"value2", ...}

The receiver must be configured to allow deserialization of the Triangle, Square, and other shape classes, by adding these classes to the deserialization whitelist. To configure the whitelist, set the jackson.deserialization.whitelist.packages system property to a comma-separated list of classes and packages. For example, to allow deserialization of the Triangle, Square classes, set the system property as follows:
```
-Djackson.deserialization.whitelist.packages=com.example.Triangle,com.example.Square
```
Alternatively, you could set the system property to allow the entire com.example package:
```
-Djackson.deserialization.whitelist.packages=com.example
```
Note
This whitelist mechanism is available only for Red Hat’s distribution of the jackson-databind library. The standard jackson-databind library uses a blacklist mechanism instead, which needs to be updated every time a potentially dangerous new gadget class is discovered.

184.5.4. Default mapping for polymorphic deserialization

If a given Java class, com.example.MyClass, is not whitelisted, it is still possible to serialize instances of the class, but on the receiving side, the instances will be deserialized using a generic, default mapping.

When polymorphic object mapping is enabled in Jackson, there are a few alternative ways of encoding an object:

With @JsonTypeInfo(use=JsonTypeInfo.Id.CLASS, include=JsonTypeInfo.As.PROPERTY):
```
{"@class":"com.example.MyClass", "property1":"value1", "property2":"value2", ...}
```
In this case, the instance will be deserialized to an Object with properties.
With @JsonTypeInfo(use=JsonTypeInfo.Id.CLASS, include=JsonTypeInfo.As.WRAPPER_ARRAY):
```
["com.example.MyClass", {"property1":"value1", "property2":"value2", ...}]
```
In this case, the instance will be deserialized to a JSON array containing two fields:
- String with value com.example.MyClass
- Object with two (or more) properties
With @JsonTypeInfo(use=JsonTypeInfo.Id.CLASS, include=JsonTypeInfo.As.WRAPPER_OBJECT):
```
{"com.example.MyClass":{"property1":"value1", "property2":"value2", ...}}
```
In this case, the instance will be deserialized to a JSON map with a single field, com.example.MyClass, and the value as Object having two (or more) properties.

184.5.5. Security risk from polymorphic deserialization

Applications that that use the FasterXML jackson-databind library to instantiate Java objects by deserializing JSON content are potentially vulnerable to a remote code execution attack. The vulnerability is not automatic, however, and it can be avoided if you take the appropriate mitigation steps.

At a minimum, the following prerequisites must all be satisfied before an attack becomes possible:

You have enabled polymorphic type handling for deserialization of JSON content in jackson-databind. There are two alternative ways of enabling polymorphic type handling in Jackson JSON:
1. Using a combination of the @JsonTypeInfo and @JsonSubTypes annotations.
2. By calling the ObjectMapper.enableDefaultTyping() method. This option is particularly dangerous, as it effectively enables polymorphic typing globally.
There are one or more gadget classes in your Java classpath. A gadget class is defined as any class that performs a sensitive (potentially exploitable) operation as a side effect of executing a constructor or a setter method (which are the methods that can be called during a deserialization).
One or more gadget classes in your Java classpath have not yet been blacklisted by the current version of jackson-databind. If you are using the standard distribution of the jackson-databind library, the gadget blacklist maintained by the Jackson JSON library is the last line of defence against the remote code execution vulnerability.
(Red Hat distribution of jackson-databind library only) You explicitly added one of the gadget classes to the deserialization whitelist on the receiver (by setting the jackson.deserialization.whitelist.packages system property). As this is something you are unlikely to do, the whitelist mechanism provides effective protection against all gadget classes by default.

Chapter 184. JSon Jackson DataFormat

184.1. Jackson Options

184.2. Spring Boot Auto-Configuration

184.3. Using custom ObjectMapper

184.4. Dependencies

184.5. Jackson ObjectMapper

184.5.1. What is object mapping?

184.5.2. What is polymorphic object mapping?

184.5.3. How to enable polymorphic object mapping

184.5.4. Default mapping for polymorphic deserialization

184.5.5. Security risk from polymorphic deserialization

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links