Class BaseNCodec
- java.lang.Object
-
- org.apache.commons.codec.binary.BaseNCodec
-
- All Implemented Interfaces:
BinaryDecoder,BinaryEncoder,Decoder,Encoder
public abstract class BaseNCodec extends java.lang.Object implements BinaryEncoder, BinaryDecoder
Abstract superclass for Base-N encoders and decoders.This class is thread-safe.
You can set the decoding behavior when the input bytes contain leftover trailing bits that cannot be created by a valid encoding. These can be bits that are unused from the final character or entire characters. The default mode is lenient decoding.
- Lenient: Any trailing bits are composed into 8-bit bytes where possible. The remainder are discarded.
- Strict: The decoding will raise an
IllegalArgumentExceptionif trailing bits are not part of a valid encoding. Any unused bits from the final character must be zero. Impossible counts of entire final characters are not allowed.
When strict decoding is enabled it is expected that the decoded bytes will be re-encoded to a byte array that matches the original, i.e. no changes occur on the final character. This requires that the input bytes use the same padding and alphabet as the encoder.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static classBaseNCodec.AbstractBuilder<T,B extends BaseNCodec.AbstractBuilder<T,B>>BuildsBase64instances.(package private) static classBaseNCodec.ContextHolds thread context so classes can be thread-safe.
-
Field Summary
Fields Modifier and Type Field Description (package private) static byte[]CHUNK_SEPARATORChunk separator per RFC 2045 section 2.1.private intchunkSeparatorLengthSize of chunk separator.(package private) byte[]decodeTableDecode table to use.protected static CodecPolicyDECODING_POLICY_DEFAULTThe default decoding policy.private CodecPolicydecodingPolicyDefines the decoding behavior when the input bytes contain leftover trailing bits that cannot be created by a valid encoding.private static intDEFAULT_BUFFER_RESIZE_FACTORprivate static intDEFAULT_BUFFER_SIZEDefines the default buffer size - currently 8192 - must be large enough for at least one encoded block+separator(package private) static byte[]EMPTY_BYTE_ARRAYThe empty byte array.private intencodedBlockSizeNumber of bytes in each full block of encoded data, for example 3 for Base64 and 8 for Base32(package private) byte[]encodeTableEncode table.(package private) static intEOFEnd-of-file marker.protected intlineLengthChunksize for encoding.protected static intMASK_8BITSMask used to extract 8 bits, used in decoding bytesprivate static intMAX_BUFFER_SIZEThe maximum size buffer to allocate.static intMIME_CHUNK_SIZEMIME chunk size per RFC 2045 section 6.8.protected bytepadPad byte.protected bytePADDeprecated.Usepad.protected static bytePAD_DEFAULTByte used to pad output.static intPEM_CHUNK_SIZEPEM chunk size per RFC 1421 section 4.3.2.4.private intunencodedBlockSizeNumber of bytes in each full block of unencoded data, for example 4 for Base64 and 5 for Base32
-
Constructor Summary
Constructors Modifier Constructor Description protectedBaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength)Deprecated.protectedBaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength, byte pad)Deprecated.protectedBaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength, byte pad, CodecPolicy decodingPolicy)Deprecated.protectedBaseNCodec(BaseNCodec.AbstractBuilder<?,?> builder)Constructs a new instance for a subclass.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods Modifier and Type Method Description (package private) intavailable(BaseNCodec.Context context)Returns the amount of buffered data available for reading.protected booleancontainsAlphabetOrPad(byte[] arrayOctet)Tests a given byte array to see if it contains any characters within the alphabet or PAD.private static intcreatePositiveCapacity(int minCapacity)Create a positive capacity at least as large the minimum required capacity.byte[]decode(byte[] array)Decodes a byte[] containing characters in the Base-N alphabet.(package private) abstract voiddecode(byte[] array, int i, int length, BaseNCodec.Context context)java.lang.Objectdecode(java.lang.Object obj)Decodes an Object using the Base-N algorithm.byte[]decode(java.lang.String array)Decodes a String containing characters in the Base-N alphabet.byte[]encode(byte[] array)Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet.byte[]encode(byte[] array, int offset, int length)Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet.(package private) abstract voidencode(byte[] array, int i, int length, BaseNCodec.Context context)java.lang.Objectencode(java.lang.Object obj)Encodes an Object using the Base-N algorithm.java.lang.StringencodeAsString(byte[] array)Encodes a byte[] containing binary data, into a String containing characters in the appropriate alphabet.java.lang.StringencodeToString(byte[] array)Encodes a byte[] containing binary data, into a String containing characters in the Base-N alphabet.protected byte[]ensureBufferSize(int size, BaseNCodec.Context context)Ensures that the buffer has room forsizebytesstatic byte[]getChunkSeparator()Gets a copy of the chunk separator per RFC 2045 section 2.1.CodecPolicygetCodecPolicy()Gets the decoding behavior policy.protected intgetDefaultBufferSize()Gets the default buffer size.longgetEncodedLength(byte[] array)Gets the amount of space needed to encode the supplied array.(package private) static intgetLength(byte[] array)Gets the array length or 0 if null.(package private) booleanhasData(BaseNCodec.Context context)Tests whether this object has buffered data for reading.protected abstract booleanisInAlphabet(byte value)Tests whether or not theoctetis in the current alphabet.booleanisInAlphabet(byte[] arrayOctet, boolean allowWhitespacePad)Tests a given byte array to see if it contains only valid characters within the alphabet.(package private) static booleanisInAlphabet(byte value, byte[] table)Tests whether or not thevalueis in the giventable.booleanisInAlphabet(java.lang.String basen)Tests a given String to see if it contains only valid characters within the alphabet.booleanisStrictDecoding()Tests true if decoding behavior is strict.protected static booleanisWhiteSpace(byte byteToCheck)Deprecated.UseCharacter.isWhitespace(int).(package private) intreadResults(byte[] b, int position, int available, BaseNCodec.Context context)Reads buffered data into the provided byte[] array, starting at position bPos, up to a maximum of bAvail bytes.private static byte[]resizeBuffer(BaseNCodec.Context context, int minCapacity)Increases our buffer by theDEFAULT_BUFFER_RESIZE_FACTOR.
-
-
-
Field Detail
-
EOF
static final int EOF
End-of-file marker.- 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
-
MAX_BUFFER_SIZE
private static final int MAX_BUFFER_SIZE
The maximum size buffer to allocate.This is set to the same size used in the JDK
ArrayList:Some VMs reserve some header words in an array. Attempts to allocate larger arrays may result in OutOfMemoryError: Requested array size exceeds VM limit.
- 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
-
DECODING_POLICY_DEFAULT
protected static final CodecPolicy DECODING_POLICY_DEFAULT
The default decoding policy.- Since:
- 1.15
-
CHUNK_SEPARATOR
static final byte[] CHUNK_SEPARATOR
Chunk separator per RFC 2045 section 2.1.- See Also:
- RFC 2045 section 2.1
-
EMPTY_BYTE_ARRAY
static final byte[] EMPTY_BYTE_ARRAY
The empty byte array.
-
PAD
@Deprecated protected final byte PAD
Deprecated.Usepad. Will be removed in 2.0.Deprecated: Will be removed in 2.0.Instance variable just in case it needs to vary later
- See Also:
- Constant Field Values
-
pad
protected final byte pad
Pad byte. Instance variable just in case it needs to vary later.
-
unencodedBlockSize
private final int unencodedBlockSize
Number of bytes in each full block of unencoded data, for example 4 for Base64 and 5 for Base32
-
encodedBlockSize
private final int encodedBlockSize
Number of bytes in each full block of encoded data, for example 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 the nearest multiple of encodedBlockSize.
-
chunkSeparatorLength
private final int chunkSeparatorLength
Size of chunk separator. Not used unlesslineLength> 0.
-
decodingPolicy
private final CodecPolicy decodingPolicy
Defines the decoding behavior when the input bytes contain leftover trailing bits that cannot be created by a valid encoding. These can be bits that are unused from the final character or entire characters. The default mode is lenient decoding. Set this totrueto enable strict decoding.- Lenient: Any trailing bits are composed into 8-bit bytes where possible. The remainder are discarded.
- Strict: The decoding will raise an
IllegalArgumentExceptionif trailing bits are not part of a valid encoding. Any unused bits from the final character must be zero. Impossible counts of entire final characters are not allowed.
When strict decoding is enabled it is expected that the decoded bytes will be re-encoded to a byte array that matches the original, i.e. no changes occur on the final character. This requires that the input bytes use the same padding and alphabet as the encoder.
-
decodeTable
final byte[] decodeTable
Decode table to use.
-
encodeTable
final byte[] encodeTable
Encode table.
-
-
Constructor Detail
-
BaseNCodec
protected BaseNCodec(BaseNCodec.AbstractBuilder<?,?> builder)
Constructs a new instance for a subclass.- Parameters:
builder- How to build this portion of the instance.- Since:
- 1.20.0
-
BaseNCodec
@Deprecated protected BaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength)Deprecated.Constructs a new instance.Note
lineLengthis rounded down to the nearest multiple of the encoded block size. IfchunkSeparatorLengthis zero, then chunking is disabled.- Parameters:
unencodedBlockSize- the size of an unencoded block (for example Base64 = 3).encodedBlockSize- the size of an encoded block (for example Base64 = 4).lineLength- if > 0, use chunking with a lengthlineLength.chunkSeparatorLength- the chunk separator length, if relevant.
-
BaseNCodec
@Deprecated protected BaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength, byte pad)Deprecated.Constructs a new instance.Note
lineLengthis rounded down to the nearest multiple of the encoded block size. IfchunkSeparatorLengthis zero, then chunking is disabled.- Parameters:
unencodedBlockSize- the size of an unencoded block (for example Base64 = 3).encodedBlockSize- the size of an encoded block (for example Base64 = 4).lineLength- if > 0, use chunking with a lengthlineLength.chunkSeparatorLength- the chunk separator length, if relevant.pad- byte used as padding byte.
-
BaseNCodec
@Deprecated protected BaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength, byte pad, CodecPolicy decodingPolicy)Deprecated.Constructs a new instance.Note
lineLengthis rounded down to the nearest multiple of the encoded block size. IfchunkSeparatorLengthis zero, then chunking is disabled.- Parameters:
unencodedBlockSize- the size of an unencoded block (for example Base64 = 3).encodedBlockSize- the size of an encoded block (for example Base64 = 4).lineLength- if > 0, use chunking with a lengthlineLength.chunkSeparatorLength- the chunk separator length, if relevant.pad- byte used as padding byte.decodingPolicy- Decoding policy.- Since:
- 1.15
-
-
Method Detail
-
createPositiveCapacity
private static int createPositiveCapacity(int minCapacity)
Create a positive capacity at least as large the minimum required capacity. If the minimum capacity is negative then this throws an OutOfMemoryError as no array can be allocated.- Parameters:
minCapacity- the minimum capacity.- Returns:
- the capacity.
- Throws:
java.lang.OutOfMemoryError- if theminCapacityis negative.
-
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
-
getLength
static int getLength(byte[] array)
Gets the array length or 0 if null.- Parameters:
array- the array or null.- Returns:
- the array length or 0 if null.
-
isInAlphabet
static boolean isInAlphabet(byte value, byte[] table)Tests whether or not thevalueis in the giventable.- Parameters:
value- The value to test.table- The table to test against.- Returns:
trueif the value is in the table,falseotherwise.
-
isWhiteSpace
@Deprecated protected static boolean isWhiteSpace(byte byteToCheck)
Deprecated.UseCharacter.isWhitespace(int).Checks if a byte value is whitespace or not.- Parameters:
byteToCheck- the byte to check.- Returns:
- true if byte is whitespace, false otherwise.
- See Also:
Character.isWhitespace(int)
-
resizeBuffer
private static byte[] resizeBuffer(BaseNCodec.Context context, int minCapacity)
Increases our buffer by theDEFAULT_BUFFER_RESIZE_FACTOR.- Parameters:
context- the context to be used.minCapacity- the minimum required capacity.- Returns:
- the resized byte[] buffer.
- Throws:
java.lang.OutOfMemoryError- if theminCapacityis negative.
-
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.
-
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:
trueif any byte is a valid character in the alphabet or PAD;falseotherwise.
-
decode
public byte[] decode(byte[] array)
Decodes a byte[] containing characters in the Base-N alphabet.- Specified by:
decodein interfaceBinaryDecoder- Parameters:
array- A byte array containing Base-N character data.- Returns:
- a byte array containing binary data.
-
decode
abstract void decode(byte[] array, int i, int length, BaseNCodec.Context context)
-
decode
public java.lang.Object decode(java.lang.Object obj) throws DecoderExceptionDecodes 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:
decodein interfaceDecoder- 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 array)
Decodes a String containing characters in the Base-N alphabet.- Parameters:
array- A String containing Base-N character data.- Returns:
- a byte array containing binary data.
-
encode
public byte[] encode(byte[] array)
Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet.- Specified by:
encodein interfaceBinaryEncoder- Parameters:
array- a byte array containing binary data.- Returns:
- A byte array containing only the base N alphabetic character data.
-
encode
public byte[] encode(byte[] array, int offset, int length)Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet.- Parameters:
array- 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
-
encode
abstract void encode(byte[] array, int i, int length, BaseNCodec.Context context)
-
encode
public java.lang.Object encode(java.lang.Object obj) throws EncoderExceptionEncodes 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:
encodein interfaceEncoder- 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[].
-
encodeAsString
public java.lang.String encodeAsString(byte[] array)
Encodes a byte[] containing binary data, into a String containing characters in the appropriate alphabet. Uses UTF8 encoding.This is a duplicate of
encodeToString(byte[]); it was merged during refactoring.- Parameters:
array- a byte array containing binary data.- Returns:
- String containing only character data in the appropriate alphabet.
- Since:
- 1.5
-
encodeToString
public java.lang.String encodeToString(byte[] array)
Encodes a byte[] containing binary data, into a String containing characters in the Base-N alphabet. Uses UTF8 encoding.- Parameters:
array- a byte array containing binary data.- Returns:
- A String containing only Base-N character data.
-
ensureBufferSize
protected byte[] ensureBufferSize(int size, BaseNCodec.Context context)Ensures that the buffer has room forsizebytes- Parameters:
size- minimum spare space required.context- the context to be used.- Returns:
- the buffer.
-
getCodecPolicy
public CodecPolicy getCodecPolicy()
Gets the decoding behavior policy.The default is lenient. If the decoding policy is strict, then decoding will raise an
IllegalArgumentExceptionif trailing bits are not part of a valid encoding. Decoding will compose trailing bits into 8-bit bytes and discard the remainder.- Returns:
- true if using strict decoding.
- Since:
- 1.15
-
getDefaultBufferSize
protected int getDefaultBufferSize()
Gets the default buffer size. Can be overridden.- Returns:
- the default buffer size.
-
getEncodedLength
public long getEncodedLength(byte[] array)
Gets the amount of space needed to encode the supplied array.- Parameters:
array- 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.
-
hasData
boolean hasData(BaseNCodec.Context context)
Tests whether this object has buffered data for reading.- Parameters:
context- the context to be used.- Returns:
- true if there is data still available for reading.
-
isInAlphabet
protected abstract boolean isInAlphabet(byte value)
Tests whether or not theoctetis in the current alphabet. Does not allow whitespace or pad.- Parameters:
value- The value to test.- Returns:
trueif the value is defined in the current alphabet,falseotherwise.
-
isInAlphabet
public boolean isInAlphabet(byte[] arrayOctet, boolean allowWhitespacePad)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.allowWhitespacePad- iftrue, then whitespace and PAD are also allowed.- Returns:
trueif 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:
trueif all characters in the String are valid characters in the alphabet or if the String is empty;false, otherwise.- See Also:
isInAlphabet(byte[], boolean)
-
isStrictDecoding
public boolean isStrictDecoding()
Tests true if decoding behavior is strict. Decoding will raise anIllegalArgumentExceptionif trailing bits are not part of a valid encoding.The default is false for lenient decoding. Decoding will compose trailing bits into 8-bit bytes and discard the remainder.
- Returns:
- true if using strict decoding.
- Since:
- 1.15
-
readResults
int readResults(byte[] b, int position, int available, BaseNCodec.Context context)Reads 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 private for access from I/O streams.
- Parameters:
b- byte[] array to extract the buffered data into.position- position in byte[] array to start extraction at.available- 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.
-
-