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 (Map) 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 {...}.

[...] JsonObject implements the Map interface and the value associated to the @items key will represent the JSON array [...].

Primitive or JsonObject If the root of the JSON is a String, Number (Long or Double), Boolean, or null, not an object { ... } nor an array { ... }, then it will be a String, long, true, false, null, double or BigDecimal. If the primitive value is wrapped in a JSON object {"value": 10} then it will be returned as a Map (JsonObject).

If you have a return object graph of JsonObject (Map-of-Maps) 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.*

Field Summary

Fields

Modifier and Type	Field and Description
static String	CLASSLOADER If set, use the specified ClassLoader
static String	CUSTOM_READER_MAP If set, this maps class ==> CustomReader
static String	CUSTOM_WRITER_MAP If set, this maps class ==> CustomWriter
static String	DATE_FORMAT Set the date format to use within the JSON output
static String	ENUM_PUBLIC_ONLY If set, indicates that private variables of ENUMs are not to be serialized
static String	FAIL_ON_UNKNOWN_TYPE Will fail JSON parsing if 'type' class defined but is not on classpath.
static String	FIELD_NAME_BLACK_LIST Set value to a Map<Class, List<String>> which will be used to control which fields on a class are not output.
static String	FIELD_SPECIFIERS Set value to a Map<Class, List<String>> which will be used to control which fields on a class are output
static String	FORCE_MAP_FORMAT_ARRAY_KEYS_ITEMS If set to true all maps are transferred to the format @keys[],@items[] regardless of the key_type
static String	ISO_DATE_FORMAT Constant for use as DATE_FORMAT value
static String	ISO_DATE_TIME_FORMAT Constant for use as DATE_FORMAT value
static String	MAX_PARSE_DEPTH Default maximum parsing depth
static String	MISSING_FIELD_HANDLER If set, this object will be called when a field is present in the JSON but missing from the corresponding class
static String	NOT_CUSTOM_READER_MAP If set, this indicates that no custom reader should be used for the specified class ==> CustomReader
static String	NOT_CUSTOM_WRITER_MAP If set, this maps class ==> CustomWriter
static String	PRETTY_PRINT Force nicely formatted JSON output
static String	SHORT_META_KEYS If set, then @type -> @t, @keys -> @k, @items -> @i
static String	SKIP_NULL_FIELDS If set, null fields are not written
static String	TYPE Force @type always
static String	TYPE_NAME_MAP If set, this map will be used when writing @type values - allows short-hand abbreviations type names
static String	UNKNOWN_OBJECT What to do when an object is found and 'type' cannot be determined.
static String	USE_MAPS If set, the read-in JSON will be turned into a Map of Maps (JsonObject) representation
static String	WRITE_LONGS_AS_STRINGS If set, longs are written in quotes (Javascript safe)

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 ReadOptionsBuilder	getReadOptionsBuilder(Map<String,Object> optionalArgs) Convert an old-style Map of options to a ReadOptionsBuilder.
static WriteOptionsBuilder	getWriteOptionsBuilder(Map<String,Object> optionalArgs) Convert an old-style Map of options to a WriteOptionsBuilder.
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 (Map) 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

Field Detail

CUSTOM_READER_MAP

public static final String CUSTOM_READER_MAP

If set, this maps class ==> CustomReader

See Also:

Constant Field Values

NOT_CUSTOM_READER_MAP

public static final String NOT_CUSTOM_READER_MAP

If set, this indicates that no custom reader should be used for the specified class ==> CustomReader

See Also:

Constant Field Values

USE_MAPS

public static final String USE_MAPS

If set, the read-in JSON will be turned into a Map of Maps (JsonObject) representation

See Also:

Constant Field Values

UNKNOWN_OBJECT

public static final String UNKNOWN_OBJECT

What to do when an object is found and 'type' cannot be determined.

See Also:

Constant Field Values

FAIL_ON_UNKNOWN_TYPE

public static final String FAIL_ON_UNKNOWN_TYPE

Will fail JSON parsing if 'type' class defined but is not on classpath.

See Also:

Constant Field Values

TYPE_NAME_MAP

public static final String TYPE_NAME_MAP

If set, this map will be used when writing @type values - allows short-hand abbreviations type names

See Also:

Constant Field Values

MISSING_FIELD_HANDLER

public static final String MISSING_FIELD_HANDLER

If set, this object will be called when a field is present in the JSON but missing from the corresponding class

See Also:

Constant Field Values

CLASSLOADER

public static final String CLASSLOADER

If set, use the specified ClassLoader

See Also:

Constant Field Values

MAX_PARSE_DEPTH

public static final String MAX_PARSE_DEPTH

Default maximum parsing depth

See Also:

Constant Field Values

CUSTOM_WRITER_MAP

public static final String CUSTOM_WRITER_MAP

If set, this maps class ==> CustomWriter

See Also:

Constant Field Values

NOT_CUSTOM_WRITER_MAP

public static final String NOT_CUSTOM_WRITER_MAP

If set, this maps class ==> CustomWriter

See Also:

Constant Field Values

DATE_FORMAT

public static final String DATE_FORMAT

Set the date format to use within the JSON output

See Also:

Constant Field Values

ISO_DATE_FORMAT

public static final String ISO_DATE_FORMAT

Constant for use as DATE_FORMAT value

See Also:

Constant Field Values

ISO_DATE_TIME_FORMAT

public static final String ISO_DATE_TIME_FORMAT

Constant for use as DATE_FORMAT value

See Also:

Constant Field Values

TYPE

public static final String TYPE

Force @type always

See Also:

Constant Field Values

PRETTY_PRINT

public static final String PRETTY_PRINT

Force nicely formatted JSON output

See Also:

Constant Field Values

FIELD_SPECIFIERS

public static final String FIELD_SPECIFIERS

Set value to a Map<Class, List<String>> which will be used to control which fields on a class are output

See Also:

Constant Field Values

FIELD_NAME_BLACK_LIST

public static final String FIELD_NAME_BLACK_LIST

Set value to a Map<Class, List<String>> which will be used to control which fields on a class are not output. Black list has always priority to FIELD_SPECIFIERS

See Also:

Constant Field Values

ENUM_PUBLIC_ONLY

public static final String ENUM_PUBLIC_ONLY

If set, indicates that private variables of ENUMs are not to be serialized

See Also:

Constant Field Values

WRITE_LONGS_AS_STRINGS

public static final String WRITE_LONGS_AS_STRINGS

If set, longs are written in quotes (Javascript safe)

See Also:

Constant Field Values

SHORT_META_KEYS

public static final String SHORT_META_KEYS

If set, then @type -> @t, @keys -> @k, @items -> @i

See Also:

Constant Field Values

SKIP_NULL_FIELDS

public static final String SKIP_NULL_FIELDS

If set, null fields are not written

See Also:

Constant Field Values

FORCE_MAP_FORMAT_ARRAY_KEYS_ITEMS

public static final String FORCE_MAP_FORMAT_ARRAY_KEYS_ITEMS

If set to true all maps are transferred to the format @keys[],@items[] regardless of the key_type

See Also:

Constant Field Values

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 (Map) that represents parsed JSON, into an actual Java object. This Map-of-Map roots would have come from a prior API call to JsonIo.toObjects(String) or JsonIo.toObjects(InputStream) with the new ReadOptionBuilder().returnAsJsonObjects() option set. This option allows you to read any JSON because it is only stuffing it into Maps, not Java objects. This API can take this Map-of-Maps representation of JSON, and then recreate the Java objects from it. It can do this, because the Map-of-Map's it returns are subclasses of Java's Map that contain a 'type' field, and it will use this to recreate the correct Java object when written via toJson and the Map (JsonObject) is passed as the root.

Parameters:

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

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 -

getReadOptionsBuilder

public static ReadOptionsBuilder getReadOptionsBuilder(Map<String,Object> optionalArgs)

Convert an old-style Map of options to a ReadOptionsBuilder. It is not recommended to use this API long term, however, this API will be the fastest route to bridge an old installation using json-io to the new API.

Parameters:

optionalArgs - Map of old json-io options

Returns:

ReadOptionsBuilder

getWriteOptionsBuilder

public static WriteOptionsBuilder getWriteOptionsBuilder(Map<String,Object> optionalArgs)

Convert an old-style Map of options to a WriteOptionsBuilder. It is not recommended to use this API long term, however, this API will be the fastest route to bridge an old installation using json-io to the new API.

Parameters:

optionalArgs - Map of old json-io options

Returns:

WriteOptionsBuilder