org.apache.commons.lang

Class StringEscapeUtils


public class StringEscapeUtils
extends java.lang.Object

Escapes and unescapes Strings for Java, Java Script, HTML, XML, and SQL.
Since:
2.0

Constructor Summary

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

Method Summary

static String
escapeHtml(String str)
Escapes the characters in a String using HTML entities.
static void
escapeHtml(Writer writer, String string)
Escapes the characters in a String using HTML entities and writes them to a Writer.
static String
escapeJava(String str)
Escapes the characters in a String using Java String rules.
static void
escapeJava(Writer out, String str)
Escapes the characters in a String using Java String rules to a Writer.
static String
escapeJavaScript(String str)
Escapes the characters in a String using JavaScript String rules.
static void
escapeJavaScript(Writer out, String str)
Escapes the characters in a String using JavaScript String rules to a Writer.
static String
escapeSql(String str)
Escapes the characters in a String to be suitable to pass to an SQL query.
static String
escapeXml(String str)
Escapes the characters in a String using XML entities.
static void
escapeXml(Writer writer, String str)
Escapes the characters in a String using XML entities.
static String
unescapeHtml(String str)
Unescapes a string containing entity escapes to a string containing the actual Unicode characters corresponding to the escapes.
static void
unescapeHtml(Writer writer, String string)
Unescapes a string containing entity escapes to a string containing the actual Unicode characters corresponding to the escapes.
static String
unescapeJava(String str)
Unescapes any Java literals found in the String.
static void
unescapeJava(Writer out, String str)
Unescapes any Java literals found in the String to a Writer.
static String
unescapeJavaScript(String str)
Unescapes any JavaScript literals found in the String.
static void
unescapeJavaScript(Writer out, String str)
Unescapes any JavaScript literals found in the String to a Writer.
static String
unescapeXml(String str)
Unescapes a string containing XML entity escapes to a string containing the actual Unicode characters corresponding to the escapes.
static void
unescapeXml(Writer writer, String str)
Unescapes a string containing XML entity escapes to a string containing the actual Unicode characters corresponding to the escapes.

Constructor Details

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 Details

escapeHtml

public static String escapeHtml(String str)
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:
str - the String to escape, may be null
Returns:
a new escaped String, null if null string input

escapeHtml

public static void escapeHtml(Writer writer,
                              String string)
            throws IOException
Escapes the characters in a String using HTML entities and writes them to a Writer.

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:
writer - the writer receiving the escaped string, not null
string - the String to escape, may be null

escapeJava

public static String escapeJava(String str)
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 must be escaped.

Example:

 input string: He didn't say, "Stop!"
 output string: He didn't say, \"Stop!\"
 
Parameters:
str - String to escape values in, may be null
Returns:
String with escaped values, null if null string input

escapeJava

public static void escapeJava(Writer out,
                              String str)
            throws IOException
Escapes the characters in a String using Java String rules to a Writer.

A null string input has no effect.

Parameters:
out - Writer to write escaped string into
str - String to escape values in, may be null
See Also:
escapeJava(java.lang.String)

escapeJavaScript

public static String escapeJavaScript(String str)
Escapes the characters in a String using JavaScript String rules.

Escapes any values it finds into their JavaScript 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 JavaScript strings is that in JavaScript, a single quote must be escaped.

Example:

 input string: He didn't say, "Stop!"
 output string: He didn\'t say, \"Stop!\"
 
Parameters:
str - String to escape values in, may be null
Returns:
String with escaped values, null if null string input

escapeJavaScript

public static void escapeJavaScript(Writer out,
                                    String str)
            throws IOException
Escapes the characters in a String using JavaScript String rules to a Writer.

A null string input has no effect.

Parameters:
out - Writer to write escaped string into
str - String to escape values in, may be null
See Also:
escapeJavaScript(java.lang.String)

escapeSql

public static String escapeSql(String str)
Escapes the characters in a String to be suitable to pass to an SQL query.

For example,

statement.executeQuery("SELECT * FROM MOVIES WHERE TITLE='" + 
   StringEscapeUtils.escapeSql("McHale's Navy") + 
   "'");

At present, this method only turns single-quotes into doubled single-quotes ("McHale's Navy" => "McHale''s Navy"). It does not handle the cases of percent (%) or underscore (_) for use in LIKE clauses. see http://www.jguru.com/faq/view.jsp?EID=8881

Parameters:
str - the string to escape, may be null
Returns:
a new String, escaped for SQL, null if null string input

escapeXml

public static String escapeXml(String str)
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 currently escaped to their numerical \\u equivalent. This may change in future releases.

Parameters:
str - the String to escape, may be null
Returns:
a new escaped String, null if null string input
See Also:
unescapeXml(java.lang.String)

escapeXml

public static void escapeXml(Writer writer,
                             String str)
            throws IOException
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 currently escaped to their numerical \\u equivalent. This may change in future releases.

Parameters:
writer - the writer receiving the unescaped string, not null
str - the String to escape, may be null
See Also:
unescapeXml(java.lang.String)

unescapeHtml

public static String unescapeHtml(String str)
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:
str - the String to unescape, may be null
Returns:
a new unescaped String, null if null string input

unescapeHtml

public static void unescapeHtml(Writer writer,
                                String string)
            throws IOException
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:
writer - the writer receiving the unescaped string, not null
string - the String to unescape, may be null

unescapeJava

public static String unescapeJava(String str)
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:
str - the String to unescape, may be null
Returns:
a new unescaped String, null if null string input

unescapeJava

public static void unescapeJava(Writer out,
                                String str)
            throws IOException
Unescapes any Java literals found in the String to a Writer.

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

A null string input has no effect.

Parameters:
out - the Writer used to output unescaped characters
str - the String to unescape, may be null

unescapeJavaScript

public static String unescapeJavaScript(String str)
Unescapes any JavaScript 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:
str - the String to unescape, may be null
Returns:
A new unescaped String, null if null string input

unescapeJavaScript

public static void unescapeJavaScript(Writer out,
                                      String str)
            throws IOException
Unescapes any JavaScript literals found in the String to a Writer.

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

A null string input has no effect.

Parameters:
out - the Writer used to output unescaped characters
str - the String to unescape, may be null

unescapeXml

public static String unescapeXml(String str)
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:
str - the String to unescape, may be null
Returns:
a new unescaped String, null if null string input

unescapeXml

public static void unescapeXml(Writer writer,
                               String str)
            throws IOException
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:
writer - the writer receiving the unescaped string, not null
str - the String to unescape, may be null