jakarta.json.bind.Jsonb Maven / Gradle / Ivy
/*
* Copyright (c) 2016, 2021 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
package jakarta.json.bind;
import java.io.InputStream;
import java.io.OutputStream;
import java.io.Reader;
import java.io.Writer;
import java.lang.reflect.Type;
/**
* {@code Jsonb} provides an abstraction over the JSON Binding framework operations:
*
*
* - {@code fromJson}: read JSON input, deserialize to Java objects content tree
*
- {@code toJson}: serialize Java objects content tree to JSON input
*
*
* Instance of this class is created using {@link jakarta.json.bind.JsonbBuilder JsonbBuilder}
* builder methods:
* {@code
* // 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 ({@code fromJson}), encoding of JSON data is detected automatically.
* Use the {@link jakarta.json.bind.JsonbConfig 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 ({@code toJson}), UTF-8 encoding is used by default
* for writing JSON data.
* Use the {@link jakarta.json.bind.JsonbConfig 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, {@code JsonbBuilder} and {@code Jsonb} instances should be
* reused - for a typical use-case, only one {@code Jsonb} instance is
* required by an application.
*
* All the methods in this class are safe for use by multiple concurrent threads.
*
* Calling {@code Closable.close()} method will cleanup all CDI managed components
* (such as adapters with CDI dependencies) created during interaction with Jsonb.
* Calling {@code close()} must be done after all threads has finished interaction with Jsonb.
* If there are remaining threads working with Jsonb and {@code close()} is called, behaviour is undefined.
*
*
* @see Jsonb
* @see JsonbBuilder
* @see java.util.ServiceLoader
* @since JSON Binding 1.0
*/
public interface Jsonb extends AutoCloseable {
/**
* Reads in a JSON data from the specified string and return the resulting
* content tree.
*
* @param str
* The string to deserialize JSON data from.
* @param type
* Type of the content tree's root object.
* @param
* Type of the content tree's root object.
*
* @return the newly created root object of the java content tree
*
* @throws JsonbException
* If any unexpected error(s) occur(s) during deserialization.
* @throws NullPointerException
* If any of the parameters is {@code null}.
*/
T fromJson(String str, Class type) throws JsonbException;
/**
* Reads in a JSON data from the specified string and return the resulting
* content tree.
*
* @param str
* The string to deserialize JSON data from.
* @param runtimeType
* Runtime type of the content tree's root object.
* @param
* Type of the content tree's root object.
*
* @return the newly created root object of the java content tree
*
* @throws JsonbException
* If any unexpected error(s) occur(s) during deserialization.
* @throws NullPointerException
* If any of the parameters is {@code null}.
*/
T fromJson(String str, Type runtimeType) throws JsonbException;
/**
* Reads in a JSON data from the specified Reader and return the
* resulting content tree.
*
* @param reader
* The character stream is read as a JSON data.
* @param type
* Type of the content tree's root object.
* @param
* Type of the content tree's root object.
*
* @return the newly created root object of the java content tree
*
* @throws JsonbException
* If any unexpected error(s) occur(s) during deserialization.
* @throws NullPointerException
* If any of the parameters is {@code null}.
*/
T fromJson(Reader reader, Class type) throws JsonbException;
/**
* Reads in a JSON data from the specified Reader and return the
* resulting content tree.
*
* @param reader
* The character stream is read as a JSON data.
*
* @param runtimeType
* Runtime type of the content tree's root object.
*
* @param
* Type of the content tree's root object.
*
* @return the newly created root object of the java content tree
*
* @throws JsonbException
* If any unexpected error(s) occur(s) during deserialization.
* @throws NullPointerException
* If any of the parameters is {@code null}.
*/
T fromJson(Reader reader, Type runtimeType) throws JsonbException;
/**
* Reads in a JSON data from the specified InputStream and return the
* resulting content tree.
*
* @param stream
* The stream is read as a JSON data. Upon a
* successful completion, the stream will be closed by this method.
* @param type
* Type of the content tree's root object.
* @param
* Type of the content tree's root object.
*
* @return the newly created root object of the java content tree
*
* @throws JsonbException
* If any unexpected error(s) occur(s) during deserialization.
* @throws NullPointerException
* If any of the parameters is {@code null}.
*/
T fromJson(InputStream stream, Class type) throws JsonbException;
/**
* Reads in a JSON data from the specified InputStream and return the
* resulting content tree.
*
* @param stream
* The stream is read as a JSON data. Upon a
* successful completion, the stream will be closed by this method.
*
* @param runtimeType
* Runtime type of the content tree's root object.
*
* @param
* Type of the content tree's root object.
*
* @return the newly created root object of the java content tree
*
* @throws JsonbException
* If any unexpected error(s) occur(s) during deserialization.
* @throws NullPointerException
* If any of the parameters is {@code null}.
*/
T fromJson(InputStream stream, Type runtimeType) throws JsonbException;
/**
* Writes the Java object tree with root object {@code object} to a String
* instance as JSON.
*
* @param object
* The root object of the object content tree to be serialized. Must not be null.
*
* @return String instance with serialized JSON data.
*
* @throws JsonbException If any unexpected problem occurs during the
* serialization, such as I/O error.
* @throws NullPointerException
* If any of the parameters is {@code null}.
*
* @since JSON Binding 1.0
*/
String toJson(Object object) throws JsonbException;
/**
* Writes the Java object tree with root object {@code object} to a String
* instance as JSON.
*
* @param object
* The root object of the object content tree to be serialized. Must not be null.
*
* @param runtimeType
* Runtime type of the content tree's root object. Provided type needs to be
* related to the type of the instance.
*
* @return String instance with serialized JSON data.
*
* @throws JsonbException If any unexpected problem occurs during the
* serialization, such as I/O error.
* @throws NullPointerException
* If any of the parameters is {@code null}.
*
* @since JSON Binding 1.0
*/
String toJson(Object object, Type runtimeType) throws JsonbException;
/**
* Writes the object content tree into a Writer character stream.
*
* @param object
* The object content tree to be serialized.
* @param writer
* The JSON will be sent as a character stream to the given
* {@link Writer}.
*
* @throws JsonbException If any unexpected problem occurs during the
* serialization.
* @throws NullPointerException
* If any of the parameters is {@code null}.
*
* @since JSON Binding 1.0
*/
void toJson(Object object, Writer writer) throws JsonbException;
/**
* Writes the object content tree into a Writer character stream.
*
* @param object
* The object content tree to be serialized.
*
* @param runtimeType
* Runtime type of the content tree's root object. Provided type needs to be
* related to the type of the instance.
*
* @param writer
* The JSON will be sent as a character stream to the given
* {@link Writer}.
*
* @throws JsonbException If any unexpected problem occurs during the
* serialization.
* @throws NullPointerException
* If any of the parameters is {@code null}.
*
* @since JSON Binding 1.0
*/
void toJson(Object object, Type runtimeType, Writer writer) throws JsonbException;
/**
* Writes the object content tree into output stream.
*
* @param object
* The object content tree to be serialized.
* @param stream
* The JSON will be sent as a byte stream to the given
* {@link OutputStream}. Upon a successful completion, the stream will be closed
* by this method.
*
* @throws JsonbException If any unexpected problem occurs during the
* serialization.
* @throws NullPointerException
* If any of the parameters is {@code null}.
*
* @since JSON Binding 1.0
*/
void toJson(Object object, OutputStream stream) throws JsonbException;
/**
* Writes the object content tree into output stream.
*
* @param object
* The object content tree to be serialized.
*
* @param runtimeType
* Runtime type of the content tree's root object. Provided type needs to be
* related to the type of the instance.
*
* @param stream
* The JSON will be sent as a byte stream to the given
* {@link OutputStream}. Upon a successful completion, the stream will be closed
* by this method.
*
* @throws JsonbException If any unexpected problem occurs during the
* serialization.
* @throws NullPointerException
* If any of the parameters is {@code null}.
*
* @since JSON Binding 1.0
*/
void toJson(Object object, Type runtimeType, OutputStream stream) throws JsonbException;
}
© 2015 - 2024 Weber Informatics LLC | Privacy Policy