1         <init-param>
  2             <param-name>com.sun.jersey.api.json.POJOMappingFeature</param-name>
  3             <param-value>true</param-value>
  4         </init-param>

  1   ClientConfig clientConfig = new DefaultClientConfig();
  2   clientConfig.getFeatures().put(JSONConfiguration.FEATURE_POJO_MAPPING, Boolean.TRUE);
  3   Client client = Client.create(clientConfig);

  1 @XmlRootElement
  2 public class MyJaxbBean {
  3   public String name;
  4   public int age;
  5       
  6   public MyJaxbBean() {} // JAXB needs this
  7 
  8   public MyJaxbBean(String name, int age) {
  9     this.name = name;
 10     this.age = age;
 11   }
 12 }

  1 @GET @Produces("application/json")
  2 public MyJaxbBean getMyBean() {
  3    return new MyJaxbBean("Agamemnon", 32);
  4 }

5.2.1. Configuration Options

Example 5.5. Tweaking JSON format using JAXB

  1 @XmlRootElement
  2 public class MyJaxbBean {
  3   
  4     @XmlElement(name="king")
  5     public String name;
  6   
  7     @XmlTransient
  8     public int age;
  9  
 10     // several lines removed       
 11 }

Example 5.6. An example of a JAXBContext resolver implementation

  1 @Provider
  2 public class JAXBContextResolver implements ContextResolver<JAXBContext> {
  3 
  4     private JAXBContext context;
  5     private Class[] types = {MyJaxbBean.class};
  6 
  7     public JAXBContextResolver() throws Exception {
  8         this.context = 
  9 	  new JSONJAXBContext( (1)
 10 	    JSONConfiguration.natural().build(), types); (2)
 11     }
 12 
 13     public JAXBContext getContext(Class<?> objectType) {
 14         for (Class type : types) {
 15             if (type == objectType) {
 16                 return context;
 17             }
 18         }
 19         return null;
 20     }
 21 }

5.2.2. JSON Notations

• MAPPED (default notation)
• NATURAL
• JETTISON_MAPPED
• BADGERFISH

Example 5.7. JAXB beans for JSON supported notations description, simple address bean

  1 @XmlRootElement
  2 public class Address {
  3     public String street;
  4     public String town;
  5 
  6     public Address(){}
  7 
  8     public Address(String street, String town) {
  9         this.street = street;
 10         this.town = town;
 11     }
 12 }

Example 5.8. JAXB beans for JSON supported notations description, contact bean

  1 @XmlRootElement
  2 public class Contact {
  3 
  4     public int id;
  5     public String name;
  6     public List<Address> addresses;
  7 
  8     public Contact() {};
  9 
 10     public Contact(int id, String name, List<Address> addresses) {
 11         this.name = name;
 12         this.id = id;
 13         this.addresses = 
 14 	        (addresses != null) ? new LinkedList<Address>(addresses) : null;
 15     }
 16 }

Example 5.9. JAXB beans for JSON supported notations description, initialization

final Address[] addresses = {new Address("Long Street 1", "Short Village")};
Contact contact = new Contact(2, "Bob", Arrays.asList(addresses));

JSONConfiguration based on mapped notation could be build with

JSONConfiguration.mapped().build()

for usage in a JAXBContext resolver, Example 5.6, “An example of a JAXBContext resolver implementation”. Then a contact bean initialized with Example 5.9, “JAXB beans for JSON supported notations description, initialization”, will be serialized as

  1 { "id":"2" 
  2  ,"name":"Bob"
  3  ,"addresses":{"street":"Long Street 1"
  4                     ,"town":"Short Village"}}

The JSON representation seems fine, and will be working flawlessly with Java based Jersey client API.

However, at least one issue might appear once you start using it with a JavaScript based client. The information, that addresses item represents an array, is being lost for every single element array. If you added another address bean to the contact,

contact.addresses.add(new Address("Short Street 1000", "Long Village"));

, you would get

  1 { "id":"2" 
  2  ,"name":"Bob"
  3  ,"addresses":[{"street":"Long Street 1","town":"Short Village"}
  4               ,{"street":"Short Street 1000","town":"Long Village"}]}

Both representations are correct, but you will not be able to consume them using a single JavaScript client, because to access "Short Village" value, you will write addresses.town in one case and addresses[0].town in the other. To fix this issue, you need to 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, you would do it with

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

You can use multiple string values in the arrays method call, in case you are dealing with more than one array item in your beans. Similar mechanism (one or more argument values) applies also for all below desribed options.

Another issue might be, that number value, 2, for id item gets written as a string, "2". To avoid this, you can use another optional property on JSONConfiguration called nonStrings.

JSONConfiguration.mapped().arrays("addresses").nonStrings("id").build()

It might happen you use XML attributes in your JAXB beans. In mapped JSON notation, these attribute names are prefixed with @ character. If id was an attribute, it´s definition would look like:

  ...
  @XmlAttribute
  public int id;
  ...

and then you would get

{"@id":"2" ...

at the JSON output. In case, you want to get rid of the @ prefix, you can take advantage of another configuration option of JSONConfiguration, called attributeAsElement. Usage is similar to previous options.

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 wanted to be strict, you might have wanted to keep a XML root tag equivalent generated in your JSON. If that is the case, another configuration option is available for you, which is called rootUnwrapping. You can use it as follows:

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

and get the following JSON for our Contact bean:

  1 {"contact":{ "id":"2" 
  2  ,"name":"Bob"
  3  ,"addresses":{"street":"Long Street 1"
  4                     ,"town":"Short Village"}}}

rootUnwrapping option is set to true by default. You should switch it to false if you use inheritance at your JAXB beans. Then JAXB might try to encode type information into root element names, and by stripping these elements off, you could break unmarshalling.

In version 1.1.1-ea, XML namespace support was added to the MAPPED JSON notation. There is of course no such thing as XML namespaces in JSON, but when working from JAXB, XML infoset is used as an intermediary format. And then when various XML namespaces are used, ceratin information related to the concrete namespaces is needed even in JSON data, so that the JSON procesor could correctly unmarshal JSON to XML and JAXB. To make it short, the XML namespace support means, you should be able to use the very same JAXB beans for XML and JSON even if XML namespaces are involved.

Namespace mapping definition is similar to Example 5.20, “XML namespace to JSON mapping configuration for Jettison based mapped notation”

  1         Map<String,String> ns2json = new HashMap<String, String>();
  2         ns2json.put("http://example.com", "example");
  3         context = new JSONJAXBContext(
  4 	      JSONConfiguration.mapped()
  5 	           .xml2JsonNs(ns2json).build(), types);

Dot character (.) will be used by default as a namespace separator in the JSON identifiers. E.g. for the above mentioned example namespace and tag T, "example.T" JSON identifier will be generated. To change this default behaviour, you can use the nsSeparator method on the mapped JSONConfiguration builder:JSONConfiguration.mapped().xml2JsonNs(ns2json).nsSeparator(':').build(). Then you will get "example:T" instead of "example.T" generated. This option should be used carefully, as the Jersey framework does not even try to check conflicts between the user selected separator character and the tag and/or namespace names.

After using mapped JSON notation for a while, it was apparent, that a need to configure all the various things manually could be a bit 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, just using

JSONConfiguration.natural().build()

for configuring your JAXBContext, you will get the following JSON for the bean initialized at Example 5.9, “JAXB beans for JSON supported notations description, initialization”:

  1 { "id":2
  2  ,"name":"Bob"
  3  ,"addresses":[{"street":"Long Street 1"
  4                      ,"town":"Short Village"}]}

You might notice, that the single element array addresses remains an array, and also the non-string id value is not limited with double quotes, as natural notation automatically detects these things.

To support cases, when you use inheritance for your 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 5.14, “Keep XML root tag equivalent in JSON mapped JSON notation”).

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

Next two notations are based on project Jettison. You might want to use one of these notations, when working with more complex XML documents. Namely when you deal with multiple XML namespaces in your JAXB beans.

Jettison based mapped notation could be configured using:

JSONConfiguration.mappedJettison().build()

If nothing else is configured, you will get similar JSON output as for the default, mapped, notation:

  1 { "contact:{"id":2
  2               ,"name":"Bob"
  3               ,"addresses":{"street":"Long Street 1"
  4                                  ,"town":"Short Village"}}

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.

If you need to deal with various XML namespaces, however, you will find Jettison mapped notation pretty useful. Lets define a particular namespace for id item:

  ...
  @XmlElement(namespace="http://example.com")
  public int id;
  ...

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

  1         Map<String,String> ns2json = new HashMap<String, String>();
  2         ns2json.put("http://example.com", "example");
  3         context = new JSONJAXBContext(
  4 	      JSONConfiguration.mappedJettison()
  5 	           .xml2JsonNs(ns2json).build(), types);

Resulting JSON will look like in the example bellow.

  1 { "contact:{"example.id":2
  2               ,"name":"Bob"
  3               ,"addresses":{"street":"Long Street 1"
  4                                  ,"town":"Short Village"}}

Please note, that id item became example.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

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()

and the output JSON for Example 5.9, “JAXB beans for JSON supported notations description, initialization” will be as follows.

  1 {"contact":{"id":{"$":"2"}
  2               ,"name":{"$":"Bob"}
  3               ,"addresses":{"street":{"$":"Long Street 1"}
  4                                  ,"town":{"$":"Short Village"}}}}

5.2.3. Examples

MyJaxbBean myBean = new MyJaxbBean("Agamemnon", 32);

  1 JSONObject myObject = new JSONObject();
  2 myObject.JSONObject myObject = new JSONObject();
  3 try {
  4   myObject.put("name", "Agamemnon");
  5   myObject.put("age", 32);
  6 } catch (JSONException ex) {
  7   LOGGER.log(Level.SEVERE, "Error ...", ex);
  8 }

5.3.1. Examples