12 Jakarta JSON Binding

Jakarta JSON Binding (JSON-B) is a standard binding layer for converting Java objects to or from JSON messages. Oracle WebLogic Server 26.1.0.0.0 supports the Jakarta JSON Binding specification by including the JSR-367 reference implementation for use with applications deployed on a WebLogic Server instance.

JSON-B defines a default mapping algorithm for converting existing Java classes to JSON, while enabling developers to customize the mapping process through the use of Java annotations. For more information, see:

This chapter includes the following sections:

About Default Mapping

Default mapping is a set of rules used by the JSON-B engine by default without any customization annotations and custom configuration provided.

This mapping is used for serializing and deserializing basic Java types (such as java.lang.String, java.lang.Long, and java.lang.Boolean), Java SE types (such as java.math.BigInteger and java.util.Optional), and Java date and time classes.

The main entry point in JSON-B is the jakarta.json.bind.Jsonb interface. It provides a set of overloaded toJson and fromJson methods to serialize Java objects to JSON documents and deserialize them back. Jsonb instances are thread safe and can be reused. It is recommended to have a single instance per configuration type.

Create an instance with JsonbBuilder.create(), or pass a JsonbConfig to JsonbBuilder.create(config). Reuse an application-owned Jsonb while needed, then close it after all users have finished. Do not close a shared instance while another thread is using it.

You can map an object, a collection, or a generic collection:

  • Mapping an object

    Use toJson(object) to serialize an object and fromJson(json, Person.class) to deserialize a concrete Person type.

  • Mapping a collection or a generic collection

    For a top-level parameterized collection such as List<Person>, pass a java.lang.reflect.Type that retains its element type to fromJson. A raw List.class does not preserve Person; object elements are then mapped as untyped maps. A Type token can be captured from an anonymous subclass as shown below.

Run JsonbMappings.main with the JSON-B implementation available. This short-lived example uses try-with-resources; a shared application instance should instead close at its owning lifecycle boundary.

import jakarta.json.bind.Jsonb;
import jakarta.json.bind.JsonbBuilder;
import java.lang.reflect.Type;
import java.util.ArrayList;
import java.util.List;

public class JsonbMappings {
    public static class Person {
        public String name;
        public Person() { }
    }

    public static void main(String[] args) throws Exception {
        try (Jsonb jsonb = JsonbBuilder.create()) {
            Person person = new Person();
            person.name = "Duke";
            String json = jsonb.toJson(person);
            Person copy = jsonb.fromJson(json, Person.class);

            Type peopleType = new ArrayList<Person>() { }
                .getClass().getGenericSuperclass();
            List<Person> people = jsonb.fromJson(
                "[{\"name\":\"Duke\"}]", peopleType);

            System.out.println(json);
            System.out.println(copy.name);
            System.out.println(people.get(0).name);
        }
    }
}

Expected output:

{"name":"Duke"}
Duke
Duke

For more information about default mapping, see:

About Customized Mapping

Customize JSON-B mapping declaratively with annotations on your Java types and members, or programmatically with jakarta.json.bind.JsonbConfig. The provider applies both forms during serialization and deserialization. Supply the configuration when creating a Jsonb instance, for example JsonbBuilder.create(config).

JSON-B supports the following customizations:

  • Creating custom configurations with formatted output
  • Changing property names
  • Customizing the order of serialized properties
  • Ignoring properties
  • Changing the default null handling
  • Using custom instantiation
  • Changing the date and number formats
  • Using binary encoding
  • Using adapters
  • Using serializer and deserializer classes
  • Using strict I-JSON support

For more information about customized mapping, see:

JSON-B Support in Jakarta REST

In a product that supports Jakarta JSON Binding, implementations must support entity providers for all Java types supported by JSON-B in combination with the media types - application/json, text/json, and any other media types matching */json or */*+json.

Note:

When both JSON-B and JSON-P are available, the JSON-B entity providers take precedence except for jakarta.json.JsonValue and its subtypes, which use the JSON-P providers.

Jakarta REST 4.0, §11.2.6

See Jakarta REST 4.0, §11.2.6, Java API for JSON Binding.

If you selected to install the WebLogic Server Examples, you'll find an example that demonstrates how to use Jakarta JSON Binding with JAX-RS in the ORACLE_HOME\wlserver\samples\server\examples\src\examples\javaee8\jsonb\jaxrs directory of your WebLogic Server distribution, where ORACLE_HOME represents the directory in which you installed WebLogic Server. For more information about the WebLogic Server code examples, see Sample Applications and Code Examples in Understanding Oracle WebLogic Server.