StringEscapeUtils

@Deprecated public class org.apache.commons.lang3.StringEscapeUtils

Deprecated: As of 3.6, use Apache Commons Text StringEscapeUtils instead.

Escapes and unescapes Strings for Java, Java Script, HTML and XML.

#ThreadSafe#

Since:

2.0

Constructors

StringEscapeUtils()

Deprecated. StringEscapeUtils instances should NOT be constructed in standard programming.

@Deprecated public StringEscapeUtils()

Deprecated: TODO Make private in 4.0.

StringEscapeUtils instances should NOT be constructed in standard programming.

Instead, the class should be used as:

StringEscapeUtils.escapeJava("foo");

This constructor is public to permit tools that require a JavaBean instance to operate.

Fields and constants

ESCAPE_CSV	Translator object for escaping individual Comma Separated Values.
ESCAPE_ECMASCRIPT	Translator object for escaping EcmaScript/JavaScript.
ESCAPE_HTML3	Translator object for escaping HTML version 3.0.
ESCAPE_HTML4	Translator object for escaping HTML version 4.0.
ESCAPE_JAVA	Translator object for escaping Java.
ESCAPE_JSON	Translator object for escaping Json.
ESCAPE_XML	Deprecated. Translator object for escaping XML.
ESCAPE_XML10	Translator object for escaping XML 1.0.
ESCAPE_XML11	Translator object for escaping XML 1.1.
UNESCAPE_CSV	Translator object for unescaping escaped Comma Separated Value entries.
UNESCAPE_ECMASCRIPT	Translator object for unescaping escaped EcmaScript.
UNESCAPE_HTML3	Translator object for unescaping escaped HTML 3.0.
UNESCAPE_HTML4	Translator object for unescaping escaped HTML 4.0.
UNESCAPE_JAVA	Translator object for unescaping escaped Java.
UNESCAPE_JSON	Translator object for unescaping escaped Json.
UNESCAPE_XML	Translator object for unescaping escaped XML.

public static final CharSequenceTranslator ESCAPE_CSV

Translator object for escaping individual Comma Separated Values. While #escapeCsv(String) is the expected method of use, this object allows the CSV escaping functionality to be used as the foundation for a custom translator.

Since:

3.0

public static final CharSequenceTranslator ESCAPE_ECMASCRIPT

Translator object for escaping EcmaScript/JavaScript. While #escapeEcmaScript(String) is the expected method of use, this object allows the EcmaScript escaping functionality to be used as the foundation for a custom translator.

Since:

3.0

public static final CharSequenceTranslator ESCAPE_HTML3

Translator object for escaping HTML version 3.0. While #escapeHtml3(String) is the expected method of use, this object allows the HTML escaping functionality to be used as the foundation for a custom translator.

Since:

3.0

public static final CharSequenceTranslator ESCAPE_HTML4

Translator object for escaping HTML version 4.0. While #escapeHtml4(String) is the expected method of use, this object allows the HTML escaping functionality to be used as the foundation for a custom translator.

Since:

3.0

public static final CharSequenceTranslator ESCAPE_JAVA

Translator object for escaping Java. While #escapeJava(String) is the expected method of use, this object allows the Java escaping functionality to be used as the foundation for a custom translator.

Since:

3.0

public static final CharSequenceTranslator ESCAPE_JSON

Translator object for escaping Json. While #escapeJson(String) is the expected method of use, this object allows the Json escaping functionality to be used as the foundation for a custom translator.

Since:

3.2

@Deprecated public static final CharSequenceTranslator ESCAPE_XML

Deprecated: Use #ESCAPE_XML10 or #ESCAPE_XML11 instead.

Translator object for escaping XML. While #escapeXml(String) is the expected method of use, this object allows the XML escaping functionality to be used as the foundation for a custom translator.

Since:

3.0

public static final CharSequenceTranslator ESCAPE_XML10

Translator object for escaping XML 1.0. While #escapeXml10(String) is the expected method of use, this object allows the XML escaping functionality to be used as the foundation for a custom translator.

Since:

3.3

public static final CharSequenceTranslator ESCAPE_XML11

Translator object for escaping XML 1.1. While #escapeXml11(String) is the expected method of use, this object allows the XML escaping functionality to be used as the foundation for a custom translator.

Since:

3.3

public static final CharSequenceTranslator UNESCAPE_CSV

Translator object for unescaping escaped Comma Separated Value entries. While #unescapeCsv(String) is the expected method of use, this object allows the CSV unescaping functionality to be used as the foundation for a custom translator.

Since:

3.0

public static final CharSequenceTranslator UNESCAPE_ECMASCRIPT

Translator object for unescaping escaped EcmaScript. While #unescapeEcmaScript(String) is the expected method of use, this object allows the EcmaScript unescaping functionality to be used as the foundation for a custom translator.

Since:

3.0

public static final CharSequenceTranslator UNESCAPE_HTML3

Translator object for unescaping escaped HTML 3.0. While #unescapeHtml3(String) is the expected method of use, this object allows the HTML unescaping functionality to be used as the foundation for a custom translator.

Since:

3.0

public static final CharSequenceTranslator UNESCAPE_HTML4

Translator object for unescaping escaped HTML 4.0. While #unescapeHtml4(String) is the expected method of use, this object allows the HTML unescaping functionality to be used as the foundation for a custom translator.

Since:

3.0

public static final CharSequenceTranslator UNESCAPE_JAVA

Translator object for unescaping escaped Java. While #unescapeJava(String) is the expected method of use, this object allows the Java unescaping functionality to be used as the foundation for a custom translator.

Since:

3.0

public static final CharSequenceTranslator UNESCAPE_JSON

Translator object for unescaping escaped Json. While #unescapeJson(String) is the expected method of use, this object allows the Json unescaping functionality to be used as the foundation for a custom translator.

Since:

3.2

public static final CharSequenceTranslator UNESCAPE_XML

Translator object for unescaping escaped XML. While #unescapeXml(String) is the expected method of use, this object allows the XML unescaping functionality to be used as the foundation for a custom translator.

Since:

3.0

Methods

escapeCsv(String)	Returns a String value for a CSV column enclosed in double quotes, if required.
escapeEcmaScript(String)	Escapes the characters in a String using EcmaScript String rules.
escapeHtml3(String)	Escapes the characters in a String using HTML entities.
escapeHtml4(String)	Escapes the characters in a String using HTML entities.
escapeJava(String)	Escapes the characters in a String using Java String rules.
escapeJson(String)	Escapes the characters in a String using Json String rules.
escapeXml(String)	Deprecated. Escapes the characters in a String using XML entities.
escapeXml10(String)	Escapes the characters in a String using XML entities.
escapeXml11(String)	Escapes the characters in a String using XML entities.
unescapeCsv(String)	Returns a String value for an unescaped CSV column.
unescapeEcmaScript(String)	Unescapes any EcmaScript literals found in the String.
unescapeHtml3(String)	Unescapes a string containing entity escapes to a string containing the actual Unicode characters corresponding to the escapes.
unescapeHtml4(String)	Unescapes a string containing entity escapes to a string containing the actual Unicode characters corresponding to the escapes.
unescapeJava(String)	Unescapes any Java literals found in the String.
unescapeJson(String)	Unescapes any Json literals found in the String.
unescapeXml(String)	Unescapes a string containing XML entity escapes to a string containing the actual Unicode characters corresponding to the escapes.

public static final String escapeCsv(String input)

Returns a String value for a CSV column enclosed in double quotes, if required.

If the value contains a comma, newline or double quote, then the String value is returned enclosed in double quotes.

Any double quote characters in the value are escaped with another double quote.

If the value does not contain a comma, newline or double quote, then the String value is returned unchanged.

See Wikipedia and RFC 4180.

Parameters:

input – The input CSV column String, may be null

Returns:

The input String, enclosed in double quotes if the value contains a comma, newline or double quote, null if null string input

Since:

2.4

public static final String escapeEcmaScript(String input)

Escapes the characters in a String using EcmaScript String rules.

Escapes any values it finds into their EcmaScript String form. Escapes the EcmaScript string delimiters (single quote, double quote and (since ES6) the backtick) as well as the template-literal interpolation sequence ${ and control-chars (tab, backslash, cr, ff, etc.).

So a tab becomes the characters '\\' and 't'.

The differences between Java strings and EcmaScript strings handled here are that in EcmaScript, a single quote, the backtick, the ${ sequence and forward-slash (/) are escaped.

Scope: the output is a correctly escaped EcmaScript string literal for any of the three string delimiters, but it is not made safe for direct embedding inside an HTML inline <script> block: HTML parser-state sequences such as <!-- and <script pass through unchanged (a literal </script> is neutralized by the forward-slash escape). HTML-context encoding must be applied separately when the result is placed in HTML.

Note that EcmaScript is best known by the JavaScript and ActionScript dialects.

Example:

input string: He didn't say, "Stop!"
output string: He didn\'t say, \"Stop!\"

Parameters:

input – String to escape values in, may be null

Returns:

String with escaped values, null if null string input

Since:

3.0

public static final String escapeHtml3(String input)

Escapes the characters in a String using HTML entities.

Supports only the HTML 3.0 entities. Apostrophes are escaped as the numeric reference '.

HTML attribute values must be quoted. This method does not escape all characters that delimit unquoted attribute values.

Parameters:

input – The String to escape, may be null

Returns:

A new escaped String, null if null string input

Since:

3.0

public static final String escapeHtml4(String input)

Escapes the characters in a String using HTML entities.

For example:

"bread" & "butter"

becomes:

"bread" & "butter".

Supports all known HTML 4.0 entities, including funky accents. Apostrophes are escaped as the numeric reference ' because ' is not a legal HTML 4.0 entity.

HTML attribute values must be quoted. This method does not escape all characters that delimit unquoted attribute values.

Parameters:

input – The String to escape, may be null

Returns:

A new escaped String, null if null string input

See also:

• ISO Entities

• HTML 3.2 Character Entities for ISO Latin-1

• HTML 4.0 Character entity references

• HTML 4.01 Character References

• HTML 4.01 Code positions

Since:

3.0

public static final String escapeJava(String input)

Escapes the characters in a String using Java String rules.

Deals correctly with quotes and control-chars (tab, backslash, cr, ff, etc.)

So a tab becomes the characters '\\' and 't'.

The only difference between Java strings and JavaScript strings is that in JavaScript, a single quote and forward-slash (/) are escaped.

Example:

input string: He didn't say, "Stop!"
output string: He didn't say, \"Stop!\"

Parameters:

input – String to escape values in, may be null

Returns:

String with escaped values, null if null string input

public static final String escapeJson(String input)

Escapes the characters in a String using Json String rules.

Escapes any values it finds into their JSON String form. Deals correctly with quotes and control-chars (tab, backslash, cr, ff, etc.)

So a tab becomes the characters '\\' and 't'.

The only difference between Java strings and Json strings is that in Json, forward-slash (/) is escaped.

Scope: the output is a correctly escaped JSON string, but it is not made safe for direct embedding inside an HTML inline <script> block: the backtick, ${, and HTML parser-state sequences such as <!-- and <script pass through unchanged (JSON offers no backslash escape for them; only a literal </script> is neutralized by the forward-slash escape). HTML-context encoding must be applied separately when the result is placed in HTML.

See https://www.ietf.org/rfc/rfc4627.txt for further details.

Example:

input string: He didn't say, "Stop!"
output string: He didn't say, \"Stop!\"

Parameters:

input – String to escape values in, may be null

Returns:

String with escaped values, null if null string input

Since:

3.2

@Deprecated public static final String escapeXml(String input)

Deprecated: Use #escapeXml10(java.lang.String) or #escapeXml11(java.lang.String) instead.

Escapes the characters in a String using XML entities.

For example: "bread" & "butter" => "bread" & "butter".

Supports only the five basic XML entities (gt, lt, quot, amp, apos). Does not support DTDs or external entities.

Note that Unicode characters greater than 0x7f are as of 3.0, no longer escaped. If you still wish this functionality, you can achieve it via the following: StringEscapeUtils.ESCAPE_XML.with( NumericEntityEscaper.between(0x7f, Integer.MAX_VALUE));

Parameters:

input – The String to escape, may be null

Returns:

A new escaped String, null if null string input

See also:

#unescapeXml(String)

public static String escapeXml10(String input)

Escapes the characters in a String using XML entities.

For example:

"bread" & "butter"

converts to:

"bread" & "butter"

Note that XML 1.0 is a text-only format: it cannot represent control characters or unpaired Unicode surrogate code points, even after escaping. The method escapeXml10 will remove characters that do not fit in the following ranges:

#x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]

Though not strictly necessary, escapeXml10 will escape characters in the following ranges:

[#x7F-#x84] | [#x86-#x9F]

The returned string can be inserted into a valid XML 1.0 or XML 1.1 document. If you want to allow more non-text characters in an XML 1.1 document, use #escapeXml11(String).

Parameters:

input – The String to escape, may be null

Returns:

A new escaped String, null if null string input

See also:

#unescapeXml(String)

Since:

3.3

public static String escapeXml11(String input)

Escapes the characters in a String using XML entities.

For example: "bread" & "butter" => "bread" & "butter".

XML 1.1 can represent certain control characters, but it cannot represent the null byte or unpaired Unicode surrogate code points, even after escaping. escapeXml11 will remove characters that do not fit in the following ranges:

[#x1-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]

escapeXml11 will escape characters in the following ranges:

[#x1-#x8] | [#xB-#xC] | [#xE-#x1F] | [#x7F-#x84] | [#x86-#x9F]

The returned string can be inserted into a valid XML 1.1 document. Do not use it for XML 1.0 documents.

Parameters:

input – The String to escape, may be null

Returns:

A new escaped String, null if null string input

See also:

#unescapeXml(String)

Since:

3.3

public static final String unescapeCsv(String input)

Returns a String value for an unescaped CSV column.

If the value is enclosed in double quotes, and contains a comma, newline or double quote, then quotes are removed.

Any double quote escaped characters (a pair of double quotes) are unescaped to just one double quote.

If the value is not enclosed in double quotes, or is and does not contain a comma, newline or double quote, then the String value is returned unchanged.

See Wikipedia and RFC 4180.

Parameters:

input – The input CSV column String, may be null

Returns:

The input String, with enclosing double quotes removed and embedded double quotes unescaped, null if null string input

Since:

2.4

public static final String unescapeEcmaScript(String input)

Unescapes any EcmaScript literals found in the String.

For example, it will turn a sequence of '\' and 'n' into a newline character, unless the '\' is preceded by another '\'.

See also:

#unescapeJava(String)

Parameters:

input – The String to unescape, may be null

Returns:

A new unescaped String, null if null string input

Since:

3.0

public static final String unescapeHtml3(String input)

Unescapes a string containing entity escapes to a string containing the actual Unicode characters corresponding to the escapes. Supports only HTML 3.0 entities.

Parameters:

input – The String to unescape, may be null

Returns:

A new unescaped String, null if null string input

Since:

3.0

public static final String unescapeHtml4(String input)

Unescapes a string containing entity escapes to a string containing the actual Unicode characters corresponding to the escapes. Supports HTML 4.0 entities.

For example, the string "<Français>" will become "<Français>"

If an entity is unrecognized, it is left alone, and inserted verbatim into the result string. e.g. ">&zzzz;x" will become ">&zzzz;x".

Parameters:

input – The String to unescape, may be null

Returns:

A new unescaped String, null if null string input

Since:

3.0

public static final String unescapeJava(String input)

Unescapes any Java literals found in the String. For example, it will turn a sequence of '\' and 'n' into a newline character, unless the '\' is preceded by another '\'.

Parameters:

input – The String to unescape, may be null

Returns:

A new unescaped String, null if null string input

public static final String unescapeJson(String input)

Unescapes any Json literals found in the String.

For example, it will turn a sequence of '\' and 'n' into a newline character, unless the '\' is preceded by another '\'.

See also:

#unescapeJava(String)

Parameters:

input – The String to unescape, may be null

Returns:

A new unescaped String, null if null string input

Since:

3.2

public static final String unescapeXml(String input)

Unescapes a string containing XML entity escapes to a string containing the actual Unicode characters corresponding to the escapes.

Supports only the five basic XML entities (gt, lt, quot, amp, apos). Does not support DTDs or external entities.

Note that numerical \u Unicode codes are unescaped to their respective Unicode characters. This may change in future releases.

Parameters:

input – The String to unescape, may be null

Returns:

A new unescaped String, null if null string input

See also:

• #escapeXml(String)

• #escapeXml10(String)

• #escapeXml11(String)