BaseNCodec (Apache Commons Codec 1.22.1 API)
Description: declaration: package: org.apache.commons.codec.binary, class: BaseNCodec

Package org.apache.commons.codec.binary

# Class BaseNCodec

java.lang.Object
org.apache.commons.codec.binary.BaseNCodec

All Implemented Interfaces:
  `BinaryDecoder`, `BinaryEncoder`, `Decoder`, `Encoder`

Direct Known Subclasses:
  `Base16`, `Base32`, `Base58`, `Base64`

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

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `BaseNCodec.AbstractBuilder<T,B extends BaseNCodec.AbstractBuilder<T,B>>`
  Builds `Base64` instances.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected static final CodecPolicy`
  `DECODING_POLICY_DEFAULT`
  The default decoding policy.
  `protected final int`
  `lineLength`
  Chunksize for encoding.
  `protected static final int`
  `MASK_8BITS`
  Mask used to extract 8 bits, used in decoding bytes
  `static final int`
  `MIME_CHUNK_SIZE`
  MIME chunk size per RFC 2045 section 6.8.
  `protected final byte`
  `pad`
  Pad byte.
  `protected final byte`
  `PAD`
  Deprecated.
  Use `pad`.
  `protected static final byte`
  `PAD_DEFAULT`
  Byte used to pad output.
  `static final int`
  `PEM_CHUNK_SIZE`
  PEM chunk size per RFC 1421 section 4.3.2.4.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `BaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength)`
  Deprecated.
  Use `BaseNCodec(AbstractBuilder)`.
  `protected`
  `BaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength, byte pad)`
  Deprecated.
  Use `BaseNCodec(AbstractBuilder)`.
  `protected`
  `BaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength, byte pad, CodecPolicy decodingPolicy)`
  Deprecated.
  Use `BaseNCodec(AbstractBuilder)`.
  `protected`
  `BaseNCodec(BaseNCodec.AbstractBuilder<?,?> builder)`
  Constructs a new instance for a subclass.

- ## Method Summary

  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[] array)`
  Decodes a byte[] containing characters in the Base-N alphabet.
  `Object`
  `decode(Object obj)`
  Decodes an Object using the Base-N algorithm.
  `byte[]`
  `decode(String array)`
  Decodes a String containing characters in the Base-N alphabet.
  `byte[]`
  `encode(byte[] array)`
  Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet.
  `byte[]`
  `encode(byte[] array, int offset, int length)`
  Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet.
  `Object`
  `encode(Object obj)`
  Encodes an Object using the Base-N algorithm.
  `String`
  `encodeAsString(byte[] array)`
  Encodes a byte[] containing binary data, into a String containing characters in the appropriate alphabet.
  `String`
  `encodeToString(byte[] array)`
  Encodes a byte[] containing binary data, into a String containing characters in the Base-N alphabet.
  `protected byte[]`
  `ensureBufferSize(int size, org.apache.commons.codec.binary.BaseNCodec.Context context)`
  Ensures that the buffer has room for `size` bytes
  `static byte[]`
  `getChunkSeparator()`
  Gets a copy of the chunk separator per RFC 2045 section 2.1.
  `CodecPolicy`
  `getCodecPolicy()`
  Gets the decoding behavior policy.
  `protected int`
  `getDefaultBufferSize()`
  Gets the default buffer size.
  `long`
  `getEncodedLength(byte[] array)`
  Gets the amount of space needed to encode the supplied array.
  `protected abstract boolean`
  `isInAlphabet(byte value)`
  Tests whether or not the `octet` is in the current alphabet.
  `boolean`
  `isInAlphabet(byte[] arrayOctet, boolean allowWhitespacePad)`
  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.
  `boolean`
  `isStrictDecoding()`
  Tests true if decoding behavior is strict.
  `protected static boolean`
  `isWhiteSpace(byte byteToCheck)`
  Deprecated.
  Use `Character.isWhitespace(int)`.

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

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

  - ### DECODING_POLICY_DEFAULT

    protected static final CodecPolicy DECODING_POLICY_DEFAULT
    The default decoding policy.
    Since:
      1.15

  - ### PAD

    @Deprecated protected final byte PAD
    Deprecated.
    Use `pad`. Will be removed in 2.0.
    Deprecated: Will be removed in 2.0.

    Instance variable just in case it needs to vary later

    See Also:
      - Constant Field Values

  - ### pad

    protected final byte pad
    Pad byte. Instance variable just in case it needs to vary later.

  - ### 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 the nearest multiple of encodedBlockSize.

- ## Constructor Details

  - ### BaseNCodec

    protected BaseNCodec(BaseNCodec.AbstractBuilder<?,?> builder)
    Constructs a new instance for a subclass.
    Parameters:
      `builder` - How to build this portion of the instance.
    Since:
      1.20.0

  - ### BaseNCodec

    @Deprecated protected BaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength)
    Deprecated.
    Use `BaseNCodec(AbstractBuilder)`.
    Constructs a new instance.

    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 (for example Base64 = 3).
      `encodedBlockSize` - The size of an encoded block (for example Base64 = 4).
      `lineLength` - if > 0, use chunking with a length `lineLength`.
      `chunkSeparatorLength` - The chunk separator length, if relevant.

  - ### BaseNCodec

    @Deprecated protected BaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength, byte pad)
    Deprecated.
    Use `BaseNCodec(AbstractBuilder)`.
    Constructs a new instance.

    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 (for example Base64 = 3).
      `encodedBlockSize` - The size of an encoded block (for example Base64 = 4).
      `lineLength` - if > 0, use chunking with a length `lineLength`.
      `chunkSeparatorLength` - The chunk separator length, if relevant.
      `pad` - byte used as padding byte.

  - ### BaseNCodec

    @Deprecated protected BaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength, byte pad, CodecPolicy decodingPolicy)
    Deprecated.
    Use `BaseNCodec(AbstractBuilder)`.
    Constructs a new instance.

    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 (for example Base64 = 3).
      `encodedBlockSize` - The size of an encoded block (for example Base64 = 4).
      `lineLength` - if > 0, use chunking with a length `lineLength`.
      `chunkSeparatorLength` - The chunk separator length, if relevant.
      `pad` - byte used as padding byte.
      `decodingPolicy` - Decoding policy.
    Since:
      1.15

- ## Method Details

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

    @Deprecated protected static boolean isWhiteSpace(byte byteToCheck)
    Deprecated.
    Use `Character.isWhitespace(int)`.
    Checks if a byte value is whitespace or not.
    Parameters:
      `byteToCheck` - The byte to check.
    Returns:
      true if byte is whitespace, false otherwise.
    See Also:
      - `Character.isWhitespace(int)`

  - ### 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[] array)
    Decodes a byte[] containing characters in the Base-N alphabet.
    Specified by:
      `decode` in interface `BinaryDecoder`
    Parameters:
      `array` - A byte array containing Base-N character data.
    Returns:
      A byte array containing binary data.

  - ### decode

    public Object decode(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(String array)
    Decodes a String containing characters in the Base-N alphabet.
    Parameters:
      `array` - A String containing Base-N character data.
    Returns:
      A byte array containing binary data.

  - ### encode

    public byte[] encode(byte[] array)
    Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet.
    Specified by:
      `encode` in interface `BinaryEncoder`
    Parameters:
      `array` - A byte array containing binary data.
    Returns:
      A byte array containing only the base N alphabetic character data.

  - ### encode

    public byte[] encode(byte[] array, int offset, int length)
    Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet.
    Parameters:
      `array` - 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 Object encode(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 String encodeAsString(byte[] array)
    Encodes a byte[] containing binary data, into a String containing characters in the appropriate alphabet. Uses UTF8 encoding.

    This is a duplicate of `encodeToString(byte[])`; it was merged during refactoring.

    Parameters:
      `array` - A byte array containing binary data.
    Returns:
      String containing only character data in the appropriate alphabet.
    Since:
      1.5

  - ### encodeToString

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

  - ### ensureBufferSize

    protected byte[] ensureBufferSize(int size, org.apache.commons.codec.binary.BaseNCodec.Context context)
    Ensures that the buffer has room for `size` bytes
    Parameters:
      `size` - minimum spare space required.
      `context` - The context to be used.
    Returns:
      The buffer.

  - ### getCodecPolicy

    public CodecPolicy getCodecPolicy()
    Gets 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

  - ### getDefaultBufferSize

    protected int getDefaultBufferSize()
    Gets the default buffer size. Can be overridden.
    Returns:
      The default buffer size.

  - ### getEncodedLength

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

  - ### isInAlphabet

    protected abstract boolean isInAlphabet(byte value)
    Tests 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 allowWhitespacePad)
    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.
      `allowWhitespacePad` - 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)`

  - ### isStrictDecoding

    public boolean isStrictDecoding()
    Tests 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