com.cedarsoftware.io

Class JsonIo

java.lang.Object

com.cedarsoftware.io.JsonIo

public class JsonIo
extends Object

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

• 1. Input: Java root | JsonObject root Output: JSON

  String json = JsonIo.toJson(JavaObject | JsonObject root, writeOptions)

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

  JsonIo.toJson(OutputStream, JavaObject | JsonObject root, writeOptions)

• 3. Input: JSON, Output: Java objects | JsonObject

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

• 4. Input: JsonObject root, Output: Java objects

  BillingInfo billInfo = JsonIo.toObjects(JsonObject, readOptions, BillingInfo.class)

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 JsonObject is returned [option #3 or #4 above with readOptions.returnType(ReturnType.JSON_VALUES)], your root value will represent one of:
JSON object {...}
JSON array [...]
JSON primitive (boolean true/false, null, long, double, String).

{...} JsonObject implements the Map interface and represents any JSON object {...}. It will respond true to isObject(), false to isArray(), and false to isPrimitive().

[...] JsonObject implements the List interface and represents any JSON array [...]. It will respond true to isArray(), false to isObject(), and false to is isPrimitive().

Primitive JsonObject If the root of the JSON is a String, Number (Long or Double), Boolean, or null, not an object { ... } nor an array { ... }, then the value can be obtained by calling .getValue() on the JsonObject. It will respond false to isObject(), false to isArray(), and true to isPrimitive().

If you have a return object graph of JsonObject and want to turn these into Java (DTO) objects, use #4. To turn the JsonObject graph back into JSON, use option #1 or #2.

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.*

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 void	main(String[] args) Call this method to see all the conversions offered.
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 <T> T	toObjects(InputStream in, ReadOptions readOptions, Class<T> rootType) Convert the passed in JSON to Java Objects.
static <T> T	toObjects(JsonObject jsonObject, ReadOptions readOptions, Class<T> rootType) Convert a root JsonObject that represents parsed JSON, into an actual Java object.
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

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. Can be a JsonObject that was loaded earlier via .toObjects() with readOptions.returnAsNativeJsonObjects().

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. The OutputStream will be closed by default. If you don't want this, set writeOptions.closeStream(false). This is useful for creating NDJSON, where multiple JSON objects are written to the stream, separated by a newline.

source - Java instance to convert to JSON format. Can be a JsonObject that was loaded earlier via .toObjects() with readOptions.returnAsNativeJsonObjects().

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. By default, it will be closed. If you don't want it closed after reading, set readOptions.closeStream(false).

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 a @type meta-property that will be used, otherwise a JsonObject will be returned.

Returns:

rootType Java instance that represents the Java equivalent of the JSON input. If the returnType() on ReadOptions is set to ReturnType.JSON_OBJECTS, then the root return value will be a JsonObject, which can represent a JSON object {...}, a JSON array [...], or a JSON primitive. JsonObject has .is*() methods on it to determine the type of object represented. If the type is a JSON primitive, use .getValue() on JSON object to obtain the primitive value.

Throws:

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

toObjects

public static <T> T toObjects(JsonObject jsonObject,
                              ReadOptions readOptions,
                              Class<T> rootType)

Convert a root JsonObject that represents parsed JSON, into an actual Java object.

Parameters:

rootType - The class that represents, in Java, the root of the underlying JSON from which the JsonObject was loaded.

Returns:

a typed Java instance object graph.

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.

main

public static void main(String[] args)

Call this method to see all the conversions offered.

Parameters:

args -