net.opentsdb.utils

Class JSON

java.lang.Object

net.opentsdb.utils.JSON

public final class JSON
extends Object

This class simply provides a static initialization and configuration of the Jackson ObjectMapper for use throughout OpenTSDB. Since the mapper takes a fair amount of construction and is thread safe, the Jackson docs recommend initializing it once per app.

The class also provides some simple wrappers around commonly used serialization and deserialization methods for POJOs as well as a JSONP wrapper. These work wonderfully for smaller objects and you can use JAVA annotations to control the de/serialization for your POJO class.

For streaming of large objects, access the mapper directly via getMapper() or getFactory()

Unfortunately since Jackson provides typed exceptions, most of these methods will pass them along so you'll have to handle them where you are making a call.

Troubleshooting POJO de/serialization:

If you get mapping errors, check some of these

• The class must provide a constructor without parameters
• Make sure fields are accessible via getters/setters or by the @JsonAutoDetect annotation
• Make sure any child objects are accessible, have the empty constructor and applicable annotations

Useful Class Annotations: @JsonAutoDetect(fieldVisibility = Visibility.ANY) - will serialize any, public or private values

@JsonSerialize(include = JsonSerialize.Inclusion.NON_NULL) - will automatically ignore any fields set to NULL, otherwise they are serialized with a literal null value

Useful Method Annotations: @JsonIgnore - Ignores the method for de/serialization purposes. CRITICAL for any methods that could cause a de/serialization infinite loop

Since:

2.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	JSON.SearchTypeDeserializer Helper class for deserializing Search type enum from human readable strings
static class	JSON.TreeRuleTypeDeserializer Helper class for deserializing Tree Rule type enum from human readable strings
static class	JSON.UniqueIdTypeDeserializer Helper class for deserializing UID type enum from human readable strings

Constructor Summary

Constructors

Constructor and Description
JSON()

Method Summary

Methods

Modifier and Type	Method and Description
static com.fasterxml.jackson.core.JsonFactory	getFactory() Returns a reference to the JsonFactory for streaming creation
static com.fasterxml.jackson.databind.ObjectMapper	getMapper() Returns a reference to the static ObjectMapper
static <T> T	parseToObject(byte[] json, Class<T> pojo) Deserializes a JSON formatted byte array to a specific class type Note: If you get mapping exceptions you may need to provide a TypeReference
static <T> T	parseToObject(byte[] json, com.fasterxml.jackson.core.type.TypeReference<T> type) Deserializes a JSON formatted byte array to a specific class type
static <T> T	parseToObject(String json, Class<T> pojo) Deserializes a JSON formatted string to a specific class type Note: If you get mapping exceptions you may need to provide a TypeReference
static <T> T	parseToObject(String json, com.fasterxml.jackson.core.type.TypeReference<T> type) Deserializes a JSON formatted string to a specific class type
static com.fasterxml.jackson.core.JsonParser	parseToStream(byte[] json) Parses a JSON formatted byte array into raw tokens for streaming or tree iteration Warning: This method can parse an invalid JSON object without throwing an error until you start processing the data
static com.fasterxml.jackson.core.JsonParser	parseToStream(InputStream json) Parses a JSON formatted inputs stream into raw tokens for streaming or tree iteration Warning: This method can parse an invalid JSON object without throwing an error until you start processing the data
static com.fasterxml.jackson.core.JsonParser	parseToStream(String json) Parses a JSON formatted string into raw tokens for streaming or tree iteration Warning: This method can parse an invalid JSON object without throwing an error until you start processing the data
static byte[]	serializeToBytes(Object object) Serializes the given object to a JSON byte array
static byte[]	serializeToJSONPBytes(String callback, Object object) Serializes the given object and wraps it in a callback function i.e.
static String	serializeToJSONPString(String callback, Object object) Serializes the given object and wraps it in a callback function i.e.
static String	serializeToString(Object object) Serializes the given object to a JSON string

Methods inherited from class java.lang.Object

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

Constructor Detail

JSON

public JSON()

Method Detail

parseToObject

public static final <T> T parseToObject(String json,
                  Class<T> pojo)

Deserializes a JSON formatted string to a specific class type Note: If you get mapping exceptions you may need to provide a TypeReference

Parameters:

json - The string to deserialize

pojo - The class type of the object used for deserialization

Returns:

An object of the pojo type

Throws:

IllegalArgumentException - if the data or class was null or parsing failed

JSONException - if the data could not be parsed

parseToObject

public static final <T> T parseToObject(byte[] json,
                  Class<T> pojo)

Deserializes a JSON formatted byte array to a specific class type Note: If you get mapping exceptions you may need to provide a TypeReference

Parameters:

json - The byte array to deserialize

pojo - The class type of the object used for deserialization

Returns:

An object of the pojo type

Throws:

IllegalArgumentException - if the data or class was null or parsing failed

JSONException - if the data could not be parsed

parseToObject

public static final <T> T parseToObject(String json,
                  com.fasterxml.jackson.core.type.TypeReference<T> type)

Deserializes a JSON formatted string to a specific class type

Parameters:

json - The string to deserialize

type - A type definition for a complex object

Returns:

An object of the pojo type

Throws:

IllegalArgumentException - if the data or type was null or parsing failed

JSONException - if the data could not be parsed

parseToObject

public static final <T> T parseToObject(byte[] json,
                  com.fasterxml.jackson.core.type.TypeReference<T> type)

Deserializes a JSON formatted byte array to a specific class type

Parameters:

json - The byte array to deserialize

type - A type definition for a complex object

Returns:

An object of the pojo type

Throws:

IllegalArgumentException - if the data or type was null or parsing failed

JSONException - if the data could not be parsed

parseToStream

public static final com.fasterxml.jackson.core.JsonParser parseToStream(String json)

Parses a JSON formatted string into raw tokens for streaming or tree iteration Warning: This method can parse an invalid JSON object without throwing an error until you start processing the data

Parameters:

json - The string to parse

Returns:

A JsonParser object to be used for iteration

Throws:

IllegalArgumentException - if the data was null or parsing failed

JSONException - if the data could not be parsed

parseToStream

public static final com.fasterxml.jackson.core.JsonParser parseToStream(byte[] json)

Parses a JSON formatted byte array into raw tokens for streaming or tree iteration Warning: This method can parse an invalid JSON object without throwing an error until you start processing the data

Parameters:

json - The byte array to parse

Returns:

A JsonParser object to be used for iteration

Throws:

IllegalArgumentException - if the data was null or parsing failed

JSONException - if the data could not be parsed

parseToStream

public static final com.fasterxml.jackson.core.JsonParser parseToStream(InputStream json)

Parses a JSON formatted inputs stream into raw tokens for streaming or tree iteration Warning: This method can parse an invalid JSON object without throwing an error until you start processing the data

Parameters:

json - The input stream to parse

Returns:

A JsonParser object to be used for iteration

Throws:

IllegalArgumentException - if the data was null or parsing failed

JSONException - if the data could not be parsed

serializeToString

public static final String serializeToString(Object object)

Serializes the given object to a JSON string

Parameters:

object - The object to serialize

Returns:

A JSON formatted string

Throws:

IllegalArgumentException - if the object was null

JSONException - if the object could not be serialized

IOException - Thrown when there was an issue reading the object

serializeToBytes

public static final byte[] serializeToBytes(Object object)

Serializes the given object to a JSON byte array

Parameters:

object - The object to serialize

Returns:

A JSON formatted byte array

Throws:

IllegalArgumentException - if the object was null

JSONException - if the object could not be serialized

IOException - Thrown when there was an issue reading the object

serializeToJSONPString

public static final String serializeToJSONPString(String callback,
                            Object object)

Serializes the given object and wraps it in a callback function i.e. <callback>(<json>) Note: This will not append a trailing semicolon

Parameters:

callback - The name of the Javascript callback to prepend

object - The object to serialize

Returns:

A JSONP formatted string

Throws:

IllegalArgumentException - if the callback method name was missing or object was null

JSONException - if the object could not be serialized

IOException - Thrown when there was an issue reading the object

serializeToJSONPBytes

public static final byte[] serializeToJSONPBytes(String callback,
                           Object object)

Serializes the given object and wraps it in a callback function i.e. <callback>(<json>) Note: This will not append a trailing semicolon

Parameters:

callback - The name of the Javascript callback to prepend

object - The object to serialize

Returns:

A JSONP formatted byte array

Throws:

IllegalArgumentException - if the callback method name was missing or object was null

JSONException - if the object could not be serialized

IOException - Thrown when there was an issue reading the object

getMapper

public static final com.fasterxml.jackson.databind.ObjectMapper getMapper()

Returns a reference to the static ObjectMapper

Returns:

The ObjectMapper

getFactory

public static final com.fasterxml.jackson.core.JsonFactory getFactory()

Returns a reference to the JsonFactory for streaming creation

Returns:

The JsonFactory object