org.json.simple

## Class Jsoner

- java.lang.Object
- - org.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 serializing data to strings in JSON format.

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    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 DeserializationException

      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:
        `DeserializationException` - if an unexpected token is encountered in the deserializable. To recover from a DeserializationException: fix the deserializable to no longer have an unexpected token and try again.

    - #### deserialize

          public static Object deserialize(String deserializable)
                                    throws DeserializationException

      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:
        `DeserializationException` - if an unexpected token is encountered in the deserializable. To recover from a DeserializationException: 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 DeserializationException 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 DeserializationException 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 DeserializationException

      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 DeserializationException) 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 DeserializationException(NumberFormatException) "123" appended to "-321" throws DeserializationException(NumberFormatException) "123e321" appended to "-1" throws DeserializationException(NumberFormatException) "null12.33.21null" throws DeserializationException(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:
        `DeserializationException` - if an unexpected token is encountered in the deserializable. To recover from a DeserializationException: 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].
      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 and serializes Enums that don't implement Jsonable as a string of their fully qualified name.
      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.