public interface Escaper
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
.
Modifier and Type | Method and Description |
---|---|
java.lang.Appendable |
escape(java.lang.Appendable out)
Returns an
Appendable instance which automatically escapes all
text appended to it before passing the resulting text to an underlying
Appendable . |
java.lang.String |
escape(java.lang.String string)
Returns the escaped form of a given literal string.
|
java.lang.String escape(java.lang.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 escapedstring
java.lang.NullPointerException
- if string
is nulljava.lang.IllegalArgumentException
- if string
contains badly formed
UTF-16 or cannot be escaped for any other reasonjava.lang.Appendable escape(java.lang.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 toAppendable
which passes text to out
after
escaping it.