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 and 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`
    `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 and 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

    Methods
    Modifier and Type | Method and 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 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

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

Copyright © 2000-2021 Apache Software Foundation. All Rights Reserved.