Class JsonEscape


  • public final class JsonEscape
    extends Object

    Utility class for performing JSON escape/unescape operations.

    Configuration of escape/unescape operations

    Escape operations can be (optionally) configured by means of:

    • Level, which defines how deep the escape operation must be (what chars are to be considered eligible for escaping, depending on the specific needs of the scenario). Its values are defined by the JsonEscapeLevel enum.
    • Type, which defines whether escaping should be performed by means of SECs (Single Escape Characters like \n) or additionally by means of u-based hexadecimal references (\u00E1). Its values are defined by the JsonEscapeType enum.

    Unescape operations need no configuration parameters. Unescape operations will always perform complete unescape of SECs (\n) and u-based (\u00E1) hexadecimal escapes.

    Features

    Specific features of the JSON escape/unescape operations performed by means of this class:

    • The JSON basic escape set is supported. This basic set consists of:
      • The Single Escape Characters: \b (U+0008), \t (U+0009), \n (U+000A), \f (U+000C), \r (U+000D), \" (U+0022), \\ (U+005C) and \/ (U+002F). Note that \/ is optional, and will only be used when the / symbol appears after <, as in </. This is to avoid accidentally closing <script> tags in HTML.
      • Two ranges of non-displayable, control characters (some of which are already part of the single escape characters list): U+0000 to U+001F (required by the JSON spec) and U+007F to U+009F (additional).
    • U-based hexadecimal escapes (a.k.a. unicode escapes) are supported both in escape and unescape operations: \u00E1.
    • Support for the whole Unicode character set: \u0000 to \u10FFFF, including characters not representable by only one char in Java (>\uFFFF).
    Input/Output

    There are four different input/output modes that can be used in escape/unescape operations:

    • String input, String output: Input is specified as a String object and output is returned as another. In order to improve memory performance, all escape and unescape operations will return the exact same input object as output if no escape/unescape modifications are required.
    • String input, java.io.Writer output: Input will be read from a String and output will be written into the specified java.io.Writer.
    • java.io.Reader input, java.io.Writer output: Input will be read from a Reader and output will be written into the specified java.io.Writer.
    • char[] input, java.io.Writer output: Input will be read from a char array (char[]) and output will be written into the specified java.io.Writer. Two int arguments called offset and len will be used for specifying the part of the char[] that should be escaped/unescaped. These methods should be called with offset = 0 and len = text.length in order to process the whole char[].
    Glossary
    SEC
    Single Escape Character: \b (U+0008), \t (U+0009), \n (U+000A), \f (U+000C), \r (U+000D), \" (U+0022), \\ (U+005C) and \/ (U+002F) (optional, only in </).
    UHEXA escapes
    Also called u-based hexadecimal escapes or simply unicode escapes: complete representation of unicode codepoints up to U+FFFF, with \u followed by exactly four hexadecimal figures: \u00E1. Unicode codepoints > U+FFFF can be represented in JSON by mean of two UHEXA escapes (a surrogate pair).
    Unicode Codepoint
    Each of the int values conforming the Unicode code space. Normally corresponding to a Java char primitive value (codepoint <= \uFFFF), but might be two chars for codepoints \u10000 to \u10FFFF if the first char is a high surrogate (\uD800 to \uDBFF) and the second is a low surrogate (\uDC00 to \uDFFF).
    References

    The following references apply:

    Since:
    1.0.0
    Author:
    Daniel Fernández
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static void escapeJson​(char[] text, int offset, int len, java.io.Writer writer)
      Perform a JSON level 2 (basic set and all non-ASCII chars) escape operation on a char[] input.
      static void escapeJson​(char[] text, int offset, int len, java.io.Writer writer, JsonEscapeType type, JsonEscapeLevel level)
      Perform a (configurable) JSON escape operation on a char[] input.
      static void escapeJson​(java.io.Reader reader, java.io.Writer writer)
      Perform a JSON level 2 (basic set and all non-ASCII chars) escape operation on a Reader input, writing results to a Writer.
      static void escapeJson​(java.io.Reader reader, java.io.Writer writer, JsonEscapeType type, JsonEscapeLevel level)
      Perform a (configurable) JSON escape operation on a Reader input, writing results to a Writer.
      static String escapeJson​(String text)
      Perform a JSON level 2 (basic set and all non-ASCII chars) escape operation on a String input.
      static void escapeJson​(String text, java.io.Writer writer)
      Perform a JSON level 2 (basic set and all non-ASCII chars) escape operation on a String input, writing results to a Writer.
      static void escapeJson​(String text, java.io.Writer writer, JsonEscapeType type, JsonEscapeLevel level)
      Perform a (configurable) JSON escape operation on a String input, writing results to a Writer.
      static String escapeJson​(String text, JsonEscapeType type, JsonEscapeLevel level)
      Perform a (configurable) JSON escape operation on a String input.
      static void escapeJsonMinimal​(char[] text, int offset, int len, java.io.Writer writer)
      Perform a JSON level 1 (only basic set) escape operation on a char[] input.
      static void escapeJsonMinimal​(java.io.Reader reader, java.io.Writer writer)
      Perform a JSON level 1 (only basic set) escape operation on a Reader input, writing results to a Writer.
      static String escapeJsonMinimal​(String text)
      Perform a JSON level 1 (only basic set) escape operation on a String input.
      static void escapeJsonMinimal​(String text, java.io.Writer writer)
      Perform a JSON level 1 (only basic set) escape operation on a String input, writing results to a Writer.
      static void unescapeJson​(char[] text, int offset, int len, java.io.Writer writer)
      Perform a JSON unescape operation on a char[] input.
      static void unescapeJson​(java.io.Reader reader, java.io.Writer writer)
      Perform a JSON unescape operation on a Reader input, writing results to a Writer.
      static String unescapeJson​(String text)
      Perform a JSON unescape operation on a String input.
      static void unescapeJson​(String text, java.io.Writer writer)
      Perform a JSON unescape operation on a String input, writing results to a Writer.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • escapeJsonMinimal

        public static String escapeJsonMinimal​(String text)

        Perform a JSON level 1 (only basic set) escape operation on a String input.

        Level 1 means this method will only escape the JSON basic escape set:

        • The Single Escape Characters: \b (U+0008), \t (U+0009), \n (U+000A), \f (U+000C), \r (U+000D), \" (U+0022), \\ (U+005C) and \/ (U+002F). Note that \/ is optional, and will only be used when the / symbol appears after <, as in </. This is to avoid accidentally closing <script> tags in HTML.
        • Two ranges of non-displayable, control characters (some of which are already part of the single escape characters list): U+0000 to U+001F (required by the JSON spec) and U+007F to U+009F (additional).

        This method calls escapeJson(String, JsonEscapeType, JsonEscapeLevel) with the following preconfigured values:

        This method is thread-safe.

        Parameters:
        text - the String to be escaped.
        Returns:
        The escaped result String. As a memory-performance improvement, will return the exact same object as the text input argument if no escaping modifications were required (and no additional String objects will be created during processing). Will return null if input is null.
      • escapeJson

        public static String escapeJson​(String text)

        Perform a JSON level 2 (basic set and all non-ASCII chars) escape operation on a String input.

        Level 2 means this method will escape:

        • The JSON basic escape set:
          • The Single Escape Characters: \b (U+0008), \t (U+0009), \n (U+000A), \f (U+000C), \r (U+000D), \" (U+0022), \\ (U+005C) and \/ (U+002F). Note that \/ is optional, and will only be used when the / symbol appears after <, as in </. This is to avoid accidentally closing <script> tags in HTML.
          • Two ranges of non-displayable, control characters (some of which are already part of the single escape characters list): U+0000 to U+001F (required by the JSON spec) and U+007F to U+009F (additional).
        • All non ASCII characters.

        This escape will be performed by using the Single Escape Chars whenever possible. For escaped characters that do not have an associated SEC, default to \uFFFF Hexadecimal Escapes.

        This method calls escapeJson(String, JsonEscapeType, JsonEscapeLevel) with the following preconfigured values:

        This method is thread-safe.

        Parameters:
        text - the String to be escaped.
        Returns:
        The escaped result String. As a memory-performance improvement, will return the exact same object as the text input argument if no escaping modifications were required (and no additional String objects will be created during processing). Will return null if input is null.
      • escapeJson

        public static String escapeJson​(String text,
                                        JsonEscapeType type,
                                        JsonEscapeLevel level)

        Perform a (configurable) JSON escape operation on a String input.

        This method will perform an escape operation according to the specified JsonEscapeType and JsonEscapeLevel argument values.

        All other String-based escapeJson*(...) methods call this one with preconfigured type and level values.

        This method is thread-safe.

        Parameters:
        text - the String to be escaped.
        type - the type of escape operation to be performed, see JsonEscapeType.
        level - the escape level to be applied, see JsonEscapeLevel.
        Returns:
        The escaped result String. As a memory-performance improvement, will return the exact same object as the text input argument if no escaping modifications were required (and no additional String objects will be created during processing). Will return null if input is null.
      • escapeJsonMinimal

        public static void escapeJsonMinimal​(String text,
                                             java.io.Writer writer)
                                      throws java.io.IOException

        Perform a JSON level 1 (only basic set) escape operation on a String input, writing results to a Writer.

        Level 1 means this method will only escape the JSON basic escape set:

        • The Single Escape Characters: \b (U+0008), \t (U+0009), \n (U+000A), \f (U+000C), \r (U+000D), \" (U+0022), \\ (U+005C) and \/ (U+002F). Note that \/ is optional, and will only be used when the / symbol appears after <, as in </. This is to avoid accidentally closing <script> tags in HTML.
        • Two ranges of non-displayable, control characters (some of which are already part of the single escape characters list): U+0000 to U+001F (required by the JSON spec) and U+007F to U+009F (additional).

        This method calls escapeJson(String, Writer, JsonEscapeType, JsonEscapeLevel) with the following preconfigured values:

        This method is thread-safe.

        Parameters:
        text - the String to be escaped.
        writer - the java.io.Writer to which the escaped result will be written. Nothing will be written at all to this writer if input is null.
        Throws:
        java.io.IOException - if an input/output exception occurs
        Since:
        1.1.2
      • escapeJson

        public static void escapeJson​(String text,
                                      java.io.Writer writer)
                               throws java.io.IOException

        Perform a JSON level 2 (basic set and all non-ASCII chars) escape operation on a String input, writing results to a Writer.

        Level 2 means this method will escape:

        • The JSON basic escape set:
          • The Single Escape Characters: \b (U+0008), \t (U+0009), \n (U+000A), \f (U+000C), \r (U+000D), \" (U+0022), \\ (U+005C) and \/ (U+002F). Note that \/ is optional, and will only be used when the / symbol appears after <, as in </. This is to avoid accidentally closing <script> tags in HTML.
          • Two ranges of non-displayable, control characters (some of which are already part of the single escape characters list): U+0000 to U+001F (required by the JSON spec) and U+007F to U+009F (additional).
        • All non ASCII characters.

        This escape will be performed by using the Single Escape Chars whenever possible. For escaped characters that do not have an associated SEC, default to \uFFFF Hexadecimal Escapes.

        This method calls escapeJson(String, Writer, JsonEscapeType, JsonEscapeLevel) with the following preconfigured values:

        This method is thread-safe.

        Parameters:
        text - the String to be escaped.
        writer - the java.io.Writer to which the escaped result will be written. Nothing will be written at all to this writer if input is null.
        Throws:
        java.io.IOException - if an input/output exception occurs
        Since:
        1.1.2
      • escapeJson

        public static void escapeJson​(String text,
                                      java.io.Writer writer,
                                      JsonEscapeType type,
                                      JsonEscapeLevel level)
                               throws java.io.IOException

        Perform a (configurable) JSON escape operation on a String input, writing results to a Writer.

        This method will perform an escape operation according to the specified JsonEscapeType and JsonEscapeLevel argument values.

        All other String/Writer-based escapeJson*(...) methods call this one with preconfigured type and level values.

        This method is thread-safe.

        Parameters:
        text - the String to be escaped.
        writer - the java.io.Writer to which the escaped result will be written. Nothing will be written at all to this writer if input is null.
        type - the type of escape operation to be performed, see JsonEscapeType.
        level - the escape level to be applied, see JsonEscapeLevel.
        Throws:
        java.io.IOException - if an input/output exception occurs
        Since:
        1.1.2
      • escapeJsonMinimal

        public static void escapeJsonMinimal​(java.io.Reader reader,
                                             java.io.Writer writer)
                                      throws java.io.IOException

        Perform a JSON level 1 (only basic set) escape operation on a Reader input, writing results to a Writer.

        Level 1 means this method will only escape the JSON basic escape set:

        • The Single Escape Characters: \b (U+0008), \t (U+0009), \n (U+000A), \f (U+000C), \r (U+000D), \" (U+0022), \\ (U+005C) and \/ (U+002F). Note that \/ is optional, and will only be used when the / symbol appears after <, as in </. This is to avoid accidentally closing <script> tags in HTML.
        • Two ranges of non-displayable, control characters (some of which are already part of the single escape characters list): U+0000 to U+001F (required by the JSON spec) and U+007F to U+009F (additional).

        This method calls escapeJson(Reader, Writer, JsonEscapeType, JsonEscapeLevel) with the following preconfigured values:

        This method is thread-safe.

        Parameters:
        reader - the Reader reading the text to be escaped.
        writer - the java.io.Writer to which the escaped result will be written. Nothing will be written at all to this writer if input is null.
        Throws:
        java.io.IOException - if an input/output exception occurs
        Since:
        1.1.2
      • escapeJson

        public static void escapeJson​(java.io.Reader reader,
                                      java.io.Writer writer)
                               throws java.io.IOException

        Perform a JSON level 2 (basic set and all non-ASCII chars) escape operation on a Reader input, writing results to a Writer.

        Level 2 means this method will escape:

        • The JSON basic escape set:
          • The Single Escape Characters: \b (U+0008), \t (U+0009), \n (U+000A), \f (U+000C), \r (U+000D), \" (U+0022), \\ (U+005C) and \/ (U+002F). Note that \/ is optional, and will only be used when the / symbol appears after <, as in </. This is to avoid accidentally closing <script> tags in HTML.
          • Two ranges of non-displayable, control characters (some of which are already part of the single escape characters list): U+0000 to U+001F (required by the JSON spec) and U+007F to U+009F (additional).
        • All non ASCII characters.

        This escape will be performed by using the Single Escape Chars whenever possible. For escaped characters that do not have an associated SEC, default to \uFFFF Hexadecimal Escapes.

        This method calls escapeJson(Reader, Writer, JsonEscapeType, JsonEscapeLevel) with the following preconfigured values:

        This method is thread-safe.

        Parameters:
        reader - the Reader reading the text to be escaped.
        writer - the java.io.Writer to which the escaped result will be written. Nothing will be written at all to this writer if input is null.
        Throws:
        java.io.IOException - if an input/output exception occurs
        Since:
        1.1.2
      • escapeJson

        public static void escapeJson​(java.io.Reader reader,
                                      java.io.Writer writer,
                                      JsonEscapeType type,
                                      JsonEscapeLevel level)
                               throws java.io.IOException

        Perform a (configurable) JSON escape operation on a Reader input, writing results to a Writer.

        This method will perform an escape operation according to the specified JsonEscapeType and JsonEscapeLevel argument values.

        All other Reader/Writer-based escapeJson*(...) methods call this one with preconfigured type and level values.

        This method is thread-safe.

        Parameters:
        reader - the Reader reading the text to be escaped.
        writer - the java.io.Writer to which the escaped result will be written. Nothing will be written at all to this writer if input is null.
        type - the type of escape operation to be performed, see JsonEscapeType.
        level - the escape level to be applied, see JsonEscapeLevel.
        Throws:
        java.io.IOException - if an input/output exception occurs
        Since:
        1.1.2
      • escapeJsonMinimal

        public static void escapeJsonMinimal​(char[] text,
                                             int offset,
                                             int len,
                                             java.io.Writer writer)
                                      throws java.io.IOException

        Perform a JSON level 1 (only basic set) escape operation on a char[] input.

        Level 1 means this method will only escape the JSON basic escape set:

        • The Single Escape Characters: \b (U+0008), \t (U+0009), \n (U+000A), \f (U+000C), \r (U+000D), \" (U+0022), \\ (U+005C) and \/ (U+002F). Note that \/ is optional, and will only be used when the / symbol appears after <, as in </. This is to avoid accidentally closing <script> tags in HTML.
        • Two ranges of non-displayable, control characters (some of which are already part of the single escape characters list): U+0000 to U+001F (required by the JSON spec) and U+007F to U+009F (additional).

        This method calls escapeJson(char[], int, int, java.io.Writer, JsonEscapeType, JsonEscapeLevel) with the following preconfigured values:

        This method is thread-safe.

        Parameters:
        text - the char[] to be escaped.
        offset - the position in text at which the escape operation should start.
        len - the number of characters in text that should be escaped.
        writer - the java.io.Writer to which the escaped result will be written. Nothing will be written at all to this writer if input is null.
        Throws:
        java.io.IOException - if an input/output exception occurs
      • escapeJson

        public static void escapeJson​(char[] text,
                                      int offset,
                                      int len,
                                      java.io.Writer writer)
                               throws java.io.IOException

        Perform a JSON level 2 (basic set and all non-ASCII chars) escape operation on a char[] input.

        Level 2 means this method will escape:

        • The JSON basic escape set:
          • The Single Escape Characters: \b (U+0008), \t (U+0009), \n (U+000A), \f (U+000C), \r (U+000D), \" (U+0022), \\ (U+005C) and \/ (U+002F). Note that \/ is optional, and will only be used when the / symbol appears after <, as in </. This is to avoid accidentally closing <script> tags in HTML.
          • Two ranges of non-displayable, control characters (some of which are already part of the single escape characters list): U+0000 to U+001F (required by the JSON spec) and U+007F to U+009F (additional).
        • All non ASCII characters.

        This escape will be performed by using the Single Escape Chars whenever possible. For escaped characters that do not have an associated SEC, default to \uFFFF Hexadecimal Escapes.

        This method calls escapeJson(char[], int, int, java.io.Writer, JsonEscapeType, JsonEscapeLevel) with the following preconfigured values:

        This method is thread-safe.

        Parameters:
        text - the char[] to be escaped.
        offset - the position in text at which the escape operation should start.
        len - the number of characters in text that should be escaped.
        writer - the java.io.Writer to which the escaped result will be written. Nothing will be written at all to this writer if input is null.
        Throws:
        java.io.IOException - if an input/output exception occurs
      • escapeJson

        public static void escapeJson​(char[] text,
                                      int offset,
                                      int len,
                                      java.io.Writer writer,
                                      JsonEscapeType type,
                                      JsonEscapeLevel level)
                               throws java.io.IOException

        Perform a (configurable) JSON escape operation on a char[] input.

        This method will perform an escape operation according to the specified JsonEscapeType and JsonEscapeLevel argument values.

        All other char[]-based escapeJson*(...) methods call this one with preconfigured type and level values.

        This method is thread-safe.

        Parameters:
        text - the char[] to be escaped.
        offset - the position in text at which the escape operation should start.
        len - the number of characters in text that should be escaped.
        writer - the java.io.Writer to which the escaped result will be written. Nothing will be written at all to this writer if input is null.
        type - the type of escape operation to be performed, see JsonEscapeType.
        level - the escape level to be applied, see JsonEscapeLevel.
        Throws:
        java.io.IOException - if an input/output exception occurs
      • unescapeJson

        public static String unescapeJson​(String text)

        Perform a JSON unescape operation on a String input.

        No additional configuration arguments are required. Unescape operations will always perform complete JSON unescape of SECs and u-based escapes.

        This method is thread-safe.

        Parameters:
        text - the String to be unescaped.
        Returns:
        The unescaped result String. As a memory-performance improvement, will return the exact same object as the text input argument if no unescaping modifications were required (and no additional String objects will be created during processing). Will return null if input is null.
      • unescapeJson

        public static void unescapeJson​(String text,
                                        java.io.Writer writer)
                                 throws java.io.IOException

        Perform a JSON unescape operation on a String input, writing results to a Writer.

        No additional configuration arguments are required. Unescape operations will always perform complete JSON unescape of SECs and u-based escapes.

        This method is thread-safe.

        Parameters:
        text - the String to be unescaped.
        writer - the java.io.Writer to which the unescaped result will be written. Nothing will be written at all to this writer if input is null.
        Throws:
        java.io.IOException - if an input/output exception occurs
        Since:
        1.1.2
      • unescapeJson

        public static void unescapeJson​(java.io.Reader reader,
                                        java.io.Writer writer)
                                 throws java.io.IOException

        Perform a JSON unescape operation on a Reader input, writing results to a Writer.

        No additional configuration arguments are required. Unescape operations will always perform complete JSON unescape of SECs and u-based escapes.

        This method is thread-safe.

        Parameters:
        reader - the Reader reading the text to be unescaped.
        writer - the java.io.Writer to which the unescaped result will be written. Nothing will be written at all to this writer if input is null.
        Throws:
        java.io.IOException - if an input/output exception occurs
        Since:
        1.1.2
      • unescapeJson

        public static void unescapeJson​(char[] text,
                                        int offset,
                                        int len,
                                        java.io.Writer writer)
                                 throws java.io.IOException

        Perform a JSON unescape operation on a char[] input.

        No additional configuration arguments are required. Unescape operations will always perform complete JSON unescape of SECs and u-based escapes.

        This method is thread-safe.

        Parameters:
        text - the char[] to be unescaped.
        offset - the position in text at which the unescape operation should start.
        len - the number of characters in text that should be unescaped.
        writer - the java.io.Writer to which the unescaped result will be written. Nothing will be written at all to this writer if input is null.
        Throws:
        java.io.IOException - if an input/output exception occurs