Jackson - Quickstart

JSON Three Ways

Jackson offers three alternative methods (one with two variants) for processing JSON:

• Streaming API (aka "Incremental parsing/generation") reads and writes JSON content as discrete events.

  • org.codehaus.jackson.JsonParser reads, org.codehaus.jackson.JsonGenerator writes.

  • Inspired by the StAX API.

• Tree Model provides a mutable in-memory tree representation of a JSON document.

  • org.codehaus.jackson.map.ObjectMapper can build trees; trees consist of JsonNode nodes.

  • The tree model is similar to the XML DOM.

• Data Binding converts JSON to and from POJOs based either on property accessor conventions or annotations.

  • There are two variants: simple and full data binding

    • Simple data binding means converting to and from Java Maps, Lists, Strings, Numbers, Booleans and nulls

    • Full data binding means converting to and from any Java bean type (as well as "simple" types mentioned above)

  • org.codehaus.jackson.map.ObjectMapper performs the marshalling (writing JSON) and unmarshalling (reading JSON) for both variants.

  • Inspired by the annotation-based (code-first) variant of JAXB.

From usage perspective, one way to summarize these 3 methods is:

• Streaming API is best performing (lowest overhead, fastest read/write; other 2 methods build on it)

• Data Binding is often most convenient

• Tree Model is most flexible

Given these properties, let's consider these in the reverse order, starting with what is usually the most natural and convenient method for Java developers: Jackson Data Binding API.

Examples

Full Data Binding (POJO) Example

Jackson's org.codehaus.jackson.map.ObjectMapper "just works" for mapping JSON data into plain old Java objects ("POJOs"). For example, given JSON data

{
  "name" : { "first" : "Joe", "last" : "Sixpack" },
  "gender" : "MALE",
  "verified" : false,
  "userImage" : "Rm9vYmFyIQ=="
}

It takes two lines of Java to turn it into a User instance:

ObjectMapper mapper = new ObjectMapper(); // can reuse, share globally
User user = mapper.readValue(new File("user.json"), User.class);

Where the User class looks something like this:

public class User {
    public enum Gender { MALE, FEMALE };

    public static class Name {
      private String _first, _last;

      public String getFirst() { return _first; }
      public String getLast() { return _last; }

      public void setFirst(String s) { _first = s; }
      public void setLast(String s) { _last = s; }
    }

    private Gender _gender;
    private Name _name;
    private boolean _isVerified;
    private byte[] _userImage;

    public Name getName() { return _name; }
    public boolean isVerified() { return _isVerified; }
    public Gender getGender() { return _gender; }
    public byte[] getUserImage() { return _userImage; }

    public void setName(Name n) { _name = n; }
    public void setVerified(boolean b) { _isVerified = b; }
    public void setGender(Gender g) { _gender = g; }
    public void setUserImage(byte[] b) { _userImage = b; }
}

Marshalling back to JSON is similarly straightforward:

mapper.writeValue(new File("user-modified.json"), user);

For fancier data binding (e.g., unmarshalling formatted dates into java.util.Date), Jackson provides annotations to customize the marshalling and unmarshalling process.

"Raw" Data Binding Example

(also known as "Untyped", or sometimes "simple" data binding)

In cases where you do not have (and don't want to create) specific Java classes to bind JSON to/from, "Untyped data binding" may be a better approach. It is used same way as full data binding, except that the formal binding type is specified simply as Object.class (or Map.class, List.class, String[].class if more specific typing is wanted). So the earlier binding of JSON that represent User data could have been done by:

Map<String,Object> userData = mapper.readValue(new File("user.json"), Map.class);

and userData would be like one we would explicit construct by:

Map<String,Object> userData = new HashMap<String,Object>();
Map<String,String> nameStruct = new HashMap<String,String>();
nameStruct.put("first", "Joe");
nameStruct.put("last", "Sixpack");
userData.put("name", nameStruct);
userData.put("gender", "MALE");
userData.put("verified", Boolean.FALSE);
userData.put("userImage", "Rm9vYmFyIQ==");

This obviously works both ways: if you did construct such a Map (or bind from JSON and modify), you could write out just as before, by:

mapper.writeValue(new File("user-modified.json"), userData);

How does this work? By specifying Map.class, we do not specify generic key/value types. But ObjectMapper does know how to bind JSON data to and from Maps (and Lists, arrays, wrapper types), and does just that. Fundamentally JSON data has no "real" type as far as Jackson is concerned -- if it can be properly mapped to a type you give, it will be mapped.

Concrete Java types that Jackson will use for simple data binding are:

JSON Type	Java Type
object	LinkedHashMap<String,Object>
array	ArrayList<Object>
string	String
number (no fraction )	Integer, Long or BigInteger (smallest applicable)
number (fraction)	Double (configurable to use BigDecimal)
true|false	Boolean
null	null

Data Binding with Generics

In addition to binding to POJOs and "simple" types, there is one additional variant: that of binding to generic (typed) containers. This case requires special handling due to so-called Type Erasure (used by Java to implement generics in somewhat backwards compatible way), which prevents you from using something like Collection<String>.class (which does not compile).

So if you want to bind data into a Map<String,User> you will need to use:

Map<String,User> result = mapper.readValue(src, new TypeReference<Map<String,User>>() { });

where TypeReference is only needed to pass generic type definition (via anynomous inner class in this case): the important part is <Map<String,User>> which defines type to bind to.

If you don't do this (and just pass Map.class), call is equivalent to binding to Map<?,?> (i.e. "untyped" Map), as explained above.

UPDATE: As an alternative, version 1.3 also allows programmatic construction of types by using TypeFactory.

Tree Model Example

Yet another way to get Objects out of JSON is to build a tree. This is similar to DOM trees for XML. The way Jackson builds trees is to use basic JsonNode base class, which exposes read access that is usually needed. Actual node types used are sub-classes; but the sub-type only needs to be used when modifying trees.

Trees can be read and written using either Streaming API (see below), or using ObjectMapper.

With ObjectMapper, you will do something like:

ObjectMapper m = new ObjectMapper();
// can either use mapper.readTree(source), or mapper.readValue(source, JsonNode.class);
JsonNode rootNode = m.readTree(new File("user.json"));
// ensure that "last name" isn't "Xmler"; if is, change to "Jsoner"
JsonNode nameNode = rootNode.path("name");
String lastName = nameNode.path("last").getTextValue().
if ("xmler".equalsIgnoreCase(lastName)) {
  ((ObjectNode)nameNode).put("last", "Jsoner");
}
// and write it out:
m.writeValue(new File("user-modified.json"), rootNode);

Or if you want to construct a Tree (for the User example) from scratch, you can do:

TreeMapper treeMapper = new TreeMapper();
ObjectNode userOb = treeMapper.objectNode();
Object nameOb = userRoot.putObject("name");
nameOb.put("first", "Joe");
nameOb.put("last", "Sixpack");
userOb.put("gender", User.Gender.MALE.toString());
userOb.put("verified", false);
byte[] imageData = getImageData(); // or wherever it comes from
userOb.put("userImage", imageData);

(NOTE: with Jackson 1.2 you can use ObjectMapper directly, using ObjectMapper.createObjectNode() to create userOb -- above example will work with JAckson 1.0 and 1.1)

Streaming API Example

And finally, there is the third way: turbo-charged, high-performance method known as Streaming API (aka incremental mode, since content is read and written incrementally).

Just for fun, let's implement the writing functionality (equivalent to earlier examples) using "raw" Streaming API: WriteJSON.java

JsonFactory f = new JsonFactory();
JsonGenerator g = f.createJsonGenerator(new File("user.json"));

g.writeStartObject();
g.writeObjectFieldStart("name");
g.writeStringField("first", "Joe");
g.writeStringField("last", "Sixpack");
g.writeEndObject(); // for field 'name'
g.writeStringField("gender", Gender.MALE);
g.writeBooleanField("verified", false);
g.writeFieldName("userImage"); // no 'writeBinaryField' (yet?)
byte[] binaryData = ...;
g.writeBinary(binaryData);
g.writeEndObject();
g.close(); // important: will force flushing of output, close underlying output stream

Not horribly bad (esp. compared to amount of work needed for writing, say, equivalent XML content), but certainly more laborious than basic Object mapping.

On the other hand, you do have full control over each and every detail. And overhead is minimal: this is still a bit faster than using ObjectMapper; not a whole lot (perhaps 20-30% faster in common cases), but still. And perhaps most importantly, output is done in streaming manner: except for some buffering, all content will be written out right away. This means that memory usage is also minimal.

How about parsing, then? Code could look something like:

JsonFactory f = new JsonFactory();
JsonParser jp = f.createJsonParser(new File("user.json"));
User user = new User();
jp.nextToken(); // will return JsonToken.START_OBJECT (verify?)
while (jp.nextToken() != JsonToken.END_OBJECT) {
  String fieldname = jp.getCurrentName();
  jp.nextToken(); // move to value, or START_OBJECT/START_ARRAY
  if ("name".equals(fieldname)) { // contains an object
    Name name = new Name();
    while (jp.nextToken() != JsonToken.END_OBJECT) {
      String namefield = jp.getCurrentName();
      jp.nextToken(); // move to value
      if ("first".equals(namefield)) {
        name.setFirst(jp.getText());
      } else if ("last".equals(namefield)) {
        name.setLast(jp.getText());
      } else {
        throw new IllegalStateException("Unrecognized field '"+fieldname+"'!");
      }
    }
    user.setName(name);
  } else if ("gender".equals(fieldname)) {
    user.setGender(User.Gender.valueOf(jp.getText()));
  } else if ("verified".equals(fieldname)) {
    user.setVerified(jp.getCurrentToken() == JsonToken.VALUE_TRUE);
  } else if ("userImage".equals(fieldname)) {
    user.setUserImage(jp.getBinaryValue());
  } else {
    throw new IllegalStateException("Unrecognized field '"+fieldname+"'!");
  }
}
jp.close(); // ensure resources get cleaned up timely and properly

which is quite a bit more than you'll use with data binding.

One final trick: it is also possible to use data binding and tree model directly from JsonParser and JsonGenerator. To do this, have a look at methods:

• JsonParser.readValueAs()

• JsonParser.readValueAsTree()

• JsonGenerator.writeObject()

• JsonGenerator.writeTree()

which do about what you might expect them to do.

The only (?) trick is that you MUST make sure you use org.codehaus.jackson.map.MappingJsonFactory for constructing "data-binding capable" parser and generator instances (instead of basic org.codehaus.jackson.JsonFactory).

Streaming API Example 2: arrays

Let's consider following POJO:

public class Foo {
    public String foo;
}

and sample JSON stream of:

String json = [{\"foo\": \"bar\"},{\"foo\": \"biz\"}]";

while there are convenient ways to work on this with databinding (see ObjectReader.readValues() for details), you can easily use streaming to iterate over stream, bind individual elements as well:

JsonFactory f = new JsonFactory();
JsonParser jp = f.createJsonParser(json);
// advance stream to START_ARRAY first:
jp.nextToken();
// and then each time, advance to opening START_OBJECT
while (jp.nextToken() == JsonToken.START_OBJECT) {
    Foo foobar = mapper.readValue(jp, Foo.class);
    // process
    // after binding, stream points to closing END_OBJECT
}

Next Steps

You may want to check out rest of JacksonDocumentation for more inspiration.