11 Java API for JSON Binding

JSON Binding (JSON-B) is a standard binding layer for converting Java objects to or from JSON messages. Oracle WebLogic Server 14.1.1.0.0 supports the Java API for JSON Binding 1.0 (JSR 367) 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:

• JSON Binding in The Java EE 8 Tutorial.
• JSON Binding 1.0 Users Guide
• JSON Binding package summary

This chapter includes the following sections:

• About Default Mapping
• About Customized Mapping
• Standard Support to Handle Application or JSON Media Type for JAX-RS

• 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.
• About Customized Mapping
  You can customize your mapping in many ways. Use JSON-B annotations for compile time customizations and JsonbConfig class for runtime customizations.
• Standard Support to Handle Application or JSON Media Type for JAX-RS
  In a product that supports the Java API for JSON-B, 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.

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 Jsonb class. 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.

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

• Mapping an object

  To map an object, you must first create a Jsonb instance, and use the toJson method to serialize to JSON and the fromJson method to deserialize back to an object.

• Mapping a collection or a generic collection

  JSON-B supports collections and generic collections handling. For proper deserialization, the runtime type of the resulting object needs to be passed to JSON-B during deserialization.

For more information about default mapping, see:

• Default Mapping in JSON Binding 1.0 Users Guide
• Using the Default Mapping in The Java EE 8 Tutorial

About Customized Mapping

You can customize your mapping in many ways. Use JSON-B annotations for compile time customizations and JsonbConfig class for runtime customizations.

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:

• Customized Mapping in JSON Binding 1.0 Users Guide
• Using Customizations in The Java EE 8 Tutorial

Standard Support to Handle Application or JSON Media Type for JAX-RS

In a product that supports the Java API for JSON-B, 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:

If both JSON-B and JSON-P are supported in the same environment, entity providers for JSON-B take precedence over those for JSON-P, for all types except JsonValue and its sub-types. Note the precedence with JSON-P.

If you selected to install the WebLogic Server Examples, you'll find an example that demonstrates how to use the Java API for 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.