Class Encoder

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