|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Escaper
An object 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>"
.
An Escaper
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, use
CharEscaperBuilder
, or extend CharEscaper
or
UnicodeEscaper
.
Method Summary | |
---|---|
Appendable |
escape(Appendable out)
Returns an Appendable instance which automatically escapes all
text appended to it before passing the resulting text to an underlying
Appendable . |
String |
escape(String string)
Returns the escaped form of a given literal string. |
Method Detail |
---|
String escape(String string)
Note that this method may treat input characters differently depending on the specific escaper implementation.
UnicodeEscaper
handles UTF-16 correctly,
including surrogate character pairs. If the input is badly formed the
escaper should throw IllegalArgumentException
.
CharEscaper
handles Java characters independently and does
not verify the input for well formed characters. A CharEscaper should not
be used in situations where input is not guaranteed to be restricted to
the Basic Multilingual Plane (BMP).
string
- the literal string to be escaped
string
NullPointerException
- if string
is null
IllegalArgumentException
- if string
contains badly formed UTF-16 or cannot be
escaped for any other reasonAppendable escape(Appendable out)
Appendable
instance which automatically escapes all
text appended to it before passing the resulting text to an underlying
Appendable
.
Note that this method may treat input characters differently depending on the specific escaper implementation.
UnicodeEscaper
handles UTF-16 correctly,
including surrogate character pairs. If the input is badly formed the
escaper should throw IllegalArgumentException
.
CharEscaper
handles Java characters independently and does
not verify the input for well formed characters. A CharEscaper should not
be used in situations where input is not guaranteed to be restricted to
the Basic Multilingual Plane (BMP).
out
- the underlying Appendable
to append escaped output to
Appendable
which passes text to out
after
escaping it.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |