User's Guide


Added by Dan Diephouse, last edited by Dejan Bosanac on Jun 09, 2008  (view change)

Labels

 
(None)

Conventions

Jettison includes two JSON/XML mapping conventions. These are detailed below.

Mapped Convention

The best way to demonstrate the Mapped convention is a short example:

<price xmlns="http://acme.com">10.00</price>

Using the mapped convention this can be turned into:

{ "acme.price" : { "10.00" }

As you can see we've mapped the http://acme.come namespace to the "acme." prefix. This creates a very readable format.

The convention follows the following rules:
1. An element with no characters or child elements is represented by { "element" : "" }
2. No namespaces declarations are ever written
3. An element with multiple child elements of the same name is represented by an array

<root><child>test</child><child>test</child></root>

In JSON this becomse:

{ "root" : { child : [ "test", "test" ] } }

BadgerFish

For information on the BadgerFish convention, check out the specification

APIs

Jettison provides some of the most popular XML handling APIs for handling JSON documents.

STaX

StAX (STreaming Api for Xml processing) is a Java based API for pull-parsing XML (and now JSON). Please refer to the specification for more details.

Writing

Here's a simple example of using STaX API to write JSON documents:

StringWriter strWriter = new StringWriter();

        // Mapped convention
        MappedNamespaceConvention con = new MappedNamespaceConvention();
        AbstractXMLStreamWriter w = new MappedXMLStreamWriter(con, strWriter);

        // BadgerFish convention
        // AbstractXMLStreamWriter w = new BadgerFishXMLStreamWriter(strWriter);

        w.writeStartDocument();
        w.writeStartElement("alice");
        w.writeCharacters("bob");
        w.writeEndElement();
        w.writeEndDocument();

        w.close();
        strWriter.close();
        System.out.println(strWriter.toString());

You can expect the following result if you are using Mapped convention

{"alice":"bob"}

and

{"alice":{"$":"bob"}}

for BadgerFish convention.

Type conversion

Availability

Available since 1.1

When writing JSON documents, Jettison tries to convert objects to their primitive representation and not to treat everything as a String. For example the following snippet:

StringWriter strWriter = new StringWriter();
        Configuration config = new Configuration();
        MappedNamespaceConvention con = new MappedNamespaceConvention(config);
        AbstractXMLStreamWriter w = new MappedXMLStreamWriter(con, strWriter);

        w.writeStartElement("root");
        w.writeCharacters("true");
        w.writeEndElement();

        w.writeEndDocument();

        w.close();
        strWriter.close();

        System.out.println(strWriter.toString());

will print

{"root":true}

instead of

{"root":"true"}

This works fine for most use cases, but some users may want to have control over this process. Jettison provides customizable type conversion mechanism. Beside default type converter used, you can use SimpleConverter which will treat everything as a String or write your own. For example,

StringWriter strWriter = new StringWriter();
        Configuration config = new Configuration();
        config.setTypeConverter(new SimpleConverter());
        MappedNamespaceConvention con = new MappedNamespaceConvention(config);
        AbstractXMLStreamWriter w = new MappedXMLStreamWriter(con, strWriter);

        w.writeStartElement("root");
        w.writeCharacters("true");
        w.writeEndElement();

        w.writeEndDocument();

        w.close();
        strWriter.close();

        System.out.println(strWriter.toString());

will produce

{"root":"true"}

Parsing

In a similar manner you can parse JSON documents using STaX API:

// Mapped convention
        JSONObject obj = new JSONObject("{\"alice\":{\"bob\"}}");
        AbstractXMLStreamReader reader = new MappedXMLStreamReader(obj);

        // BadgerFish
        // JSONObject obj = new JSONObject("{ \"alice\": { \"$\" : \"bob\" } }");
        // AbstractXMLStreamReader reader = new BadgerFishXMLStreamReader(obj);

        assertEquals(XMLStreamReader.START_ELEMENT, reader.next());
        assertEquals("alice", reader.getName().getLocalPart());


        assertEquals(XMLStreamReader.CHARACTERS, reader.next());
        assertEquals("bob", reader.getText());
        assertEquals(XMLStreamReader.END_ELEMENT, reader.next());
        assertEquals("alice", reader.getName().getLocalPart());
        assertEquals(XMLStreamReader.END_DOCUMENT, reader.next());