JSON Binding

We are working on a fresh, updated Jakarta EE Tutorial. This section hasn’t yet been updated.

This chapter describes the Jakarta JSON Binding. JSON is a data exchange format widely used in web services and other connected applications. For a brief overview of JSON, see Introduction to JSON.

The Jakarta JSON Binding specification provides a standard binding layer (metadata and runtime) between Java classes and JSON documents. One Jakarta JSON Binding reference implementation is Yasson, which is developed through Eclipse.org and is included as part of GlassFish Server.

You can learn more about Yasson at https://projects.eclipse.org/projects/ee4j.yasson.

JSON Binding in the Jakarta EE Platform

Jakarta EE includes support for the Jakarta JSON Binding spec, which provides an API that can serialize Java objects to JSON documents and deserialize JSON documents to Java objects. Jakarta JSON Binding contains the following packages:

The jakarta.json.bind package contains the binding interface, the builder interface, and a configuration class. Main Classes and Interfaces in jakarta.json.bind lists the main classes and interfaces in this package.
The jakarta.json.bind.adapter package contains the JsonbAdapter interface, which provides methods for binding custom Java types by converting them to known types.
The jakarta.json.bind.annotation package defines annotations that can be used to customize default binding behavior. Annotations can be used for field, JavaBean property, type, or package elements.
The jakarta.json.bind.config package interfaces and classes for customizing default binding behavior. Main Classes and Interfaces in jakarta.json.bind.config lists the main classes and interfaces in this package.
The jakarta.json.bind.serializer package contains interfaces that are used to create serialization and deserialization routines for custom types that cannot be easily mapped using the JsonbAdapter methods. Main Classes and Interfaces in jakarta.json.bind.serializer lists the main interfaces in this package.
The jakarta.json.bind.spi package contains a Service Provider Interface (SPI) for creating JSON Binding implementations. This package contains the JsonbProvider class, which contains the methods that a service provider implements.

Main Classes and Interfaces in jakarta.json.bind
Class or Interface	Description
`Jsonb`	Contains the JSON binding methods for serializing Java objects to JSON and deserailizing JSON to Java objects.
`JsonBuilder`	Used by clients to create `Jsonb` instances.
`JsonbConfig`	Used to set configuration properties on `Jsonb` instances. Properties include binding strategies and properties for configuring custom serializers and deserializers.
`JsonbException`	Indicates that a problem occurred during JSON binding.

Main Classes and Interfaces in jakarta.json.bind.config
Class or Interface	Description
`PropertyNamingStrategy`	Used to set how property names are translated.
`PropertyVisibilityStrategy`	Used to set whether fields and methods should be considered properties overriding the default scope and field access behavior.
`BinaryDataStrategy`	Used to set binary encoding.
`PropertyOrderStrategy`	Used to set how properties are ordered during serialization.

Main Classes and Interfaces in jakarta.json.bind.serializer
Class or Interface	Description
`JsonbDeserializer`	Used to create a deserialization routine for a custom type.
`JsonbSerializer`	Used to create a serialization routine for a custom type.

Overview of the JSON Binding API

This section provides basic instructions for using the Jakarta JSON Binding client API. The instructions provide a basis for understanding the Running the jsonbbasics Example Application. Refer to the Jakarta JSON Binding project page for API documentation and a more detailed User Guide.

Creating a jasonb Instance

A jsonb instance provides access to methods for binding objects to JSON. A single jsonb instance is required for most applications. A jsonb instance is created using the JsonbBuilder interface, which is a client’s entry point to the JSON Binding API. For example:

Jsonb jsonb = JsonbBuilder.create();

Using the Default Mapping

Jakarta JSON Binding provides default mappings for serializing and deserializing basic Java and Java SE types as well Java date and time classes. To use the default mappings and mapping behavior, create a josnb instance and use the toJson method to serialize to JSON and the fromJson method to deserialize back to an object. The following example binds a simple Person object that contains a single name field.

Jsonb jsonb = JsonbBuilder.create();

Person person = new Person();
person.name = "Fred";

Jsonb jsonb = JsonbBuilder.create();

// serialize to JSON
String result = jsonb.toJson(person);

// deserialize from JSON
person = jsonb.fromJson("{name:\"joe\"}", Person.class);

Using Customizations

Jakarta JSON Binding supports many ways to customize the default mapping behavior. For runtime customizations, a JsonbConfig configuration object is used when creating the jsonbinstance. The JsonbConfig class supports many configuration options and also includes advanced options for binding custom types. For advanced options, see the JsonbAdapter interface and the JsonbSerializer and JsonbDeserializer interfaces.

The following example creates a configuration object that sets the FORMATTING property to specify whether or not the serialized JSON data is formatted with linefeeds and indentation.

JsonbConfig config = new JsonbConfig()
    .withFormatting(true);

Jsonb jsonb = JsonbBuilder.create(config);

Using Annotations

Jakarta JSON Binding includes many annotations that can be used at compile time to customize the default mapping behavior. The following example uses the @JsonbProperty annotation to change the name field to person-name when the object is serialized to JSON.

public class Person {
    @JsonbProperty("person-name")
    private String name;
}

The resulting JSON document is written as:

{
    "person-name": "Fred",
}

Running the jsonbbasics Example Application

This section describes how to build and run the jsonbbasics example application. This example is a web application that demonstrates how to serialize an object to JSON and how to deserialize JSON to an object.

The jsonbbasics example application is in the jakartaee-examples/tutorial/web/jsonb/jsonbbasics directory.

Components of the jsonbbasics Example Application

The jsonbbasics example application contains the following files.

Two Jakarta Faces pages.
- The index.xhtml page contains a form to collect data that is used to create a Person object.
- The jsongenerated.xhtml page contains a text area that displays the data in JSON format.
The JsonbBean.java managed bean, which is a session-scoped managed bean that stores the data from the form and directs the navigation between the Facelets pages. This file contains code that uses the JSON Binding API.

Running the jsonbbasics Example Application

This section describes how to run the jsonbbasics example application from the command line using Maven.

To run the jsonbbasics example application using Maven:

Make sure that GlassFish Server has been started (see Starting and Stopping GlassFish Server).

In a terminal window, go to:

jakartaee-examples/tutorial/web/jsonb/jsonbbasics

Enter the following command to deploy the application:
```
mvn install
```
Open a web browser window and enter the following address:
```
http://localhost:8080/jsonbbasics/
```
Enter data on form and click Serialize to JSON to submit the form. The following page shows the JSON format of the object data.
Click Deserialize JSON. The index page displays and contains the fields populated from the object data.

Further Information about the Jakarta JSON Binding

For more information on Jakarta JSON Binding, see:

Jakarta JSON Binding spec:
https://jakarta.ee/specifications/jsonb/
Specification project:
https://github.com/eclipse-ee4j/jsonb-api
Yasson (Implementation):
https://projects.eclipse.org/projects/ee4j.yasson