org.apache.commons.codec.binary
Class BaseNCodec

java.lang.Object
  extended by org.apache.commons.codec.binary.BaseNCodec
All Implemented Interfaces:
BinaryDecoder, BinaryEncoder, Decoder, Encoder
Direct Known Subclasses:
Base32, Base64

public abstract class BaseNCodec
extends Object
implements BinaryEncoder, BinaryDecoder

Abstract superclass for Base-N encoders and decoders.

This class is thread-safe.

Version:
$Id: BaseNCodec.java 1382490 2012-09-09 13:10:38Z sebb $

Nested Class Summary
(package private) static class BaseNCodec.Context
          Holds thread context so classes can be thread-safe.
 
Field Summary
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 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
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.
 
Method Summary
(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)
           
 Object decode(Object obj)
          Decodes an Object using the Base-N algorithm.
 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.
(package private) abstract  void encode(byte[] pArray, int i, int length, BaseNCodec.Context context)
           
 Object encode(Object obj)
          Encodes an Object using the Base-N algorithm.
 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, 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(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

protected final byte PAD
See Also:
Constant Field Values

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

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 Object encode(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 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 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 Object decode(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(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(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.7-SNAPSHOT - Copyright © 2002-2013 - Apache Software Foundation