Overview

JSON short for JavaScript Object Notation, is a lightweight computer data interchange format. It is a text-based, human-readable format for representing simple data structures and associative arrays (called objects). This module provides transformers and filters for working with JSON encoded messages including converting to and from JavaBeans and XML.

Classpath Settings

The latest JSON module uses JSON-Lib 2.2.3 JDK5 and has been tested with Mule 2.2.1.

Mule Standalone

To set up the Mule classpath to use JSON transformers, you must first download the Mule JSON distribution. Then simply take all the JARs inside the distribution lib/ directory and put them in MULE_HOME/lib/user.

Maven

If you are using Maven, you can use the MuleForge repositories and add a dependency to Jersey that way. First add the MuleForge repository to your POM:

<repositories>
    <repository>
      <id>muleforge</id>
      <name>MuleForge Repository</name>
      <url>http://repository.muleforge.org</url>
    </repository>
</repositories>

Then add the dependency:

<dependencies>
  <dependency>
    <groupId>org.mule.modules</groupId>
    <artifactId>mule-module-json</artifactId>
    <version>2.2</version>
  </dependency>
</dependencies>

Using the JSON module

Once you have included the JSON module in your project or in the Mule distribution you can use it by adding the JSON namespace in your Mule XML configuration file -

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesource.org/schema/mule/core/2.2"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:json="http://www.mulesource.org/schema/mule/json/2.2"
      xsi:schemaLocation="
       http://www.mulesource.org/schema/mule/core/2.2 
http://www.mulesource.org/schema/mule/core/2.2/mule.xsd
       http://www.mulesource.org/schema/mule/json/2.2 
http://www.mulesource.org/schema/mule/json/2.2/mule-json.xsd">

</mule>

Now you can start using JSON configuration elements in your configuration.

Configuration Reference

Transformers

<object-to-json-transformer ...>

Converts a java object to a JSON encoded object that can be consumed by other languages such as Javascript or Ruby. The JSON engine can be configured using the jsonConfig attribute. This is an object reference to an instance of: net.sf.json.JsonConfig. This can be created as a spring bean. Users can configure a comma-separated list of property names to exclude or include i.e. excludeProperties="address,postcode". The returnClass for this transformer is always java.lang.String, there is no need to set this.

Attributes

Name	Type	Required	Description
jsonConfig-ref	string	no	The JSON engine can be configured using the jsonConfig attribute. This is an object reference to an instance of: net.sf.json.JsonConfig. This can be created as a spring bean.
excludeProperties	string	no	Users can configure a comma-separated list of property names to exclude i.e. excludeProperties="address,postcode".
includeProperties	string	no	Configure a comma-separated list of property names to include i.e. includeProperties="name,email".
sourceClass	name (no spaces)	no	Restrict the accepted source class object to a specific type. If not set the transformer will handle all source types.

Child Elements

Name	Cardinality	Description

Example

In this example we configure a transformer to convert from a JavaBean to a JSON encoded string. The transformer by default will encode any JavaBean, but we have restricted the object type it can handle by setting sourceClass to org.mule.tck.models.fruit.Orange.
We also exclude the brand and radius properties, these will not be serialized.

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesource.org/schema/mule/core/2.2"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:json="http://www.mulesource.org/schema/mule/json/2.2"
      xsi:schemaLocation="
       http://www.mulesource.org/schema/mule/core/2.2 
http://www.mulesource.org/schema/mule/core/2.2/mule.xsd
       http://www.mulesource.org/schema/mule/json/2.2 
http://www.mulesource.org/schema/mule/json/2.2/mule-json.xsd">

   <json:object-to-json-transformer name="orangeToJson" excludeProperties="brand, radius" sourceClass="org.mule.tck.testmodels.fruit.Orange"/>
</mule>

<json-to-object-transformer ...>

A transformer that will convert a JSON encoded object graph to a java object. The object type is determined by the 'returnClass' attribute. Note that this transformers supports Arrays and Lists. For example, to convert a JSON string to an array of org.foo.Person, set the the returnClass=[Lorg.foo.Person; . The JSON engine can be configured using the jsonConfig attribute. This is an object reference to an instance of: net.sf.json.JsonConfig. This can be created as a spring bean.

Attributes

Name	Type	Required	Default	Description
jsonConfig-ref	string	no		The JSON engine can be configured using the jsonConfig attribute. This is an object reference to an instance of: net.sf.json.JsonConfig. This can be created as a spring bean.

Child Elements

Name	Cardinality	Description

Example

In this example we configure a custom instance of the jsonConfig object (using Spring notation) which gives you full control over the Json Transformation. See the JSON-Lib JavaDocs for more information about this class.

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesource.org/schema/mule/core/2.2"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:json="http://www.mulesource.org/schema/mule/json/2.2"
      xmlns:spring="http://www.springframework.org/schema/beans"
      xsi:schemaLocation="
       http://www.springframework.org/schema/beans 
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
       http://www.mulesource.org/schema/mule/core/2.2 
http://www.mulesource.org/schema/mule/core/2.2/mule.xsd
       http://www.mulesource.org/schema/mule/json/2.2 
http://www.mulesource.org/schema/mule/json/2.2/mule-json.xsd">

    <json:json-to-object-transformer name="jsonToOrangeArray" returnClass="org.mule.tck.testmodels.fruit.Orange"
                                     jsonConfig-ref="jsonConfig"/>


    <spring:bean name="jsonConfig" class="net.sf.json.JsonConfig">
        <spring:property name="classMap">
            <spring:map value-type="java.lang.Class">
                <spring:entry key="apple" value="org.mule.tck.testmodels.fruit.Apple"/>
                <spring:entry key="banana" value="org.mule.tck.testmodels.fruit.Banana"/>
            </spring:map>
        </spring:property>
    </spring:bean>
</mule>

<json-to-xml-transformer ...>

Converts a JSON encoded object representation in to an XML representation. Each property and enclosing element are wrapped in XML elements these generated element names can be set on the transformer. Names can be configured for Object elements, array elements and value elements. The returnClass for this transformer is always java.lang.String, there is no need to set this.

Attributes

Name	Type	Required	Description
objectElementName	name (no spaces)	no	The XML element name to use for representing objects in the JSON ecoded object. The default is 'o'.
arrayElementName	name (no spaces)	no	The XML element name to use for representing objects in the JSON ecoded object. The default is 'a'.
valueElementName	name (no spaces)	no	The XML element name to use for representing object values (properties) in the JSON ecoded object. The default is 'e'.

Child Elements

Name	Cardinality	Description

Example

In this example we configure a transformer to convert from JSON to Xml. We define the element names for arrays, objects and values.

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesource.org/schema/mule/core/2.2"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:json="http://www.mulesource.org/schema/mule/json/2.2"
      xsi:schemaLocation="
       http://www.mulesource.org/schema/mule/core/2.2 
http://www.mulesource.org/schema/mule/core/2.2/mule.xsd
       http://www.mulesource.org/schema/mule/json/2.2 
http://www.mulesource.org/schema/mule/json/2.2/mule-json.xsd">

  <json:json-to-xml-transformer name="jsonToXml" arrayElementName="array" objectElementName="obj" valueElementName="value"/>

If we have the JSON string:

{'name': 'foo', 'passwd': 'bar'}

It will get converted into:

<obj><name type="string">foo</name><passwd type="string">bar</passwd></obj>

Filters

<is-json-filter ...>

A filter that will determine if the current message payload is a JSON encoded message.

Attributes

Name	Type	Required	Default	Description

Child Elements

Name	Cardinality	Description

Example

There are not configuration parameters for this filter.

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesource.org/schema/mule/core/2.2"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:json="http://www.mulesource.org/schema/mule/json/2.2"
      xsi:schemaLocation="
       http://www.mulesource.org/schema/mule/core/2.2 
http://www.mulesource.org/schema/mule/core/2.2/mule.xsd
       http://www.mulesource.org/schema/mule/json/2.2 
http://www.mulesource.org/schema/mule/json/2.2/mule-json.xsd">

  <json:is-json-filter name="jsonFilter"/>

Table of Contents

Overview

Classpath Settings

Mule Standalone

Maven

Using the JSON module

Configuration Reference

Transformers

<object-to-json-transformer ...>

Attributes

Child Elements

Example

<json-to-object-transformer ...>

Attributes

Child Elements

Example

<json-to-xml-transformer ...>

Attributes

Child Elements

Example

Filters

<is-json-filter ...>

Attributes

Child Elements

Example

Labels