Package 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.
Since:
2.0.0

  • Method Summary

    Modifier and Type
    Method
    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 Details

    • 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

      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

      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:

    • 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].
      Since:
      2.2.0 to allow pretty printing with spaces instead of tabs.
      See Also:

    • 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

      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.