BaseNCodec (Apache Tomcat 9.0.73 API Documentation)

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 java.lang.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` | Pad byte.
    `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​(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.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.
    `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​(java.lang.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 Detail

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

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