native-support-for-json.adoc

Native Support for JSON

JSON is now natively supported in Mule, meaning you can work with JSON documents and bind them automatically to Java objects. Further information is available in the JSON Module configuration reference.

JSON Transformers Added

JSON transformers have been added to make it easy to work with JSON encoded messages. We have used the excellent Jackson Framework which means Mule also supports JSON /Object bindings.

Examples

For example, using AJAX, you usually receive JSON. From here, you can get a request for a javabean from the server side, and you can convert that automatically to JSON.

Another example, if you get a request from outside, such as a Webservice request, your REST type content could be JSON or XML, while internally the components would be javabeans.

In this case, the feature would automatically respond to a JSON request with a JSON response.

Using the JSON Module

JSON, short for JavaScript Object Notation, is a lightweight data interchange format. It is a text-based, human-readable format for representing simple data structures and associative arrays (called objects).

JSON Bindings

Mule support binding JSON data to objects and marshaling Java object to JSON using the Jackson Framework. Jackson uses annotations to describe how data is mapped to a Java object model. For example, lets say we have an JSON file that describes a person. When we receive that JSON data we want to convert it into a Person object. The JSON looks like this:

{
    "name":"John Doe",
    "dob":"01/01/1970",
    "emailAddresses":[
        {
            "type":"home",
            "address":"john.doe@gmail.com"
        },
        {
            "type":"work",
            "address":"jdoe@bigco.com"
        }
    ]
}

And we have an object Person we want to create from the JSON data. We use annotations to describe how to perform the mapping. We use the @JsonAutoDetect to say that field member names map directly to JSON field names:

@JsonAutoDetect
public class Person
{
    private String name;
    private String dob;

    private List<EmailAddress> emailAddresses;

    public String getName()
    {
        return name;
    }

    public void setName(String name)
    {
        this.name = name;
    }

    public String getDob()
    {
        return dob;
    }

    public void setDob(String dob)
    {
        this.dob = dob;
    }

    public List<EmailAddress> getEmailAddresses()
    {
        return emailAddresses;
    }

    public void setEmailAddresses(List<EmailAddress> emailAddresses)
    {
        this.emailAddresses = emailAddresses;
    }
}

The EmailAddress object that is used in the emailAddresses is just another JavaBean with the @JsonAutoDetect annotation.

At this point iBeans can figure out whether to perform a JSON transforms based on the parameters of the method being called. For example:

public class PersonService {

    public void processPerson(Person person) {
        //tickle person
    }
}

Now if we configure this component in a flow:

<flow name="processPerson">
    <jms:inbound-endpoint queue="people.queue"/>
    <component class="org.mule.example.PersonService"/>
</flow>

Here we could receive the contents of the people.json file above on a JMS queue, Mule would see that Person.class is an annotated JSON object and that we had received JSON data from the JMS queue and perform the conversion.

Using the Transformers Explicitly

Often you may want to define a transformer explicitly in Mule, this is done by importing the json namespace:

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:json="http://www.mulesoft.org/schema/mule/json"
      xsi:schemaLocation="
       http://www.mulesoft.org/schema/mule/core
http://www.mulesoft.org/schema/mule/core/3.6/mule.xsd
       http://www.mulesoft.org/schema/mule/json
http://www.mulesoft.org/schema/mule/json/3.6/mule-json.xsd">

</mule>

Then simply configuring the transformer like any other transformer. When converting from JSON to an object form the transformer needs to define the returnClass This is the class that the Json payload will get transformed into.

<json:json-to-object-transformer name="jsonToFruitCollection" returnClass="
org.mule.module.json.transformers.FruitCollection"/>

When converting an object to Json, you need to specify the expected source class to convert -

<json:object-to-json-transformer name="fruitCollectionToJson"
     sourceClass="org.mule.module.json.transformers.FruitCollection">

Annotating objects

Jackson uses annotations to describe how to marshal and unmarshal an object to and from JSON, this is similar in concept to JAXB. However, sometimes it may not be possible to annotate the object class you want to marshal (usually because you do not have access to its source code). Instead you can define mixins. A Mixin is an interface or abstract class (needed when doing constructor injection) that defines abstract methods with Jackson annotations. The method signatures must match the methods on the object being mashalled, at runtime the annotations will be 'mixed' with the object type. To configure Mixins, use the mixin-map element or configure them on the transformer directly.

<json:mixin-map name="myMixins">
    <json:mixin mixinClass="org.mule.module.json.transformers.FruitCollectionMixin"
        targetClass="org.mule.module.json.transformers.FruitCollection"/>
    <json:mixin
        mixinClass="org.mule.module.json.transformers.AppleMixin"
        targetClass="org.mule.tck.testmodels.fruit.Apple"/>
</json:mixin-map>

    <json:json-to-object-transformer name="jsonToFruitCollection" returnClass="
org.mule.module.json.transformers.FruitCollection" mixins-ref="myMixins">

Or on the transformer directly -

<json:object-to-json-transformer name="fruitCollectionToJson"
            sourceClass="org.mule.module.json.transformers.FruitCollection">
        <json:serialization-mixin
                mixinClass="org.mule.module.json.transformers.AppleMixin"
                targetClass="org.mule.tck.testmodels.fruit.Apple"/>
</json:object-to-json-transformer>