com.google.gdata.util.common.base

Class CharEscapers

java.lang.Object

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

public final class CharEscapers
extends Object

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

Method Summary

Methods

Modifier and Type	Method and Description
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:

• The alphanumeric characters "a" through "z", "A" through "Z" and "0" through "9" remain the same.
• The special characters ".", "-", "*", and "_" remain the same.
• The space character " " is converted into a plus sign "+".
• All other characters are converted into one or more bytes using UTF-8 encoding and each byte is then represented by the 3-character string "%XY", where "XY" is the two-digit, uppercase, hexadecimal representation of the byte value.

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

  This escaper has identical behavior to (but is potentially much faster than):

  • FastURLEncoder.encode(String)
  • FastURLEncoder.encode(String,String) with the encoding name "UTF-8"
  • UriEncoder.encode(String)
  • UriEncoder.encode(String,java.nio.charset.Charset) with the UTF_8 Charset
  • URLEncoder.encode(String, String) with the encoding name "UTF-8"

  This method is equivalent to uriEscaper(true).

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:

• The alphanumeric characters "a" through "z", "A" through "Z" and "0" through "9" remain the same.
• The unreserved characters ".", "-", "~", and "_" remain the same.
• The general delimiters "@" and ":" remain the same.
• The subdelimiters "!", "$", "&", "'", "(", ")", "*", ",", ";", and "=" remain the same.
• The space character " " is converted into %20.
• All other characters are converted into one or more bytes using UTF-8 encoding and each byte is then represented by the 3-character string "%XY", where "XY" is the two-digit, uppercase, hexadecimal representation of the byte value.

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:

• The alphanumeric characters "a" through "z", "A" through "Z" and "0" through "9" remain the same.
• The unreserved characters ".", "-", "~", and "_" remain the same.
• The general delimiters "@" and ":" remain the same.
• The path delimiters "/" and "?" remain the same.
• The subdelimiters "!", "$", "'", "(", ")", "*", ",", and ";", remain the same.
• The space character " " is converted into %20.
• The equals sign "=" is converted into %3D.
• The ampersand "&" is converted into %26.
• All other characters are converted into one or more bytes using UTF-8 encoding and each byte is then represented by the 3-character string "%XY", where "XY" is the two-digit, uppercase, hexadecimal representation of the byte value.

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:

• The alphanumeric characters "a" through "z", "A" through "Z" and "0" through "9" remain the same.
• The special characters ".", "-", "*", and "_" remain the same.
• If plusForSpace was specified, the space character " " is converted into a plus sign "+". Otherwise it is converted into "%20".
• All other characters are converted into one or more bytes using UTF-8 encoding and each byte is then represented by the 3-character string "%XY", where "XY" is the two-digit, uppercase, hexadecimal representation of the byte value.

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:

• The alphanumeric characters "a" through "z", "A" through "Z" and "0" through "9" remain the same.
• The special characters "!", "(", ")", "*", "-", ".", "_", "~", ",", "/" and ":" remain the same.
• The space character " " is converted into a plus sign "+".
• All other characters are converted into one or more bytes using UTF-8 encoding and each byte is then represented by the 3-character string "%XY", where "XY" is the two-digit, uppercase, hexadecimal representation of the byte value.

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:

NullPointerException - if any of the arguments is null