Class BaseNCodec

  • Direct Known Subclasses:
    Base64

    public abstract class BaseNCodec
    extends Object
    Abstract superclass for Base-N encoders and decoders.

    This class is thread-safe.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected int lineLength
      Chunksize for encoding.
      protected static int MASK_8BITS
      Mask used to extract 8 bits, used in decoding bytes
      static int MIME_CHUNK_SIZE
      MIME chunk size per RFC 2045 section 6.8.
      protected byte pad  
      protected static byte PAD_DEFAULT
      Byte used to pad output.
      static int PEM_CHUNK_SIZE
      PEM chunk size per RFC 1421 section 4.3.2.4.
      protected static StringManager sm  
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected BaseNCodec​(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength)
      Note lineLength is rounded down to the nearest multiple of the encoded block size.
      protected BaseNCodec​(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength, byte pad)
      Note lineLength is rounded down to the nearest multiple of the encoded block size.
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      protected boolean containsAlphabetOrPad​(byte[] arrayOctet)
      Tests a given byte array to see if it contains any characters within the alphabet or PAD.
      byte[] decode​(byte[] pArray)
      Decodes a byte[] containing characters in the Base-N alphabet.
      byte[] decode​(byte[] pArray, int off, int len)  
      byte[] decode​(String pArray)
      Decodes a String containing characters in the Base-N alphabet.
      byte[] encode​(byte[] pArray)
      Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet.
      byte[] encode​(byte[] pArray, int offset, int length)
      Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet.
      String encodeAsString​(byte[] pArray)
      Encodes a byte[] containing binary data, into a String containing characters in the appropriate alphabet.
      String encodeToString​(byte[] pArray)
      Encodes a byte[] containing binary data, into a String containing characters in the Base-N alphabet.
      protected byte[] ensureBufferSize​(int size, org.apache.tomcat.util.codec.binary.BaseNCodec.Context context)
      Ensure that the buffer has room for size bytes
      static byte[] getChunkSeparator()
      Gets a copy of the chunk separator per RFC 2045 section 2.1.
      protected int getDefaultBufferSize()
      Get the default buffer size.
      long getEncodedLength​(byte[] pArray)
      Calculates the amount of space needed to encode the supplied array.
      protected abstract boolean isInAlphabet​(byte value)
      Returns whether or not the octet is in the current alphabet.
      boolean isInAlphabet​(byte[] arrayOctet, boolean allowWSPad)
      Tests a given byte array to see if it contains only valid characters within the alphabet.
      boolean isInAlphabet​(String basen)
      Tests a given String to see if it contains only valid characters within the alphabet.
      protected static boolean isWhiteSpace​(byte byteToCheck)
      Checks if a byte value is whitespace or not.
    • Field Detail

      • MIME_CHUNK_SIZE

        public static final int MIME_CHUNK_SIZE
        MIME chunk size per RFC 2045 section 6.8.

        The 76 character limit does not count the trailing CRLF, but counts all other characters, including any equal signs.

        See Also:
        RFC 2045 section 6.8, Constant Field Values
      • PEM_CHUNK_SIZE

        public static final int PEM_CHUNK_SIZE
        PEM chunk size per RFC 1421 section 4.3.2.4.

        The 64 character limit does not count the trailing CRLF, but counts all other characters, including any equal signs.

        See Also:
        RFC 1421 section 4.3.2.4, Constant Field Values
      • MASK_8BITS

        protected static final int MASK_8BITS
        Mask used to extract 8 bits, used in decoding bytes
        See Also:
        Constant Field Values
      • PAD_DEFAULT

        protected static final byte PAD_DEFAULT
        Byte used to pad output.
        See Also:
        Constant Field Values
      • pad

        protected final byte pad
      • lineLength

        protected final int lineLength
        Chunksize for encoding. Not used when decoding. A value of zero or less implies no chunking of the encoded data. Rounded down to nearest multiple of encodedBlockSize.
    • Constructor Detail

      • BaseNCodec

        protected BaseNCodec​(int unencodedBlockSize,
                             int encodedBlockSize,
                             int lineLength,
                             int chunkSeparatorLength)
        Note lineLength is rounded down to the nearest multiple of the encoded block size. If chunkSeparatorLength is zero, then chunking is disabled.
        Parameters:
        unencodedBlockSize - the size of an unencoded block (e.g. Base64 = 3)
        encodedBlockSize - the size of an encoded block (e.g. Base64 = 4)
        lineLength - if > 0, use chunking with a length lineLength
        chunkSeparatorLength - the chunk separator length, if relevant
      • BaseNCodec

        protected BaseNCodec​(int unencodedBlockSize,
                             int encodedBlockSize,
                             int lineLength,
                             int chunkSeparatorLength,
                             byte pad)
        Note lineLength is rounded down to the nearest multiple of the encoded block size. If chunkSeparatorLength is zero, then chunking is disabled.
        Parameters:
        unencodedBlockSize - the size of an unencoded block (e.g. Base64 = 3)
        encodedBlockSize - the size of an encoded block (e.g. Base64 = 4)
        lineLength - if > 0, use chunking with a length lineLength
        chunkSeparatorLength - the chunk separator length, if relevant
        pad - byte used as padding byte.
    • Method Detail

      • getChunkSeparator

        public static byte[] getChunkSeparator()
        Gets a copy of the chunk separator per RFC 2045 section 2.1.
        Returns:
        the chunk separator
        Since:
        1.15
        See Also:
        RFC 2045 section 2.1
      • isWhiteSpace

        protected static boolean isWhiteSpace​(byte byteToCheck)
        Checks if a byte value is whitespace or not. Whitespace is taken to mean: space, tab, CR, LF
        Parameters:
        byteToCheck - the byte to check
        Returns:
        true if byte is whitespace, false otherwise
      • containsAlphabetOrPad

        protected boolean containsAlphabetOrPad​(byte[] arrayOctet)
        Tests a given byte array to see if it contains any characters within the alphabet or PAD. Intended for use in checking line-ending arrays
        Parameters:
        arrayOctet - byte array to test
        Returns:
        true if any byte is a valid character in the alphabet or PAD; false otherwise
      • decode

        public byte[] decode​(byte[] pArray)
        Decodes a byte[] containing characters in the Base-N alphabet.
        Parameters:
        pArray - A byte array containing Base-N character data
        Returns:
        a byte array containing binary data
      • decode

        public byte[] decode​(byte[] pArray,
                             int off,
                             int len)
      • decode

        public byte[] decode​(String pArray)
        Decodes a String containing characters in the Base-N alphabet.
        Parameters:
        pArray - A String containing Base-N character data
        Returns:
        a byte array containing binary data
      • encode

        public byte[] encode​(byte[] pArray)
        Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet.
        Parameters:
        pArray - a byte array containing binary data
        Returns:
        A byte array containing only the base N alphabetic character data
      • encode

        public byte[] encode​(byte[] pArray,
                             int offset,
                             int length)
        Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet.
        Parameters:
        pArray - a byte array containing binary data
        offset - initial offset of the subarray.
        length - length of the subarray.
        Returns:
        A byte array containing only the base N alphabetic character data
        Since:
        1.11
      • encodeAsString

        public String encodeAsString​(byte[] pArray)
        Encodes a byte[] containing binary data, into a String containing characters in the appropriate alphabet. Uses UTF8 encoding.
        Parameters:
        pArray - a byte array containing binary data
        Returns:
        String containing only character data in the appropriate alphabet.
        Since:
        1.5 This is a duplicate of encodeToString(byte[]); it was merged during refactoring.
      • encodeToString

        public String encodeToString​(byte[] pArray)
        Encodes a byte[] containing binary data, into a String containing characters in the Base-N alphabet. Uses UTF8 encoding.
        Parameters:
        pArray - a byte array containing binary data
        Returns:
        A String containing only Base-N character data
      • ensureBufferSize

        protected byte[] ensureBufferSize​(int size,
                                          org.apache.tomcat.util.codec.binary.BaseNCodec.Context context)
        Ensure that the buffer has room for size bytes
        Parameters:
        size - minimum spare space required
        context - the context to be used
        Returns:
        the buffer
      • getDefaultBufferSize

        protected int getDefaultBufferSize()
        Get the default buffer size. Can be overridden.
        Returns:
        the default buffer size.
      • getEncodedLength

        public long getEncodedLength​(byte[] pArray)
        Calculates the amount of space needed to encode the supplied array.
        Parameters:
        pArray - byte[] array which will later be encoded
        Returns:
        amount of space needed to encoded the supplied array. Returns a long since a max-len array will require > Integer.MAX_VALUE
      • isInAlphabet

        protected abstract boolean isInAlphabet​(byte value)
        Returns whether or not the octet is in the current alphabet. Does not allow whitespace or pad.
        Parameters:
        value - The value to test
        Returns:
        true if the value is defined in the current alphabet, false otherwise.
      • isInAlphabet

        public boolean isInAlphabet​(byte[] arrayOctet,
                                    boolean allowWSPad)
        Tests a given byte array to see if it contains only valid characters within the alphabet. The method optionally treats whitespace and pad as valid.
        Parameters:
        arrayOctet - byte array to test
        allowWSPad - if true, then whitespace and PAD are also allowed
        Returns:
        true if all bytes are valid characters in the alphabet or if the byte array is empty; false, otherwise
      • isInAlphabet

        public boolean isInAlphabet​(String basen)
        Tests a given String to see if it contains only valid characters within the alphabet. The method treats whitespace and PAD as valid.
        Parameters:
        basen - String to test
        Returns:
        true if all characters in the String are valid characters in the alphabet or if the String is empty; false, otherwise
        See Also:
        isInAlphabet(byte[], boolean)