This is an automated email from the ASF dual-hosted git repository. ggregory pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/commons-codec.git
commit 42de0206fd6494d57727d9f139ae6be385214c7c Author: Gary D. Gregory <[email protected]> AuthorDate: Sun Oct 12 18:43:47 2025 -0400 Internal refactoring Deprecate some old constructors --- .../org/apache/commons/codec/binary/Base16.java | 7 - .../org/apache/commons/codec/binary/Base32.java | 6 - .../org/apache/commons/codec/binary/Base64.java | 9 - .../apache/commons/codec/binary/BaseNCodec.java | 316 +++++++++------------ 4 files changed, 128 insertions(+), 210 deletions(-) diff --git a/src/main/java/org/apache/commons/codec/binary/Base16.java b/src/main/java/org/apache/commons/codec/binary/Base16.java index 99e1f0e6..ba3c5d1f 100644 --- a/src/main/java/org/apache/commons/codec/binary/Base16.java +++ b/src/main/java/org/apache/commons/codec/binary/Base16.java @@ -18,7 +18,6 @@ package org.apache.commons.codec.binary; import java.util.Arrays; -import java.util.Objects; import org.apache.commons.codec.CodecPolicy; @@ -157,11 +156,6 @@ public class Base16 extends BaseNCodec { */ private final byte[] decodeTable; - /** - * Encode table to use. - */ - private final byte[] encodeTable; - /** * Constructs a Base16 codec used for decoding and encoding. */ @@ -194,7 +188,6 @@ public class Base16 extends BaseNCodec { private Base16(final Builder builder) { super(builder); - this.encodeTable = Objects.requireNonNull(builder.getEncodeTable(), "encodeTable"); this.decodeTable = Arrays.equals(encodeTable, LOWER_CASE_ENCODE_TABLE) ? LOWER_CASE_DECODE_TABLE : UPPER_CASE_DECODE_TABLE; } diff --git a/src/main/java/org/apache/commons/codec/binary/Base32.java b/src/main/java/org/apache/commons/codec/binary/Base32.java index 0beac482..0314712d 100644 --- a/src/main/java/org/apache/commons/codec/binary/Base32.java +++ b/src/main/java/org/apache/commons/codec/binary/Base32.java @@ -280,11 +280,6 @@ public class Base32 extends BaseNCodec { */ private final int encodeSize; - /** - * Encode table to use. - */ - private final byte[] encodeTable; - /** * Line separator for encoding. Not used when decoding. Only used if lineLength > 0. */ @@ -344,7 +339,6 @@ public class Base32 extends BaseNCodec { private Base32(final Builder builder) { super(builder); Objects.requireNonNull(builder.getEncodeTable(), "encodeTable"); - this.encodeTable = builder.getEncodeTable(); this.decodeTable = Arrays.equals(builder.getEncodeTable(), HEX_ENCODE_TABLE) ? HEX_DECODE_TABLE : DECODE_TABLE; if (builder.getLineLength() > 0) { final byte[] lineSeparator = builder.getLineSeparator(); diff --git a/src/main/java/org/apache/commons/codec/binary/Base64.java b/src/main/java/org/apache/commons/codec/binary/Base64.java index 9950d04d..803722ae 100644 --- a/src/main/java/org/apache/commons/codec/binary/Base64.java +++ b/src/main/java/org/apache/commons/codec/binary/Base64.java @@ -505,14 +505,6 @@ public class Base64 extends BaseNCodec { return urlSafe ? URL_SAFE_ENCODE_TABLE : STANDARD_ENCODE_TABLE; } - /** - * Encode table to use: either STANDARD or URL_SAFE or custom. - * Note: the DECODE_TABLE above remains static because it is able - * to decode both STANDARD and URL_SAFE streams, but the encodeTable must be a member variable so we can switch - * between the two modes. - */ - private final byte[] encodeTable; - /** * Decode table to use. */ @@ -698,7 +690,6 @@ public class Base64 extends BaseNCodec { } this.isStandardEncodeTable = Arrays.equals(builder.getEncodeTable(), STANDARD_ENCODE_TABLE); this.isUrlSafe = Arrays.equals(builder.getEncodeTable(), URL_SAFE_ENCODE_TABLE); - this.encodeTable = builder.getEncodeTable(); this.decodeTable = this.isStandardEncodeTable || this.isUrlSafe ? DECODE_TABLE : calculateDecodeTable(this.encodeTable); // TODO could be simplified if there is no requirement to reject invalid line sep when length <=0 // @see test case Base64Test.testConstructors() diff --git a/src/main/java/org/apache/commons/codec/binary/BaseNCodec.java b/src/main/java/org/apache/commons/codec/binary/BaseNCodec.java index fde69ca1..8b8e4814 100644 --- a/src/main/java/org/apache/commons/codec/binary/BaseNCodec.java +++ b/src/main/java/org/apache/commons/codec/binary/BaseNCodec.java @@ -34,20 +34,17 @@ import org.apache.commons.codec.EncoderException; * This class is thread-safe. * </p> * <p> - * 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. + * 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. * </p> * <ul> * <li>Lenient: Any trailing bits are composed into 8-bit bytes where possible. The remainder are discarded. - * <li>Strict: The decoding will raise an {@link 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. + * <li>Strict: The decoding will raise an {@link 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. * </ul> * <p> - * 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. + * 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. * </p> */ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { @@ -81,6 +78,7 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { * <p> * This is the same as the expression: * </p> + * * <pre> * (B) this * </pre> @@ -207,7 +205,6 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { this.unencodedBlockSize = unencodedBlockSize; return asThis(); } - } /** @@ -218,47 +215,36 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { static class Context { /** - * Placeholder for the bytes we're dealing with for our based logic. - * Bitwise operations store and extract the encoding or decoding from this variable. + * Placeholder for the bytes we're dealing with for our based logic. Bitwise operations store and extract the encoding or decoding from this variable. */ int ibitWorkArea; - /** - * Placeholder for the bytes we're dealing with for our based logic. - * Bitwise operations store and extract the encoding or decoding from this variable. + * Placeholder for the bytes we're dealing with for our based logic. Bitwise operations store and extract the encoding or decoding from this variable. */ long lbitWorkArea; - /** * Buffer for streaming. */ byte[] buffer; - /** * Position where next character should be written in the buffer. */ int pos; - /** * Position where next character should be read from the buffer. */ int readPos; - /** - * Boolean flag to indicate the EOF has been reached. Once EOF has been reached, this object becomes useless, - * and must be thrown away. + * Boolean flag to indicate the EOF has been reached. Once EOF has been reached, this object becomes useless, and must be thrown away. */ boolean eof; - /** - * Variable tracks how many characters have been written to the current line. Only used when encoding. We use - * it to make sure each encoded line never goes beyond lineLength (if lineLength > 0). + * Variable tracks how many characters have been written to the current line. Only used when encoding. We use it to make sure each encoded line never + * goes beyond lineLength (if lineLength > 0). */ int currentLinePos; - /** - * Writes to the buffer only occur after every 3/5 reads when encoding, and every 4/8 reads when decoding. This - * variable helps track that. + * Writes to the buffer only occur after every 3/5 reads when encoding, and every 4/8 reads when decoding. This variable helps track that. */ int modulus; @@ -269,9 +255,8 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { */ @Override public String toString() { - return String.format("%s[buffer=%s, currentLinePos=%s, eof=%s, ibitWorkArea=%s, lbitWorkArea=%s, " + - "modulus=%s, pos=%s, readPos=%s]", this.getClass().getSimpleName(), Arrays.toString(buffer), - currentLinePos, eof, ibitWorkArea, lbitWorkArea, modulus, pos, readPos); + return String.format("%s[buffer=%s, currentLinePos=%s, eof=%s, ibitWorkArea=%s, lbitWorkArea=%s, " + "modulus=%s, pos=%s, readPos=%s]", + this.getClass().getSimpleName(), Arrays.toString(buffer), currentLinePos, eof, ibitWorkArea, lbitWorkArea, modulus, pos, readPos); } } @@ -281,82 +266,67 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { * @since 1.7 */ static final int EOF = -1; - /** - * MIME chunk size per RFC 2045 section 6.8. + * MIME chunk size per RFC 2045 section 6.8. * * <p> - * The {@value} character limit does not count the trailing CRLF, but counts all other characters, including any - * equal signs. + * The {@value} character limit does not count the trailing CRLF, but counts all other characters, including any equal signs. * </p> * * @see <a href="http://www.ietf.org/rfc/rfc2045.txt";>RFC 2045 section 6.8</a> */ public static final int MIME_CHUNK_SIZE = 76; - /** * PEM chunk size per RFC 1421 section 4.3.2.4. * * <p> - * The {@value} character limit does not count the trailing CRLF, but counts all other characters, including any - * equal signs. + * The {@value} character limit does not count the trailing CRLF, but counts all other characters, including any equal signs. * </p> * * @see <a href="https://tools.ietf.org/html/rfc1421";>RFC 1421 section 4.3.2.4</a> */ public static final int PEM_CHUNK_SIZE = 64; - private static final int DEFAULT_BUFFER_RESIZE_FACTOR = 2; - /** - * Defines the default buffer size - currently {@value} - * - must be large enough for at least one encoded block+separator + * Defines the default buffer size - currently {@value} - must be large enough for at least one encoded block+separator */ private static final int DEFAULT_BUFFER_SIZE = 8192; - /** * The maximum size buffer to allocate. * - * <p>This is set to the same size used in the JDK {@link java.util.ArrayList}:</p> - * <blockquote> - * Some VMs reserve some header words in an array. - * Attempts to allocate larger arrays may result in - * OutOfMemoryError: Requested array size exceeds VM limit. - * </blockquote> + * <p> + * This is set to the same size used in the JDK {@link java.util.ArrayList}: + * </p> + * <blockquote> Some VMs reserve some header words in an array. Attempts to allocate larger arrays may result in OutOfMemoryError: Requested array size + * exceeds VM limit. </blockquote> */ private static final int MAX_BUFFER_SIZE = Integer.MAX_VALUE - 8; - /** Mask used to extract 8 bits, used in decoding bytes */ protected static final int MASK_8BITS = 0xff; - /** * Byte used to pad output. */ protected static final byte PAD_DEFAULT = '='; // Allow static access to default - /** * The default decoding policy. * * @since 1.15 */ protected static final CodecPolicy DECODING_POLICY_DEFAULT = CodecPolicy.LENIENT; - /** * Chunk separator per RFC 2045 section 2.1. * * @see <a href="http://www.ietf.org/rfc/rfc2045.txt";>RFC 2045 section 2.1</a> */ - static final byte[] CHUNK_SEPARATOR = {'\r', '\n'}; - + static final byte[] CHUNK_SEPARATOR = { '\r', '\n' }; /** * The empty byte array. */ static final byte[] EMPTY_BYTE_ARRAY = {}; /** - * 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. + * 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. * * @param minCapacity the minimum capacity * @return the capacity @@ -415,7 +385,7 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { /** * Increases our buffer by the {@link #DEFAULT_BUFFER_RESIZE_FACTOR}. * - * @param context the context to be used + * @param context the context to be used * @param minCapacity the minimum required capacity * @return the resized byte[] buffer * @throws OutOfMemoryError if the {@code minCapacity} is negative @@ -445,48 +415,39 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { */ @Deprecated protected final byte PAD = PAD_DEFAULT; - /** Pad byte. Instance variable just in case it needs to vary later. */ protected final byte pad; - /** Number of bytes in each full block of unencoded data, for example 4 for Base64 and 5 for Base32 */ private final int unencodedBlockSize; - /** Number of bytes in each full block of encoded data, for example 3 for Base64 and 8 for Base32 */ private final int encodedBlockSize; - /** - * 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. + * 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. */ protected final int lineLength; - /** * Size of chunk separator. Not used unless {@link #lineLength} > 0. */ private final int chunkSeparatorLength; - /** - * 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 to - * {@code true} to enable strict decoding. + * 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 to {@code true} to enable strict decoding. * <ul> - * <li>Lenient: Any trailing bits are composed into 8-bit bytes where possible. - * The remainder are discarded. - * <li>Strict: The decoding will raise an {@link 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. + * <li>Lenient: Any trailing bits are composed into 8-bit bytes where possible. The remainder are discarded. + * <li>Strict: The decoding will raise an {@link 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. * </ul> * <p> - * 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. + * 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. * </p> */ private final CodecPolicy decodingPolicy; + /** + * Encode table. + */ + final byte[] encodeTable; /** * Constructs a new instance for a subclass. @@ -502,20 +463,23 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { this.chunkSeparatorLength = builder.lineSeparator.length; this.pad = builder.padding; this.decodingPolicy = Objects.requireNonNull(builder.decodingPolicy, "codecPolicy"); + this.encodeTable = builder.getEncodeTable(); } /** * Constructs a new instance. * <p> - * Note {@code lineLength} is rounded down to the nearest multiple of the encoded block size. - * If {@code chunkSeparatorLength} is zero, then chunking is disabled. + * Note {@code lineLength} is rounded down to the nearest multiple of the encoded block size. If {@code chunkSeparatorLength} is zero, then chunking is + * disabled. * </p> * - * @param unencodedBlockSize the size of an unencoded block (for example Base64 = 3) - * @param encodedBlockSize the size of an encoded block (for example Base64 = 4) - * @param lineLength if > 0, use chunking with a length {@code lineLength} - * @param chunkSeparatorLength the chunk separator length, if relevant + * @param unencodedBlockSize the size of an unencoded block (for example Base64 = 3). + * @param encodedBlockSize the size of an encoded block (for example Base64 = 4). + * @param lineLength if > 0, use chunking with a length {@code lineLength}. + * @param chunkSeparatorLength the chunk separator length, if relevant. + * @deprecated Use {@link BaseNCodec#BaseNCodec(AbstractBuilder)}. */ + @Deprecated protected BaseNCodec(final int unencodedBlockSize, final int encodedBlockSize, final int lineLength, final int chunkSeparatorLength) { this(unencodedBlockSize, encodedBlockSize, lineLength, chunkSeparatorLength, PAD_DEFAULT); } @@ -523,16 +487,18 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { /** * Constructs a new instance. * <p> - * Note {@code lineLength} is rounded down to the nearest multiple of the encoded block size. - * If {@code chunkSeparatorLength} is zero, then chunking is disabled. + * Note {@code lineLength} is rounded down to the nearest multiple of the encoded block size. If {@code chunkSeparatorLength} is zero, then chunking is + * disabled. * </p> * - * @param unencodedBlockSize the size of an unencoded block (for example Base64 = 3) - * @param encodedBlockSize the size of an encoded block (for example Base64 = 4) - * @param lineLength if > 0, use chunking with a length {@code lineLength} - * @param chunkSeparatorLength the chunk separator length, if relevant - * @param pad byte used as padding byte. + * @param unencodedBlockSize the size of an unencoded block (for example Base64 = 3). + * @param encodedBlockSize the size of an encoded block (for example Base64 = 4). + * @param lineLength if > 0, use chunking with a length {@code lineLength}. + * @param chunkSeparatorLength the chunk separator length, if relevant. + * @param pad byte used as padding byte. + * @deprecated Use {@link BaseNCodec#BaseNCodec(AbstractBuilder)}. */ + @Deprecated protected BaseNCodec(final int unencodedBlockSize, final int encodedBlockSize, final int lineLength, final int chunkSeparatorLength, final byte pad) { this(unencodedBlockSize, encodedBlockSize, lineLength, chunkSeparatorLength, pad, DECODING_POLICY_DEFAULT); } @@ -540,18 +506,20 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { /** * Constructs a new instance. * <p> - * Note {@code lineLength} is rounded down to the nearest multiple of the encoded block size. - * If {@code chunkSeparatorLength} is zero, then chunking is disabled. + * Note {@code lineLength} is rounded down to the nearest multiple of the encoded block size. If {@code chunkSeparatorLength} is zero, then chunking is + * disabled. * </p> * - * @param unencodedBlockSize the size of an unencoded block (for example Base64 = 3) - * @param encodedBlockSize the size of an encoded block (for example Base64 = 4) - * @param lineLength if > 0, use chunking with a length {@code lineLength} - * @param chunkSeparatorLength the chunk separator length, if relevant - * @param pad byte used as padding byte. - * @param decodingPolicy Decoding policy. + * @param unencodedBlockSize the size of an unencoded block (for example Base64 = 3). + * @param encodedBlockSize the size of an encoded block (for example Base64 = 4). + * @param lineLength if > 0, use chunking with a length {@code lineLength}. + * @param chunkSeparatorLength the chunk separator length, if relevant. + * @param pad byte used as padding byte. + * @param decodingPolicy Decoding policy. * @since 1.15 + * @deprecated Use {@link BaseNCodec#BaseNCodec(AbstractBuilder)}. */ + @Deprecated protected BaseNCodec(final int unencodedBlockSize, final int encodedBlockSize, final int lineLength, final int chunkSeparatorLength, final byte pad, final CodecPolicy decodingPolicy) { this.unencodedBlockSize = unencodedBlockSize; @@ -561,26 +529,26 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { this.chunkSeparatorLength = chunkSeparatorLength; this.pad = pad; this.decodingPolicy = Objects.requireNonNull(decodingPolicy, "codecPolicy"); + this.encodeTable = null; } /** * Returns the amount of buffered data available for reading. * - * @param context the context to be used + * @param context the context to be used. * @return The amount of buffered data available for reading. */ - int available(final Context context) { // package protected for access from I/O streams + int available(final Context context) { // package protected for access from I/O streams return hasData(context) ? context.pos - context.readPos : 0; } /** * 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 + * Intended for use in checking line-ending arrays. * - * @param arrayOctet - * byte array to test - * @return {@code true} if any byte is a valid character in the alphabet or PAD; {@code false} otherwise + * @param arrayOctet byte array to test. + * @return {@code true} if any byte is a valid character in the alphabet or PAD; {@code false} otherwise. */ protected boolean containsAlphabetOrPad(final byte[] arrayOctet) { if (arrayOctet != null) { @@ -596,9 +564,8 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { /** * Decodes a byte[] containing characters in the Base-N alphabet. * - * @param array - * A byte array containing Base-N character data - * @return a byte array containing binary data + * @param array A byte array containing Base-N character data. + * @return a byte array containing binary data. */ @Override public byte[] decode(final byte[] array) { @@ -617,15 +584,12 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { abstract void decode(byte[] array, int i, int length, Context context); /** - * 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. + * 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. * - * @param obj - * Object to decode - * @return 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[] + * @param obj Object to decode. + * @return 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[]. */ @Override public Object decode(final Object obj) throws DecoderException { @@ -641,9 +605,8 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { /** * Decodes a String containing characters in the Base-N alphabet. * - * @param array - * A String containing Base-N character data - * @return a byte array containing binary data + * @param array A String containing Base-N character data. + * @return a byte array containing binary data. */ public byte[] decode(final String array) { return decode(StringUtils.getBytesUtf8(array)); @@ -652,9 +615,8 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { /** * Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet. * - * @param array - * a byte array containing binary data - * @return A byte array containing only the base N alphabetic character data + * @param array a byte array containing binary data. + * @return A byte array containing only the base N alphabetic character data. */ @Override public byte[] encode(final byte[] array) { @@ -665,16 +627,12 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { } /** - * Encodes a byte[] containing binary data, into a byte[] containing - * characters in the alphabet. + * Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet. * - * @param array - * a byte array containing binary data - * @param offset - * initial offset of the subarray. - * @param length - * length of the subarray. - * @return A byte array containing only the base N alphabetic character data + * @param array a byte array containing binary data. + * @param offset initial offset of the subarray. + * @param length length of the subarray. + * @return A byte array containing only the base N alphabetic character data. * @since 1.11 */ public byte[] encode(final byte[] array, final int offset, final int length) { @@ -693,14 +651,12 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { abstract void encode(byte[] array, int i, int length, Context context); /** - * 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[]. + * 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[]. * - * @param obj - * Object to encode + * @param obj Object to encode. * @return 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[] + * @throws EncoderException if the parameter supplied is not of type byte[]. */ @Override public Object encode(final Object obj) throws EncoderException { @@ -711,27 +667,24 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { } /** - * Encodes a byte[] containing binary data, into a String containing characters in the appropriate alphabet. - * Uses UTF8 encoding. + * Encodes a byte[] containing binary data, into a String containing characters in the appropriate alphabet. Uses UTF8 encoding. * <p> * This is a duplicate of {@link #encodeToString(byte[])}; it was merged during refactoring. * </p> * - * @param array a byte array containing binary data + * @param array a byte array containing binary data. * @return String containing only character data in the appropriate alphabet. * @since 1.5 - */ + */ public String encodeAsString(final byte[] array) { return StringUtils.newStringUtf8(encode(array)); } /** - * Encodes a byte[] containing binary data, into a String containing characters in the Base-N alphabet. - * Uses UTF8 encoding. + * Encodes a byte[] containing binary data, into a String containing characters in the Base-N alphabet. Uses UTF8 encoding. * - * @param array - * a byte array containing binary data - * @return A String containing only Base-N character data + * @param array a byte array containing binary data. + * @return A String containing only Base-N character data. */ public String encodeToString(final byte[] array) { return StringUtils.newStringUtf8(encode(array)); @@ -740,8 +693,8 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { /** * Ensures that the buffer has room for {@code size} bytes * - * @param size minimum spare space required - * @param context the context to be used + * @param size minimum spare space required. + * @param context the context to be used. * @return the buffer */ protected byte[] ensureBufferSize(final int size, final Context context) { @@ -761,12 +714,11 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { * Gets the decoding behavior policy. * * <p> - * The default is lenient. If the decoding policy is strict, then decoding will raise an - * {@link IllegalArgumentException} if trailing bits are not part of a valid encoding. Decoding will compose - * trailing bits into 8-bit bytes and discard the remainder. + * The default is lenient. If the decoding policy is strict, then decoding will raise an {@link IllegalArgumentException} if trailing bits are not part of a + * valid encoding. Decoding will compose trailing bits into 8-bit bytes and discard the remainder. * </p> * - * @return true if using strict decoding + * @return true if using strict decoding. * @since 1.15 */ public CodecPolicy getCodecPolicy() { @@ -785,9 +737,8 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { /** * Gets the amount of space needed to encode the supplied array. * - * @param array byte[] array which will later be encoded - * @return amount of space needed to encode the supplied array. - * Returns a long since a max-len array will require > Integer.MAX_VALUE + * @param array byte[] array which will later be encoded. + * @return amount of space needed to encode the supplied array. Returns a long since a max-len array will require > Integer.MAX_VALUE. */ public long getEncodedLength(final byte[] array) { // Calculate non-chunked size - rounded up to allow for padding @@ -803,30 +754,27 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { /** * Tests whether this object has buffered data for reading. * - * @param context the context to be used + * @param context the context to be used. * @return true if there is data still available for reading. */ - boolean hasData(final Context context) { // package protected for access from I/O streams + boolean hasData(final Context context) { // package protected for access from I/O streams return context.pos > context.readPos; } /** - * Tests whether or not the {@code octet} is in the current alphabet. - * Does not allow whitespace or pad. + * Tests whether or not the {@code octet} is in the current alphabet. Does not allow whitespace or pad. * - * @param value The value to test + * @param value The value to test. * @return {@code true} if the value is defined in the current alphabet, {@code false} otherwise. */ protected abstract boolean isInAlphabet(byte value); /** - * 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. + * 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. * - * @param arrayOctet byte array to test - * @param allowWSPad if {@code true}, then whitespace and PAD are also allowed - * @return {@code true} if all bytes are valid characters in the alphabet or if the byte array is empty; - * {@code false}, otherwise + * @param arrayOctet byte array to test. + * @param allowWSPad if {@code true}, then whitespace and PAD are also allowed. + * @return {@code true} if all bytes are valid characters in the alphabet or if the byte array is empty; {@code false}, otherwise. */ public boolean isInAlphabet(final byte[] arrayOctet, final boolean allowWSPad) { for (final byte octet : arrayOctet) { @@ -838,12 +786,10 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { } /** - * Tests a given String to see if it contains only valid characters within the alphabet. - * The method treats whitespace and PAD as valid. + * Tests a given String to see if it contains only valid characters within the alphabet. The method treats whitespace and PAD as valid. * - * @param basen String to test - * @return {@code true} if all characters in the String are valid characters in the alphabet or if - * the String is empty; {@code false}, otherwise + * @param basen String to test. + * @return {@code true} if all characters in the String are valid characters in the alphabet or if the String is empty; {@code false}, otherwise. * @see #isInAlphabet(byte[], boolean) */ public boolean isInAlphabet(final String basen) { @@ -851,15 +797,13 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { } /** - * Tests true if decoding behavior is strict. Decoding will raise an {@link IllegalArgumentException} if trailing - * bits are not part of a valid encoding. + * Tests true if decoding behavior is strict. Decoding will raise an {@link IllegalArgumentException} if trailing bits are not part of a valid encoding. * * <p> - * The default is false for lenient decoding. Decoding will compose trailing bits into 8-bit bytes and discard the - * remainder. + * The default is false for lenient decoding. Decoding will compose trailing bits into 8-bit bytes and discard the remainder. * </p> * - * @return true if using strict decoding + * @return true if using strict decoding. * @since 1.15 */ public boolean isStrictDecoding() { @@ -867,20 +811,16 @@ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { } /** - * 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. + * 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. * <p> * Package private for access from I/O streams. * </p> * - * @param b - * byte[] array to extract the buffered data into. - * @param bPos - * position in byte[] array to start extraction at. - * @param bAvail - * amount of bytes we're allowed to extract. We may extract fewer (if fewer are available). - * @param context - * the context to be used + * @param b byte[] array to extract the buffered data into. + * @param bPos position in byte[] array to start extraction at. + * @param bAvail amount of bytes we're allowed to extract. We may extract fewer (if fewer are available). + * @param context the context to be used. * @return The number of bytes successfully extracted into the provided byte[] array. */ int readResults(final byte[] b, final int bPos, final int bAvail, final Context context) {
