Add Base32.Builder (allows custom alphabets)

Author: garydgregory

src/changes/changes.xml

@@ -48,6 +48,7 @@ The <action> type attribute can be add,update,fix,remove.
       <action type="add" dev="ggregory" due-to="Gary Gregory">Add override org.apache.commons.codec.language.bm.Rule.PhonemeExpr.size().</action>
       <action type="add" dev="ggregory" due-to="Chris Kocel, Gary Gregory">Add support for Base64 custom alphabets #266.</action>
       <action type="add" dev="ggregory" due-to="Gary Gregory">Add Base64.Builder (allows custom alphabets).</action> 
+      <action type="add" dev="ggregory" due-to="Gary Gregory">Add Base32.Builder (allows custom alphabets).</action> 
       <!-- FIX -->
       <action type="fix" dev="ggregory" due-to="Gary Gregory">Optimize memory allocation in PhoneticEngine.</action>
       <action type="fix" dev="ggregory" due-to="Gary Gregory">BCodec and QCodec encode() methods throw UnsupportedCharsetException instead of EncoderException.</action>

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

@@ -42,14 +42,49 @@
  */
 public class Base32 extends BaseNCodec {
 
+    /**
+     * Builds {@link Base32} instances.
+     *
+     * @since 1.17.0
+     */
+    public static class Builder extends AbstractBuilder<Base32, Builder> {
+
+        /** Padding byte. */
+        private byte padding = PAD_DEFAULT;
+
+        /**
+         * Constructs a new instance.
+         */
+        public Builder() {
+            super(ENCODE_TABLE);
+        }
+
+        @Override
+        public Base32 get() {
+            return new Base32(getLineLength(), getLineSeparator(), getEncodeTable(), padding, getDecodingPolicy());
+        }
+
+        /**
+         * Sets the padding byte.
+         *
+         * @param padding the padding byte.
+         * @return this.
+         */
+        public Builder setPadding(final byte padding) {
+            this.padding = padding;
+            return this;
+        }
+
+    }
+
     /**
      * BASE32 characters are 5 bits in length. They are formed by taking a block of five octets to form a 40-bit string, which is converted into eight BASE32
      * characters.
      */
     private static final int BITS_PER_ENCODED_BYTE = 5;
+
     private static final int BYTES_PER_ENCODED_BLOCK = 8;
     private static final int BYTES_PER_UNENCODED_BLOCK = 5;
-
     /**
      * 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
      * positive integer equivalents. Characters that are not in the Base32 alphabet but fall within the bounds of the array are translated to -1.
@@ -127,6 +162,16 @@ public class Base32 extends BaseNCodec {
     /** Mask used to extract 1 bits, used when decoding final trailing character. */
     private static final long MASK_1BITS = 0x01L;
 
+    /**
+     * Creates a new Builder.
+     *
+     * @return a new Builder.
+     * @since 1.17.0
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
     // The static final fields above are used for the original static byte[] methods on Base32.
     // The private member fields below are used with the new streaming approach, which requires
     // some state be preserved between calls of encode() and decode().
@@ -262,7 +307,7 @@ public Base32(final int lineLength, final byte[] lineSeparator, final boolean us
      *                      then the output will not be divided into lines (chunks). Ignored when decoding.
      * @param lineSeparator Each line of encoded data will end with this sequence of bytes.
      * @param useHex        if {@code true}, then use Base32 Hex alphabet, otherwise use Base32 alphabet
-     * @param padding       byte used as padding byte.
+     * @param padding       padding byte.
      * @throws IllegalArgumentException Thrown when the {@code lineSeparator} contains Base32 characters. Or the lineLength &gt; 0 and lineSeparator is null.
      */
     public Base32(final int lineLength, final byte[] lineSeparator, final boolean useHex, final byte padding) {
@@ -282,7 +327,7 @@ public Base32(final int lineLength, final byte[] lineSeparator, final boolean us
      *                       then the output will not be divided into lines (chunks). Ignored when decoding.
      * @param lineSeparator  Each line of encoded data will end with this sequence of bytes.
      * @param useHex         if {@code true}, then use Base32 Hex alphabet, otherwise use Base32 alphabet
-     * @param padding        byte used as padding byte.
+     * @param padding        padding byte.
      * @param decodingPolicy The decoding policy.
      * @throws IllegalArgumentException Thrown when the {@code lineSeparator} contains Base32 characters. Or the lineLength &gt; 0 and lineSeparator is null.
      * @since 1.15
@@ -304,7 +349,7 @@ public Base32(final int lineLength, final byte[] lineSeparator, final boolean us
      *                       then the output will not be divided into lines (chunks). Ignored when decoding.
      * @param lineSeparator  Each line of encoded data will end with this sequence of bytes.
      * @param encodeTable    A Base32 alphabet.
-     * @param padding        byte used as padding byte.
+     * @param padding        padding byte.
      * @param decodingPolicy The decoding policy.
      * @throws IllegalArgumentException Thrown when the {@code lineSeparator} contains Base32 characters. Or the lineLength &gt; 0 and lineSeparator is null.
      */
@@ -554,6 +599,15 @@ void encode(final byte[] input, int inPos, final int inAvail, final Context cont
         }
     }
 
+    /**
+     * Gets the line separator (for testing only).
+     *
+     * @return the line separator.
+     */
+    byte[] getLineSeparator() {
+        return lineSeparator;
+    }
+
     /**
      * Returns whether or not the {@code octet} is in the Base32 alphabet.
      *

src/main/java/org/apache/commons/codec/binary/Base64.java

@@ -166,6 +166,7 @@ public Builder setUrlSafe(final boolean urlSafe) {
     private static final int MASK_4BITS = 0xf;
     /** Mask used to extract 2 bits, used when decoding final trailing character. */
     private static final int MASK_2BITS = 0x3;
+
     /**
      * Creates a new Builder.
      *

src/test/java/org/apache/commons/codec/binary/Base32Test.java

@@ -355,6 +355,41 @@ public void testBase32SamplesNonDefaultPadding() throws Exception {
         }
     }
 
+    @Test
+    public void testBuilderCodecPolicy() {
+        assertEquals(CodecPolicy.LENIENT, Base32.builder().get().getCodecPolicy());
+        assertEquals(CodecPolicy.LENIENT, Base32.builder().setDecodingPolicy(CodecPolicy.LENIENT).get().getCodecPolicy());
+        assertEquals(CodecPolicy.STRICT, Base32.builder().setDecodingPolicy(CodecPolicy.STRICT).get().getCodecPolicy());
+        assertEquals(CodecPolicy.LENIENT, Base32.builder().setDecodingPolicy(CodecPolicy.STRICT).setDecodingPolicy(null).get().getCodecPolicy());
+        assertEquals(CodecPolicy.LENIENT, Base32.builder().setDecodingPolicy(null).get().getCodecPolicy());
+    }
+
+    @Test
+    public void testBuilderLineAttributes() {
+        assertNull(Base32.builder().get().getLineSeparator());
+        assertNull(Base32.builder().setLineSeparator(BaseNCodec.CHUNK_SEPARATOR).get().getLineSeparator());
+        assertArrayEquals(BaseNCodec.CHUNK_SEPARATOR, Base32.builder().setLineLength(4).setLineSeparator(BaseNCodec.CHUNK_SEPARATOR).get().getLineSeparator());
+        assertArrayEquals(BaseNCodec.CHUNK_SEPARATOR, Base32.builder().setLineLength(4).setLineSeparator(null).get().getLineSeparator());
+        assertArrayEquals(BaseNCodec.CHUNK_SEPARATOR, Base32.builder().setLineLength(10).setLineSeparator(null).get().getLineSeparator());
+        assertNull(Base32.builder().setLineLength(-1).setLineSeparator(null).get().getLineSeparator());
+        assertNull(Base32.builder().setLineLength(0).setLineSeparator(null).get().getLineSeparator());
+        assertArrayEquals(new byte[] { 1 }, Base32.builder().setLineLength(4).setLineSeparator((byte) 1).get().getLineSeparator());
+        assertEquals("MZXXQ===", Base32.builder().setLineLength(4).get().encodeToString("fox".getBytes(CHARSET_UTF8)));
+    }
+
+    @Test
+    public void testBuilderPadingByte() {
+        assertNull(Base32.builder().get().getLineSeparator());
+        assertNull(Base32.builder().setLineSeparator(BaseNCodec.CHUNK_SEPARATOR).get().getLineSeparator());
+        assertArrayEquals(BaseNCodec.CHUNK_SEPARATOR, Base32.builder().setLineLength(4).setLineSeparator(BaseNCodec.CHUNK_SEPARATOR).get().getLineSeparator());
+        assertArrayEquals(BaseNCodec.CHUNK_SEPARATOR, Base32.builder().setLineLength(4).setLineSeparator(null).get().getLineSeparator());
+        assertArrayEquals(BaseNCodec.CHUNK_SEPARATOR, Base32.builder().setLineLength(10).setLineSeparator(null).get().getLineSeparator());
+        assertNull(Base32.builder().setLineLength(-1).setLineSeparator(null).get().getLineSeparator());
+        assertNull(Base32.builder().setLineLength(0).setLineSeparator(null).get().getLineSeparator());
+        assertArrayEquals(new byte[] { 1 }, Base32.builder().setLineLength(4).setLineSeparator((byte) 1).get().getLineSeparator());
+        assertEquals("MZXXQ___", Base32.builder().setLineLength(4).setPadding((byte) '_').get().encodeToString("fox".getBytes(CHARSET_UTF8)));
+    }
+
     @Test
     public void testCodec200() {
         final Base32 codec = new Base32(true, (byte) 'W'); // should be allowed