javax.json.bind

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

Modifier and Type	Method and 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.
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.
void	toJson(Object object, Writer writer) Writes the object content tree into a Writer character stream.

Methods inherited from interface java.lang.AutoCloseable

close

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.

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.

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.

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