public abstract class Encoder
extends java.lang.Object
This is the low-level encoding API. For each flavor of encoding there is an instance of this class that performs the actual encoding. Overriding and implementing Encoders outside of the OWASP Encoder's project is not currently supported.
Unless otherwise documented, instances of these classes are
thread-safe. Encoders implementations do not generally carry
state, and if they do the state will be flush with a call to encode(java.nio.CharBuffer, java.nio.CharBuffer, boolean)
with
endOfInput
set to true
.
To use an Encoder instance directly, repeatedly call encode(java.nio.CharBuffer, java.nio.CharBuffer, boolean)
with
the endOfInput
parameter set to false
while there
is (the possibility of) more input to encode. Once there is no
more input to encode, call encode(java.nio.CharBuffer,
java.nio.CharBuffer, boolean)
with endOfInput
set to
true
until the method returns CoderResult.UNDERFLOW
.
In general, this class is not expected to be needed directly.
Use the Encode
fluent interface for encoding Strings or
EncodedWriter
for large blocks of contextual encoding.
Encode
,
EncodedWriter
Modifier and Type | Field and Description |
---|---|
(package private) static char[] |
HEX
Hexadecimal conversion array.
|
(package private) static int |
HEX_MASK
Bit-mask used for encoding values in hexadecimal.
|
(package private) static int |
HEX_SHIFT
Bit-shift used for encoding values in hexadecimal.
|
Constructor and Description |
---|
Encoder()
Package-private constructor to prevent having to support
external implementations of this class.
|
Modifier and Type | Method and Description |
---|---|
java.nio.charset.CoderResult |
encode(java.nio.CharBuffer input,
java.nio.CharBuffer output,
boolean endOfInput)
This is the kernel of encoding.
|
(package private) java.nio.charset.CoderResult |
encodeArrays(java.nio.CharBuffer input,
java.nio.CharBuffer output,
boolean endOfInput)
The core encoding loop used when both the input and output buffers
are array backed.
|
(package private) java.nio.charset.CoderResult |
encodeBuffers(java.nio.CharBuffer input,
java.nio.CharBuffer output,
boolean endOfInput)
The core encoding loop used when either or both input and output
buffers are NOT array-backed.
|
(package private) abstract int |
firstEncodedOffset(java.lang.String input,
int off,
int len)
Scans the input string for the first character index that requires
encoding.
|
(package private) abstract int |
maxEncodedLength(int n)
Returns the maximum encoded length (in chars) of an input sequence of
n characters. |
(package private) static java.nio.charset.CoderResult |
overflow(java.nio.CharBuffer input,
int i,
java.nio.CharBuffer output,
int j)
Internal helper method to properly position buffers after encoding up
until an overflow.
|
(package private) static java.nio.charset.CoderResult |
underflow(java.nio.CharBuffer input,
int i,
java.nio.CharBuffer output,
int j)
Internal helper method to properly position buffers after encoding up
until an underflow.
|
static final char[] HEX
static final int HEX_SHIFT
static final int HEX_MASK
Encoder()
public java.nio.charset.CoderResult encode(java.nio.CharBuffer input, java.nio.CharBuffer output, boolean endOfInput)
This is the kernel of encoding. Currently only CharBuffers
backed by arrays (i.e. CharBuffer.hasArray()
returns true
) are supported. Using a
direct-mapped CharBuffer will result in an
UnsupportedOperationException, though this behavior
may change in future releases.
This method should be called repeatedly while endOfInput
set to false
while there is more input.
Once there is no more input, this method should be called
endOfInput
set to false
until CoderResult.UNDERFLOW
is returned.
After any call to this method, except when endOfInput
is true
and the method returns UNDERFLOW
, there may be characters left to encode in the
input
buffer (i.e. input.hasRemaining() ==
true
). This will happen when the encoder needs to see more
input before determining what to do--for example when encoding
for CDATA, if the input ends with "foo]]"
, the encoder
will need to see the next character to determine if it is a ">"
or not.
Example usage:
CharBuffer input = CharBuffer.allocate(1024); CharBuffer output = CharBuffer.allocate(1024); CoderResult cr; // assuming doRead fills in the input buffer or // returns -1 at end of input while(doRead(input) != -1) { input.flip(); for (;;) { cr = encoder.encode(input, output, false); if (cr.isUnderflow()) { break; } if (cr.isOverflow()) { // assuming doWrite flushes the encoded // characters somewhere. output.flip(); doWrite(output); output.compact(); } } input.compact(); } // at end of input input.flip(); do { cr = encoder.encode(input, output, true); output.flip(); doWrite(output); output.compact(); } while (cr.isOverflow());
input
- the input buffer to encodeoutput
- the output buffer to receive the encoded resultsendOfInput
- set to true
if there is no more input, and any
remaining characters at the end of input will either be encoded or
replaced as invalid.CoderResult.UNDERFLOW
or CoderResult.OVERFLOW
. No other
CoderResult value will be returned. Characters or sequences
that might conceivably return and invalid or unmappable
character result (as part of the nio Charset API) are
automatically replaced to avoid security implications.java.nio.charset.CoderResult encodeArrays(java.nio.CharBuffer input, java.nio.CharBuffer output, boolean endOfInput)
input
- the input buffer.output
- the output buffer.endOfInput
- when true, this is the last input to encodejava.nio.charset.CoderResult encodeBuffers(java.nio.CharBuffer input, java.nio.CharBuffer output, boolean endOfInput) throws java.lang.UnsupportedOperationException
input
- the input buffer.output
- the output buffer.endOfInput
- when true, this is the last input to encodejava.lang.UnsupportedOperationException
- -- alwaysabstract int maxEncodedLength(int n)
n
characters.n
- the number of characters of inputabstract int firstEncodedOffset(java.lang.String input, int off, int len)
input
- the input to check for encodingoff
- the offset of the first character to checklen
- the number of characters to checkoff+len
if no characters in the input require encoding.static java.nio.charset.CoderResult overflow(java.nio.CharBuffer input, int i, java.nio.CharBuffer output, int j)
input
- the input bufferi
- the array offset in the input buffer (translated to position)output
- the output bufferj
- the array offset in the output buffer (translated to position)static java.nio.charset.CoderResult underflow(java.nio.CharBuffer input, int i, java.nio.CharBuffer output, int j)
input
- the input bufferi
- the array offset in the input buffer (translated to position)output
- the output bufferj
- the array offset in the output buffer (translated to position)