org.apache.commons.lang3

Class StringEscapeUtils

java.lang.Object

org.apache.commons.lang3.StringEscapeUtils

public class StringEscapeUtils
extends java.lang.Object

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

#ThreadSafe#

Since:

2.0

Field Summary

Fields

Modifier and Type	Field and Description
static CharSequenceTranslator	ESCAPE_CSV Translator object for escaping individual Comma Separated Values.
static CharSequenceTranslator	ESCAPE_ECMASCRIPT Translator object for escaping EcmaScript/JavaScript.
static CharSequenceTranslator	ESCAPE_HTML3 Translator object for escaping HTML version 3.0.
static CharSequenceTranslator	ESCAPE_HTML4 Translator object for escaping HTML version 4.0.
static CharSequenceTranslator	ESCAPE_JAVA Translator object for escaping Java.
static CharSequenceTranslator	ESCAPE_JSON Translator object for escaping Json.
static CharSequenceTranslator	ESCAPE_XML Translator object for escaping XML.
static CharSequenceTranslator	UNESCAPE_CSV Translator object for unescaping escaped Comma Separated Value entries.
static CharSequenceTranslator	UNESCAPE_ECMASCRIPT Translator object for unescaping escaped EcmaScript.
static CharSequenceTranslator	UNESCAPE_HTML3 Translator object for unescaping escaped HTML 3.0.
static CharSequenceTranslator	UNESCAPE_HTML4 Translator object for unescaping escaped HTML 4.0.
static CharSequenceTranslator	UNESCAPE_JAVA Translator object for unescaping escaped Java.
static CharSequenceTranslator	UNESCAPE_JSON Translator object for unescaping escaped Json.
static CharSequenceTranslator	UNESCAPE_XML Translator object for unescaping escaped XML.

Constructor Summary

Constructors

Constructor and Description
StringEscapeUtils() StringEscapeUtils instances should NOT be constructed in standard programming.

Method Summary

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

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ESCAPE_JAVA

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

ESCAPE_ECMASCRIPT

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

ESCAPE_JSON

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

ESCAPE_XML

public static final CharSequenceTranslator ESCAPE_XML

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

ESCAPE_HTML3

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

ESCAPE_HTML4

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

ESCAPE_CSV

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

UNESCAPE_JAVA

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

UNESCAPE_ECMASCRIPT

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

UNESCAPE_JSON

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

UNESCAPE_HTML3

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

UNESCAPE_HTML4

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

UNESCAPE_XML

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

UNESCAPE_CSV

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

Constructor Detail

StringEscapeUtils

public StringEscapeUtils()

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.

Method Detail

escapeJava

public static final java.lang.String escapeJava(java.lang.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

escapeEcmaScript

public static final java.lang.String escapeEcmaScript(java.lang.String input)

Escapes the characters in a String using EcmaScript String rules.

Escapes any values it finds into their EcmaScript 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 EcmaScript strings is that in EcmaScript, a single quote and forward-slash (/) are escaped.

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

escapeJson

public static final java.lang.String escapeJson(java.lang.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.

See http://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

unescapeJava

public static final java.lang.String unescapeJava(java.lang.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

unescapeEcmaScript

public static final java.lang.String unescapeEcmaScript(java.lang.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 '\'.

Parameters:

input - the String to unescape, may be null

Returns:

A new unescaped String, null if null string input

Since:

3.0

See Also:

unescapeJava(String)

unescapeJson

public static final java.lang.String unescapeJson(java.lang.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 '\'.

Parameters:

input - the String to unescape, may be null

Returns:

A new unescaped String, null if null string input

Since:

3.2

See Also:

unescapeJava(String)

escapeHtml4

public static final java.lang.String escapeHtml4(java.lang.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. Note that the commonly used apostrophe escape character (') is not a legal entity and so is not supported).

Parameters:

input - the String to escape, may be null

Returns:

a new escaped String, null if null string input

Since:

3.0

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

escapeHtml3

public static final java.lang.String escapeHtml3(java.lang.String input)

Escapes the characters in a String using HTML entities.

Supports only the HTML 3.0 entities.

Parameters:

input - the String to escape, may be null

Returns:

a new escaped String, null if null string input

Since:

3.0

unescapeHtml4

public static final java.lang.String unescapeHtml4(java.lang.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 "&lt;Fran&ccedil;ais&gt;" will become "<Français>"

If an entity is unrecognized, it is left alone, and inserted verbatim into the result string. e.g. "&gt;&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

unescapeHtml3

public static final java.lang.String unescapeHtml3(java.lang.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

escapeXml

public static final java.lang.String escapeXml(java.lang.String input)

Escapes the characters in a String using XML entities.

For example: "bread" & "butter" => &quot;bread&quot; &amp; &quot;butter&quot;.

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(java.lang.String)

unescapeXml

public static final java.lang.String unescapeXml(java.lang.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)

escapeCsv

public static final java.lang.String escapeCsv(java.lang.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

unescapeCsv

public static final java.lang.String unescapeCsv(java.lang.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