Escaper that converts literal text into a format safe for inclusion in a particular
context (such as an XML document). Typically (but not always), the inverse process of
"unescaping" the text is performed automatically by the relevant parser.
For example, an XML escaper would convert the literal string "Foo<Bar>" into
"Foo<Bar>" to prevent "<Bar>" from being confused with an XML tag. When the
resulting XML document is parsed, the parser API will return this text as the original literal
string "Foo<Bar>".
Note
This class is similar to CharEscaper but with one very important difference.
A CharEscaper can only process Java UTF16
characters in isolation and may not cope when it encounters surrogate pairs. This class
facilitates the correct escaping of all Unicode characters.
As there are important reasons, including potential security issues, to handle Unicode correctly if you are considering implementing a new escaper you should favor using UnicodeEscaper wherever possible.
A UnicodeEscaper instance is required to be stateless, and safe when used concurrently by
multiple threads.
Several popular escapers are defined as constants in the class CharEscapers. To create
your own escapers extend this class and implement the escape(int) method.
| Modifier and Type | Field and Description |
|---|---|
| private static final int | DEST_PAD
The amount of padding (chars) to use when growing the escape buffer. |
| private static final ThreadLocal | DEST_TL
A thread-local destination buffer to keep us from creating new buffers. |
| Access | Constructor and Description |
|---|---|
| public |
| Modifier and Type | Method and Description |
|---|---|
| protected static final int | Returns: the Unicode code point for the given index or the negated value of the trailing high surrogate character at the end of the sequencethe sequence of characters from which to decode the code point seq, int the index of the first character to decode index, int the index beyond the last valid character to decode end)Returns the Unicode code point of the character at the given index. |
| protected abstract char[] | Returns: the replacement characters, ornull if no escaping was neededthe Unicode code point to escape if necessary cp)Returns the escaped form of the given Unicode code point, or |
| public String | Returns: the escaped form ofstringthe literal string to be escaped string)Implements org. |
| public Appendable | Returns: anAppendable which passes text to out after escaping itthe underlying out)Appendable to append escaped output toImplements org. Appendable instance which automatically escapes all text appended to it
before passing the resulting text to an underlying Appendable.
|
| protected final String | Returns: the escaped form ofstringthe literal string to be escaped s, int the index to start escaping from index)Returns the escaped form of a given literal string, starting at the given index. |
| private static final char[] | growBuffer(char[] dest, int index, int size)
Helper method to grow the character buffer as needed, this only happens once in a while so it's ok if it's in a method call. |
| protected int | nextEscapeIndex(CharSequence
a sequence of characters csq, int the index of the first character to be scanned start, int the index immediately after the last character to be scanned end)Scans a sub-sequence of characters from a given |
| DEST_PAD | back to summary |
|---|---|
| private static final int DEST_PAD The amount of padding (chars) to use when growing the escape buffer. | |
| DEST_TL | back to summary |
|---|---|
| private static final ThreadLocal<char[]> DEST_TL A thread-local destination buffer to keep us from creating new buffers. The starting size is 1024 characters. If we grow past this we don't put it back in the threadlocal, we just keep going and grow as needed. | |
| UnicodeEscaper | back to summary |
|---|---|
| public UnicodeEscaper() | |
| codePointAt | back to summary |
|---|---|
| protected static final int codePointAt(CharSequence seq, int index, int end) Returns the Unicode code point of the character at the given index.
Unlike The behaviour of this method is as follows:
| |
| escape | back to summary |
|---|---|
| protected abstract char[] escape(int cp) Returns the escaped form of the given Unicode code point, or If an empty array is returned, this effectively strips the input character from the resulting text.
If the character does not need to be escaped, this method should return If the implementation of this method cannot correctly handle a particular code point then it should either throw an appropriate runtime exception or return a suitable replacement character. It must never silently discard invalid input as this may constitute a security risk.
| |
| escape | back to summary |
|---|---|
| public String escape(String string) Implements org. Returns the escaped form of a given literal string.
If you are escaping input in arbitrary successive chunks, then it is not generally safe to use
this method. If an input string ends with an unmatched high surrogate character, then this
method will throw Note When implementing an escaper it is a good idea to override this method for
efficiency by inlining the implementation of
| |
| escape | back to summary |
|---|---|
| public Appendable escape(final Appendable out) Implements org. Returns an
Unlike
The methods of the returned object will propagate any exceptions thrown by the underlying
For well formed UTF-16 the escaping behavior
is identical to that of
{
@code
StringBuilder sb = new StringBuilder();
escaper.escape(sb).append(string);
return sb.toString();
}
| |
| escapeSlow | back to summary |
|---|---|
| protected final String escapeSlow(String s, int index) Returns the escaped form of a given literal string, starting at the given index. This method is
called by the
This method is not reentrant and may only be invoked by the top level
| |
| growBuffer | back to summary |
|---|---|
| private static final char[] growBuffer(char[] dest, int index, int size) Helper method to grow the character buffer as needed, this only happens once in a while so it's ok if it's in a method call. If the index passed in is 0 then no copying will be done. | |
| nextEscapeIndex | back to summary |
|---|---|
| protected int nextEscapeIndex(CharSequence csq, int start, int end) Scans a sub-sequence of characters from a given Note When implementing an escaper, it is a good idea to override this method for
efficiency. The base class implementation determines successive Unicode code points and invokes
Note however that if your escaper does not escape characters in the supplementary range, you should either continue to validate the correctness of any surrogate characters encountered or provide a clear warning to users that your escaper does not validate its input.
See
| |