JSON Support

RESTful

JSON Support


Jersey JSON support comes as a set of JAX-RS MessageBodyReader and MessageBodyWriter providers distributed with jersey-json module. These providers enable using three basic approaches when working with JSON format: POJO support, JAXB suppport and low-level support.

We will overview all approaches of using JSON format in the article. All examples will need a dependency to jersey-json module in pom.xml:

<dependency>
     <groupId>com.sun.jersey</groupId>
     <artifactId>jersey-json</artifactId>
     <version>1.17</version>
</dependency>

1. POJO Support

POJO support represents the most simple way to convert POJO to JSON and back.

Example 1.1. POJO

The Exam is a class of objects, which will be converted to JSON:

public class Exam {
    public int id;
    public String name;

    public Exam() {}
    public Exam(int id, String name) {
        this.id = id;
        this.name = name;
    }
}

Example 1.2. RESTful Web Services Jersey JSON example

ExamService's method getExam() is signed as produced MediaType.APPLICATION_JSON:

@Path("exam")
public class ExamService {
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Exam getExam() {
        return new Exam(3, "OCEJWSD 6");
    }
}

Example 1.3. Setting JSONConfiguration.FEATURE_POJO_MAPPING feature in web.xml

To use this approach, it is required to turn the JSONConfiguration.FEATURE_POJO_MAPPING feature on. This can be done in web.xml setting the feature in servlet init parameter:

<servlet>
    <servlet-name>Example Component</servlet-name>
    <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
    <init-param>
        <param-name>jersey.config.server.provider.packages</param-name>
        <param-value>com.examclouds</param-value>
    </init-param>
    <init-param>
        <param-name>com.sun.jersey.api.json.POJOMappingFeature</param-name>
        <param-value>true</param-value>
    </init-param>
</servlet>
<servlet-mapping>
    <servlet-name>Example Component</servlet-name>
    <url-pattern>/*</url-pattern>
</servlet-mapping>

The ExamService resource can be accessed by GET .../exam. The result will be:

{"id":3,"name":"OCEJWSD 6"}

Example 1.5. Jersey Client

When using Jersey client to test ExamService, JSONConfiguration.FEATURE_POJO_MAPPING feature should be set to configuration:

ClientConfig clientConfig = new DefaultClientConfig();
clientConfig.getFeatures().put(JSONConfiguration.FEATURE_POJO_MAPPING, Boolean.TRUE);
Client client = Client.create(clientConfig);
WebResource resource = client.resource(".../exam");
String result = resource.accept(MediaType.APPLICATION_JSON_TYPE).get(String.class);
System.out.print(result);

2. JAXB Support

This approach gives the possibility quickly and easily produce and consume both JSON and XML data format. A disadvantage of JAXB based approach can be appeared if it is required to work with a very specific JSON format. A lot of configuration options are provided to solve this problem.

2.1. Simple JAXB Implementation

Example 2.1. JAXB for JSON implementation

Let's start with the simple example of JAXB:

@XmlRootElement
public class Exam {
    public int id;
    public String name;

    public Exam() {}
    public Exam(int id, String name) {
        this.id = id;
        this.name = name;
    }
}

Example 2.2. Resource which generate JSON representation

The method of resource is annotated to produce JSON data format:

@Path("exam")
public class ExamService {
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Exam getExam() {
        return new Exam(3, "OCEJWSD 6");
    }
}

The resource can be accessed by GET ../exam. The result is:

{"id":3,"name":"OCEJWSD 6"}

2.2. Use JAXB Annotations

JAXB gives the possibility to change JSON format, for example to omit some fields or rename others.

Example 2.3. JAXB implementation which omit and rename fields

This example demonstrates how to omit "id" field and rename the "name" field to "certification":

@XmlRootElement
public class Exam {
    @XmlTransient
    public int id;

    @XmlElement(name="certification")
    public String name;

    public Exam() {}
    public Exam(int id, String name) {
        this.id = id;
        this.name = name;
    }
}

Resource from Example 2.2. can be used to test it. The result will be:

{"certification":"OCEJWSD 6"}

2.3. JSON Notations

JSONConfiguration has four JSON notations. Each notation serializes JSON in a different way. Here is a list of supported notations:

  • Mapped (default notation)
  • Natural
  • Jettison Mapped
  • Badgerfish

To set JSON notations it is required to configure Jersey JSON procesor. Next example shows how to do it:

Example 2.4. A JAXBContext resolver implementation

Different configuration options can be set on an JSONConfiguration instance. This instance is used to create a JSONConfigurated JSONJAXBContext, which serves as a main configuration point in this area. Implement a ContextResolver<JAXBContext> to pass specialized JSONJAXBContext to Jersey:

@Provider
public class JAXBContextResolver implements ContextResolver<JAXBContext> {
    private JAXBContext context;
    private Class[] types = {Exam.class};

    public JAXBContextResolver() throws Exception {
        this.context = new JSONJAXBContext(
                JSONConfiguration.natural().build(), types);//1
    }

    public JAXBContext getContext(Class<?> objectType) {
        for (Class type : types) {
            if (type == objectType) {
                return context;
            }
        }
        return null;
    }
}

Each notation and its configuration options are described bellow, using a simple example. Following are JAXB beans and resource, which will be used.

Example 2.5. A simple Exam bean

@XmlRootElement
public class Exam {
    public int id;
    public String name;
    public List<Category> categories;

    public Exam() {
    }

    public Exam(int id, String name, List<Category> categories) {
        this.id = id;
        this.name = name;
        this.categories = categories;
    }
}

Example 2.6. A simple Category bean

@XmlRootElement
public class Category {
    public String name;
    public int questionsNumber;

    public Category() {
    }

    public Category(String name, int questionsNumber) {
        this.name = name;
        this.questionsNumber = questionsNumber;
    }
}

Example 2.7. Resource

@Path("exam")
public class ExamService {
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Exam getExam() {
        List<Category> categories = new ArrayList<Category>();
        categories.add(new Category("JAXP",3));
      //  categories.add(new Category("REST",50));
        return new Exam(3, "OCEJWSD 6", categories);
    }
}

2.3.1. Mapped Notation

To set mapped notation to the JSONConfiguration, modify //1 line in Example 2.4 to:

JSONConfiguration.mapped().build()

Then Exam bean will be serialized as:

{"id":"3","name":"OCEJWSD 6","categories":{"name":"JAXP","questionsNumber":"3"}}

One issue might appear if using it with a JavaScript based client. The information, that "categories" item represents an array, is being lost for every single element array. Shortly, to satisfy a JavaScript client, it should be:

{"id":"3","name":"OCEJWSD 6","categories":[{"name":"JAXP","questionsNumber":"3"}]}

If you add another "category" bean to the "exam" (uncomment line in Example 2.7), it works properly.

To fix this issue, you should instruct the JSON processor, what items need to be treated as arrays by setting an optional property, arrays, on your JSONConfiguration object. For our case, it should be:

Example 2.8. Force arrays in mapped JSON notation

JSONConfiguration.mapped().arrays("categories").build()

Items "id" and "questionNumber" are integer numbers, but they are represented as a String in the result. It is possible to change it using another optional property on JSONConfiguration called nonStrings:

Example 2.9. Force non-string values in mapped JSON notation

JSONConfiguration.mapped().arrays("categories").nonStrings("id","questionsNumber").build()

The result will be:

{"id":3,"name":"OCEJWSD 6","categories":[{"name":"JAXP","questionsNumber":3}]}

Notice, that nonString method accepts multiple string values. The same is true for "arrays" method as well.

The JAXB beans can have XML attributes:

Example 2.10. JAXB with XML attribute

@XmlRootElement
public class Exam {
    @XmlAttribute
    public int id;
    ...
}

In mapped JSON notation, these attribute names are prefixed with @ character:

{"@id":"3"...

If you want to remove "@" prefix from the JSON output, use attributeAsElement configuration option of JSONConfiguration:

Example 2.11. XML attributes as XML elements in mapped JSON notation

JSONConfiguration.mapped().attributeAsElement("id").build()

Mapped JSON notation was designed to produce the simplest possible JSON expression out of JAXB beans. While in XML, you must always have a root tag to start a XML document with, there is no such a constraint in JSON. If you want to keep a XML root tag equivalent generated in your JSON, use rootUnwrapping configuration option:

Example 2.12. Keep XML root tag equivalent in JSON mapped JSON notation

JSONConfiguration.mapped().rootUnwrapping(false).build()

The result will be:

{"exam":{"id":"3","name":"OCEJWSD 6","categories":{"name":"JAXP","questionsNumber":"3"}}}

Mapped JSON notation supports XML namespace.

Example 2.13. JAXB with a namespace

For example, lets look at the Exam class, where "id" item has declared namespace.

@XmlRootElement
public class Exam {
    @XmlElement(namespace="http://examclouds.com")
    public int id;
   ...
}

To make a JSON object to contain declared namespace, use xml2JsonNs method of JSONConfiguration:

Example 2.14. XML namespace to JSON mapping configuration for mapped notation

Map<String,String> ns2json = new HashMap<String, String>();
ns2json.put("http://examclouds.com", "examclouds");
this.context = new JSONJAXBContext(
     JSONConfiguration.mapped().xml2JsonNs(ns2json).build(), types);

 The result will be:

{"examclouds.id":"3","name":"OCEJWSD 6","categories":{"name":"JAXP","questionsNumber":"3"}}

2.3.2. Natural Notation

After using mapped JSON notation for a while, it was apparent, that a need to configure all the various things manually could be problematic. To avoid the manual work, a new, natural, JSON notation was introduced in Jersey version 1.0.2. With natural notation, Jersey will automatically figure out how individual items need to be processed, so that you do not need to do any kind of manual configuration. Java arrays and lists are mapped into JSON arrays, even for single-element cases. Java numbers and booleans are correctly mapped into JSON numbers and booleans, and you do not need to bother with XML attributes, as in JSON, they keep the original names. So without any additional configuration, you can just use

JSONConfiguration.natural().build()

for configuring JAXBContext. The following JSON will be the result for our Exam bean:

Example 2.15. JSON expression produced using natural notation

{"id":3,"name":"OCEJWSD 6","categories":[{"name":"JAXP","questionsNumber":3}]}

Notice, that the single element array "categories" remains an array, and also the non-string "id" and "questionsNumber" values are not limited with double quotes, as natural notation automatically detects these things.

To support cases, when inheritance is used for JAXB beans, an option was introduced to the natural JSON configuration builder to forbid XML root element stripping. The option looks pretty same as at the default mapped notation case (Example 2.12):

Example 2.16. Keep XML root tag equivalent in JSON natural JSON notation

JSONConfiguration.natural().rootUnwrapping(false).build()

2.3.3. Jettison Mapped Notation

This notation is based on Jettison project. It can be used when working with more complex XML documents for example with multiple XML namespaces in your JAXB beans. Jettison based mapped notation could be configured using:

JSONConfiguration.mappedJettison().build()

The resulting JSON is similar to the default mapped notation. The only difference is, your numbers and booleans will not be converted into strings, but you have no option for forcing arrays remain arrays in single-element case. Also the JSON object, representing XML root tag is being produced:

Example 2.17. JSON expression produced using Jettison based mapped notation

{"exam":{"id":3,"name":"OCEJWSD 6","categories":{"name":"JAXP","questionsNumber":3}}}

If it is required to work with various XML namespaces, however, you can find Jettison mapped notation very useful. Lets define a particular namespace for "id" item:

@XmlRootElement
public class Exam {
    @XmlElement(namespace="http://www.examclouds.com")
    public int id;
     ...
}

Then you simply configure a mapping from XML namespace into JSON prefix as follows:

Example 2.18. XML namespace to JSON mapping configuration for Jettison based mapped notation

Map<String,String> ns2json = new HashMap<String, String>();
ns2json.put("http://www.examclouds.com", "examclouds");
this.context = new JSONJAXBContext(
       JSONConfiguration.mappedJettison().xml2JsonNs(ns2json).build(), types);

Resulting JSON will look like this:

{"exam":{"examclouds.id":3,
          "name":"OCEJWSD 6",
          "categories":{"name":"JAXP","questionsNumber":3}}}

Note, that "id" item became examclouds.id based on the XML namespace mapping. If you have more XML namespaces in your XML, you will need to configure appropriate mapping for all of them.

2.3.4. Badgerfish Notation

Badgerfish notation is the other notation based on Jettison. From JSON and JavaScript perspective, this notation is definitely the worst readable one. You will probably not want to use it, unless you need to make sure your JAXB beans could be flawlessly written and read back to and from JSON, without bothering with any formatting configuration, namespaces, etc.

JSONConfiguration instance using badgerfish notation could be built with:

JSONConfiguration.badgerFish().build()

The output JSON will be:

{"exam":{"id":{"$":"3"},
         "name":{"$":"OCEJWSD 6"},
         "categories":{"name":{"$":"JAXP"},"questionsNumber":{"$":"3"}}}}

3. Low-Level JSON Support

JSONObject and JSONArray classes taken from Jettison project are used for data representations in this approach. The biggest advantage here is, that you will gain full control over the JSON format produced and consumed. On the other hand, dealing with your data model objects will probably be a bit more complex, than when taking the JAXB based approach. 

Example 3.1. JAXB bean creation

The example shows how to construct a simple Exam JAXB bean:

List<Category> categories = new ArrayList<Category>();
categories.add(new Category("JAXP",3));
Exam exam = Exam(3, "OCEJWSD 6", categories);

The example produces JSON:

{"id":3,"name":"OCEJWSD 6","categories":[{"name":"JAXP","questionsNumber":3}]}

To build an equivalent JSONObject, you will need to write more lines of code:

Example 3.2. Constructing a JSONObject

JSONObject exam = new JSONObject();
JSONObject category = new JSONObject();
JSONArray categories = new JSONArray();
try {
     category.put("name", "JAXP");
     category.put("questionsNumber", 3);
     categories.put(category);

     exam.put("id", 3);
     exam.put("name", "OCEJWSD 6");
     exam.put("categories", categories);
} catch (JSONException e) {
     System.out.print(e);
}

 

Sources:  Jersey Tutorial - JSON Support



0 comments
Leave your comment: