Class BaseNCodec
- All Implemented Interfaces:
BinaryDecoder,BinaryEncoder,Decoder,Encoder
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 ClassesModifier and TypeClassDescriptionstatic classBaseNCodec.AbstractBuilder<T,B extends BaseNCodec.AbstractBuilder<T, B>> BuildsBase64instances. -
Field Summary
FieldsModifier and TypeFieldDescriptionprotected static final CodecPolicyThe default decoding policy.protected final intChunksize for encoding.protected static final intMask used to extract 8 bits, used in decoding bytesstatic final intMIME chunk size per RFC 2045 section 6.8.protected final bytePad byte.protected final byteDeprecated.protected static final byteByte used to pad output.static final intPEM chunk size per RFC 1421 section 4.3.2.4. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotectedBaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength) Constructs a new instance.protectedBaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength, byte pad) Constructs a new instance.protectedBaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength, byte pad, CodecPolicy decodingPolicy) Constructs a new instance. -
Method Summary
Modifier and TypeMethodDescriptionprotected booleancontainsAlphabetOrPad(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.Decodes an Object using the Base-N algorithm.byte[]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.Encodes an Object using the Base-N algorithm.encodeAsString(byte[] pArray) Encodes a byte[] containing binary data, into a String containing characters in the appropriate alphabet.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.commons.codec.binary.BaseNCodec.Context context) Ensure that the buffer has room forsizebytesstatic byte[]Gets a copy of the chunk separator per RFC 2045 section 2.1.Returns the decoding behavior policy.protected intGets the default buffer size.longgetEncodedLength(byte[] pArray) Calculates the amount of space needed to encode the supplied array.protected abstract booleanisInAlphabet(byte value) Returns whether or not theoctetis in the current alphabet.booleanisInAlphabet(byte[] arrayOctet, boolean allowWSPad) Tests a given byte array to see if it contains only valid characters within the alphabet.booleanisInAlphabet(String basen) Tests a given String to see if it contains only valid characters within the alphabet.booleanReturns true if decoding behavior is strict.protected static booleanisWhiteSpace(byte byteToCheck) Deprecated.
-
Field Details
-
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:
-
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:
-
MASK_8BITS
Mask used to extract 8 bits, used in decoding bytes- See Also:
-
PAD_DEFAULT
Byte used to pad output.- See Also:
-
DECODING_POLICY_DEFAULT
The default decoding policy.- Since:
- 1.15
-
PAD
Deprecated.Usepad. Will be removed in 2.0.- See Also:
-
pad
Pad byte. Instance variable just in case it needs to vary later. -
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 Details
-
BaseNCodec
protected BaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength) 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 lengthlineLengthchunkSeparatorLength- the chunk separator length, if relevant
-
BaseNCodec
protected BaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength, byte pad) 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 lengthlineLengthchunkSeparatorLength- the chunk separator length, if relevantpad- byte used as padding byte.
-
BaseNCodec
protected BaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength, byte pad, CodecPolicy decodingPolicy) 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 lengthlineLengthchunkSeparatorLength- the chunk separator length, if relevantpad- byte used as padding byte.decodingPolicy- Decoding policy.- Since:
- 1.15
-
-
Method Details
-
getChunkSeparator
Gets a copy of the chunk separator per RFC 2045 section 2.1.- Returns:
- the chunk separator
- Since:
- 1.15
- See Also:
-
isWhiteSpace
Deprecated.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:
-
containsAlphabetOrPad
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
Decodes a byte[] containing characters in the Base-N alphabet.- Specified by:
decodein interfaceBinaryDecoder- Parameters:
pArray- A byte array containing Base-N character data- Returns:
- a byte array containing binary data
-
decode
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:
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
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
Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet.- Specified by:
encodein interfaceBinaryEncoder- Parameters:
pArray- a byte array containing binary data- Returns:
- A byte array containing only the base N alphabetic character data
-
encode
Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet.- Parameters:
pArray- a byte array containing binary dataoffset- 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
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:
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
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:
pArray- a byte array containing binary data- Returns:
- String containing only character data in the appropriate alphabet.
- Since:
- 1.5
-
encodeToString
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.commons.codec.binary.BaseNCodec.Context context) Ensure that the buffer has room forsizebytes- Parameters:
size- minimum spare space requiredcontext- the context to be used- Returns:
- the buffer
-
getCodecPolicy
Returns 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
Gets the default buffer size. Can be overridden.- Returns:
- the default buffer size.
-
getEncodedLength
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
Returns 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
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 testallowWSPad- 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
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:
-
isStrictDecoding
Returns 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
-
pad.