[CODEC-272] Add RandomAccessFile digest methods #31.

- This is a slightly different version from
#31
- Refactor updateDigest(MessageDigest,RandomAccessFile) into an new
private updateDigest(MessageDigest,FileChannel) as possible public
candidate.
- Do NOT seek to 0 on a RandomAccessFile before calling updateDigest():
We do not do this for ByteBuffer input, so do not do it here and be
consistent to assume that when the caller says 'digest this' then do it
from where the input stands (like a stream).
- Add methods in the file to keep methods in alphabetical order.
- Closes #31.

Author: Gary Gregory

src/changes/changes.xml

@@ -49,6 +49,7 @@ The <action> type attribute can be add,update,fix,remove.
       <action issue="CODEC-264" dev="aherbert" due-to="Claude Warren" type="add">Add MurmurHash3.hash128x64 methods to fix sign extension error during seeding in hash128 methods.</action>
       <action issue="CODEC-267" dev="aherbert" due-to="Claude Warren" type="add">Add MurmurHash3.hash32x86 methods and IncrementalHash32x86 to fix sign extension error in hash32 methods.</action>
       <action issue="CODEC-269" dev="aherbert" type="fix">Allow repeat calls to MurmurHash3.IncrementalHash32.end() to generate the same value.</action>
+      <action issue="CODEC-272" dev="ggregory" type="add" due-to="Behrang, Alex Herbert, Gary Gregory">Add RandomAccessFile digest methods #31.</action>
     </release>
 
     <release version="1.13" date="2019-07-20" description="Feature and fix release.">

src/main/java/org/apache/commons/codec/digest/DigestUtils.java

@@ -20,9 +20,11 @@
 import java.io.BufferedInputStream;
 import java.io.File;
 import java.io.FileInputStream;
+import java.io.RandomAccessFile;
 import java.io.IOException;
 import java.io.InputStream;
 import java.nio.ByteBuffer;
+import java.nio.channels.FileChannel;
 import java.security.MessageDigest;
 import java.security.NoSuchAlgorithmException;
 
@@ -115,6 +117,19 @@ public static byte[] digest(final MessageDigest messageDigest, final InputStream
         return updateDigest(messageDigest, data).digest();
     }
 
+    /**
+     * Reads through a RandomAccessFile using non-blocking-io (NIO) and returns the digest for the data
+     *
+     * @param messageDigest The MessageDigest to use (e.g. MD5)
+     * @param data Data to digest
+     * @return the digest
+     * @throws IOException On error reading from the stream
+     * @since 1.14
+     */
+    public static byte[] digest(final MessageDigest messageDigest, final RandomAccessFile data) throws IOException {
+        return updateDigest(messageDigest, data).digest();
+    }
+
     /**
      * Returns a <code>MessageDigest</code> for the given <code>algorithm</code>.
      *
@@ -699,6 +714,32 @@ public static byte[] sha3_224(final String data) {
         return sha3_224(StringUtils.getBytesUtf8(data));
     }
 
+    /**
+     * Calculates the SHA3-224 digest and returns the value as a hex string.
+     *
+     * @param data
+     *            Data to digest
+     * @return SHA3-224 digest as a hex string
+     * @since 1.12
+     */
+    public static String sha3_224Hex(final byte[] data) {
+        return Hex.encodeHexString(sha3_224(data));
+    }
+
+    /**
+     * Calculates the SHA3-224 digest and returns the value as a hex string.
+     *
+     * @param data
+     *            Data to digest
+     * @return SHA3-224 digest as a hex string
+     * @throws IOException
+     *             On error reading from the stream
+     * @since 1.12
+     */
+    public static String sha3_224Hex(final InputStream data) throws IOException {
+        return Hex.encodeHexString(sha3_224(data));
+    }
+
     /**
      * Calculates the SHA3-224 digest and returns the value as a hex string.
      *
@@ -749,6 +790,32 @@ public static byte[] sha3_256(final String data) {
         return sha3_256(StringUtils.getBytesUtf8(data));
     }
 
+    /**
+     * Calculates the SHA3-256 digest and returns the value as a hex string.
+     *
+     * @param data
+     *            Data to digest
+     * @return SHA3-256 digest as a hex string
+     * @since 1.12
+     */
+    public static String sha3_256Hex(final byte[] data) {
+        return Hex.encodeHexString(sha3_256(data));
+    }
+
+    /**
+     * Calculates the SHA3-256 digest and returns the value as a hex string.
+     *
+     * @param data
+     *            Data to digest
+     * @return SHA3-256 digest as a hex string
+     * @throws IOException
+     *             On error reading from the stream
+     * @since 1.12
+     */
+    public static String sha3_256Hex(final InputStream data) throws IOException {
+        return Hex.encodeHexString(sha3_256(data));
+    }
+
     /**
      * Calculates the SHA3-256 digest and returns the value as a hex string.
      *
@@ -799,6 +866,32 @@ public static byte[] sha3_384(final String data) {
         return sha3_384(StringUtils.getBytesUtf8(data));
     }
 
+    /**
+     * Calculates the SHA3-384 digest and returns the value as a hex string.
+     *
+     * @param data
+     *            Data to digest
+     * @return SHA3-384 digest as a hex string
+     * @since 1.12
+     */
+    public static String sha3_384Hex(final byte[] data) {
+        return Hex.encodeHexString(sha3_384(data));
+    }
+
+    /**
+     * Calculates the SHA3-384 digest and returns the value as a hex string.
+     *
+     * @param data
+     *            Data to digest
+     * @return SHA3-384 digest as a hex string
+     * @throws IOException
+     *             On error reading from the stream
+     * @since 1.12
+     */
+    public static String sha3_384Hex(final InputStream data) throws IOException {
+        return Hex.encodeHexString(sha3_384(data));
+    }
+
     /**
      * Calculates the SHA3-384 digest and returns the value as a hex string.
      *
@@ -849,6 +942,32 @@ public static byte[] sha3_512(final String data) {
         return sha3_512(StringUtils.getBytesUtf8(data));
     }
 
+    /**
+     * Calculates the SHA3-512 digest and returns the value as a hex string.
+     *
+     * @param data
+     *            Data to digest
+     * @return SHA3-512 digest as a hex string
+     * @since 1.12
+     */
+    public static String sha3_512Hex(final byte[] data) {
+        return Hex.encodeHexString(sha3_512(data));
+    }
+
+    /**
+     * Calculates the SHA3-512 digest and returns the value as a hex string.
+     *
+     * @param data
+     *            Data to digest
+     * @return SHA3-512 digest as a hex string
+     * @throws IOException
+     *             On error reading from the stream
+     * @since 1.12
+     */
+    public static String sha3_512Hex(final InputStream data) throws IOException {
+        return Hex.encodeHexString(sha3_512(data));
+    }
+
     /**
      * Calculates the SHA3-512 digest and returns the value as a hex string.
      *
@@ -987,54 +1106,6 @@ public static String sha512Hex(final byte[] data) {
         return Hex.encodeHexString(sha512(data));
     }
 
-    /**
-     * Calculates the SHA3-224 digest and returns the value as a hex string.
-     *
-     * @param data
-     *            Data to digest
-     * @return SHA3-224 digest as a hex string
-     * @since 1.12
-     */
-    public static String sha3_224Hex(final byte[] data) {
-        return Hex.encodeHexString(sha3_224(data));
-    }
-
-    /**
-     * Calculates the SHA3-256 digest and returns the value as a hex string.
-     *
-     * @param data
-     *            Data to digest
-     * @return SHA3-256 digest as a hex string
-     * @since 1.12
-     */
-    public static String sha3_256Hex(final byte[] data) {
-        return Hex.encodeHexString(sha3_256(data));
-    }
-
-    /**
-     * Calculates the SHA3-384 digest and returns the value as a hex string.
-     *
-     * @param data
-     *            Data to digest
-     * @return SHA3-384 digest as a hex string
-     * @since 1.12
-     */
-    public static String sha3_384Hex(final byte[] data) {
-        return Hex.encodeHexString(sha3_384(data));
-    }
-
-    /**
-     * Calculates the SHA3-512 digest and returns the value as a hex string.
-     *
-     * @param data
-     *            Data to digest
-     * @return SHA3-512 digest as a hex string
-     * @since 1.12
-     */
-    public static String sha3_512Hex(final byte[] data) {
-        return Hex.encodeHexString(sha3_512(data));
-    }
-
     /**
      * Calculates the SHA-512 digest and returns the value as a hex string.
      *
@@ -1049,62 +1120,6 @@ public static String sha512Hex(final InputStream data) throws IOException {
         return Hex.encodeHexString(sha512(data));
     }
 
-    /**
-     * Calculates the SHA3-224 digest and returns the value as a hex string.
-     *
-     * @param data
-     *            Data to digest
-     * @return SHA3-224 digest as a hex string
-     * @throws IOException
-     *             On error reading from the stream
-     * @since 1.12
-     */
-    public static String sha3_224Hex(final InputStream data) throws IOException {
-        return Hex.encodeHexString(sha3_224(data));
-    }
-
-    /**
-     * Calculates the SHA3-256 digest and returns the value as a hex string.
-     *
-     * @param data
-     *            Data to digest
-     * @return SHA3-256 digest as a hex string
-     * @throws IOException
-     *             On error reading from the stream
-     * @since 1.12
-     */
-    public static String sha3_256Hex(final InputStream data) throws IOException {
-        return Hex.encodeHexString(sha3_256(data));
-    }
-
-    /**
-     * Calculates the SHA3-384 digest and returns the value as a hex string.
-     *
-     * @param data
-     *            Data to digest
-     * @return SHA3-384 digest as a hex string
-     * @throws IOException
-     *             On error reading from the stream
-     * @since 1.12
-     */
-    public static String sha3_384Hex(final InputStream data) throws IOException {
-        return Hex.encodeHexString(sha3_384(data));
-    }
-
-    /**
-     * Calculates the SHA3-512 digest and returns the value as a hex string.
-     *
-     * @param data
-     *            Data to digest
-     * @return SHA3-512 digest as a hex string
-     * @throws IOException
-     *             On error reading from the stream
-     * @since 1.12
-     */
-    public static String sha3_512Hex(final InputStream data) throws IOException {
-        return Hex.encodeHexString(sha3_512(data));
-    }
-
     /**
      * Calculates the SHA-512 digest and returns the value as a hex string.
      *
@@ -1207,6 +1222,27 @@ public static MessageDigest updateDigest(final MessageDigest digest, final File
         }
     }
 
+    /**
+     * Reads through a RandomAccessFile and updates the digest for the data using non-blocking-io (NIO).
+     * 
+     * TODO Decide if this should be public.
+     *
+     * @param digest The MessageDigest to use (e.g. MD5)
+     * @param data Data to digest
+     * @return the digest
+     * @throws IOException On error reading from the stream
+     * @since 1.14
+     */
+    private static MessageDigest updateDigest(final MessageDigest digest, final FileChannel data) throws IOException {
+        final ByteBuffer buffer = ByteBuffer.allocate(STREAM_BUFFER_LENGTH);
+        while (data.read(buffer) > 0) {
+            buffer.flip();
+            digest.update(buffer);
+            buffer.clear();
+        }
+        return digest;
+    }
+
     /**
      * Reads through an InputStream and updates the digest for the data
      *
@@ -1231,6 +1267,21 @@ public static MessageDigest updateDigest(final MessageDigest digest, final Input
         return digest;
     }
 
+    
+    /**
+     * Reads through a RandomAccessFile and updates the digest for the data using non-blocking-io (NIO)
+     *
+     * @param digest The MessageDigest to use (e.g. MD5)
+     * @param data Data to digest
+     * @return the digest
+     * @throws IOException On error reading from the stream
+     * @since 1.14
+     */
+    public static MessageDigest updateDigest(final MessageDigest digest, final RandomAccessFile data)
+            throws IOException {
+        return updateDigest(digest, data.getChannel());
+    }
+
     /**
      * Updates the given {@link MessageDigest} from a String (converted to bytes using UTF-8).
      * <p>

src/test/java/org/apache/commons/codec/digest/DigestUtilsTest.java

@@ -24,6 +24,7 @@
 import java.io.File;
 import java.io.FileOutputStream;
 import java.io.IOException;
+import java.io.RandomAccessFile;
 import java.nio.ByteBuffer;
 import java.security.MessageDigest;
 import java.util.Random;
@@ -47,6 +48,10 @@ public class DigestUtilsTest {
 
     private File testFile;
 
+    private File testRandomAccessFile;
+
+    private RandomAccessFile testRandomAccessFileWrapper;
+
     private void assumeJava8() {
         Assume.assumeTrue(SystemUtils.isJavaVersionAtLeast(JavaVersion.JAVA_1_8));
     }
@@ -63,20 +68,34 @@ File getTestFile() {
         return testFile;
     }
 
+    RandomAccessFile getTestRandomAccessFile() {
+        return testRandomAccessFileWrapper;
+    }
+
     @Before
     public void setUp() throws Exception {
         new Random().nextBytes(testData);
         testFile = File.createTempFile(DigestUtilsTest.class.getName(), ".dat");
         try (final FileOutputStream fos = new FileOutputStream(testFile)) {
             fos.write(testData);
         }
+
+        testRandomAccessFile = File.createTempFile(DigestUtilsTest.class.getName(), ".dat");
+        try (final FileOutputStream fos = new FileOutputStream(testRandomAccessFile)) {
+            fos.write(testData);
+        }
+        testRandomAccessFileWrapper = new RandomAccessFile(testRandomAccessFile, "rw");
     }
 
     @After
     public void tearDown() {
         if (!testFile.delete()) {
             testFile.deleteOnExit();
         }
+
+        if (!testRandomAccessFile.delete()) {
+            testRandomAccessFile.deleteOnExit();
+        }
     }
 
     @Test(expected=IllegalArgumentException.class)