Parsing JSON with svenson

Svenson tries to give you a maximum of flexibility when parsing JSON. From parsing JSON it a nested graph of maps and lists, to parsing it into a Object graph of your own classes with dynamic parts, every combination short of transforming the JSON prior to parsing it is possible.

Simple Parsing

Per default, JSON will just produce a nested graph of maps and lists. Here is an example of default parsing:

import org.svenson.JSONParser;

...
    // assume json to be a JSON datasets as String
    Object o = JSONParser.defaultJSONParser().parse(json);

o will now contain either a map or a list instance, depending on whether the first symbol in the JSON is '{' or '['.

Parsing into concrete types

While this can be useful if you have absolutely no idea about the JSON structure you are receiving, you usually do have an idea about that and so might want to define a root type:

import org.svenson.JSONParser;

...
    // assume json, json2 and json3 to be a JSON datasets as String
    Map m = JSONParser.defaultJSONParser().parse(Map.class, json);
   
    List m = JSONParser.defaultJSONParser().parse(List.class, json2);

    MyBean bean = JSONParser.defaultJSONParser().parse(MyBean.class, json3);

These are examples of parsing with a defined root type. JSONParser will try to parse the json dataset into the given type and throws an org.svenson.JSONParseException when that is not possible.

By default, arrays will be parsed into java.util.List instances and objects into java.util.Map instances. If you define beans as root type or as a type hint, objects can also be parsed into beans of that type, provided that all JSON properties have a corresponding java properties (or the bean implements DynamicProperties).

Apart from property access, there is another way to parse arrays into a bean property. A JSON dataset like

{
    "qux" : [ ... ],
}

can also be parsed into a class like

    public class Baz
    {
        ...
        public void addQux(Qux qux)
        {
            ...
        }
    }

where there is a method starting with "add" and ending on the same name as the corresponding JSON property.

@JSONProperty

See Generating JSON for how to influence the handling with the @JSONProperty annotation.

Interface Mapping

As you can see in the example above, you can use interfaces as root types. That is of course only possible if JSONParser knows, what concrete implementations of these interface it is supposed to generate. You can feed a map mapping an interface type to an implementing type to JSONParser#setInterfaceMappings(Map<Class,Class>)

Type Hints

We know now how to define a root type. But what if you want to define concrete types not at the root of the JSON structure, but deep within it?

This is where Type Hints come into play. With type hints you can define a concrete type to be used at a specific point within the JSON structure.

import org.svenson.JSONParser;

...
    // assume json to be an JSON dataset as String
    JSONParser parser = new JSONParser();
    parser.addTypeHint(".foos[]", Foo.class);

    Map result = parser.parse(Map.class, json);

Here you can see how to set up parser with one type hint that is able to parse JSON datasets like

    {
        "foos" : [ ... ]
    }

so that result is a Map with a key "foos" mapping to a list of Foo instances. For this to work, Foo needs to have a default constructor and the objects in the "foos" array must be parsable into Foo instances.

@JSONTypeHint

You can achieve the same effect by annotating a property method that has a list or map as property type with the org.svenson.JSONTypeHint.

import java.util.List;
import org.svenson.JSONTypeHint;

public class Foo
{
    private List<Bar> bars;

    @JSONTypeHint(Bar.class)
    public void setBars(List<Bar> bars)
    {
        this.bars = bars;
    }
}

This will ensure that the objects in the bar property array will be parsed into Bar instances.

{
    "bars" : [ ... ]
}

This is necessary because of the type erasure.

Dynamic Properties

If your classes need the ability to cope with abritrary properties whose names are not known at compile time, you can implement org.svenson.DynamicProperties or extend org.svenson.AbstractDynamicProperties

import org.svenson.AbstractDynamicProperties;

public class MyBean extends AbstractDynamicProperties
{
   private String foo;

   public String getFoo()
   {
       return foo;
   }

   public void setFoo(String foo)
   {
       this.foo = foo;
   }
}

Implemented this way, MyBean can both have regular java properties and can also be provided with dynamic properties with arbritrary names and values. These dynamic Properties can be accessed with the methods defined in the DynamicProperties interface.

Regular java properties will have precedence over dynamic ones, so in this example, the foo property will always be available via getFoo() and not via getProperty("foo")

...
public interface DynamicProperties
{
    /**
     * Sets the attribute with the given name to the given value.
     *
     * @param name
     * @param value if <code>null</code>, the attribute is removed.
     */
    void setProperty(String name, Object value);

    /**
     * returns value of the attribute with the given name.
     *
     * @param name
     */
    Object getProperty(String name);

    /**
     * Returns the set of available dynamic attribute names.
     *
     * @return
     */
    Set<String> propertyNames();
}

Type Mapper

Type Mappers are for now the most complex mechanism with which you can control the types used to parse your JSON messages. Classes implementing the TypeMapper interface can be registered by calling JSONParser#setTypeMapper(TypeMapper) ( If you really need to define more than one type mapper, use org.svenson.CompositeTypeMapper ).

...
/**
 * Inspects the current position of a tokenizer and decides what type to use at that position.
 *
 * @author shelmberger
 */
public interface TypeMapper
{
    /**
     * Returns the type to use for the current tokenizer position or <code>null</code>, if the type mapper does not want to
     * change the type used at this position. The type mapper must reset the tokenizer to a token stream position that allows
     * the parsing to continue. this will usually be the tokenizer position on method entry. (i.e. the first token received by the
     * type mapper needs to be fed to {@link JSONTokenizer#pushBack(org.svenson.tokenize.Token)}
     *
     * @param tokenizer         tokenizer to get the tokens from. needs to set to a position behind the inspected value to continue
     *                          parsing correctly.
     *
     * @param parsePathInfo     the current parsing path within the root object
     * @param typeHint          initial type hint as configured by {@link JSONParser#addTypeHint(String, Class)}, can also be <code>null</code>.
     *
     * @return type hint or <code>null</code>, if the type mapper does not want to
     * change the type used at this position.
     */
    Class getTypeHint(JSONTokenizer tokenizer, String parsePathInfo, Class typeHint);
}

They can inspect the token stream generated by the provided JSONTokenizer and decide to overide the configured type hint.

PropertyValueBasedTypeMapper

org.svenson.PropertyValueBasedTypeMapper is one predefined TypeMapper that comes with the svenson distribution. It allows you to select the type to parse a JSON object into based on the value of a property of that JSON object.

For example a data-structure like

{
    "total_rows": 3,
    "offset": 0,
    "rows": [{ "type":"foo", "value":"aaa" },{ "type":"bar", "value":"bbb" },{ "value":"ccc","type":"bar"  }]
}

can be parsed with the following code:

        JSONParser parser = new JSONParser();
        PropertyValueBasedTypeMapper mapper = new PropertyValueBasedTypeMapper();
        mapper.setParsePathInfo(".rows[]");
        mapper.addFieldValueMapping("foo", Foo.class);
        mapper.addFieldValueMapping("bar", Bar.class);
        parser.setTypeMapper(mapper);

The type mapper will ensure that the values of the rows array will be mapped to Foo and Bar instances based on the value of they "type" property.

ClassNameBasedTypeMapper

The org.svenson.ClassNameBasedTypeMapper is another type mapper delivered with svenson that works like the PropertyValueBasedTypeMapper but does not require type configuration but instead uses either fully or partially qualified class names with optional base type enforcement.

Parsing from a input stream

Since svenson 1.3.0 you can also parse JSON directly from an input stream.

import java.io.FileInputStream;
import java.io.IOException;
import java.util.Map;

import org.svenson.JSONParser;
import org.svenson.tokenize.InputStreamSource;

...
        // assume inputStream to be an input stream delivering JSON data
        JSONParser parser = JSONParser.defaultJSONParser();        
        InputStreamSource source = new InputStreamSource( inputStream, true);
        Map m = parser.parse(Map.class, source);

Object Factories

You can now also create object factories by implementing the org.svenson.ObjectFactory interface

public interface ObjectFactory<T>
{
    /**
     * Returns <code>true</code> if the factory can create objects of the given class
     * 
     * @param cls
     * @return
     */
    boolean supports(Class<T> cls);
    
    /**
     * Creates an instance of the given type.
     * @param typeHint
     * @return
     */
    T create(Class<T> typeHint);
}

and registering your instance by calling JSONParser#addObjectFactory(org.svenson.ObjectFactory).

The future

I might add even more flexibility when I see use cases for it that are general enough to be included. Object factories, JSON transformation.. A lot would be possible but for now I have no clear vision of that.

So if your requirements are not met by svenson, you could try contacting me to give me a clearer idea of what could be added.