JavaScript Object Notation (aka JSON) is a very popular lightweight data-interchange format. Jodd JSON is a lightweight library for (de)serializing Java objects into and from JSON.

Before you say: "Yet another one?", please check what makes Jodd JSON unique. The power of the library is its control over the process of serialization and parsing; ease of use and great performances.

Quick Start

Let's see how to serialize:

Book book = new Book();
book.setName("Jodd in Action);
book.setYear(2018);
book.setAuthors(List.of(new Author("Igor")));

String json = JsonSerializer.create()
        .include("authors")
        .serialize(book);

The resulting JSON may look like this:

{
    "name" : "Jodd In Action",
    "year" : 2018,
    "authors" : [
        { "firstName" : "Igor" }
    ]
}

Parse the JSON back to Java:

Book book2 = new JsonParser()
        .parse(json, Book.class);

Pretty simple, right? But don't get blinded by the simplicity, Jodd JSON is pretty powerful. Did I mention it is one of the fastest JSON frameworks out there?

Main features

• simple syntax and fluent interface,

• lazy parser that is super fast,

• annotations for better conversion control,

• convenient JSONObject and JSONArray classes,

• powerful exclusion and inclusion rules,

• serializer definition for types,

• the only library that can handle any number size,

• pretty formatting of the JSON output,

• loose, more forgiving, parsing mode,

• ways to address the keys and values of the Maps

• flexible fine-tuning,

• and more…

License

The code is released under the BSD-2-Clause license. It has a minimal set of dependencies with the same or similarly open license, so you should be able to use it in any project and for any purpose.

Jodd JSON is released on Maven Central. You can use the following snippets to add it to your project:

<dependency>
  <groupId>org.jodd</groupId>
  <artifactId>jodd-json</artifactId>
  <version>x.x.x</version>
</dependency>

implementation 'org.jodd:jodd-json:x.x.x'

<dependency org="org.jodd" name="jodd-json" rev="x.x.x" />

[org.jodd/jodd-json "x.x.x"]

'org.jodd:jodd-json:jar:x.x.x'

That is all!

Snapshots

Jodd JSON snapshots are published on Maven Central Snapshot repo.

Convert bean to map

Sometimes you may want to convert an object into a map, using the JsonSerializer exclude/include rules. This can be done with BeanSerializer, in few steps like this:

final Map<String, Object> map = new HashMap<String, Object>();

JsonContext jsonContext = new JsonSerializer().createJsonContext(null);

BeanSerializer beanSerializer = new BeanSerializer(jsonContext, bean) {
    @Override
    protected void onSerializableProperty(
            String propertyName, Class propertyType, Object value) {
        map.put(propertyName, value);
    }
};

beanSerializer.serialize();

BeanSerializer parse beans and match properties to all include/exclude rules. Resulting map will contain all included properties of a bean. Serializing this map or the bean should give exactly the same results!

This may be handy if you have some further filtering options on some bean.

Use JsonWriter

JsonWriter is a simple class that writes JSON to the output. You can use it to construct JSON directly, without serialization:

StringBuilder sb = new StringBuilder();
JsonWriter jsonWriter = new JsonWriter(sb);

jsonWriter.writeOpenObject();
jsonWriter.writeName("one");
jsonWriter.writeNumber(Long.valueOf(123));
jsonWriter.writeComma();
jsonWriter.writeName("two");
jsonWriter.writeString("UberLight");
jsonWriter.writeCloseObject();

This can be handy when e.g. you need to wrap your serialized JSON into another simple map. Instead of creating a new Map object you can simply use the writer with the JSON result to create the same thing, but faster.

Default object types of parsed JSON inputs are Map and List. While this can be enough, sometimes you want a more developer-friendly way to navigate the returned object, especially nested values - you keep casting all over the code. Jodd JSON comes with two nice classes: JsonObject and JsonArray that can be used instead of defaults. They are quite convenient to work with JSON structure.

Here is an example of the usage:

Serialization

Both JsonObject and JsonArray may be used for serialization, too. You can use them to construct the JSON structure and then serialize it as usual.

Binary values

JsonObject is able to read and write binaries i.e. byte[]. Of course, JSON format does not support the binary types, hence the input array is encoded to Base64. Similarly,the Base64 field can be read as binary and convert into the byte[].

Jodd JSON serialization and parsing can be configured globally using the static fields.

The global configuration for JsonSerializer is defined in JsonSerializer.Defaults class. There you can enable some flags and set some values that will be used by default by any new instance of the JsonSerializer.

The same thing applies to the JsonParser. Its default configuration is in JsonParser.Defaults.

JsonSerializer serializes objects into JSON strings. Create an instance of the serializer, configure it and you're done! You may re-use the JsonSerializer instances (i.e. configurations). Let's see more about how serialization works.

Basic usage

Create the new instance of JsonSerializer and pass an object to serialize:

JsonSerializer jsonSerializer = new JsonSerializer();
String json = jsonSerializer.serialize(object);

or as a one-liner:

String json = JsonSerializer.create().serialize(object);

Thats it! JsonSerializer process the target object according to its type. It recognizes arrays, lists, maps, collections, strings, numbers etc. and returns them in a correct JSON format.

If you pass an object, JsonSerializer will scan all its properties (defined by getters) and create JSON map from it. Each property of a bean will be also serialized according to its type and so on. Of course, JsonSerializer detects circular dependencies (by checking an object's identity).

There is one important default behavior of JsonSerializer:

Collections (lists, arrays...) are not serialized by default. {: .attn}

This plays well with some 3rd party libraries (like ORM) where collections represent lazy relationships.

Path

JSON serialization is recursive: all properties of target bean gets serialized and so on. During the serialization, JsonSerializer browse the 'object graph' of given object. Current serialization position is determined by the path: a string that consist of dot-separated property names up to the current position.

For example, the path may be user.work.prefix. This means that we can get its value in Java by calling: getUser().getWork().getPrefix() on target object.

Deep serialization

If you want to serialize everything, including the collections, don't worry! Just set the deep flag to true:

String json = jsonSerializer.create().deep(true).serialize(object);

The object will be fully serialized. If all your use-cases use deep serialization, it's easy to enable it globally in the configuration.

Class name meta-data

By default, JsonSerializer does not outputs object's class name. However, sometimes we want to preserve the type of serialized object (especially if we want to parse the JSON string back into object). To do this, just enable this feature:

JsonSerializer.create()
    .setClassMetadataName("class")
    .serialize(object);

This feature can be enabled to be default, too.

JSON Type Serializers

JsonSerializer knows to serializes primitives, collections, strings, integers, and various Java types that are commonly used as bean properties. For each type, there is a TypeJsonSerializer instance that defines how type is serialized to a JSON.

It is possible to add a custom serializer for a type. We can:

• register custom serializer for a type, so all instances of this type would be registered the same way, or

• we can bind a property path to custom serializer:

final SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy/MM/dd");
String json = new JsonSerializer()
        .withSerializer("birthdate", new DateJsonSerializer() {
            @Override
            public void serialize(JsonContext jsonContext, Date date) {
                jsonContext.writeString(dateFormat.format(date));
            }
        })
        .serialize(foo);

Jodd JSON comes with default set of type serializers that should cover all common types and needs. However, don't hesitate to build your own type serializer when needed.

Pretty JSON

Default JSON output is not human readable as it does not have any line break. There is a pretty version of a serializer that returns beautiful JSON:

JsonSerializer serializer = new PrettyJsonSerializer();

or as a one-liner:

JsonSerializer.createPrettyOne()

User can control the indentation size and used character.

So far we have seen that JsonSerializer excludes the collections, and that this behavior is controlled by the deep flag. There is more sophisticated way on how to configure what to serialize. Serialization process can be fine-tuned: properties can be included and excluded. There are several ways how to do this.

Include/Exclude methods

By using include() and exclude() methods we can include and exclude a property referenced by it's path. Let's take the following class as an example:

public class Person {

    private String name;
    private Address home;
    private Address work;
    private List<Phone> phones = new ArrayList<Phone>();

    // ... and getters and setters
}

If we serialize this class using default JsonSerializer we will get JSON object with 3 keys: name, home and work. Property phones is not serialized by default as it is a collection.

We can include phones with the following code:

String json = new JsonSerializer
    .include('phones')
    .serialize(object);

In the same way we can exclude a property. For example:

String json = new JsonSerializer
    .exclude('work')
    .include('phones')
    .serialize(object);

Resulting JSON in this case would also be a map with 3 keys: name, home and phones.

Of course, you can specify nested include/exclude paths, like:

String json = JsonSerializer.create()
    .exclude('work')
    .include('phones')
    .exclude('phones.areaCode')
    .serialize(object);

This time we changed how the inner object (Phone) is serialized.

Include/exclude paths can contain a wildcard (*). Wildcard replaces more properties at once. Wildcard can only substitute whole property names, not partials. Here is how it can be used:

String json = new JsonSerializer
    .exclude('*')
    .include('name')
    .serialize(object);

Resulting JSON map this time contains just one key: name, as all others properties are excluded.

JSON Annotation

Using include/exclude methods can be cumbersome if done frequently. Json provides a way to express these rules using annotation. The @JSON annotation marks a property (getter or a field) as included by default.

In above example we may say that Phones are integral part of a Person and that we should always have them serialized. So we can do the following:

public class Person {

    private String name;
    private Address home;
    private Address work;
    @JSON
    private List<Phone> phones = new ArrayList<Phone>();

    // ... getters and setters
}

That's it! But wait, that's not all :) Json supports two ways how a class can be annotated:

• In the default mode, JSON annotations simply defines additional properties that have to be included. All other properties, that are not marked with an annotation, are also included according to the rules. This mode is usually used to include collection properties, that are excluded by default.

• In the strict mode, JSON annotation defines only properties that have to be included. All other properties, that are not marked with an annotation, are not included, even though they should be according to the rules. Strict mode is enabled by annotating the class with the annotation and setting the strict element to true:

@JSON(strict = true)
public class Person {

    @JSON
    private String name;
    @JSON
    private Address home;
    private Address work;
    @JSON
    private List<Phone> phones = new ArrayList<Phone>();

    // ... and getters and setters
}

Here property work is not serialized as it is not annotated and the class is serialized in strict mode.

Custom key names

Furthermore, JSON annotation can change the name of the generated keys, e.g.:

public class Person {

    @JSON
    private String name;
    @JSON(name = "home_address")
    private Address home;

    //...
}

We have changed the name of the home property to home_address.

Custom JSON Annotation

An awesome feature is that it is possible to set custom JSON annotation. If you do not want to use default annotation from Jodd JSON, then just create your own annotation and register it. You don't have to copy all annotation fields, just those that you really need.

Custom annotations is a great way how you can integrate Json with the existing codebase.

Excluding types

We can also exclude properties of certain type or that matches certain type name wildcard pattern. Sometimes we need to serialize complex beans that contain properties that are meaningless for the serialization, like streams. We can exclude such properties from getting serialized:

new JsonSerializer()
    .excludeTypes(InputStream.class)
    .serialize(object);

This will exclude properties that are of InputStream type. We could also add the following rule:

new JsonSerializer()
    .excludeTypes(InputStream.class)
    .excludeTypes("javax.*")
    .serialize(object);

where the whole package gets excluded.

Jodd JSON parser reads JSON string and converts it into objects (i.e. object graph). Mapping JSON data to Java objects may be tricky. Jodd JSON uses class and property types to map string JSON values into specific Java type. And as a bonus, it is super fast.

Basic usage

The parser class is JsonParser. When no target type is provided, the parser will convert JSON string to Java Map and List. Like this:

JsonParser jsonParser = new JsonParser();
Map map = jsonParser.parse(
    "{ \"one\" : { \"two\" : 285 }, \"three\" : true}");

or as a one-liner:

Map map = JsonParser.create().parse("{ ... }");

JSON string here is converted into a Map that contains 2 keys. One of the keys (one) holds another Map instance. As you can see from the example, simple JSON data types are converted into their counter-part Java types. Boolean value is converted to Boolean, number is converted to a Number or BigInteger etc. JsonParser finds the best possible type; for example, if number can be stored into an int then Integer is returned, but if it is a decimal value then Double is returned and so on.

Ok, let's now see how to map JSON to types.

Parsing to types

Let's start with the JSON data:

{
    "name" : "Mak",
    "bars" : {
        "123": {"amount" : 12300},
        "456": {"amount" : 45600}
    },
    "inters" : {
        "letterJ" : {"sign" : "J"},
        "letterO" : {"sign" : "O"},
        "letterD" : {"sign" : "D"}
    }
}

This data can be mapped to Java type like:

public class User {
    private String name;
    private Map<String, Bar> bars;
    private Map<String, Inter> inters;
    // ...
}

Property name is a simple property. But bars is a Map of Bars:

public class Bar {
    private Integer amount;
    // ...
}

This is no problem for JsonParser. It will parse inner JSON maps to Bar types, since the generic type of the property specifies the map's content type. In the same way JsonParser can handle the inters map.

JsonParser jsonParser = new JsonParser();
User user = jsonParser.parse(json, User.class);

JsonParser now converts JSON directly to a target type. Let's remember:

Using this approach, JsonParser can parse complex JSON strings into Java object graph, as long it can resolve the type information.

Define the target type with paths

To introduce some more complexity, let's say that Inter is an interface:

public interface Inter {
    public char getSign();
}

and one of its implementations is:

public class InterImpl implements Inter {
    protected char sign;

    public char getSign() {
        return sign;
    }
    public void setSign(char sign) {
        this.sign = sign;
    }
}

Now, this is something JsonParser that can't figure out by looking at the inters property types and its generic information. We need to explicitly specify the target type for maps values. As you could guess, we can use a path to specify the mapping. But in this case, the path needs to address the values of the map! No problem - by using a special path name value we can address all the values of a map:

User user = new JsonParser()
    .map("inters.values", InterImpl.class)
    .parse(json, User.class);

Nice! Similar to the value, we could specify the key's type, using the path reference keys. Look at the following example:

String json = "{\"eee\" : {\"123\" : \"name\"}}";

Map<String, Map<Long, String>> map =
    new JsonParser()
    .map("values.keys", Long.class)
    .parse(json);

We changed the key type of the inner map. This is one more thing to remember:

Now we have a powerful tool that can parse about any JSON to any Java type. Here is another example:

  {
    "1": {
      "first": {
        "areaCode": "404"
      },
      "second": {
        "name": "Jodd"
      }
    }
  }

Maybe parsed like this:

Map<String, Pair<Phone, Network>> complex = new JsonParser()
    .map("values", Pair.class)
    .map("values.first", Phone.class)
    .map("values.second", Network.class)
    .parse(json);

Each value of the returned map is going to be a Pair of two different types.

Alt(ernative) paths

As seen, the path can contain special names like values or keys to reference ALL values of a map or ALL keys of a map (or of an array). But you can not change the type of particular map value, since these special paths address ALL items.

But there is a solution to this. By enabling the alternative paths with .useAltPaths() we are telling JsonParser to match paths to current map values! By default, this option is disabled, for performance reasons (there is some penalty because more paths are matched).

With alt paths enabled, you can reference any value on the map, too.

Class meta-data name

Sometimes JSON string does contain information about the target type, stored in 'special' key like class or __class. If you have such JSON or if you have used this option with JsonSerializer, you can enable this feature with JsonParser as well:

Target target =
    new JsonParser()
    .setClassMetadataName("class")
    .parse(json);

Now every JSON map will be scanned for this special key class that holds the full class name of the target. But be careful:

Every JSON map first must be converted to a Map so we can fetch the class name and then converted to a target class. Because of this double conversion expect performance penalties if using class metadata name.

There are security risks using class meta-data. You may expose a security hole in case an untrusted source manages to specify a class that is accessible through class loader and exposes a set of methods and/or fields, access to which opens an actual security hole. Such classes are known as deserialization gadgets.

Because of this, use of "default typing" is not encouraged in general, and in particular is recommended against if the source of content is not trusted. Conversely, default typing may be used for processing content in cases where both ends (sender and receiver) are controlled by the same entity.

For additional security control there is a method to whitelist allowed class names wildcards: allowClass(). If the class name does not match one of set wildcard patterns, JsonParser will throw an exception. To reset the whitelist, use allowAllClasses().

Type conversion

As for everything in Jodd, JoddParser uses powerful TypeConverter to convert between strings to real types.

Value converters

Sometimes data comes in different flavors. For example, Date may be specified as a string in yyyy/MM/dd format and not as a number of milliseconds. So we need to explicitly convert the string into Date. For that, we can use ValueConverter:

final SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy/MM/dd");

Person person = new JsonParser()
        .withValueConverter("birthdate", new ValueConverter<String, Date>() {
            public Date convert(String data) {
                try {
                    return dateFormat.parse(data);
                } catch (ParseException pe) {
                    throw new JsonException(pe);
                }
            }
        })
        .parse(json, Person.class);

Loose mode

Jodd Json parser consumes only valid JSON strings. If the JSON string is not valid, an exception is thrown with a detailed message of why parsing failed.

But real-world often does not play by the rules ;) Therefore, JsonParser may run in so-called loose mode, when it can process more:

JsonParser jsonParser = new JsonParser().looseMode(true);

Here is what loose mode may handle:

• both single and double quotes are accepted.

• invalid escape characters are just added to the output.

• strings may be unquoted, too.

For example, JsonParser in loose mode may parse the following input:

{
    key : value,
    'my' : 'hol\\x'
}

This JSON is not valid, but it can be parsed, too.

Lazy mode

Finally, the performance gem. A common scenario is parsing a (big) JSON document only to access a few keys. For these situations, we actually don't need to parse the complete JSON, only the elements that we need.

Jodd JSON has a lazy mode that provides exactly that feature. It returns the Map or the List i.e. in the lazy mode, there is no sense to parse to concrete types. The returned object is lazy since the parsing happens only on key retrieval.

This may boost performance a lot (in the explained scenario)! The downside of this approach is that the JSON string is kept in memory while the returned object exists. Please use the lazy mode with care.

JsonParser jsonParser = new JsonParser().lazy(true);

or as a one-liner:

JsonParser jsonParser = JsonParser.createLazyOne();