Add builders to org.apache.commons.codec.digest streams and deprecate

some old constructors

Author: garydgregory

src/changes/changes.xml

@@ -51,6 +51,7 @@ The <action> type attribute can be add,update,fix,remove.
       <action type="update" dev="ggregory" due-to="Gary Gregory">BaseNCodecOutputStream subclasses are now type-safe to match its matching BaseNCodec.</action>
       <!-- ADD -->
       <action type="add" dev="ggregory" due-to="Fredrik Kjellberg, Gary Gregory">Add org.apache.commons.codec.digest.CRC16.</action>
+      <action type="add" dev="ggregory" due-to="Gary Gregory">Add builders to org.apache.commons.codec.digest streams and deprecate some old constructors.</action>
       <!-- UPDATE -->
       <action type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">Bump org.apache.commons:commons-parent from 85 to 88.</action>
       <action type="update" dev="ggregory" due-to="Gary Gregory">[test] Bump org.apache.commons:commons-lang3 from 3.18.0 to 3.19.0.</action>

src/conf/spotbugs-exclude-filter.xml

@@ -98,4 +98,10 @@
     <Class name="org.apache.commons.codec.language.bm.Rule$PhonemeList" />
     <Method name="&lt;init&gt;" />
   </Match>
+  <Match>
+    <!-- By design -->
+    <Bug pattern="EI_EXPOSE_REP2" />
+    <Class name="org.apache.commons.codec.binary.BaseNCodecOutputStream$AbstractBuilder" />
+    <Method name="setOutputStream" />
+  </Match>
 </FindBugsFilter>

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

@@ -0,0 +1,93 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.codec.binary;
+
+import java.util.function.Supplier;
+
+/**
+ * Builds input and output stream instances in {@link BaseNCodec} format.
+ *
+ * @param <T> the stream type to build.
+ * @param <C> A {@link BaseNCodec} subclass.
+ * @param <B> the builder subclass.
+ * @since 1.20.0
+ */
+public abstract class AbstractBaseNCodecStreamBuilder<T, C extends BaseNCodec, B extends AbstractBaseNCodecStreamBuilder<T, C, B>> implements Supplier<T> {
+
+    private C baseNCodec;
+    private boolean encode;
+
+    /**
+     * Constructs a new instance.
+     */
+    public AbstractBaseNCodecStreamBuilder() {
+        baseNCodec = newBaseNCodec();
+    }
+
+    @SuppressWarnings("unchecked")
+    B asThis() {
+        return (B) this;
+    }
+
+    /**
+     * Gets the codec to encode/decode a stream.
+     *
+     * @return the codec to encode/decode a stream.
+     */
+    protected C getBaseNCodec() {
+        return baseNCodec;
+    }
+
+    /**
+     * Gets whether to encode or decode a stream.
+     *
+     * @return whether to encode or decode a stream.
+     */
+    protected boolean getEncode() {
+        return encode;
+    }
+
+    /**
+     * Creates a new BaseNCodec subclass of type C.
+     *
+     * @return a new BaseNCodec subclass of type C.
+     */
+    protected abstract C newBaseNCodec();
+
+    /**
+     * Sets a BaseNCodec subclass of type C.
+     *
+     * @param baseNCodec a BaseNCodec subclass of type C.
+     * @return {@code this} instance.
+     */
+    public B setBaseNCodec(final C baseNCodec) {
+        this.baseNCodec = baseNCodec != null ? baseNCodec : newBaseNCodec();
+        return asThis();
+    }
+
+    /**
+     * Sets whether we should encode all data read (true), or if false if we should decode.
+     *
+     * @param encode encode or decode.
+     * @return {@code this} instance.
+     */
+    public B setEncode(final boolean encode) {
+        this.encode = encode;
+        return asThis();
+    }
+}

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

@@ -49,7 +49,6 @@ public class Base16 extends BaseNCodec {
     private static final int BITS_PER_ENCODED_BYTE = 4;
     private static final int BYTES_PER_ENCODED_BLOCK = 2;
     private static final int BYTES_PER_UNENCODED_BLOCK = 1;
-
     /**
      * This array is a lookup table that translates Unicode characters drawn from the "Base16 Alphabet" (as specified in Table 5 of RFC 4648) into their 4-bit
      * positive integer equivalents. Characters that are not in the Base16 alphabet but fall within the bounds of the array are translated to -1.
@@ -64,13 +63,11 @@ public class Base16 extends BaseNCodec {
             -1, 10, 11, 12, 13, 14, 15                                      // 40-46 A-F
     };
     // @formatter:on
-
     /**
      * This array is a lookup table that translates 4-bit positive integer index values into their "Base16 Alphabet" equivalents as specified in Table 5 of RFC
      * 4648.
      */
     private static final byte[] UPPER_CASE_ENCODE_TABLE = { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', 'B', 'C', 'D', 'E', 'F' };
-
     /**
      * This array is a lookup table that translates Unicode characters drawn from the a lower-case "Base16 Alphabet" into their 4-bit positive integer
      * equivalents. Characters that are not in the Base16 alphabet but fall within the bounds of the array are translated to -1.
@@ -87,20 +84,16 @@ public class Base16 extends BaseNCodec {
             -1, 10, 11, 12, 13, 14, 15                                      // 60-66 a-f
     };
     // @formatter:on
-
     /**
      * This array is a lookup table that translates 4-bit positive integer index values into their "Base16 Alphabet" lower-case equivalents.
      */
     private static final byte[] LOWER_CASE_ENCODE_TABLE = { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f' };
-
     /** Mask used to extract 4 bits, used when decoding character. */
     private static final int MASK_4_BITS = 0x0f;
-
     /**
      * Decode table to use.
      */
     private final byte[] decodeTable;
-
     /**
      * Encode table to use.
      */
@@ -124,24 +117,25 @@ public Base16(final boolean lowerCase) {
 
     /**
      * Constructs a Base16 codec used for decoding and encoding.
-     * @param encodeTable    the encode table.
+     *
+     * @param lowerCase      if {@code true} then use a lower-case Base16 alphabet.
      * @param decodingPolicy Decoding policy.
      */
-    private Base16(final byte[] encodeTable, final CodecPolicy decodingPolicy) {
-        super(BYTES_PER_UNENCODED_BLOCK, BYTES_PER_ENCODED_BLOCK, 0, 0, PAD_DEFAULT, decodingPolicy);
-        Objects.requireNonNull(encodeTable, "encodeTable");
-        this.encodeTable = encodeTable;
-        this.decodeTable = encodeTable == LOWER_CASE_ENCODE_TABLE ? LOWER_CASE_DECODE_TABLE : UPPER_CASE_DECODE_TABLE;
+    public Base16(final boolean lowerCase, final CodecPolicy decodingPolicy) {
+        this(lowerCase ? LOWER_CASE_ENCODE_TABLE : UPPER_CASE_ENCODE_TABLE, decodingPolicy);
     }
 
     /**
      * Constructs a Base16 codec used for decoding and encoding.
      *
-     * @param lowerCase      if {@code true} then use a lower-case Base16 alphabet.
+     * @param encodeTable    the encode table.
      * @param decodingPolicy Decoding policy.
      */
-    public Base16(final boolean lowerCase, final CodecPolicy decodingPolicy) {
-        this(lowerCase ? LOWER_CASE_ENCODE_TABLE : UPPER_CASE_ENCODE_TABLE, decodingPolicy);
+    private Base16(final byte[] encodeTable, final CodecPolicy decodingPolicy) {
+        super(BYTES_PER_UNENCODED_BLOCK, BYTES_PER_ENCODED_BLOCK, 0, 0, PAD_DEFAULT, decodingPolicy);
+        Objects.requireNonNull(encodeTable, "encodeTable");
+        this.encodeTable = encodeTable;
+        this.decodeTable = encodeTable == LOWER_CASE_ENCODE_TABLE ? LOWER_CASE_DECODE_TABLE : UPPER_CASE_DECODE_TABLE;
     }
 
     @Override
@@ -240,7 +234,7 @@ public boolean isInAlphabet(final byte octet) {
      */
     private void validateTrailingCharacter() {
         if (isStrictDecoding()) {
-            throw new IllegalArgumentException("Strict decoding: Last encoded character is a valid base 16 alphabet character but not a possible encoding. " +
+            throw new IllegalArgumentException("Strict decoding: Last encoded character is a valid Base 16 alphabet character but not a possible encoding. " +
                     "Decoding requires at least two characters to create one byte.");
         }
     }

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

@@ -20,63 +20,98 @@
 import java.io.InputStream;
 
 import org.apache.commons.codec.CodecPolicy;
+import org.apache.commons.codec.binary.BaseNCodecInputStream.AbstracBuilder; // NOPMD: Required by ECJ (Eclipse)
 
 /**
  * Provides Base16 decoding in a streaming fashion (unlimited size).
  * <p>
- * The default behavior of the Base16InputStream is to DECODE, whereas the default behavior of the
- * {@link Base16OutputStream} is to ENCODE, but this behavior can be overridden by using a different constructor.
+ * The default behavior of the Base16InputStream is to DECODE, whereas the default behavior of the {@link Base16OutputStream} is to ENCODE, but this behavior
+ * can be overridden by using a different constructor.
  * </p>
  *
  * @see Base16
  * @since 1.15
  */
-public class Base16InputStream extends BaseNCodecInputStream<Base16> {
+public class Base16InputStream extends BaseNCodecInputStream<Base16, Base16InputStream, Base16InputStream.Builder> {
+
+    /**
+     * Builds instances of Base16InputStream.
+     */
+    public static class Builder extends AbstracBuilder<Base16InputStream, Base16, Builder> {
+
+        /**
+         * Constructs a new instance.
+         */
+        public Builder() {
+            // empty
+        }
+
+        @Override
+        public Base16InputStream get() {
+            return new Base16InputStream(this);
+        }
+
+        @Override
+        protected Base16 newBaseNCodec() {
+            return new Base16();
+        }
+    }
+
+    /**
+     * Constructs a new Builder.
+     *
+     * @return a new Builder.
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    private Base16InputStream(final Builder builder) {
+        super(builder);
+    }
 
     /**
      * Constructs a Base16InputStream such that all data read is Base16-decoded from the original provided InputStream.
      *
      * @param inputStream InputStream to wrap.
      */
     public Base16InputStream(final InputStream inputStream) {
-        this(inputStream, false);
+        super(builder().setInputStream(inputStream));
     }
 
     /**
-     * Constructs a Base16InputStream such that all data read is either Base16-encoded or Base16-decoded from the original
-     * provided InputStream.
+     * Constructs a Base16InputStream such that all data read is either Base16-encoded or Base16-decoded from the original provided InputStream.
      *
      * @param inputStream InputStream to wrap.
-     * @param doEncode true if we should encode all data read from us, false if we should decode.
+     * @param encode    true if we should encode all data read from us, false if we should decode.
      */
-    public Base16InputStream(final InputStream inputStream, final boolean doEncode) {
-        this(inputStream, doEncode, false);
+    @Deprecated
+    public Base16InputStream(final InputStream inputStream, final boolean encode) {
+        super(builder().setInputStream(inputStream).setEncode(encode));
     }
 
     /**
-     * Constructs a Base16InputStream such that all data read is either Base16-encoded or Base16-decoded from the original
-     * provided InputStream.
+     * Constructs a Base16InputStream such that all data read is either Base16-encoded or Base16-decoded from the original provided InputStream.
      *
      * @param inputStream InputStream to wrap.
-     * @param doEncode true if we should encode all data read from us, false if we should decode.
-     * @param lowerCase if {@code true} then use a lower-case Base16 alphabet.
+     * @param encode    true if we should encode all data read from us, false if we should decode.
+     * @param lowerCase   if {@code true} then use a lower-case Base16 alphabet.
      */
-    public Base16InputStream(final InputStream inputStream, final boolean doEncode,
-            final boolean lowerCase) {
-        this(inputStream, doEncode, lowerCase, CodecPolicy.LENIENT);
+    @Deprecated
+    public Base16InputStream(final InputStream inputStream, final boolean encode, final boolean lowerCase) {
+        super(builder().setInputStream(inputStream).setEncode(encode).setBaseNCodec(new Base16(lowerCase)));
     }
 
     /**
-     * Constructs a Base16InputStream such that all data read is either Base16-encoded or Base16-decoded from the original
-     * provided InputStream.
+     * Constructs a Base16InputStream such that all data read is either Base16-encoded or Base16-decoded from the original provided InputStream.
      *
-     * @param inputStream InputStream to wrap.
-     * @param doEncode true if we should encode all data read from us, false if we should decode.
-     * @param lowerCase if {@code true} then use a lower-case Base16 alphabet.
+     * @param inputStream    InputStream to wrap.
+     * @param encode       true if we should encode all data read from us, false if we should decode.
+     * @param lowerCase      if {@code true} then use a lower-case Base16 alphabet.
      * @param decodingPolicy Decoding policy.
      */
-    public Base16InputStream(final InputStream inputStream, final boolean doEncode,
-            final boolean lowerCase, final CodecPolicy decodingPolicy) {
-        super(inputStream, new Base16(lowerCase, decodingPolicy), doEncode);
+    @Deprecated
+    public Base16InputStream(final InputStream inputStream, final boolean encode, final boolean lowerCase, final CodecPolicy decodingPolicy) {
+        super(builder().setInputStream(inputStream).setEncode(encode).setBaseNCodec(new Base16(lowerCase, decodingPolicy)));
     }
 }