Class Encoder
- java.lang.Object
-
- org.owasp.encoder.Encoder
-
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)
withendOfInput
set totrue
.To use an Encoder instance directly, repeatedly call
encode(java.nio.CharBuffer, java.nio.CharBuffer, boolean)
with theendOfInput
parameter set tofalse
while there is (the possibility of) more input to encode. Once there is no more input to encode, callencode(java.nio.CharBuffer, java.nio.CharBuffer, boolean)
withendOfInput
set totrue
until the method returnsCoderResult.UNDERFLOW
.In general, this class is not expected to be needed directly. Use the
Encode
fluent interface for encoding Strings orEncodedWriter
for large blocks of contextual encoding.- See Also:
Encode
,EncodedWriter
-
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description java.nio.charset.CoderResult
encode(java.nio.CharBuffer input, java.nio.CharBuffer output, boolean endOfInput)
This is the kernel of encoding.
-
-
-
Method Detail
-
encode
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()
returnstrue
) 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 tofalse
while there is more input. Once there is no more input, this method should be calledendOfInput
set tofalse
untilCoderResult.UNDERFLOW
is returned.After any call to this method, except when
endOfInput
istrue
and the method returnsUNDERFLOW
, there may be characters left to encode in theinput
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());
- Parameters:
input
- the input buffer to encodeoutput
- the output buffer to receive the encoded resultsendOfInput
- set totrue
if there is no more input, and any remaining characters at the end of input will either be encoded or replaced as invalid.- Returns:
- Either
CoderResult.UNDERFLOW
orCoderResult.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.
-
-