com.cedarsoftware.util.io

Class JsonIo

java.lang.Object

com.cedarsoftware.util.io.JsonIo

public class JsonIo
extends Object

This is the main API for json-io. Use these methods to convert:

• 1. Input: Java root Output: JSON

  String json = JsonIo.toJson(root, writeOptions)

• 2. Input: Java root Output: JSON -> outputStream

  JsonIo.toJson(OutputStream, root, writeOptions)

• 3. Input: JSON, Output: Java objects

  BillingInfo billInfo = JsonIo.toObjects(String | InputStream, readOptions, BillingInfo.class)

• 4. Input: JSON, Output: JsonObject

  JsonObject JsonIo.toJsonValues(String | InputStream, readOptions)

Often, the goal is to get JSON to Java objects and from Java objects to JSON. That is #1 and #3 above.

For approaches #1 and #2 above, json-io will check the root object type (regular Java class or JsonObject instance) to know which type of Object Graph it is serializing to JSON.

There are occasions where you may just want the raw JSON data, without anchoring it to a set of "DTO" Java objects. For example, you may have an extreme amount of data, and you want to process it as fast as possible, and in streaming mode. The JSON specification has great primitives which are universally useful in many languages. In Java that is boolean, null, long [or BigInteger], and double [or BigDecimal], and String.

When JsonValue is returned (option #4 above), your root value will be a JsonObject instance (Map). In the future, you may also recceive any of the following:

JSON object {...}
JSON array [...]
JSON primitive (boolean, null, long, double, String).

JsonObject implements the JsonValue interface and represents any JSON object {...}. It also implements the Map interface to make it easy to put/get values to/from it.

JsonArray implements JsonValue and represents an array [...] and also implements List interface, making it easy to set/get values to/from it.

JsonPrimitive implements JsonValue and represents one of the 5 JSON primitive value types.

Author:

John DeRegnaucourt ([email protected]), Kenny Partlow ([email protected])
Copyright (c) Cedar Software LLC

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

License

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.*

Constructor Summary

Constructors

Constructor and Description
JsonIo()

Method Summary

Modifier and Type	Method and Description
static <T> T	deepCopy(Object source, ReadOptions readOptions, WriteOptions writeOptions) Copy an object graph using JSON.
static String	formatJson(String json) Format the passed in JSON into multi-line, indented format, commonly used in JSON online editors.
static String	formatJson(String json, ReadOptions readOptions, WriteOptions writeOptions) Format the passed in JSON into multi-line, indented format, commonly used in JSON online editors.
static String	toJson(Object srcObject, WriteOptions writeOptions) Convert the passed in Java source object to JSON.
static void	toJson(OutputStream out, Object source, WriteOptions writeOptions) Convert the passed in Java source object to JSON.
static JsonObject	toJsonValues(InputStream inputStream, ReadOptions readOptions) Note that the return type will match one of these JSON types: JsonObject, JsonArray, or JsonPrimitive, all of which implement JsonValue.
static JsonObject	toJsonValues(String json, ReadOptions readOptions) Note that the return type will match one of these JSON types: JsonObject, JsonArray, or JsonPrimitive, all of which implement JsonValue.
static <T> T	toObjects(InputStream in, ReadOptions readOptions, Class<T> rootType) Convert the passed in JSON to Java Objects.
static <T> T	toObjects(String json, ReadOptions readOptions, Class<T> rootType) Convert the passed in JSON to Java Objects.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JsonIo

public JsonIo()

Method Detail

toJson

public static String toJson(Object srcObject,
                            WriteOptions writeOptions)

Convert the passed in Java source object to JSON.

Parameters:

srcObject - Java instance to convert to JSON format.

writeOptions - Feature options settings to control the JSON output. Can be null, in which case, default settings will be used.

Returns:

String of JSON that represents the srcObject in JSON format.

Throws:

JsonIoException - A runtime exception thrown if any errors happen during serialization

toJson

public static void toJson(OutputStream out,
                          Object source,
                          WriteOptions writeOptions)

Convert the passed in Java source object to JSON. If you want a copy of the JSON that was written to the OutputStream, you can wrap the output stream before calling this method, like this:

ByteArrayOutputStream baos = new ByteArrayOutputStream(originalOutputStream);
JsonIo.toJson(baos, source, writeOptions);
baos.flush();
String json = new String(baos.toByteArray(), StandardCharsets.UTF_8);


Parameters:

out - OutputStream destination for the JSON output.

source - Root Java object to begin creating the JSON.

writeOptions - Feature options settings to control the JSON output. Can be null, in which case, default settings will be used.

Throws:

JsonIoException - A runtime exception thrown if any errors happen during serialization

toObjects

public static <T> T toObjects(String json,
                              ReadOptions readOptions,
                              Class<T> rootType)

Convert the passed in JSON to Java Objects.

Parameters:

json - String containing JSON content.

readOptions - Feature options settings to control the JSON processing. Can be null, in which case, default settings will be used.

rootType - Class of the root type of object that will be returned. Can be null, in which case a best-guess will be made for the Class type of the return object. If it has an @type meta-property that will be used, otherwise the JSON types { ... } will return a Map, [...] will return Object[] or Collection, and the primtive types will be returned (String, long, Double, boolean, or null).

Returns:

rootType Java instance that represents the Java equivalent of the passed in JSON string.

Throws:

JsonIoException - A runtime exception thrown if any errors happen during serialization

toObjects

public static <T> T toObjects(InputStream in,
                              ReadOptions readOptions,
                              Class<T> rootType)

Convert the passed in JSON to Java Objects.

Parameters:

in - InputStream bringing JSON content.

readOptions - Feature options settings to control the JSON processing. Can be null, in which case, default settings will be used.

rootType - Class of the root type of object that will be returned. Can be null, in which case a best-guess will be made for the Class type of the return object. If it has an @type meta-property that will be used, otherwise the JSON types { ... } will return a Map, [...] will return Object[] or Collection, and the primtive types will be returned (String, long, double, boolean, or null).

Returns:

rootType Java instance that represents the Java equivalent of the JSON input.

Throws:

JsonIoException - A runtime exception thrown if any errors happen during serialization

toJsonValues

public static JsonObject toJsonValues(String json,
                                      ReadOptions readOptions)

Note that the return type will match one of these JSON types: JsonObject, JsonArray, or JsonPrimitive, all of which implement JsonValue.

Parameters:

json - json string

readOptions - options to use when reading. Can be null, in which case the defaults will be used.

Returns:

JsonValue graph, containing JsonObjects, JsonArrays, and/or JsonPrimitives.

toJsonValues

public static JsonObject toJsonValues(InputStream inputStream,
                                      ReadOptions readOptions)

Note that the return type will match one of these JSON types: JsonObject, JsonArray, or JsonPrimitive, all of which implement JsonValue.

Parameters:

inputStream - bytes representing UTF-8 string

readOptions - options to use when reading. Can be null, in which case the defaults will be used.

Returns:

JsonValue graph, containing JsonObjects, JsonArrays, and/or JsonPrimitives.

formatJson

public static String formatJson(String json,
                                ReadOptions readOptions,
                                WriteOptions writeOptions)

Format the passed in JSON into multi-line, indented format, commonly used in JSON online editors.

Parameters:

readOptions - ReadOptions to control the feature options. Can be null to take the defaults.

writeOptions - WriteOptions to control the feature options. Can be null to take the defaults.

json - String JSON content.

Returns:

String JSON formatted in human readable, standard multi-line, indented format.

formatJson

public static String formatJson(String json)

Format the passed in JSON into multi-line, indented format, commonly used in JSON online editors.

Parameters:

json - String JSON content.

Returns:

String JSON formatted in human readable, standard multi-line, indented format.

deepCopy

public static <T> T deepCopy(Object source,
                             ReadOptions readOptions,
                             WriteOptions writeOptions)

Copy an object graph using JSON.

Parameters:

source - Object root object to copy

readOptions - ReadOptions feature settings. Can be null for default ReadOptions.

writeOptions - WriteOptions feature settings. Can be null for default WriteOptions.

Returns:

A new, duplicate instance of the original.