Fluent-Json user guide

  1. Quickstart
  2. Mappers
  3. Java 8

1. Quickstart

It’s almost impossible to go wrong with Fluent-Json builder so here’s a taste of what you can do.

JsonObject jsonObject = JsonBuilderFactory.buildObject() //Create a new builder for an object
  .addNull("nullKey")                            //1. Add a null to the object

  .add("stringKey", "Hello")                     //2. Add a string to the object
  .add("stringNullKey", (String) null)           //3. Add a null string to the object

  .add("numberKey", 2)                           //4. Add a number to the object
  .add("numberNullKey", (Float) null)            //5. Add a null number to the object

  .add("booleanKey", true)                       //6. Add a boolean to the object
  .add("booleanNullKey", (Boolean) null)         //7. Add a null boolean to the object

  .add("characterKey", 'c')                      //8. Add a character to the object
  .add("characterNullKey", (Character) null)     //9. Add a null character to the object

  .addObject("objKey")                           //10. Add a nested object
    .add("nestedPropertyKey", 4)                 //11. Add a nested property to the nested object
    .end()                                       //12. End nested object and return to the parent builder

  .addArray("arrayKey")                          //13. Add an array to the object
    .addObject()                                 //14. Add a nested object to the array
      .end()                                     //15. End the nested object
    .add("arrayElement")                         //16. Add a string to the array
    .end()                                       //17. End the array

    .getJson();                                  //Get the JsonObject

String json = jsonObject.toString();
{
  "nullKey": null,              //1
  "stringKey": "Hello",         //2
  "stringNullKey": null,        //3
  "numberKey": 2,               //4
  "numberNullKey": null,        //5
  "booleanKey": true,           //6
  "booleanNullKey": null,       //7
  "characterKey": "c",          //8
  "characterNullKey": null,     //9
  "objKey": {                   //10
    "nestedPropertyKey": 4      //11
  },                            //12
  "arrayKey": [                 //13
    {},                         //14,15
    "arrayElement"              //16
  ]                             //17
}                               

Note that the builder is fully type safe and at all times knows if you are on an array or object element and what the root object you are creating is.

2. Mappers

Fluent-Json has the concept of mappers that allow you to create reusable mapping of your domain objects to json.

Say you want to generate the following json:

[
 {
    userName:"Bryn",
    ageInYears:34
 },
 {
    userName:"Bob",
    ageInYears:56
 },
]

And you have a domain class:

interface User {
  String getName();
  int getAge();
}

You can use a mapper to map the domain object to the output format

import static org.jglue.fluentjson.JsonBuilderFactory.buildArray;
import static org.jglue.fluentjson.JsonBuilderFactory.buildObject;

Collection<User> users = ...;

JsonArray jsonArray = buildArray(new AbstractMapper<User>() {
    JsonBuilder map(User u) {
      return buildObject().add("userName", u.getName()).add("ageInYears", u.getAge());
    }
  }, users).getJson();

Mappers can be used in arrays and objects not just for creating top level objects

import static org.jglue.fluentjson.JsonBuilderFactory.buildArray;
import static org.jglue.fluentjson.JsonBuilderFactory.buildObject;

Collection<User> users = ...;

JsonArray jsonArray = buildObject()
  .add("groupName", "admin")
  .add("users", new AbstractMapper<User>() {
    JsonBuilder map(User u) {
      return buildObject().add("userName", u.getName()).add("ageInYears", u.getAge());
    }
  }, users).getJson();
{
  "groupName": "admin",
  "users": [
   {
      userName:"Bryn",
      ageInYears:34
   },
   {
      userName:"Bob",
      ageInYears:56
   },
  ]
}

3. Java 8

Fluent-Json is ideal for Java8. Using lambda expressions for mappers you can do things like this:

import static org.jglue.fluentjson.JsonBuilderFactory.buildArray;
import static org.jglue.fluentjson.JsonBuilderFactory.buildObject;

Collection<User> users = ...;
JsonArray jsonArray = buildArray(u-> { return buildObject()
                                       .add("userName", u.getName())
                                       .add("ageInYears", u.getAge()) }, users).getJson();

Post to Twitter