Class Jsoner


  • public class Jsoner
    extends java.lang.Object
    Jsoner provides JSON utilities for escaping strings to be JSON compatible, thread safe parsing (RFC 7159) JSON strings, and thread safe serializing data to strings in JSON format.
    Since:
    2.0.0
    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static java.lang.Object deserialize​(java.io.Reader readableDeserializable)
      Deserializes a readable stream according to the RFC 7159 JSON specification.
      static java.lang.Object deserialize​(java.lang.String deserializable)
      A convenience method that assumes a StringReader to deserialize a string.
      static JsonArray deserialize​(java.lang.String deserializable, JsonArray defaultValue)
      A convenience method that assumes a JsonArray must be deserialized.
      static JsonObject deserialize​(java.lang.String deserializable, JsonObject defaultValue)
      A convenience method that assumes a JsonObject must be deserialized.
      static JsonArray deserializeMany​(java.io.Reader deserializable)
      A convenience method that assumes multiple RFC 7159 JSON values (except numbers) have been concatenated together for deserilization which will be collectively returned in a JsonArray wrapper.
      static java.lang.String escape​(java.lang.String escapable)
      Escapes potentially confusing or important characters in the String provided.
      static JsonKey mintJsonKey​(java.lang.String key, java.lang.Object value)
      Creates a new JsonKey that wraps the given string and value.
      static void prettyPrint​(java.io.Reader readable, java.io.Writer writable, java.lang.String indentation, java.lang.String newline)
      Makes the JSON input more easily human readable using indentation and newline of the caller's choice.
      static java.lang.String prettyPrint​(java.lang.String printable)
      A convenience method to pretty print a String with tabs ("\t") and "\n" for newlines.
      static java.lang.String prettyPrint​(java.lang.String printable, int spaces)
      Deprecated.
      3.1.0 in favor of Jsoner#prettyPrint(Reader, Writer, String, String) due to arbitrary limitations enforced by this implementation.
      static java.lang.String serialize​(java.lang.Object jsonSerializable)
      A convenience method that assumes a StringWriter.
      static void serialize​(java.lang.Object jsonSerializable, java.io.Writer writableDestination)
      Serializes values according to the RFC 7159 JSON specification.
      static void serializeCarelessly​(java.lang.Object jsonSerializable, java.io.Writer writableDestination)
      Serializes like the first version of this library.
      static void serializeStrictly​(java.lang.Object jsonSerializable, java.io.Writer writableDestination)
      Serializes JSON values and only JSON values according to the RFC 7159 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 java.lang.Object deserialize​(java.io.Reader readableDeserializable)
                                            throws JsonException
        Deserializes a readable stream according to the RFC 7159 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 java.lang.Object deserialize​(java.lang.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​(java.lang.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​(java.lang.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​(java.io.Reader deserializable)
                                         throws JsonException
        A convenience method that assumes multiple RFC 7159 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 java.lang.String escape​(java.lang.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​(java.lang.String key,
                                          java.lang.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 void prettyPrint​(java.io.Reader readable,
                                       java.io.Writer writable,
                                       java.lang.String indentation,
                                       java.lang.String newline)
                                throws java.io.IOException,
                                       JsonException
        Makes the JSON input more easily human readable using indentation and newline of the caller's choice. This means the validity of the JSON printed by this method is dependent on the caller's choice of indentation and newlines.
        Parameters:
        readable - representing a JSON formatted string with out extraneous characters, like one returned from Jsoner#serialize(Object).
        writable - represents where the pretty printed JSON should be written to.
        indentation - representing the indentation used to format the JSON string. NOT validated as a proper indentation. It is recommended to use tabs ("\t"), but 3, 4, or 8 spaces are common alternatives.
        newline - representing the newline used to format the JSON string. NOT validated as a proper newline. It is recommended to use "\n", but "\r" or "/r/n" are common alternatives.
        Throws:
        java.io.IOException - if the provided writer encounters an IO issue.
        JsonException - if the provided reader encounters an IO issue.
        Since:
        3.1.0 made public to allow large JSON inputs and more pretty print control.
        See Also:
        prettyPrint(String)
      • prettyPrint

        public static java.lang.String prettyPrint​(java.lang.String printable)
        A convenience method to pretty print a String with tabs ("\t") and "\n" for newlines.
        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

        @Deprecated
        public static java.lang.String prettyPrint​(java.lang.String printable,
                                                   int spaces)
        Deprecated.
        3.1.0 in favor of Jsoner#prettyPrint(Reader, Writer, String, String) due to arbitrary limitations enforced by this implementation.
        A convenience method to pretty print a String with the provided spaces count and "\n" for newlines.
        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:
        java.lang.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 java.lang.String serialize​(java.lang.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:
        java.lang.IllegalArgumentException - if the jsonSerializable isn't serializable in JSON.
        See Also:
        serialize(Object, Writer), StringWriter
      • serialize

        public static void serialize​(java.lang.Object jsonSerializable,
                                     java.io.Writer writableDestination)
                              throws java.io.IOException
        Serializes values according to the RFC 7159 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:
        java.io.IOException - if the writableDestination encounters an I/O problem, like being closed while in use.
        java.lang.IllegalArgumentException - if the jsonSerializable isn't serializable in JSON.
      • serializeCarelessly

        public static void serializeCarelessly​(java.lang.Object jsonSerializable,
                                               java.io.Writer writableDestination)
                                        throws java.io.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:
        java.io.IOException - if the writableDestination encounters an I/O problem, like being closed while in use.
      • serializeStrictly

        public static void serializeStrictly​(java.lang.Object jsonSerializable,
                                             java.io.Writer writableDestination)
                                      throws java.io.IOException
        Serializes JSON values and only JSON values according to the RFC 7159 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:
        java.io.IOException - if the writableDestination encounters an I/O problem, like being closed while in use.
        java.lang.IllegalArgumentException - if the jsonSerializable isn't serializable in raw JSON.