Skip to content

Commit 05f0bfc

Browse files
garydgregorygarydgregory
committed
Javadoc
1 parent 892d671 commit 05f0bfc

File tree

1 file changed

+67
-11
lines changed
  • src/main/java/org/apache/commons/codec/binary

1 file changed

+67
-11
lines changed

‎src/main/java/org/apache/commons/codec/binary/Base32.java‎

Lines changed: 67 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,8 @@ public class Base32 extends BaseNCodec {
6666
public static class Builder extends AbstractBuilder<Base32, Builder> {
6767

6868
/**
69-
* Constructs a new instance.
69+
* Constructs a new instance using <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-6">RFC 4648 Section 6, Table 3: The Base 32
70+
* Alphabet</a>.
7071
*/
7172
public Builder() {
7273
super(ENCODE_TABLE);
@@ -97,7 +98,13 @@ public Builder setHexDecodeTable(final boolean useHex) {
9798
* This overrides a value previously set with {@link #setEncodeTable(byte...)}.
9899
* </p>
99100
*
100-
* @param useHex use Base32 hexadecimal if {@code true}, otherwise use the Base32 alphabet.
101+
* @param useHex
102+
* <ul>
103+
* <li>If true, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-7">RFC 4648 Section 7, Table 4: Base 32 Encoding
104+
* with Extended Hex Alphabet</a></li>
105+
* <li>If false, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-6">RFC 4648 Section 6, Table 3: The Base 32
106+
* Alphabet</a></li>
107+
* </ul>
101108
* @return {@code this} instance.
102109
* @since 1.18.0
103110
*/
@@ -114,6 +121,7 @@ public Builder setHexEncodeTable(final boolean useHex) {
114121

115122
private static final int BYTES_PER_ENCODED_BLOCK = 8;
116123
private static final int BYTES_PER_UNENCODED_BLOCK = 5;
124+
117125
/**
118126
* This array is a lookup table that translates Unicode characters drawn from the "Base32 Alphabet" (as specified in Table 3 of RFC 4648) into their 5-bit
119127
* positive integer equivalents. Characters that are not in the Base32 alphabet but fall within the bounds of the array are translated to -1.
@@ -134,8 +142,10 @@ public Builder setHexEncodeTable(final boolean useHex) {
134142
// @formatter:on
135143

136144
/**
137-
* This array is a lookup table that translates 5-bit positive integer index values into their "Base32 Alphabet" equivalents as specified in Table 3 of RFC
138-
* 4648.
145+
* This array is a lookup table that translates 5-bit positive integer index values into their "Base32 Alphabet" equivalents as specified in
146+
* <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-6">RFC 4648 Section 6, Table 3: The Base 32 Alphabet</a>.
147+
*
148+
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-6">RFC 4648 Section 6, Table 3: The Base 32 Alphabet</a>
139149
*/
140150
// @formatter:off
141151
private static final byte[] ENCODE_TABLE = {
@@ -148,6 +158,7 @@ public Builder setHexEncodeTable(final boolean useHex) {
148158
/**
149159
* This array is a lookup table that translates Unicode characters drawn from the "Base32 Hex Alphabet" (as specified in Table 4 of RFC 4648) into their
150160
* 5-bit positive integer equivalents. Characters that are not in the Base32 Hex alphabet but fall within the bounds of the array are translated to -1.
161+
*
151162
*/
152163
// @formatter:off
153164
private static final byte[] HEX_DECODE_TABLE = {
@@ -165,8 +176,11 @@ public Builder setHexEncodeTable(final boolean useHex) {
165176
// @formatter:on
166177

167178
/**
168-
* This array is a lookup table that translates 5-bit positive integer index values into their "Base32 Hex Alphabet" equivalents as specified in Table 4 of
169-
* RFC 4648.
179+
* This array is a lookup table that translates 5-bit positive integer index values into their "Base 32 Encoding with Extended Hex Alphabet" equivalents as
180+
* specified in <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-7">RFC 4648 Section 7, Table 4: Base 32 Encoding with Extended Hex
181+
* Alphabet</a>.
182+
*
183+
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-7">RFC 4648 Section 7, Table 4: Base 32 Encoding with Extended Hex Alphabet</a>
170184
*/
171185
// @formatter:off
172186
private static final byte[] HEX_ENCODE_TABLE = {
@@ -209,6 +223,18 @@ private static byte[] decodeTable(final boolean useHex) {
209223
return useHex ? HEX_DECODE_TABLE : DECODE_TABLE;
210224
}
211225

226+
/**
227+
* Gets the encoding table that matches {@code useHex}.
228+
*
229+
* @param useHex
230+
* <ul>
231+
* <li>If true, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-7">RFC 4648 Section 7, Table 4: Base 32 Encoding with
232+
* Extended Hex Alphabet</a></li>
233+
* <li>If false, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-6">RFC 4648 Section 6, Table 3: The Base 32
234+
* Alphabet</a></li>
235+
* </ul>
236+
* @return the encoding table that matches {@code useHex}.
237+
*/
212238
private static byte[] encodeTable(final boolean useHex) {
213239
return useHex ? HEX_ENCODE_TABLE : ENCODE_TABLE;
214240
}
@@ -250,7 +276,13 @@ public Base32() {
250276
* When encoding the line length is 0 (no chunking).
251277
* </p>
252278
*
253-
* @param useHex if {@code true} then use Base32 Hex alphabet
279+
* @param useHex
280+
* <ul>
281+
* <li>If true, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-7">RFC 4648 Section 7, Table 4: Base 32 Encoding with
282+
* Extended Hex Alphabet</a></li>
283+
* <li>If false, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-6">RFC 4648 Section 6, Table 3: The Base 32
284+
* Alphabet</a></li>
285+
* </ul>
254286
*/
255287
public Base32(final boolean useHex) {
256288
this(0, null, useHex, PAD_DEFAULT);
@@ -262,7 +294,13 @@ public Base32(final boolean useHex) {
262294
* When encoding the line length is 0 (no chunking).
263295
* </p>
264296
*
265-
* @param useHex if {@code true} then use Base32 Hex alphabet
297+
* @param useHex
298+
* <ul>
299+
* <li>If true, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-7">RFC 4648 Section 7, Table 4: Base 32 Encoding with
300+
* Extended Hex Alphabet</a></li>
301+
* <li>If false, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-6">RFC 4648 Section 6, Table 3: The Base 32
302+
* Alphabet</a></li>
303+
* </ul>
266304
* @param padding byte used as padding byte.
267305
*/
268306
public Base32(final boolean useHex, final byte padding) {
@@ -324,7 +362,13 @@ public Base32(final int lineLength, final byte[] lineSeparator) {
324362
* @param lineLength Each line of encoded data will be at most of the given length (rounded down to the nearest multiple of 8). If lineLength &lt;= 0,
325363
* then the output will not be divided into lines (chunks). Ignored when decoding.
326364
* @param lineSeparator Each line of encoded data will end with this sequence of bytes.
327-
* @param useHex if {@code true}, then use Base32 Hex alphabet, otherwise use Base32 alphabet
365+
* @param useHex
366+
* <ul>
367+
* <li>If true, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-7">RFC 4648 Section 7, Table 4: Base 32 Encoding with
368+
* Extended Hex Alphabet</a></li>
369+
* <li>If false, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-6">RFC 4648 Section 6, Table 3: The Base 32
370+
* Alphabet</a></li>
371+
* </ul>
328372
* @throws IllegalArgumentException Thrown when the {@code lineSeparator} contains Base32 characters. Or the lineLength &gt; 0 and lineSeparator is null.
329373
*/
330374
public Base32(final int lineLength, final byte[] lineSeparator, final boolean useHex) {
@@ -343,7 +387,13 @@ public Base32(final int lineLength, final byte[] lineSeparator, final boolean us
343387
* @param lineLength Each line of encoded data will be at most of the given length (rounded down to the nearest multiple of 8). If lineLength &lt;= 0,
344388
* then the output will not be divided into lines (chunks). Ignored when decoding.
345389
* @param lineSeparator Each line of encoded data will end with this sequence of bytes.
346-
* @param useHex if {@code true}, then use Base32 Hex alphabet, otherwise use Base32 alphabet
390+
* @param useHex
391+
* <ul>
392+
* <li>If true, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-7">RFC 4648 Section 7, Table 4: Base 32 Encoding with
393+
* Extended Hex Alphabet</a></li>
394+
* <li>If false, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-6">RFC 4648 Section 6, Table 3: The Base 32
395+
* Alphabet</a></li>
396+
* </ul>
347397
* @param padding padding byte.
348398
* @throws IllegalArgumentException Thrown when the {@code lineSeparator} contains Base32 characters. Or the lineLength &gt; 0 and lineSeparator is null.
349399
*/
@@ -363,7 +413,13 @@ public Base32(final int lineLength, final byte[] lineSeparator, final boolean us
363413
* @param lineLength Each line of encoded data will be at most of the given length (rounded down to the nearest multiple of 8). If lineLength &lt;= 0,
364414
* then the output will not be divided into lines (chunks). Ignored when decoding.
365415
* @param lineSeparator Each line of encoded data will end with this sequence of bytes.
366-
* @param useHex use Base32 hexadecimal if {@code true}, otherwise use the Base32 alphabet.
416+
* @param useHex
417+
* <ul>
418+
* <li>If true, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-7">RFC 4648 Section 7, Table 4: Base 32 Encoding with
419+
* Extended Hex Alphabet</a></li>
420+
* <li>If false, then use <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-6">RFC 4648 Section 6, Table 3: The Base 32
421+
* Alphabet</a></li>
422+
* </ul>
367423
* @param padding padding byte.
368424
* @param decodingPolicy The decoding policy.
369425
* @throws IllegalArgumentException Thrown when the {@code lineSeparator} contains Base32 characters. Or the lineLength &gt; 0 and lineSeparator is null.

0 commit comments

Comments
 (0)