Interface Jsonb

  • All Superinterfaces:
    AutoCloseable

    public interface Jsonb
    extends AutoCloseable

    Jsonb provides an abstraction over the JSON Binding framework operations:

    • fromJson: read JSON input, deserialize to Java objects content tree
    • toJson: serialize Java objects content tree to JSON input

    Instance of this class is created using JsonbBuilder builder methods:

    
     // 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
    Can de-serialize JSON data that represents either an entire JSON document or a subtree of a JSON document.
    Reading (deserializing) object content tree from a File:

         Jsonb jsonb = JsonbBuilder.create();
         Book book = jsonb.fromJson(new FileReader("jsonfile.json"), Book.class);
    If the deserialization process is unable to deserialize the JSON content to an object content tree, 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) object content tree to a File:

         jsonb.toJson(object, new FileWriter("foo.json"));
    Writing (serializing) to a Writer:

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

    Encoding

    In deserialization operations (fromJson), encoding of JSON data is detected automatically. Use the JsonbConfig API to configure expected input encoding used within deserialization operations. Client applications are expected to supply a valid character encoding as defined in the RFC 7159 and supported by 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 used within serialization operations. Client applications are expected to supply a valid character encoding as defined in the RFC 7159 and supported by Java Platform.

    For optimal use, JsonbBuilder and Jsonb instances should be reused - for a typical use-case, only one Jsonb instance is required by an application.

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

    Calling Closable.close() method will cleanup all CDI managed components (such as adapters with CDI dependencies) created during interaction with Jsonb. Calling close() must be done after all threads has finished interaction with Jsonb. If there are remaining threads working with Jsonb and close() is called, behaviour is undefined.

    Since:
    JSON Binding 1.0
    See Also:
    Jsonb, JsonbBuilder, ServiceLoader
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      <T> T fromJson​(InputStream stream, Class<T> type)
      Reads in a JSON data from the specified InputStream and return the resulting content tree.
      <T> T fromJson​(InputStream stream, Type runtimeType)
      Reads in a JSON data from the specified InputStream and return the resulting content tree.
      <T> T fromJson​(Reader reader, Class<T> type)
      Reads in a JSON data from the specified Reader and return the resulting content tree.
      <T> T fromJson​(Reader reader, Type runtimeType)
      Reads in a JSON data from the specified Reader and return the resulting content tree.
      <T> T fromJson​(String str, Class<T> type)
      Reads in a JSON data from the specified string and return the resulting content tree.
      <T> T fromJson​(String str, Type runtimeType)
      Reads in a JSON data from the specified string and return the resulting content tree.
      String toJson​(Object object)
      Writes the Java object tree with root object object to a String instance as JSON.
      void toJson​(Object object, OutputStream stream)
      Writes the object content tree into output 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 root object object to a String instance as JSON.
      void toJson​(Object object, Type runtimeType, OutputStream stream)
      Writes the object content tree into output stream.
      void toJson​(Object object, Type runtimeType, Writer writer)
      Writes the object content tree into a Writer character stream.
    • Method Detail

      • fromJson

        <T> T fromJson​(String str,
                       Class<T> type)
                throws JsonbException
        Reads in a JSON data from the specified string and return 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 any unexpected error(s) occur(s) during deserialization.
        NullPointerException - If any of the parameters is null.
      • fromJson

        <T> T fromJson​(String str,
                       Type runtimeType)
                throws JsonbException
        Reads in a JSON data from the specified string and return 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 any unexpected error(s) occur(s) during deserialization.
        NullPointerException - If any of the parameters is null.
      • fromJson

        <T> T fromJson​(Reader reader,
                       Class<T> type)
                throws JsonbException
        Reads in a JSON data from the specified Reader and return the resulting content tree.
        Type Parameters:
        T - Type of the content tree's root object.
        Parameters:
        reader - The character stream is read as a 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 any unexpected error(s) occur(s) during deserialization.
        NullPointerException - If any of the parameters is null.
      • fromJson

        <T> T fromJson​(Reader reader,
                       Type runtimeType)
                throws JsonbException
        Reads in a JSON data from the specified Reader and return the resulting content tree.
        Type Parameters:
        T - Type of the content tree's root object.
        Parameters:
        reader - The character stream is read as a 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 any unexpected error(s) occur(s) during deserialization.
        NullPointerException - If any of the parameters is null.
      • fromJson

        <T> T fromJson​(InputStream stream,
                       Class<T> type)
                throws JsonbException
        Reads in a JSON data from the specified InputStream and return the resulting content tree.
        Type Parameters:
        T - Type of the content tree's root object.
        Parameters:
        stream - The stream is read as a JSON data. Upon a successful completion, the stream will be 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 any unexpected error(s) occur(s) during deserialization.
        NullPointerException - If any of the parameters is null.
      • fromJson

        <T> T fromJson​(InputStream stream,
                       Type runtimeType)
                throws JsonbException
        Reads in a JSON data from the specified InputStream and return the resulting content tree.
        Type Parameters:
        T - Type of the content tree's root object.
        Parameters:
        stream - The stream is read as a JSON data. Upon a successful completion, the stream will be 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 any unexpected error(s) occur(s) during deserialization.
        NullPointerException - If any of the parameters is null.
      • toJson

        String toJson​(Object object)
               throws JsonbException
        Writes the Java object tree with 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 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 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. Provided type needs to be related to the type of the instance.
        Returns:
        String instance with serialized JSON data.
        Throws:
        JsonbException - If any unexpected problem occurs during the serialization, such as 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. Provided type needs to be related to the type of the instance.
        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 into output 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 a successful completion, the stream will be 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 into output stream.
        Parameters:
        object - The object content tree to be serialized.
        runtimeType - Runtime type of the content tree's root object. Provided type needs to be related to the type of the instance.
        stream - The JSON will be sent as a byte stream to the given OutputStream. Upon a successful completion, the stream will be 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