Add MessageDigestInputStream and deprecate

MessageDigestCalculatingInputStream

9 files changed, 322 insertions, 30 deletions

diff --git a/pom.xml b/pom.xml
index 592367ff..ac5ee3d7 100644
--- a/pom.xml
+++ b/pom.xml
@@ -289,6 +289,12 @@ file comparators, endian transformation classes, and much more.
       <scope>test</scope>
     </dependency>
     <dependency>
+      <groupId>commons-codec</groupId>
+      <artifactId>commons-codec</artifactId>
+      <version>1.16.0</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
       <groupId>org.openjdk.jmh</groupId>
       <artifactId>jmh-core</artifactId>
       <version>${jmh.version}</version>
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index 109061de..ff6a6c48 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -121,6 +121,9 @@ The <action> type attribute can be add,update,fix,remove.
       <action dev="ggregory" type="add" due-to="Gary Gregory">
         Add org.apache.commons.io.StreamIterator.
       </action>
+      <action dev="ggregory" type="add" due-to="Gary Gregory">
+        Add MessageDigestInputStream and deprecate MessageDigestCalculatingInputStream.
+      </action>
       <!-- UPDATE -->
       <action dev="ggregory" type="update" due-to="Gary Gregory">
         Bump org.apache.commons:commons-parent from 62 to 64.
diff --git a/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java b/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java
index 429b225b..97d7ff59 100644
--- a/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java
@@ -27,7 +27,7 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
 
 /**
  * This class is an example for using an {@link ObservableInputStream}. It creates its own {@link org.apache.commons.io.input.ObservableInputStream.Observer},
- * which calculates a checksum using a MessageDigest, for example an MD5 sum.
+ * which calculates a checksum using a {@link MessageDigest}, for example, a SHA-512 sum.
  * <p>
  * To build an instance, see {@link Builder}.
  * </p>
@@ -36,12 +36,11 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
  * Cryptography Architecture Standard Algorithm Name Documentation</a> for information about standard algorithm names.
  * </p>
  * <p>
- * <em>Note</em>: Neither {@link ObservableInputStream}, nor {@link MessageDigest}, are thread safe. So is {@link MessageDigestCalculatingInputStream}.
- * </p>
- * <p>
- * TODO Rename to MessageDigestInputStream in 3.0.
+ * <em>Note</em>: Neither {@link ObservableInputStream}, nor {@link MessageDigest}, are thread safe, so is {@link MessageDigestCalculatingInputStream}.
  * </p>
+ * @deprecated Use {@link MessageDigestInputStream}.
  */
+@Deprecated
 public class MessageDigestCalculatingInputStream extends ObservableInputStream {
 
     /**
@@ -96,6 +95,9 @@ public class MessageDigestCalculatingInputStream extends ObservableInputStream {
 
         /**
          * Sets the message digest.
+         * <p>
+         * The MD5 cryptographic algorithm is weak and should not be used.
+         * </p>
          *
          * @param messageDigest the message digest.
          */
@@ -105,6 +107,9 @@ public class MessageDigestCalculatingInputStream extends ObservableInputStream {
 
         /**
          * Sets the name of the name of the message digest algorithm.
+         * <p>
+         * The MD5 cryptographic algorithm is weak and should not be used.
+         * </p>
          *
          * @param algorithm the name of the algorithm. See the MessageDigest section in the
          *                  <a href= "https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#MessageDigest"> Java Cryptography
@@ -192,6 +197,9 @@ public class MessageDigestCalculatingInputStream extends ObservableInputStream {
 
     /**
      * Constructs a new instance, which calculates a signature on the given stream, using the given {@link MessageDigest}.
+     * <p>
+     * The MD5 cryptographic algorithm is weak and should not be used.
+     * </p>
      *
      * @param inputStream   the stream to calculate the message digest for
      * @param messageDigest the message digest to use
@@ -206,6 +214,9 @@ public class MessageDigestCalculatingInputStream extends ObservableInputStream {
 
     /**
      * Constructs a new instance, which calculates a signature on the given stream, using a {@link MessageDigest} with the given algorithm.
+     * <p>
+     * The MD5 cryptographic algorithm is weak and should not be used.
+     * </p>
      *
      * @param inputStream the stream to calculate the message digest for
      * @param algorithm   the name of the algorithm requested. See the MessageDigest section in the
diff --git a/src/main/java/org/apache/commons/io/input/MessageDigestInputStream.java b/src/main/java/org/apache/commons/io/input/MessageDigestInputStream.java
new file mode 100644
index 00000000..d822256b
--- /dev/null
+++ b/src/main/java/org/apache/commons/io/input/MessageDigestInputStream.java
@@ -0,0 +1,193 @@
+/*
+ * 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
+ *
+ *      http://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.io.input;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+import java.util.Objects;
+
+import org.apache.commons.io.build.AbstractStreamBuilder;
+
+/**
+ * This class is an example for using an {@link ObservableInputStream}. It creates its own {@link org.apache.commons.io.input.ObservableInputStream.Observer},
+ * which calculates a checksum using a {@link MessageDigest}, for example, a SHA-512 sum.
+ * <p>
+ * To build an instance, see {@link Builder}.
+ * </p>
+ * <p>
+ * See the MessageDigest section in the <a href= "https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#MessageDigest"> Java
+ * Cryptography Architecture Standard Algorithm Name Documentation</a> for information about standard algorithm names.
+ * </p>
+ * <p>
+ * You must specify a message digest algorithm name or instance.
+ * </p>
+ * <p>
+ * <em>Note</em>: Neither {@link ObservableInputStream}, nor {@link MessageDigest}, are thread safe, so is {@link MessageDigestInputStream}.
+ * </p>
+ *
+ * @since 2.15.0
+ */
+public final class MessageDigestInputStream extends ObservableInputStream {
+
+    /**
+     * Builds new {@link MessageDigestInputStream} instances.
+     * <p>
+     * For example:
+     * </p>
+     * <pre>{@code
+     * MessageDigestInputStream s = MessageDigestInputStream.builder()
+     *   .setPath(path)
+     *   .setMessageDigest("SHA-512")
+     *   .get();}
+     * </pre>
+     * <p>
+     * You must specify a message digest algorithm name or instance.
+     * </p>
+     */
+    public static class Builder extends AbstractStreamBuilder<MessageDigestInputStream, Builder> {
+
+        private MessageDigest messageDigest;
+
+        /**
+         * Constructs a new Builder.
+         */
+        public Builder() {
+            // empty
+        }
+
+        /**
+         * Constructs a new instance.
+         * <p>
+         * This builder use the aspects InputStream, OpenOption[], and MessageDigest.
+         * </p>
+         * <p>
+         * You must provide an origin that can be converted to an InputStream by this builder, otherwise, this call will throw an
+         * {@link UnsupportedOperationException}.
+         * </p>
+         *
+         * @return a new instance.
+         * @throws UnsupportedOperationException if the origin cannot provide an InputStream.
+         * @see #getInputStream()
+         */
+        @SuppressWarnings("resource")
+        @Override
+        public MessageDigestInputStream get() throws IOException {
+            return new MessageDigestInputStream(getInputStream(), messageDigest);
+        }
+
+        /**
+         * Sets the message digest.
+         * <p>
+         * The MD5 cryptographic algorithm is weak and should not be used.
+         * </p>
+         *
+         * @param messageDigest the message digest.
+         * @return this
+         */
+        public Builder setMessageDigest(final MessageDigest messageDigest) {
+            this.messageDigest = messageDigest;
+            return this;
+        }
+
+        /**
+         * Sets the name of the name of the message digest algorithm.
+         * <p>
+         * The MD5 cryptographic algorithm is weak and should not be used.
+         * </p>
+         *
+         * @param algorithm the name of the algorithm. See the MessageDigest section in the
+         *                  <a href= "https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#MessageDigest"> Java Cryptography
+         *                  Architecture Standard Algorithm Name Documentation</a> for information about standard algorithm names.
+         * @return this
+         * @throws NoSuchAlgorithmException if no Provider supports a MessageDigestSpi implementation for the specified algorithm.
+         */
+        public Builder setMessageDigest(final String algorithm) throws NoSuchAlgorithmException {
+            this.messageDigest = MessageDigest.getInstance(algorithm);
+            return this;
+        }
+
+    }
+
+    /**
+     * Maintains the message digest.
+     */
+    public static class MessageDigestMaintainingObserver extends Observer {
+
+        private final MessageDigest messageDigest;
+
+        /**
+         * Constructs an MessageDigestMaintainingObserver for the given MessageDigest.
+         *
+         * @param messageDigest the message digest to use
+         * @throws NullPointerException if messageDigest is null.
+         */
+        public MessageDigestMaintainingObserver(final MessageDigest messageDigest) {
+            this.messageDigest = Objects.requireNonNull(messageDigest, "messageDigest");
+        }
+
+        @Override
+        public void data(final byte[] input, final int offset, final int length) throws IOException {
+            messageDigest.update(input, offset, length);
+        }
+
+        @Override
+        public void data(final int input) throws IOException {
+            messageDigest.update((byte) input);
+        }
+    }
+
+    /**
+     * Constructs a new {@link Builder}.
+     *
+     * @return a new {@link Builder}.
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    private final MessageDigest messageDigest;
+
+    /**
+     * Constructs a new instance, which calculates a signature on the given stream, using the given {@link MessageDigest}.
+     * <p>
+     * The MD5 cryptographic algorithm is weak and should not be used.
+     * </p>
+     *
+     * @param inputStream   the stream to calculate the message digest for
+     * @param messageDigest the message digest to use
+     * @throws NullPointerException if messageDigest is null.
+     */
+    private MessageDigestInputStream(final InputStream inputStream, final MessageDigest messageDigest) {
+        super(inputStream, new MessageDigestMaintainingObserver(messageDigest));
+        this.messageDigest = messageDigest;
+    }
+
+    /**
+     * Gets the {@link MessageDigest}, which is being used for generating the checksum.
+     * <p>
+     * <em>Note</em>: The checksum will only reflect the data, which has been read so far. This is probably not, what you expect. Make sure, that the complete
+     * data has been read, if that is what you want. The easiest way to do so is by invoking {@link #consume()}.
+     * </p>
+     *
+     * @return the message digest used
+     */
+    public MessageDigest getMessageDigest() {
+        return messageDigest;
+    }
+}
diff --git a/src/main/java/org/apache/commons/io/input/ObservableInputStream.java b/src/main/java/org/apache/commons/io/input/ObservableInputStream.java
index ee080f06..a97702fb 100644
--- a/src/main/java/org/apache/commons/io/input/ObservableInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/ObservableInputStream.java
@@ -39,7 +39,7 @@ import org.apache.commons.io.function.IOConsumer;
  * be used.
  * </p>
  *
- * @see MessageDigestCalculatingInputStream
+ * @see MessageDigestInputStream
  */
 public class ObservableInputStream extends ProxyInputStream {
 
diff --git a/src/test/java/org/apache/commons/io/input/MessageDigestCalculatingInputStreamTest.java b/src/test/java/org/apache/commons/io/input/MessageDigestCalculatingInputStreamTest.java
index 517a014e..9123c41f 100644
--- a/src/test/java/org/apache/commons/io/input/MessageDigestCalculatingInputStreamTest.java
+++ b/src/test/java/org/apache/commons/io/input/MessageDigestCalculatingInputStreamTest.java
@@ -20,40 +20,57 @@ import static org.junit.jupiter.api.Assertions.assertArrayEquals;
 
 import java.io.ByteArrayInputStream;
 import java.security.MessageDigest;
-import java.util.Random;
 
+import org.apache.commons.codec.digest.DigestUtils;
+import org.apache.commons.codec.digest.MessageDigestAlgorithms;
+import org.apache.commons.io.input.MessageDigestCalculatingInputStream.Builder;
 import org.junit.jupiter.api.Test;
 
 /**
  * Tests {@link MessageDigestCalculatingInputStream}.
  */
+@SuppressWarnings("deprecation")
 public class MessageDigestCalculatingInputStreamTest {
 
-    public static byte[] generateRandomByteStream(final int pSize) {
-        final byte[] buffer = new byte[pSize];
-        final Random rnd = new Random();
-        rnd.nextBytes(buffer);
-        return buffer;
-    }
-
     @Test
-    public void test() throws Exception {
+    public void testNormalUse() throws Exception {
         for (int i = 256; i < 8192; i = i * 2) {
-            final byte[] buffer = generateRandomByteStream(i);
-            final MessageDigest messageDigest = MessageDigestCalculatingInputStream.getDefaultMessageDigest();
-            final byte[] expect = messageDigest.digest(buffer);
+            final byte[] buffer = MessageDigestInputStreamTest.generateRandomByteStream(i);
+            final MessageDigest defaultMessageDigest = MessageDigestCalculatingInputStream.getDefaultMessageDigest();
+            final byte[] defaultExpect = defaultMessageDigest.digest(buffer);
+            // Defaults
             try (MessageDigestCalculatingInputStream messageDigestInputStream = new MessageDigestCalculatingInputStream(new ByteArrayInputStream(buffer))) {
                 messageDigestInputStream.consume();
-                assertArrayEquals(expect, messageDigestInputStream.getMessageDigest().digest());
+                assertArrayEquals(defaultExpect, messageDigestInputStream.getMessageDigest().digest());
             }
             try (MessageDigestCalculatingInputStream messageDigestInputStream = MessageDigestCalculatingInputStream.builder()
                     .setInputStream(new ByteArrayInputStream(buffer)).get()) {
                 messageDigestInputStream.consume();
-                assertArrayEquals(expect, messageDigestInputStream.getMessageDigest().digest());
+                assertArrayEquals(defaultExpect, messageDigestInputStream.getMessageDigest().digest());
             }
             try (MessageDigestCalculatingInputStream messageDigestInputStream = MessageDigestCalculatingInputStream.builder().setByteArray(buffer).get()) {
                 messageDigestInputStream.consume();
-                assertArrayEquals(expect, messageDigestInputStream.getMessageDigest().digest());
+                assertArrayEquals(defaultExpect, messageDigestInputStream.getMessageDigest().digest());
+            }
+            // SHA-512
+            final byte[] sha512Expect = DigestUtils.sha512(buffer);
+            {
+                final Builder builder = MessageDigestCalculatingInputStream.builder();
+                builder.setMessageDigest(MessageDigestAlgorithms.SHA_512);
+                builder.setInputStream(new ByteArrayInputStream(buffer));
+                try (MessageDigestCalculatingInputStream messageDigestInputStream = builder.get()) {
+                    messageDigestInputStream.consume();
+                    assertArrayEquals(sha512Expect, messageDigestInputStream.getMessageDigest().digest());
+                }
+            }
+            {
+                final Builder builder = MessageDigestCalculatingInputStream.builder();
+                builder.setMessageDigest(MessageDigestAlgorithms.SHA_512);
+                builder.setInputStream(new ByteArrayInputStream(buffer));
+                try (MessageDigestCalculatingInputStream messageDigestInputStream = builder.get()) {
+                    messageDigestInputStream.consume();
+                    assertArrayEquals(sha512Expect, messageDigestInputStream.getMessageDigest().digest());
+                }
             }
         }
     }
diff --git a/src/test/java/org/apache/commons/io/input/MessageDigestInputStreamTest.java b/src/test/java/org/apache/commons/io/input/MessageDigestInputStreamTest.java
new file mode 100644
index 00000000..d41da0b7
--- /dev/null
+++ b/src/test/java/org/apache/commons/io/input/MessageDigestInputStreamTest.java
@@ -0,0 +1,65 @@
+/*
+ * 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
+ *
+ *      http://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.io.input;
+
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import java.io.ByteArrayInputStream;
+import java.util.Random;
+
+import org.apache.commons.codec.digest.DigestUtils;
+import org.apache.commons.codec.digest.MessageDigestAlgorithms;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Tests {@link MessageDigestInputStream}.
+ */
+public class MessageDigestInputStreamTest {
+
+    static byte[] generateRandomByteStream(final int pSize) {
+        final byte[] buffer = new byte[pSize];
+        final Random rnd = new Random();
+        rnd.nextBytes(buffer);
+        return buffer;
+    }
+
+    @Test
+    public void testNoDefault() throws Exception {
+        assertThrows(IllegalStateException.class, () -> MessageDigestInputStream.builder().get());
+        assertThrows(NullPointerException.class, () -> MessageDigestInputStream.builder().setInputStream(new ByteArrayInputStream(new byte[] { 1 })).get());
+    }
+
+    @Test
+    public void testNormalUse() throws Exception {
+        for (int i = 256; i < 8192; i = i * 2) {
+            final byte[] buffer = generateRandomByteStream(i);
+            final byte[] expect = DigestUtils.sha512(buffer);
+            try (MessageDigestInputStream messageDigestInputStream = MessageDigestInputStream.builder().setMessageDigest(MessageDigestAlgorithms.SHA_512)
+                    .setInputStream(new ByteArrayInputStream(buffer)).get()) {
+                messageDigestInputStream.consume();
+                assertArrayEquals(expect, messageDigestInputStream.getMessageDigest().digest());
+            }
+            try (MessageDigestInputStream messageDigestInputStream = MessageDigestInputStream.builder().setByteArray(buffer)
+                    .setMessageDigest(DigestUtils.getSha512Digest()).get()) {
+                messageDigestInputStream.consume();
+                assertArrayEquals(expect, messageDigestInputStream.getMessageDigest().digest());
+            }
+        }
+    }
+
+}
diff --git a/src/test/java/org/apache/commons/io/input/ObservableInputStreamTest.java b/src/test/java/org/apache/commons/io/input/ObservableInputStreamTest.java
index 4c9b193b..8c099ade 100644
--- a/src/test/java/org/apache/commons/io/input/ObservableInputStreamTest.java
+++ b/src/test/java/org/apache/commons/io/input/ObservableInputStreamTest.java
@@ -153,8 +153,7 @@ public class ObservableInputStreamTest {
      */
     @Test
     public void testDataByteCalled_add() throws Exception {
-        final byte[] buffer = MessageDigestCalculatingInputStreamTest
-            .generateRandomByteStream(IOUtils.DEFAULT_BUFFER_SIZE);
+        final byte[] buffer = MessageDigestInputStreamTest.generateRandomByteStream(IOUtils.DEFAULT_BUFFER_SIZE);
         final DataViewObserver lko = new DataViewObserver();
         try (ObservableInputStream ois = new ObservableInputStream(new ByteArrayInputStream(buffer))) {
             assertEquals(-1, lko.lastValue);
@@ -185,8 +184,7 @@ public class ObservableInputStreamTest {
      */
     @Test
     public void testDataByteCalled_ctor() throws Exception {
-        final byte[] buffer = MessageDigestCalculatingInputStreamTest
-            .generateRandomByteStream(IOUtils.DEFAULT_BUFFER_SIZE);
+        final byte[] buffer = MessageDigestInputStreamTest.generateRandomByteStream(IOUtils.DEFAULT_BUFFER_SIZE);
         final DataViewObserver lko = new DataViewObserver();
         try (ObservableInputStream ois = new ObservableInputStream(new ByteArrayInputStream(buffer), lko)) {
             assertEquals(-1, lko.lastValue);
@@ -216,10 +214,9 @@ public class ObservableInputStreamTest {
      */
     @Test
     public void testDataBytesCalled() throws Exception {
-        final byte[] buffer = MessageDigestCalculatingInputStreamTest
-            .generateRandomByteStream(IOUtils.DEFAULT_BUFFER_SIZE);
+        final byte[] buffer = MessageDigestInputStreamTest.generateRandomByteStream(IOUtils.DEFAULT_BUFFER_SIZE);
         try (ByteArrayInputStream bais = new ByteArrayInputStream(buffer);
-            final ObservableInputStream ois = new ObservableInputStream(bais)) {
+                final ObservableInputStream ois = new ObservableInputStream(bais)) {
             final DataViewObserver observer = new DataViewObserver();
             final byte[] readBuffer = new byte[23];
             assertNull(observer.buffer);
diff --git a/src/test/java/org/apache/commons/io/input/TimestampedObserverTest.java b/src/test/java/org/apache/commons/io/input/TimestampedObserverTest.java
index 54922005..ea37b381 100644
--- a/src/test/java/org/apache/commons/io/input/TimestampedObserverTest.java
+++ b/src/test/java/org/apache/commons/io/input/TimestampedObserverTest.java
@@ -51,7 +51,7 @@ public class TimestampedObserverTest {
         assertTrue(timestampedObserver.getOpenToNowDuration().toNanos() > 0);
         assertNull(timestampedObserver.getCloseInstant());
         assertFalse(timestampedObserver.isClosed());
-        final byte[] buffer = MessageDigestCalculatingInputStreamTest.generateRandomByteStream(IOUtils.DEFAULT_BUFFER_SIZE);
+        final byte[] buffer = MessageDigestInputStreamTest.generateRandomByteStream(IOUtils.DEFAULT_BUFFER_SIZE);
         try (ObservableInputStream ois = new ObservableInputStream(new ByteArrayInputStream(buffer), timestampedObserver)) {
             assertTrue(timestampedObserver.getOpenInstant().isAfter(before));
             assertTrue(timestampedObserver.getOpenToNowDuration().toNanos() > 0);
@@ -68,7 +68,7 @@ public class TimestampedObserverTest {
     @Test
     public void testExample() throws IOException {
         final TimestampedObserver timestampedObserver = new TimestampedObserver();
-        final byte[] buffer = MessageDigestCalculatingInputStreamTest
+        final byte[] buffer = MessageDigestInputStreamTest
             .generateRandomByteStream(IOUtils.DEFAULT_BUFFER_SIZE);
         try (ObservableInputStream ois = new ObservableInputStream(new ByteArrayInputStream(buffer),
             timestampedObserver)) {