Module jakarta.json.bind
Package jakarta.json.bind

Interface Jsonb

All Superinterfaces:
AutoCloseable
public interface Jsonb extends AutoCloseable

Converts Java objects to and from JSON documents.

Jsonb provides an abstraction over the JSON Binding framework operations:

  • fromJson: reads JSON input, deserializes to a Java objects content tree
  • toJson: serializes a Java objects content tree to JSON output

An instance of this class is created using a JsonbBuilder builder method:


 // Example 1 - Creating Jsonb using default JsonbBuilder instance provided by default JsonbProvider
 Jsonb jsonb = JsonbBuilder.create();

 // Example 2 - Creating Jsonb instance for a specific provider specified by a class name
 Jsonb jsonb = JsonbBuilder.newBuilder("foo.bar.ProviderImpl").build();

 // Example 3 - Creating Jsonb instance from a custom provider implementation
 Jsonb jsonb = new CustomJsonbBuilder().build();

Deserializing (reading) JSON

You can deserialize JSON data that represents either an entire JSON document or a subtree of a JSON document.

Reading (deserializing) an object content tree from a file: 


   Jsonb jsonb = JsonbBuilder.create();
   try (FileReader reader = new FileReader("jsonfile.json")) {
       Book book = jsonb.fromJson(reader, Book.class);
   }

If the deserialization process is unable to deserialize the JSON content to an object content tree, a fatal error is reported that terminates processing by throwing JsonbException.

Serializing (writing) to JSON

Serialization writes the representation of a Java object content tree into JSON data.

Writing (serializing) an object content tree to a file:


   try (FileWriter writer = new FileWriter("foo.json")) {
       jsonb.toJson(object, writer);
   }

Writing (serializing) to a Writer:


   PrintWriter writer = new PrintWriter(System.out);
   jsonb.toJson(object, writer);
   writer.flush();

Encoding

In deserialization operations (fromJson), encoding of JSON data is detected automatically. You can use the JsonbConfig API to manually configure the input encoding for deserialization operations. Applications must supply a valid character encoding as defined in the RFC 7159 and which is also supported by the Java Platform.

In serialization operations (toJson), UTF-8 encoding is used by default for writing JSON data. Use the JsonbConfig API to configure the output encoding for serialization operations. Applications must supply a valid character encoding as defined in the RFC 7159 and which is also supported by Java Platform.

For optimal performance, reuse Jsonb instances. For a typical use-case, only one Jsonb instance is required by an application.

All the methods in this class are safe for concurrent use by multiple threads.

Calling the AutoCloseable.close() method cleans up all CDI managed components (such as adapters with CDI dependencies) created during interaction with the respective Jsonb instance. Calling close() must be done after all threads have finished interaction with the Jsonb instance. If there are remaining threads working with the Jsonb instance and close() is called, behaviour is undefined.

Since:
JSON Binding 1.0
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    <T> T
    fromJson(InputStream stream, Class<T> type)
    Reads JSON data from the specified InputStream and returns the resulting content tree.
    <T> T
    fromJson(InputStream stream, Type runtimeType)
    Reads JSON data from the specified InputStream and returns the resulting content tree.
    <T> T
    fromJson(Reader reader, Class<T> type)
    Reads JSON data from the specified reader and returns the resulting content tree.
    <T> T
    fromJson(Reader reader, Type runtimeType)
    Reads JSON data from the specified reader and returns the resulting content tree.
    <T> T
    fromJson(String str, Class<T> type)
    Reads JSON data from the specified string and returns the resulting content tree.
    <T> T
    fromJson(String str, Type runtimeType)
    Reads JSON data from the specified string and returns the resulting content tree.
    String
    toJson(Object object)
    Writes the Java object tree with the given root object, object, to a String instance as JSON.
    void
    toJson(Object object, OutputStream stream)
    Writes the object content tree to the given stream.
    void
    toJson(Object object, Writer writer)
    Writes the object content tree into a Writer character stream.
    String
    toJson(Object object, Type runtimeType)
    Writes the Java object tree with the given root object, object, to a String instance as JSON.
    void
    toJson(Object object, Type runtimeType, OutputStream stream)
    Writes the object content tree to the given stream.
    void
    toJson(Object object, Type runtimeType, Writer writer)
    Writes the object content tree into a Writer character stream.

    Methods inherited from interface java.lang.AutoCloseable

    close

  • Method Details

    • fromJson

      <T> T fromJson(String str, Class<T> type) throws JsonbException
      Reads JSON data from the specified string and returns the resulting content tree.
      Type Parameters:
      T - Type of the content tree's root object.
      Parameters:
      str - The string to deserialize JSON data from.
      type - Type of the content tree's root object.
      Returns:
      the newly created root object of the java content tree
      Throws:
      JsonbException - If an unexpected error occurs during deserialization.
      NullPointerException - If any of the parameters is null.

    • fromJson

      <T> T fromJson(String str, Type runtimeType) throws JsonbException
      Reads JSON data from the specified string and returns the resulting content tree.
      Type Parameters:
      T - Type of the content tree's root object.
      Parameters:
      str - The string to deserialize JSON data from.
      runtimeType - Runtime type of the content tree's root object.
      Returns:
      the newly created root object of the java content tree
      Throws:
      JsonbException - If an unexpected error occurs during deserialization.
      NullPointerException - If any of the parameters is null.

    • fromJson

      <T> T fromJson(Reader reader, Class<T> type) throws JsonbException
      Reads JSON data from the specified reader and returns the resulting content tree.
      Type Parameters:
      T - Type of the content tree's root object.
      Parameters:
      reader - The character stream from which to read JSON data.
      type - Type of the content tree's root object.
      Returns:
      the newly created root object of the java content tree
      Throws:
      JsonbException - If an unexpected error occurs during deserialization.
      NullPointerException - If any of the parameters is null.

    • fromJson

      <T> T fromJson(Reader reader, Type runtimeType) throws JsonbException
      Reads JSON data from the specified reader and returns the resulting content tree.
      Type Parameters:
      T - Type of the content tree's root object.
      Parameters:
      reader - The character stream from which to read JSON data.
      runtimeType - Runtime type of the content tree's root object.
      Returns:
      the newly created root object of the Java content tree
      Throws:
      JsonbException - If an unexpected error occurs during deserialization.
      NullPointerException - If any of the parameters is null.

    • fromJson

      <T> T fromJson(InputStream stream, Class<T> type) throws JsonbException
      Reads JSON data from the specified InputStream and returns the resulting content tree.
      Type Parameters:
      T - Type of the content tree's root object.
      Parameters:
      stream - The stream from which to read JSON data. Upon successful completion, the stream is closed by this method.
      type - Type of the content tree's root object.
      Returns:
      the newly created root object of the Java content tree
      Throws:
      JsonbException - If an unexpected error occurs during deserialization.
      NullPointerException - If any of the parameters is null.

    • fromJson

      <T> T fromJson(InputStream stream, Type runtimeType) throws JsonbException
      Reads JSON data from the specified InputStream and returns the resulting content tree.
      Type Parameters:
      T - Type of the content tree's root object.
      Parameters:
      stream - The stream from which to read JSON data. Upon successful completion, the stream is closed by this method.
      runtimeType - Runtime type of the content tree's root object.
      Returns:
      the newly created root object of the Java content tree
      Throws:
      JsonbException - If an unexpected error occurs during deserialization.
      NullPointerException - If any of the parameters is null.

    • toJson

      String toJson(Object object) throws JsonbException
      Writes the Java object tree with the given root object, object, to a String instance as JSON.
      Parameters:
      object - The root object of the object content tree to be serialized. Must not be null.
      Returns:
      String instance with serialized JSON data.
      Throws:
      JsonbException - If any unexpected problem occurs during the serialization, such as an I/O error.
      NullPointerException - If any of the parameters is null.
      Since:
      JSON Binding 1.0

    • toJson

      String toJson(Object object, Type runtimeType) throws JsonbException
      Writes the Java object tree with the given root object, object, to a String instance as JSON.
      Parameters:
      object - The root object of the object content tree to be serialized. Must not be null.
      runtimeType - Runtime type of the content tree's root object. The provided runtimeType must be a supertype of, or the same type as, the actual class of the provided object.
      Returns:
      String instance with serialized JSON data.
      Throws:
      JsonbException - If any unexpected problem occurs during the serialization, such as an I/O error.
      NullPointerException - If any of the parameters is null.
      Since:
      JSON Binding 1.0

    • toJson

      void toJson(Object object, Writer writer) throws JsonbException
      Writes the object content tree into a Writer character stream.
      Parameters:
      object - The object content tree to be serialized.
      writer - The JSON will be sent as a character stream to the given Writer.
      Throws:
      JsonbException - If any unexpected problem occurs during the serialization.
      NullPointerException - If any of the parameters is null.
      Since:
      JSON Binding 1.0

    • toJson

      void toJson(Object object, Type runtimeType, Writer writer) throws JsonbException
      Writes the object content tree into a Writer character stream.
      Parameters:
      object - The object content tree to be serialized.
      runtimeType - Runtime type of the content tree's root object. The provided runtimeType must be a supertype of, or the same type as, the actual class of the provided object.
      writer - The JSON will be sent as a character stream to the given Writer.
      Throws:
      JsonbException - If any unexpected problem occurs during the serialization.
      NullPointerException - If any of the parameters is null.
      Since:
      JSON Binding 1.0

    • toJson

      void toJson(Object object, OutputStream stream) throws JsonbException
      Writes the object content tree to the given stream.
      Parameters:
      object - The object content tree to be serialized.
      stream - The JSON will be sent as a byte stream to the given OutputStream. Upon successful completion, the stream is closed by this method.
      Throws:
      JsonbException - If any unexpected problem occurs during the serialization.
      NullPointerException - If any of the parameters is null.
      Since:
      JSON Binding 1.0

    • toJson

      void toJson(Object object, Type runtimeType, OutputStream stream) throws JsonbException
      Writes the object content tree to the given stream.
      Parameters:
      object - The object content tree to be serialized.
      runtimeType - Runtime type of the content tree's root object. The provided runtimeType must be a supertype of, or the same type as, the actual class of the provided object.
      stream - The JSON will be sent as a byte stream to the given OutputStream. Upon successful completion, the stream is closed by this method.
      Throws:
      JsonbException - If any unexpected problem occurs during the serialization.
      NullPointerException - If any of the parameters is null.
      Since:
      JSON Binding 1.0