Package org.apache.commons.codec.binary

Class BaseNCodec

  • All Implemented Interfaces:
    BinaryDecoder, BinaryEncoder, Decoder, Encoder
    Direct Known Subclasses:
    Base16, Base32, Base64
    public abstract class BaseNCodec
extends java.lang.Object
implements BinaryEncoder, BinaryDecoder
    Abstract superclass for Base-N encoders and decoders.

    This class is thread-safe.

    You can set the decoding behavior when the input bytes contain leftover trailing bits that cannot be created by a valid encoding. These can be bits that are unused from the final character or entire characters. The default mode is lenient decoding.
    • Lenient: Any trailing bits are composed into 8-bit bytes where possible. The remainder are discarded.
    • Strict: The decoding will raise an IllegalArgumentException if trailing bits are not part of a valid encoding. Any unused bits from the final character must be zero. Impossible counts of entire final characters are not allowed.

    When strict decoding is enabled it is expected that the decoded bytes will be re-encoded to a byte array that matches the original, i.e. no changes occur on the final character. This requires that the input bytes use the same padding and alphabet as the encoder.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int MIME_CHUNK_SIZE
      MIME chunk size per RFC 2045 section 6.8.
      static int PEM_CHUNK_SIZE
      PEM chunk size per RFC 1421 section 4.3.2.4.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      byte[] decode​(byte[] pArray)
      Decodes a byte[] containing characters in the Base-N alphabet.
      java.lang.Object decode​(java.lang.Object obj)
      Decodes an Object using the Base-N algorithm.
      byte[] decode​(java.lang.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.
      java.lang.Object encode​(java.lang.Object obj)
      Encodes an Object using the Base-N algorithm.
      java.lang.String encodeAsString​(byte[] pArray)
      Encodes a byte[] containing binary data, into a String containing characters in the appropriate alphabet.
      java.lang.String encodeToString​(byte[] pArray)
      Encodes a byte[] containing binary data, into a String containing characters in the Base-N alphabet.
      static byte[] getChunkSeparator()
      Gets a copy of the chunk separator per RFC 2045 section 2.1.
      CodecPolicy getCodecPolicy()
      Returns the decoding behavior policy.
      long getEncodedLength​(byte[] pArray)
      Calculates the amount of space needed to encode the supplied array.
      boolean isInAlphabet​(byte[] arrayOctet, boolean allowWSPad)
      Tests a given byte array to see if it contains only valid characters within the alphabet.
      boolean isInAlphabet​(java.lang.String basen)
      Tests a given String to see if it contains only valid characters within the alphabet.
      boolean isStrictDecoding()
      Returns true if decoding behavior is strict.

      • Methods inherited from class java.lang.Object

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

    • 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

    • 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

      • decode

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

      • decode

        public java.lang.Object decode​(java.lang.Object obj)
                        throws DecoderException
        Decodes an Object using the Base-N algorithm. This method is provided in order to satisfy the requirements of the Decoder interface, and will throw a DecoderException if the supplied object is not of type byte[] or String.
        Specified by:
        decode in interface Decoder
        Parameters:
        obj - Object to decode
        Returns:
        An object (of type byte[]) containing the binary data which corresponds to the byte[] or String supplied.
        Throws:
        DecoderException - if the parameter supplied is not of type byte[]

      • decode

        public byte[] decode​(java.lang.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.
        Specified by:
        encode in interface BinaryEncoder
        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

      • encode

        public java.lang.Object encode​(java.lang.Object obj)
                        throws EncoderException
        Encodes an Object using the Base-N algorithm. This method is provided in order to satisfy the requirements of the Encoder interface, and will throw an EncoderException if the supplied object is not of type byte[].
        Specified by:
        encode in interface Encoder
        Parameters:
        obj - Object to encode
        Returns:
        An object (of type byte[]) containing the Base-N encoded data which corresponds to the byte[] supplied.
        Throws:
        EncoderException - if the parameter supplied is not of type byte[]

      • encodeAsString

        public java.lang.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 java.lang.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

      • getCodecPolicy

        public CodecPolicy getCodecPolicy()
        Returns the decoding behavior policy.

        The default is lenient. If the decoding policy is strict, then decoding will raise an IllegalArgumentException if trailing bits are not part of a valid encoding. Decoding will compose trailing bits into 8-bit bytes and discard the remainder.

        Returns:
        true if using strict decoding
        Since:
        1.15

      • 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

        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​(java.lang.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)

      • isStrictDecoding

        public boolean isStrictDecoding()
        Returns true if decoding behavior is strict. Decoding will raise an IllegalArgumentException if trailing bits are not part of a valid encoding.

        The default is false for lenient decoding. Decoding will compose trailing bits into 8-bit bytes and discard the remainder.

        Returns:
        true if using strict decoding
        Since:
        1.15