public abstract class BaseNCodec extends java.lang.Object implements BinaryEncoder, BinaryDecoder
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.IllegalArgumentException
if 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.
Modifier and Type | Class and Description |
---|---|
(package private) static class |
BaseNCodec.Context
Holds thread context so classes can be thread-safe.
|
Modifier and Type | Field and Description |
---|---|
(package private) static byte[] |
CHUNK_SEPARATOR
Chunk separator per RFC 2045 section 2.1.
|
private int |
chunkSeparatorLength
Size of chunk separator.
|
protected static CodecPolicy |
DECODING_POLICY_DEFAULT
The default decoding policy.
|
private CodecPolicy |
decodingPolicy
Defines the decoding behavior when the input bytes contain leftover trailing bits that
cannot be created by a valid encoding.
|
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
|
private static int |
MAX_BUFFER_SIZE
The maximum size buffer to allocate.
|
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.
|
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. |
protected |
BaseNCodec(int unencodedBlockSize,
int encodedBlockSize,
int lineLength,
int chunkSeparatorLength,
byte pad,
CodecPolicy decodingPolicy)
Note
lineLength is rounded down to the nearest multiple of the encoded block size. |
Modifier and Type | Method and Description |
---|---|
(package private) int |
available(BaseNCodec.Context context)
Returns the amount of buffered data available for reading.
|
private static int |
compareUnsigned(int x,
int y)
Compares two
int values numerically treating the values
as unsigned. |
protected boolean |
containsAlphabetOrPad(byte[] arrayOctet)
Tests a given byte array to see if it contains any characters within the alphabet or PAD.
|
private static int |
createPositiveCapacity(int minCapacity)
Create a positive capacity at least as large the minimum required capacity.
|
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.
|
byte[] |
encode(byte[] pArray,
int offset,
int length)
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 |
static byte[] |
getChunkSeparator()
Gets a copy of the chunk separator per RFC 2045 section 2.1.
|
CodecPolicy |
getCodecPolicy()
Returns the decoding behavior policy.
|
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.
|
boolean |
isStrictDecoding()
Returns true if decoding behavior is strict.
|
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 static byte[] |
resizeBuffer(BaseNCodec.Context context,
int minCapacity)
Increases our buffer by the
DEFAULT_BUFFER_RESIZE_FACTOR . |
static final int EOF
public static final int MIME_CHUNK_SIZE
The 76 character limit does not count the trailing CRLF, but counts all other characters, including any equal signs.
public static final int PEM_CHUNK_SIZE
The 64 character limit does not count the trailing CRLF, but counts all other characters, including any equal signs.
private static final int DEFAULT_BUFFER_RESIZE_FACTOR
private static final int DEFAULT_BUFFER_SIZE
private static final int MAX_BUFFER_SIZE
This is set to the same size used in the JDK java.util.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.
protected static final int MASK_8BITS
protected static final byte PAD_DEFAULT
protected static final CodecPolicy DECODING_POLICY_DEFAULT
static final byte[] CHUNK_SEPARATOR
@Deprecated protected final byte PAD
pad
. Will be removed in 2.0.protected final byte pad
private final int unencodedBlockSize
private final int encodedBlockSize
protected final int lineLength
private final int chunkSeparatorLength
lineLength
> 0.private final CodecPolicy decodingPolicy
true
to enable strict decoding.
IllegalArgumentException
if 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.
protected BaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength)
lineLength
is rounded down to the nearest multiple of the encoded block size.
If chunkSeparatorLength
is zero, then chunking is disabled.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 relevantprotected BaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength, byte pad)
lineLength
is rounded down to the nearest multiple of the encoded block size.
If chunkSeparatorLength
is zero, then chunking is disabled.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 relevantpad
- byte used as padding byte.protected BaseNCodec(int unencodedBlockSize, int encodedBlockSize, int lineLength, int chunkSeparatorLength, byte pad, CodecPolicy decodingPolicy)
lineLength
is rounded down to the nearest multiple of the encoded block size.
If chunkSeparatorLength
is zero, then chunking is disabled.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 relevantpad
- byte used as padding byte.decodingPolicy
- Decoding policy.private static int compareUnsigned(int x, int y)
int
values numerically treating the values
as unsigned. Taken from JDK 1.8.
TODO: Replace with JDK 1.8 Integer::compareUnsigned(int, int).
x
- the first int
to comparey
- the second int
to compare0
if x == y
; a value less
than 0
if x < y
as unsigned values; and
a value greater than 0
if x > y
as
unsigned valuesprivate static int createPositiveCapacity(int minCapacity)
minCapacity
- the minimum capacityjava.lang.OutOfMemoryError
- if the minCapacity
is negativepublic static byte[] getChunkSeparator()
protected static boolean isWhiteSpace(byte byteToCheck)
byteToCheck
- the byte to checkprivate static byte[] resizeBuffer(BaseNCodec.Context context, int minCapacity)
DEFAULT_BUFFER_RESIZE_FACTOR
.context
- the context to be usedminCapacity
- the minimum required capacityjava.lang.OutOfMemoryError
- if the minCapacity
is negativeint available(BaseNCodec.Context context)
context
- the context to be usedprotected boolean containsAlphabetOrPad(byte[] arrayOctet)
arrayOctet
- byte array to testtrue
if any byte is a valid character in the alphabet or PAD; false
otherwisepublic byte[] decode(byte[] pArray)
decode
in interface BinaryDecoder
pArray
- A byte array containing Base-N character dataabstract void decode(byte[] pArray, int i, int length, BaseNCodec.Context context)
public java.lang.Object decode(java.lang.Object obj) throws DecoderException
decode
in interface Decoder
obj
- Object to decodeDecoderException
- if the parameter supplied is not of type byte[]public byte[] decode(java.lang.String pArray)
pArray
- A String containing Base-N character datapublic byte[] encode(byte[] pArray)
encode
in interface BinaryEncoder
pArray
- a byte array containing binary datapublic byte[] encode(byte[] pArray, int offset, int length)
pArray
- a byte array containing binary dataoffset
- initial offset of the subarray.length
- length of the subarray.abstract void encode(byte[] pArray, int i, int length, BaseNCodec.Context context)
public java.lang.Object encode(java.lang.Object obj) throws EncoderException
encode
in interface Encoder
obj
- Object to encodeEncoderException
- if the parameter supplied is not of type byte[]public java.lang.String encodeAsString(byte[] pArray)
pArray
- a byte array containing binary dataencodeToString(byte[])
; it was merged during refactoring.public java.lang.String encodeToString(byte[] pArray)
pArray
- a byte array containing binary dataprotected byte[] ensureBufferSize(int size, BaseNCodec.Context context)
size
bytessize
- minimum spare space requiredcontext
- the context to be usedpublic CodecPolicy getCodecPolicy()
The default is lenient. If the decoding policy is strict, then decoding will raise an
IllegalArgumentException
if trailing bits are not part of a valid encoding. Decoding will compose
trailing bits into 8-bit bytes and discard the remainder.
protected int getDefaultBufferSize()
public long getEncodedLength(byte[] pArray)
pArray
- byte[] array which will later be encodedboolean hasData(BaseNCodec.Context context)
context
- the context to be usedprotected abstract boolean isInAlphabet(byte value)
octet
is in the current alphabet.
Does not allow whitespace or pad.value
- The value to testtrue
if the value is defined in the current alphabet, false
otherwise.public boolean isInAlphabet(byte[] arrayOctet, boolean allowWSPad)
arrayOctet
- byte array to testallowWSPad
- if true
, then whitespace and PAD are also allowedtrue
if all bytes are valid characters in the alphabet or if the byte array is empty;
false
, otherwisepublic boolean isInAlphabet(java.lang.String basen)
basen
- String to testtrue
if all characters in the String are valid characters in the alphabet or if
the String is empty; false
, otherwiseisInAlphabet(byte[], boolean)
public boolean isStrictDecoding()
IllegalArgumentException
if 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.
int readResults(byte[] b, int bPos, int bAvail, BaseNCodec.Context context)
Package protected for access from I/O streams.
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