BaseNCodec (Encode/Decode Utilities (Version 1.10))
Date: 2018-05-06

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:
    Base32, Base64

      public abstract class BaseNCodec
      extends java.lang.Object
      implements BinaryEncoder, BinaryDecoder

  Abstract superclass for Base-N encoders and decoders.

  This class is thread-safe.

  Version:
    $Id: BaseNCodec.java 1634404 2014-10-26 23:06:10Z ggregory $

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `(package private) static class` | `BaseNCodec.Context` Holds thread context so classes can be thread-safe.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private int` | `chunkSeparatorLength` Size of chunk separator.
    `private static int` | `DEFAULT_BUFFER_RESIZE_FACTOR`
    `private static int` | `DEFAULT_BUFFER_SIZE` Defines the default buffer size - currently 8192 - must be large enough for at least one encoded block+separator
    `private int` | `encodedBlockSize` Number of bytes in each full block of encoded data, e.g.
    `(package private) static int` | `EOF` EOF
    `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 byte` | `PAD` Deprecated. Use `pad`. Will be removed in 2.0.
    `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.
    `private int` | `unencodedBlockSize` Number of bytes in each full block of unencoded data, e.g.

  - ### 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 `encodedBlockSize` If `chunkSeparatorLength` is zero, then chunking is disabled.
    `protected` | `BaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength, byte pad)` Note `lineLength` is rounded down to the nearest multiple of `encodedBlockSize` If `chunkSeparatorLength` is zero, then chunking is disabled.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `(package private) int` | `available(BaseNCodec.Context context)` Returns the amount of buffered data available for reading.
    `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.
    `(package private) abstract void` | `decode(byte[] pArray, int i, int length, BaseNCodec.Context context)`
    `java.lang.Object` | `decode(java.lang.Object obj)` Decodes an Object using the Base-N algorithm.
    `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.
    `(package private) abstract void` | `encode(byte[] pArray, int i, int length, BaseNCodec.Context context)`
    `java.lang.Object` | `encode(java.lang.Object obj)` Encodes an Object using the Base-N algorithm.
    `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, 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.
    `(package private) boolean` | `hasData(BaseNCodec.Context context)` Returns true if this object has buffered data for reading.
    `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.
    `(package private) int` | `readResults(byte[] b, int bPos, int bAvail, BaseNCodec.Context context)` Extracts buffered data into the provided byte[] array, starting at position bPos, up to a maximum of bAvail bytes.
    `private byte[]` | `resizeBuffer(BaseNCodec.Context context)` Increases our buffer by the `DEFAULT_BUFFER_RESIZE_FACTOR`.

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

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

- - ### Field Detail

    - #### EOF

          static final int EOF

      EOF
      Since:
        1.7
      See Also:
        Constant Field Values

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

    - #### DEFAULT_BUFFER_RESIZE_FACTOR

          private static final int DEFAULT_BUFFER_RESIZE_FACTOR

      See Also:
        Constant Field Values

    - #### DEFAULT_BUFFER_SIZE

          private static final int DEFAULT_BUFFER_SIZE

      Defines the default buffer size - currently 8192 - must be large enough for at least one encoded block+separator
      See Also:
        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

          @Deprecated
          protected final byte PAD

      Deprecated. Use `pad`. Will be removed in 2.0.
      See Also:
        Constant Field Values

    - #### pad

          protected final byte pad

    - #### unencodedBlockSize

          private final int unencodedBlockSize

      Number of bytes in each full block of unencoded data, e.g. 4 for Base64 and 5 for Base32

    - #### encodedBlockSize

          private final int encodedBlockSize

      Number of bytes in each full block of encoded data, e.g. 3 for Base64 and 8 for Base32

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

    - #### chunkSeparatorLength

          private final int chunkSeparatorLength

      Size of chunk separator. Not used unless `lineLength` > 0.

  - ### Constructor Detail

    - #### BaseNCodec

          protected BaseNCodec(int unencodedBlockSize,
                    int encodedBlockSize,
                    int lineLength,
                    int chunkSeparatorLength)

      Note `lineLength` is rounded down to the nearest multiple of `encodedBlockSize` 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 `encodedBlockSize` 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

    - #### hasData

          boolean hasData(BaseNCodec.Context context)

      Returns true if this object has buffered data for reading.
      Parameters:
        `context` - the context to be used
      Returns:
        true if there is data still available for reading.

    - #### available

          int available(BaseNCodec.Context context)

      Returns the amount of buffered data available for reading.
      Parameters:
        `context` - the context to be used
      Returns:
        The amount of buffered data available for reading.

    - #### getDefaultBufferSize

          protected int getDefaultBufferSize()

      Get the default buffer size. Can be overridden.
      Returns:
        `DEFAULT_BUFFER_SIZE`

    - #### resizeBuffer

          private byte[] resizeBuffer(BaseNCodec.Context context)

      Increases our buffer by the `DEFAULT_BUFFER_RESIZE_FACTOR`.
      Parameters:
        `context` - the context to be used

    - #### ensureBufferSize

          protected byte[] ensureBufferSize(int size,
                                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

    - #### readResults

          int readResults(byte[] b,
                        int bPos,
                        int bAvail,
                        BaseNCodec.Context context)

      Extracts buffered data into the provided byte[] array, starting at position bPos, up to a maximum of bAvail bytes. Returns how many bytes were actually extracted.

      Package protected for access from I/O streams.

      Parameters:
        `b` - byte[] array to extract the buffered data into.
        `bPos` - position in byte[] array to start extraction at.
        `bAvail` - amount of bytes we're allowed to extract. We may extract fewer (if fewer are available).
        `context` - the context to be used
      Returns:
        The number of bytes successfully extracted into the provided byte[] array.

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

    - #### encode

          public java.lang.Object encode(java.lang.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[]

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

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

    - #### decode

          public java.lang.Object decode(java.lang.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(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

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

    - #### 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 basen alphabetic character data

    - #### encode

          abstract void encode(byte[] pArray,
                    int i,
                    int length,
                    BaseNCodec.Context context)

    - #### decode

          abstract void decode(byte[] pArray,
                    int i,
                    int length,
                    BaseNCodec.Context context)

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

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

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

commons-codec version 1.10 - Copyright © 2002-2018 - Apache Software Foundation