BaseNCodec (Apache Tomcat 10.1.16 API Documentation)
Description: declaration: package: org.apache.tomcat.util.codec.binary, class: BaseNCodec

Package org.apache.tomcat.util.codec.binary

# Class BaseNCodec

java.lang.Object
org.apache.tomcat.util.codec.binary.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 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 static final byte`
  `PAD_DEFAULT`
  Byte used to pad output.
  `protected static final 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

  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.
  `protected byte[]`
  `ensureBufferSize(int size, org.apache.tomcat.util.codec.binary.BaseNCodec.Context context)`
  Ensure that the buffer has room for `size` bytes
  `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.

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

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

- ## Field Details

  - ### sm

    protected static final StringManager sm

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

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

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

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