org.owasp.encoder

Class Encoder

java.lang.Object

org.owasp.encoder.Encoder

public abstract class Encoder
extends 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.

Author:

Jeff Ichnowski

See Also:

Encode, EncodedWriter

Method Summary

Modifier and Type	Method and Description
CoderResult	encode(CharBuffer input, CharBuffer output, boolean endOfInput) This is the kernel of encoding.

Methods inherited from class java.lang.Object

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

Method Detail

encode

public CoderResult encode(CharBuffer input,
                          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.