javax.json.bind.Jsonb Maven / Gradle / Ivy
The newest version!
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2016, 2017 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://oss.oracle.com/licenses/CDDL+GPL-1.1
* or LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.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 javax.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 javax.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 javax.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.
*
* @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.
*
* @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.
*
* @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;
}