/*
* 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;
/**
* <p>{@code Jsonb} provides an abstraction over the JSON Binding framework operations:</p>
*
* <ul>
* <li>{@code fromJson}: read JSON input, deserialize to Java objects content tree
* <li>{@code toJson}: serialize Java objects content tree to JSON input
* </ul>
*
* <p>Instance of this class is created using {@link javax.json.bind.JsonbBuilder JsonbBuilder}
* builder methods:</p>
* <pre>{@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();
* }</pre>
*
* <b>Deserializing (reading) JSON</b><br>
* <blockquote>
* Can de-serialize JSON data that represents either an entire JSON
* document or a subtree of a JSON document.
* </blockquote>
* <blockquote>
* Reading (deserializing) object content tree from a File:<br><br>
* <pre>
* Jsonb jsonb = JsonbBuilder.create();
* Book book = jsonb.fromJson(new FileReader("jsonfile.json"), Book.class);</pre>
* 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.
* </blockquote>
*
* <p><b>Serializing (writing) to JSON</b></p>
* <blockquote>
* Serialization writes the representation of a Java object content tree into
* JSON data.
* </blockquote>
* <blockquote>
* Writing (serializing) object content tree to a File:<br><br>
* <pre>
* jsonb.toJson(object, new FileWriter("foo.json"));</pre>
* Writing (serializing) to a Writer:<br><br>
* <pre>
* jsonb.toJson(object, new PrintWriter(System.out));
* </pre>
* </blockquote>
*
* <p><b>Encoding</b></p>
* <blockquote>
* 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
* <a href="http://tools.ietf.org/html/rfc7159">RFC 7159</a> 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
* <a href="http://tools.ietf.org/html/rfc7159">RFC 7159</a> and supported by Java Platform.
* </blockquote>
*
* <p>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.</p>
*
* <p>All the methods in this class are safe for use by multiple concurrent threads.</p>
*
* <p>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.
* </p>
*
* @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 <T>
* 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> T
fromJson(
String str,
Class<T>
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 <T>
* 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> 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 <T>
* 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> T
fromJson(
Reader reader,
Class<T>
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 <T>
* 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> 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 <T>
* 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> T
fromJson(
InputStream stream,
Class<T>
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 <T>
* 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> 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;
}