Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.lang
Class StringEscapeUtils

    java.lang.Object
      |
      +--org.apache.commons.lang.StringEscapeUtils

public class StringEscapeUtils
extends Object

Escapes and unescapes `String`s for Java, Java Script, HTML, XML, and SQL.

Since:
  2.0
Version:
  $Id: StringEscapeUtils.java 471626 2006-11-06 04:02:09Z bayard $
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.

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.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

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 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
  Throws:
    `IllegalArgumentException` - if the Writer is `null`
    `IOException` - if error occurs on underlying Writer
  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
  Throws:
    `IllegalArgumentException` - if the Writer is `null`
    `IOException` - if error occurs on underlying Writer
  See Also:
    `escapeJavaScript(java.lang.String)`

### 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
  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(String)`

### 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
  Throws:
    `IllegalArgumentException` - if the Writer is `null`
    `IOException` - if error occurs on underlying Writer
  See Also:
    `unescapeJava(Writer,String)`

### escapeHtml

    public static String escapeHtml(String str)

  Escapes the characters in a `String` using HTML entities.

  For example:

  `"bread" & "butter"`

  becomes:

  `&quot;bread&quot; &amp; &quot;butter&quot;`.

  Supports all known HTML 4.0 entities, including funky accents. Note that the commonly used apostrophe escape character (&apos;) 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(String)`, 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)
                           throws IOException

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

  For example:

  `"bread" & "butter"`

  becomes:

  `&quot;bread&quot; &amp; &quot;butter&quot;`.

  Supports all known HTML 4.0 entities, including funky accents. Note that the commonly used apostrophe escape character (&apos;) 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(String)`, `unescapeHtml(String)`, 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

### 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:
    `escapeHtml(Writer, String)`

### 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
  Throws:
    `IllegalArgumentException` - if the writer is null
    `IOException` - if an IOException occurs
  See Also:
    `escapeHtml(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"` => `&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 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:
    `unescapeXml(java.lang.String)`

### escapeXml

    public static String escapeXml(String str)

  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 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)`

### 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
  Throws:
    `IllegalArgumentException` - if the writer is null
    `IOException` - if there is a problem writing
  See Also:
    `escapeXml(String)`

### 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(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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2005 - Apache Software Foundation