org.apache.commons.lang

Class StringEscapeUtils

public class StringEscapeUtils extends Object

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

Since: 2.0

Version: $Id: StringEscapeUtils.java 612880 2008-01-17 17:34:43Z ggregory $

Author: Apache Jakarta Turbine Purple Technology Alexander Day Chaffee Antony Riley Helge Tesgaard Sean Brown Gary Gregory Phil Steitz Pete Gieser

Constructor Summary
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 Summary
static StringescapeCsv(String str)

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.
static voidescapeCsv(Writer out, String str)

Writes 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 written 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 written unchanged (null values are ignored).

see Wikipedia and RFC 4180.
static StringescapeHtml(String str)

Escapes the characters in a String using HTML entities.

For example:

"bread" & "butter"

becomes:

"bread" & "butter".

static voidescapeHtml(Writer writer, String string)

Escapes the characters in a String using HTML entities and writes them to a Writer.

For example:

"bread" & "butter"

becomes:

"bread" & "butter".
static StringescapeJava(String str)

Escapes the characters in a String using Java String rules.

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

static voidescapeJava(Writer out, String str)

Escapes the characters in a String using Java String rules to a Writer.

A null string input has no effect.

static StringescapeJavaScript(String str)

Escapes the characters in a String using JavaScript String rules.

Escapes any values it finds into their JavaScript String form.

static voidescapeJavaScript(Writer out, String str)

Escapes the characters in a String using JavaScript String rules to a Writer.

A null string input has no effect.

static StringescapeSql(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").

static voidescapeXml(Writer writer, String str)

Escapes the characters in a String using XML entities.

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

static StringescapeXml(String str)

Escapes the characters in a String using XML entities.

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

static StringunescapeCsv(String str)

Returns a String value for an unescaped CSV column.

static voidunescapeCsv(Writer out, String str)

Returns a String value for an unescaped CSV column.

static StringunescapeHtml(String str)

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

static voidunescapeHtml(Writer writer, String string)

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

static StringunescapeJava(String str)

Unescapes any Java literals found in the String.

static voidunescapeJava(Writer out, String str)

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.

static StringunescapeJavaScript(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 '\'.

static voidunescapeJavaScript(Writer out, String str)

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.

static voidunescapeXml(Writer writer, 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).

static StringunescapeXml(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).

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

escapeCsv

public static String escapeCsv(String str)

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: str 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

escapeCsv

public static void escapeCsv(Writer out, String str)

Writes 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 written 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 written unchanged (null values are ignored).

see Wikipedia and RFC 4180.

Parameters: str the input CSV column String, may be null out Writer to write input string to, enclosed in double quotes if it contains a comma, newline or double quote

Throws: IOException if error occurs on underlying Writer

Since: 2.4

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

See Also: unescapeHtml 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

escapeHtml

public static void escapeHtml(Writer writer, String string)

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

Throws: IllegalArgumentException if the writer is null IOException when Writer passed throws the exception from calls to the Writer#write(int) methods.

See Also: escapeHtml unescapeHtml 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

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)

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

Throws: IllegalArgumentException if the Writer is null IOException if error occurs on underlying Writer

See Also: StringEscapeUtils

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)

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

Throws: IllegalArgumentException if the Writer is null IOException if error occurs on underlying Writer

See Also: StringEscapeUtils

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 void escapeXml(Writer writer, 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: writer the writer receiving the unescaped string, not null str the String to escape, may be null

Throws: IllegalArgumentException if the writer is null IOException if there is a problem writing

See Also: StringEscapeUtils

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: StringEscapeUtils

unescapeCsv

public static String unescapeCsv(String str)

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: str 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

unescapeCsv

public static void unescapeCsv(Writer out, String str)

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: str the input CSV column String, may be null out Writer to write the input String to, with enclosing double quotes removed and embedded double quotes unescaped, null if null string input

Throws: IOException if error occurs on underlying Writer

Since: 2.4

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

See Also: StringEscapeUtils

unescapeHtml

public 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. 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

Throws: IllegalArgumentException if the writer is null IOException if an IOException occurs

See Also: escapeHtml

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)

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

Throws: IllegalArgumentException if the Writer is null IOException if error occurs on underlying Writer

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

See Also: unescapeJava

unescapeJavaScript

public static void unescapeJavaScript(Writer out, String str)

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

Throws: IllegalArgumentException if the Writer is null IOException if error occurs on underlying Writer

See Also: unescapeJava

unescapeXml

public 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.

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

Throws: IllegalArgumentException if the writer is null IOException if there is a problem writing

See Also: escapeXml

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

See Also: escapeXml

Copyright © 2001-2011 - Apache Software Foundation