Class Encoder
- java.lang.Object
-
- org.owasp.encoder.Encoder
-
- Direct Known Subclasses:
CDATAEncoder
,ChainedEncoder
,CSSEncoder
,HTMLEncoder
,JavaEncoder
,JavaScriptEncoder
,URIEncoder
,XMLCommentEncoder
,XMLEncoder
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
-
-
Field Summary
Fields Modifier and Type Field 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 Summary
Constructors Constructor Description Encoder()
Package-private constructor to prevent having to support external implementations of this class.
-
Method Summary
All Methods Static Methods Instance Methods Abstract 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.(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 ofn
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.
-
-
-
Field Detail
-
HEX
static final char[] HEX
Hexadecimal conversion array. Package private to prevent corruption.
-
HEX_SHIFT
static final int HEX_SHIFT
Bit-shift used for encoding values in hexadecimal.- See Also:
- Constant Field Values
-
HEX_MASK
static final int HEX_MASK
Bit-mask used for encoding values in hexadecimal.- See Also:
- Constant Field Values
-
-
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.
-
encodeArrays
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. The loop is expected to fetch the arrays and interact with the arrays directly for performance.- Parameters:
input
- the input buffer.output
- the output buffer.endOfInput
- when true, this is the last input to encode- Returns:
- UNDERFLOW or OVERFLOW
-
encodeBuffers
java.nio.charset.CoderResult encodeBuffers(java.nio.CharBuffer input, java.nio.CharBuffer output, boolean endOfInput) throws java.lang.UnsupportedOperationException
The core encoding loop used when either or both input and output buffers are NOT array-backed. E.g. they are direct buffers or perhaps the input buffer is a read-only wrapper. In any case, this method is not currently implemented by any of the encoder implementations since it is not expected to be common use-case. The stub is included here for completeness and to demarcate where the non-array-backed use-case would be included.- Parameters:
input
- the input buffer.output
- the output buffer.endOfInput
- when true, this is the last input to encode- Returns:
- never returns.
- Throws:
java.lang.UnsupportedOperationException
- -- always
-
maxEncodedLength
abstract int maxEncodedLength(int n)
Returns the maximum encoded length (in chars) of an input sequence ofn
characters.- Parameters:
n
- the number of characters of input- Returns:
- the worst-case number of characters required to encode
-
firstEncodedOffset
abstract int firstEncodedOffset(java.lang.String input, int off, int len)
Scans the input string for the first character index that requires encoding. If the entire input does not require encoding then the length is returned. This method is used by the Encode.forXYZ methods to return input strings unchanged when possible.- Parameters:
input
- the input to check for encodingoff
- the offset of the first character to checklen
- the number of characters to check- Returns:
- the index of the first character to encode. The return value
will be
off+len
if no characters in the input require encoding.
-
overflow
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.- Parameters:
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)- Returns:
- CoderResult.OVERFLOW
-
underflow
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.- Parameters:
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)- Returns:
- CoderResult.UNDERFLOW
-
-