com.github.cliftonlabs.json_simple

Class Jsoner

java.lang.Object

com.github.cliftonlabs.json_simple.Jsoner

public class Jsoner
extends Object

Jsoner provides JSON utilities for escaping strings to be JSON compatible, thread safe parsing (RFC 4627) JSON strings, and thread safe serializing data to strings in JSON format.

Since:

2.0.0

Method Summary

Modifier and Type	Method and Description
static Object	deserialize(Reader readableDeserializable) Deserializes a readable stream according to the RFC 4627 JSON specification.
static Object	deserialize(String deserializable) A convenience method that assumes a StringReader to deserialize a string.
static JsonArray	deserialize(String deserializable, JsonArray defaultValue) A convenience method that assumes a JsonArray must be deserialized.
static JsonObject	deserialize(String deserializable, JsonObject defaultValue) A convenience method that assumes a JsonObject must be deserialized.
static JsonArray	deserializeMany(Reader deserializable) A convenience method that assumes multiple RFC 4627 JSON values (except numbers) have been concatenated together for deserilization which will be collectively returned in a JsonArray wrapper.
static String	escape(String escapable) Escapes potentially confusing or important characters in the String provided.
static JsonKey	mintJsonKey(String key, Object value) Creates a new JsonKey that wraps the given string and value.
static String	prettyPrint(String printable) Formats the JSON string to be more easily human readable using tabs for indentation.
static String	prettyPrint(String printable, int spaces) Formats the JSON string to be more easily human readable using an arbitrary amount of spaces for indentation.
static String	serialize(Object jsonSerializable) A convenience method that assumes a StringWriter.
static void	serialize(Object jsonSerializable, Writer writableDestination) Serializes values according to the RFC 4627 JSON specification.
static void	serializeCarelessly(Object jsonSerializable, Writer writableDestination) Serializes like the first version of this library.
static void	serializeStrictly(Object jsonSerializable, Writer writableDestination) Serializes JSON values and only JSON values according to the RFC 4627 JSON specification.

Methods inherited from class java.lang.Object

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

Method Detail

deserialize

public static Object deserialize(Reader readableDeserializable)
                          throws JsonException

Deserializes a readable stream according to the RFC 4627 JSON specification.

Parameters:

readableDeserializable - representing content to be deserialized as JSON.

Returns:

either a boolean, null, Number, String, JsonObject, or JsonArray that best represents the deserializable.

Throws:

JsonException - if an unexpected token is encountered in the deserializable. To recover from a JsonException: fix the deserializable to no longer have an unexpected token and try again.

deserialize

public static Object deserialize(String deserializable)
                          throws JsonException

A convenience method that assumes a StringReader to deserialize a string.

Parameters:

deserializable - representing content to be deserialized as JSON.

Returns:

either a boolean, null, Number, String, JsonObject, or JsonArray that best represents the deserializable.

Throws:

JsonException - if an unexpected token is encountered in the deserializable. To recover from a JsonException: fix the deserializable to no longer have an unexpected token and try again.

See Also:

deserialize(Reader), StringReader

deserialize

public static JsonArray deserialize(String deserializable,
                                    JsonArray defaultValue)

A convenience method that assumes a JsonArray must be deserialized.

Parameters:

deserializable - representing content to be deserializable as a JsonArray.

defaultValue - representing what would be returned if deserializable isn't a JsonArray or an IOException, NullPointerException, or JsonException occurs during deserialization.

Returns:

a JsonArray that represents the deserializable, or the defaultValue if there isn't a JsonArray that represents deserializable.

See Also:

deserialize(Reader)

deserialize

public static JsonObject deserialize(String deserializable,
                                     JsonObject defaultValue)

A convenience method that assumes a JsonObject must be deserialized.

Parameters:

deserializable - representing content to be deserializable as a JsonObject.

defaultValue - representing what would be returned if deserializable isn't a JsonObject or an IOException, NullPointerException, or JsonException occurs during deserialization.

Returns:

a JsonObject that represents the deserializable, or the defaultValue if there isn't a JsonObject that represents deserializable.

See Also:

deserialize(Reader)

deserializeMany

public static JsonArray deserializeMany(Reader deserializable)
                                 throws JsonException

A convenience method that assumes multiple RFC 4627 JSON values (except numbers) have been concatenated together for deserilization which will be collectively returned in a JsonArray wrapper. There may be numbers included, they just must not be concatenated together as it is prone to NumberFormatExceptions (thus causing a JsonException) or the numbers no longer represent their respective values. Examples: "123null321" returns [123, null, 321] "nullnullnulltruefalse\"\"{}[]" returns [null, null, null, true, false, "", {}, []] "123" appended to "321" returns [123321] "12.3" appended to "3.21" throws JsonException(NumberFormatException) "123" appended to "-321" throws JsonException(NumberFormatException) "123e321" appended to "-1" throws JsonException(NumberFormatException) "null12.33.21null" throws JsonException(NumberFormatException)

Parameters:

deserializable - representing concatenated content to be deserialized as JSON in one reader. Its contents may not contain two numbers concatenated together.

Returns:

a JsonArray that contains each of the concatenated objects as its elements. Each concatenated element is either a boolean, null, Number, String, JsonArray, or JsonObject that best represents the concatenated content inside deserializable.

Throws:

JsonException - if an unexpected token is encountered in the deserializable. To recover from a JsonException: fix the deserializable to no longer have an unexpected token and try again.

escape

public static String escape(String escapable)

Escapes potentially confusing or important characters in the String provided.

Parameters:

escapable - an unescaped string.

Returns:

an escaped string for usage in JSON; An escaped string is one that has escaped all of the quotes ("), backslashes (\), return character (\r), new line character (\n), tab character (\t), backspace character (\b), form feed character (\f) and other control characters [u0000..u001F] or characters [u007F..u009F], [u2000..u20FF] with a backslash (\) which itself must be escaped by the backslash in a java string.

mintJsonKey

public static JsonKey mintJsonKey(String key,
                                  Object value)

Creates a new JsonKey that wraps the given string and value. This function should NOT be used in favor of existing constants and enumerations to make code easier to maintain.

Parameters:

key - represents the JsonKey as a String.

value - represents the value the JsonKey uses.

Returns:

a JsonKey that represents the provided key and value.

prettyPrint

public static String prettyPrint(String printable)

Formats the JSON string to be more easily human readable using tabs for indentation.

Parameters:

printable - representing a JSON formatted string with out extraneous characters, like one returned from Jsoner#serialize(Object).

Returns:

printable except it will have '\n' then '\t' characters inserted after '[', '{', ',' and before ']' '}' tokens in the JSON. It will return null if printable isn't a JSON string.

prettyPrint

public static String prettyPrint(String printable,
                                 int spaces)

Formats the JSON string to be more easily human readable using an arbitrary amount of spaces for indentation.

Parameters:

printable - representing a JSON formatted string with out extraneous characters, like one returned from Jsoner#serialize(Object).

spaces - representing the amount of spaces to use for indentation. Must be between 2 and 10.

Returns:

printable except it will have '\n' then space characters inserted after '[', '{', ',' and before ']' '}' tokens in the JSON. It will return null if printable isn't a JSON string.

Throws:

IllegalArgumentException - if spaces isn't between [2..10].

Since:

2.2.0 to allow pretty printing with spaces instead of tabs.

See Also:

prettyPrint(String)

serialize

public static String serialize(Object jsonSerializable)

A convenience method that assumes a StringWriter.

Parameters:

jsonSerializable - represents the object that should be serialized as a string in JSON format.

Returns:

a string, in JSON format, that represents the object provided.

Throws:

IllegalArgumentException - if the jsonSerializable isn't serializable in JSON.

See Also:

serialize(Object, Writer), StringWriter

serialize

public static void serialize(Object jsonSerializable,
                             Writer writableDestination)
                      throws IOException

Serializes values according to the RFC 4627 JSON specification. It will also trust the serialization provided by any Jsonables it serializes.

Parameters:

jsonSerializable - represents the object that should be serialized in JSON format.

writableDestination - represents where the resulting JSON text is written to.

Throws:

IOException - if the writableDestination encounters an I/O problem, like being closed while in use.

IllegalArgumentException - if the jsonSerializable isn't serializable in JSON.

serializeCarelessly

public static void serializeCarelessly(Object jsonSerializable,
                                       Writer writableDestination)
                                throws IOException

Serializes like the first version of this library. It has been adapted to use Jsonable for serializing custom objects, but otherwise works like the old JSON string serializer. It will allow non-JSON values in its output like the old one. It can be helpful for last resort log statements and debugging errors in self generated JSON. Anything serialized using this method isn't guaranteed to be deserializable.

Parameters:

jsonSerializable - represents the object that should be serialized in JSON format.

writableDestination - represents where the resulting JSON text is written to.

Throws:

IOException - if the writableDestination encounters an I/O problem, like being closed while in use.

serializeStrictly

public static void serializeStrictly(Object jsonSerializable,
                                     Writer writableDestination)
                              throws IOException

Serializes JSON values and only JSON values according to the RFC 4627 JSON specification.

Parameters:

jsonSerializable - represents the object that should be serialized in JSON format.

writableDestination - represents where the resulting JSON text is written to.

Throws:

IOException - if the writableDestination encounters an I/O problem, like being closed while in use.

IllegalArgumentException - if the jsonSerializable isn't serializable in raw JSON.