Package org.owasp.encoder

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) 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.

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

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 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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

Constructor Detail

Encoder

Encoder()

Package-private constructor to prevent having to support external implementations of this class. This may be opened up in future releases.

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() 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());
 

Parameters:

input - the input buffer to encode

output - the output buffer to receive the encoded results

endOfInput - 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.

Returns:

Either 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.

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 of n 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 encoding

off - the offset of the first character to check

len - 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 buffer

i - the array offset in the input buffer (translated to position)

output - the output buffer

j - 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 buffer

i - the array offset in the input buffer (translated to position)

output - the output buffer

j - the array offset in the output buffer (translated to position)

Returns:

CoderResult.UNDERFLOW