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

# Class BaseNCodec

java.lang.Object
org.apache.tomcat.util.codec.binary.BaseNCodec

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

Direct Known Subclasses:
  `Base64`

public abstract class BaseNCodec extends Object implements BinaryEncoder, BinaryDecoder
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.
  `static final int`
  `PEM_CHUNK_SIZE`
  PEM chunk size per RFC 1421 section 4.3.2.4.
  `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)`
  `Object`
  `decode(Object obj)`
  Deprecated.
  This unused method will be removed in Tomcat 9
  `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.
  `Object`
  `encode(Object obj)`
  Deprecated.
  This unused method will be removed in Tomcat 9
  `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.

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

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

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

  - ### decode

    @Deprecated public Object decode(Object obj) throws DecoderException
    Deprecated.
    This unused method will be removed in Tomcat 9
    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[]

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

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

  - ### encode

    @Deprecated public Object encode(Object obj) throws EncoderException
    Deprecated.
    This unused method will be removed in Tomcat 9
    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[]

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

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