com.google.gdata.util.common.base
Class CharEscapers

java.lang.Object
  extended by com.google.gdata.util.common.base.CharEscapers

public final class CharEscapers
extends java.lang.Object

Utility functions for dealing with CharEscapers, and some commonly used CharEscaper instances.


Method Summary
static CharEscaper asciiHtmlEscaper()
          Returns a CharEscaper instance that escapes special characters in a string so it can safely be included in an HTML document in either element content or attribute values.
static Escaper cppUriEscaper()
          Returns a Escaper instance that escapes Java characters in a manner compatible with the C++ webutil/url URL class (the kGoogle1Escape set).
static CharEscaper fallThrough(CharEscaper primary, CharEscaper secondary)
          Returns a composite CharEscaper instance that tries to escape characters using a primary CharEscaper first and falls back to a secondary one if there is no escaping.
static CharEscaper htmlEscaper()
          Returns a CharEscaper instance that escapes special characters in a string so it can safely be included in an HTML document in either element content or attribute values.
static CharEscaper javaCharEscaper()
          Returns a CharEscaper instance that escapes special characters in a string so it can safely be included in a Java char or string literal.
static CharEscaper javascriptEscaper()
          Returns a CharEscaper instance that escapes non-ASCII characters in a string so it can safely be included in a Javascript string literal.
static CharEscaper javaStringEscaper()
          Returns a CharEscaper instance that escapes special characters in a string so it can safely be included in a Java string literal.
static CharEscaper javaStringUnicodeEscaper()
          Returns a CharEscaper instance that replaces non-ASCII characters in a string with their Unicode escape sequences (\\uxxxx where xxxx is a hex number).
static CharEscaper nullEscaper()
          Returns a CharEscaper that does no escaping.
static CharEscaper pythonEscaper()
          Returns a CharEscaper instance that escapes special characters from a string so it can safely be included in a Python string literal.
static Escaper uriEscaper()
          Returns an Escaper instance that escapes Java chars so they can be safely included in URIs.
static Escaper uriEscaper(boolean plusForSpace)
          Returns a Escaper instance that escapes Java characters so they can be safely included in URIs.
static Escaper uriPathEscaper()
          Returns an Escaper instance that escapes Java chars so they can be safely included in URI path segments.
static Escaper uriQueryStringEscaper()
          Returns an Escaper instance that escapes Java chars so they can be safely included in URI query string segments.
static CharEscaper xmlContentEscaper()
          Returns a CharEscaper instance that escapes special characters in a string so it can safely be included in an XML document in element content.
static CharEscaper xmlEscaper()
          Returns a CharEscaper instance that escapes special characters in a string so it can safely be included in an XML document in either element content or attribute values.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

nullEscaper

public static CharEscaper nullEscaper()
Returns a CharEscaper that does no escaping.


xmlEscaper

public static CharEscaper xmlEscaper()
Returns a CharEscaper instance that escapes special characters in a string so it can safely be included in an XML document in either element content or attribute values.

Note

: silently removes null-characters and control characters, as there is no way to represent them in XML.


xmlContentEscaper

public static CharEscaper xmlContentEscaper()
Returns a CharEscaper instance that escapes special characters in a string so it can safely be included in an XML document in element content.

Note

: double and single quotes are not escaped, so it is not safe to use this escaper to escape attribute values. Use the xmlEscaper() escaper to escape attribute values or if you are unsure. Also silently removes non-whitespace control characters, as there is no way to represent them in XML.


htmlEscaper

public static CharEscaper htmlEscaper()
Returns a CharEscaper instance that escapes special characters in a string so it can safely be included in an HTML document in either element content or attribute values.

Note

: alters non-ASCII and control characters. The entity list was taken from: here


asciiHtmlEscaper

public static CharEscaper asciiHtmlEscaper()
Returns a CharEscaper instance that escapes special characters in a string so it can safely be included in an HTML document in either element content or attribute values.

Note

: does not alter non-ASCII and control characters.


uriEscaper

public static Escaper uriEscaper()
Returns an Escaper instance that escapes Java chars so they can be safely included in URIs. For details on escaping URIs, see section 2.4 of RFC 2396.

When encoding a String, the following rules apply:


uriPathEscaper

public static Escaper uriPathEscaper()
Returns an Escaper instance that escapes Java chars so they can be safely included in URI path segments. For details on escaping URIs, see section 2.4 of RFC 3986.

When encoding a String, the following rules apply:

Note: Unlike other escapers, URI escapers produce uppercase hexidecimal sequences. From RFC 3986:
"URI producers and normalizers should use uppercase hexadecimal digits for all percent-encodings."


uriQueryStringEscaper

public static Escaper uriQueryStringEscaper()
Returns an Escaper instance that escapes Java chars so they can be safely included in URI query string segments. When the query string consists of a sequence of name=value pairs separated by &, the names and values should be individually encoded. If you escape an entire query string in one pass with this escaper, then the "=" and "&" characters used as separators will also be escaped.

This escaper is also suitable for escaping fragment identifiers.

For details on escaping URIs, see section 2.4 of RFC 3986.

When encoding a String, the following rules apply:

Note: Unlike other escapers, URI escapers produce uppercase hexidecimal sequences. From RFC 3986:
"URI producers and normalizers should use uppercase hexadecimal digits for all percent-encodings."


uriEscaper

public static Escaper uriEscaper(boolean plusForSpace)
Returns a Escaper instance that escapes Java characters so they can be safely included in URIs. For details on escaping URIs, see section 2.4 of RFC 2396.

When encoding a String, the following rules apply:

Note: Unlike other escapers, URI escapers produce uppercase hexidecimal sequences. From RFC 3986:
"URI producers and normalizers should use uppercase hexadecimal digits for all percent-encodings."

Parameters:
plusForSpace - if true space is escaped to + otherwise it is escaped to %20. Although common, the escaping of spaces as plus signs has a very ambiguous status in the relevant specifications. You should prefer %20 unless you are doing exact character-by-character comparisons of URLs and backwards compatibility requires you to use plus signs.
See Also:
uriEscaper()

cppUriEscaper

public static Escaper cppUriEscaper()
Returns a Escaper instance that escapes Java characters in a manner compatible with the C++ webutil/url URL class (the kGoogle1Escape set).

When encoding a String, the following rules apply:

Note: Unlike other escapers, URI escapers produce uppercase hexidecimal sequences. From RFC 3986:
"URI producers and normalizers should use uppercase hexadecimal digits for all percent-encodings."

Note: This escaper is a special case and is not compliant with RFC 2396. Specifically it will not escape "/", ":" and ",". This is only provided for certain limited use cases and you should favor using uriEscaper() whenever possible.


javaStringEscaper

public static CharEscaper javaStringEscaper()
Returns a CharEscaper instance that escapes special characters in a string so it can safely be included in a Java string literal.

Note

: does not escape single quotes, so use the escaper returned by javaCharEscaper() if you are generating char literals or if you are unsure.


javaCharEscaper

public static CharEscaper javaCharEscaper()
Returns a CharEscaper instance that escapes special characters in a string so it can safely be included in a Java char or string literal. The behavior of this escaper is the same as that of the javaStringEscaper(), except it also escapes single quotes.


javaStringUnicodeEscaper

public static CharEscaper javaStringUnicodeEscaper()
Returns a CharEscaper instance that replaces non-ASCII characters in a string with their Unicode escape sequences (\\uxxxx where xxxx is a hex number). Existing escape sequences won't be affected.


pythonEscaper

public static CharEscaper pythonEscaper()
Returns a CharEscaper instance that escapes special characters from a string so it can safely be included in a Python string literal. Does not have any special handling for non-ASCII characters.


javascriptEscaper

public static CharEscaper javascriptEscaper()
Returns a CharEscaper instance that escapes non-ASCII characters in a string so it can safely be included in a Javascript string literal. Non-ASCII characters are replaced with their ASCII javascript escape sequences (e.g., \\uhhhh or \xhh).


fallThrough

public static CharEscaper fallThrough(CharEscaper primary,
                                      CharEscaper secondary)
Returns a composite CharEscaper instance that tries to escape characters using a primary CharEscaper first and falls back to a secondary one if there is no escaping.

The returned escaper will attempt to escape each character using the primary escaper, and if the primary escaper has no escaping for that character, it will use the secondary escaper. If the secondary escaper has no escaping for a character either, the original character will be used. If the primary escaper has an escape for a character, the secondary escaper will not be used at all for that character; the escaped output of the primary is not run through the secondary. For a case where you would like to first escape with one escaper, and then with another, it is recommended that you call each escaper in order.

Parameters:
primary - The primary CharEscaper to use
secondary - The secondary CharEscaper to use if the first one has no escaping rule for a character
Throws:
java.lang.NullPointerException - if any of the arguments is null