Burningwave JSON

Burningwave JSON is an advanced, free and open source JSON handler for Java. The search and validation possibilities offered by this library are practically infinite and this page will illustrate an overview of the components exposed by the library and some examples of basic operation: for any further help visit the relevant section.

And now we will see:

• including Burningwave JSON in your project
• finding values ​​and paths in a JSON document
• validating values of a JSON document
• how to ask for assistance

Including Burningwave JSON in your project

To include Burningwave JSON library in your projects simply use with Apache Maven:

<dependency>
    <groupId>org.burningwave</groupId>
    <artifactId>json</artifactId>
    <version>0.13.0</version>
</dependency>

Requiring the Burningwave JSON module

To use Burningwave JSON as a Java module you need to add the following to your module-info.java:

requires org.burningwave.json;

Enabling the JVM Driver

Burningwave JSON uses the Burningwave Reflection library that, by default, doesn't use the the Burningwave JVM Driver: if you want to enable it consult the relevant section on the Burningwave Reflection project.

Finding values ​​and paths in a JSON document

The following example is available in the ObjectHandlerTest class. Let's assume the following JSON document:

{
    "quiz": {
        "sport": {
            "q1": {
                "question": "Which one is correct team name in NBA?",
                "options": [
                    "New York Bulls",
                    "Los Angeles Kings",
                    "Golden State Warriros",
                    "Huston Rocket"
                ],
                "answer": "Huston Rocket"
            }
        },
        "maths": {
            "q1": {
                "question": "5 + 7 = ?",
                "options": [
                    "10",
                    "11",
                    "12",
                    "13"
                ],
                "answer": "12"
            },
            "q2": {
                "question": "12 - 8 = ?",
                "options": [
                    "1",
                    "2",
                    "3",
                    "4"
                ],
                "answer": "4"
            }
        }
    }
}

First of all, to find values in a JSON document we need to load it via ObjectHandler. The ObjectHandler wraps the JSON document and contains the path and the value of the node you are visiting within the JSON. To instantiate an ObjectHandler follow this code:

Facade facade = Facade.create();
//Loading the JSON object 
ObjectHandler objectHandler = facade.newObjectHandler(
	ObjectHandlerTest.class.getClassLoader().getResourceAsStream("quiz.json"),
	Root.class
);

After loaded the JSON we need to instantiate a Finder. There are 3 kinds of Finder:

• the ObjectHandler.Finder that which allows you to search for elements within the JSON ​​returning ObjectHandlers
• the ObjectHandler.ValueFinder that which allows you to search for elements within the JSON ​​directly returning the values
• the ObjectHandler.ValueFinderAndConverter that which allows you to search for elements within the JSON ​​and convert the values found

The ObjectHandler.Finder

To obtain this kind of finder use this code:

ObjectHandler.Finder finder = objectHandler.newFinder();

Once you obtained the finder you can use it to search items inside the JSON document:

//Searching for the first occurrence by path suffix
ObjectHandler sportOH = finder.findFirstForPathEndsWith("sport");

//Retrieving the path of the sport object ("quiz.sport")
String sportPath = sportOH.getPath();

//Retrieving the value of the sport object
Sport sport = sportOH.getValue();

ObjectHandler option2OfSportQuestionOH = finder.findFirstForPathEndsWith(Path.of("sport", "q1", "options[1]"));
String option2OfSportQuestionOHPath = option2OfSportQuestionOH.getPath();
String option2OfSportQuestion = option2OfSportQuestionOH.getValue();

ObjectHandler questionOneOH = finder.findForPathEquals(Path.of("quiz", "sport", "q1"));
String questionOnePath = questionOneOH.getPath();
Question questionOne = questionOneOH.getValue();

The ObjectHandler.ValueFinder

To obtain this kind of finder use this code:

ObjectHandler.Finder finder = objectHandler.newValueFinder();

Once you obtained the finder you can use it to search items inside the JSON document:

//Searching for the first occurrence by path suffix
Sport sport = finder.findFirstForPathEndsWith("sport");

String option2OfSportQuestion = finder.findFirstForPathEndsWith(Path.of("sport", "q1", "options[1]"));
Question questionOne = finder.findForPathEquals(Path.of("quiz", "sport", "q1"));

The ObjectHandler.ValueFinderAndConverter

To obtain this kind of finder use this code:

ObjectHandler.Finder finderAndConverter = objectHandler.newValueFinderAndConverter();

Once you obtained the finder you can use it to search items inside the JSON document and convert them:

//Searching for the first occurrence by path suffix and convert it
Map<String, Object> sportAsMap = finderAndConverter.findFirstForPathEndsWith("sport");

Validating values of a JSON document

The following example is available in the ValidatorTest class. To validate a JSON document you need to obtain the Validator and then register the checks:

facade.validator().registerCheck(
	//Checking whether a value in any field marked as required (e.g.: @JsonProperty(value = "answer", required = true)) is null
	Check.forAll().checkMandatory(),
	//Checking whether a string value in any field is empty
	Check.forAllStringValues().execute(pathValidationContext -> {
		if (pathValidationContext.getValue() != null && pathValidationContext.getValue().trim().equals("")) {
			pathValidationContext.rejectValue("IS_EMPTY", "is empty");
		}
	})	
);

Once registered the checks, to execute the validation you must call the validate method:

Collection<Throwable> exceptions =
	facade.validator().validate(
		Validation.Config.forJsonObject(objectHandler.getValue())
		//By calling this method the validation will be performed on the entire document,
		//otherwise the validation will stop at the first exception thrown
		.withCompleteValidation()
	);

Ask for assistance

If this guide can't help you, you can:

• open a discussion here on GitHub
• report a bug here on GitHub
• ask on Stack Overflow