JSON Binding
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 theJsonbAdapter
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 theJsonbAdapter
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 theJsonbProvider
class, which contains the methods that a service provider implements.
Class or Interface | Description |
---|---|
|
Contains the JSON binding methods for serializing Java objects to JSON and deserailizing JSON to Java objects. |
|
Used by clients to create |
|
Used to set configuration properties on |
|
Indicates that a problem occurred during JSON binding. |
Class or Interface | Description |
---|---|
|
Used to set how property names are translated. |
|
Used to set whether fields and methods should be considered properties overriding the default scope and field access behavior. |
|
Used to set binary encoding. |
|
Used to set how properties are ordered during serialization. |
Class or Interface | Description |
---|---|
|
Used to create a deserialization routine for a custom type. |
|
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 aPerson
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