[CODEC-211] Create enum MessageDigestAlgorithm and deprecate class MessageDigestAlgorithms

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/codec/trunk@1743778 13f79535-47bb-0310-9956-ffa450edef68

Author: garydgregory

src/changes/changes.xml

@@ -47,6 +47,7 @@ The <action> type attribute can be add,update,fix,remove.
       <action dev="ggregory" type="fix" issue="CODEC-207" due-to="Gary Gregory">Charsets Javadoc breaks build when using Java 8</action>         
       <action dev="ggregory" type="fix" issue="CODEC-199" due-to="Yossi Tamari">Bug in HW rule in Soundex</action>         
       <action dev="ggregory" type="fix" issue="CODEC-209" due-to="Gary Gregory">Javadoc for SHA-224 DigestUtils methods should mention Java 1.8.0 restriction instead of 1.4.0.</action>         
+      <action dev="ggregory" type="add" issue="CODEC-211" due-to="Gary Gregory">Create enum MessageDigestAlgorithm and deprecate class MessageDigestAlgorithms</action>         
       <action dev="ggregory" type="add" issue="CODEC-210" due-to="Gary Gregory">Add DigestUtils.getDigest(String, MessageDigest)</action>         
       <action dev="ggregory" type="add" issue="CODEC-208" due-to="Gary Gregory">Make some DigestUtils APIs public</action>         
       <action dev="ggregory" type="add" issue="CODEC-206" due-to="Gary Gregory">Add java.io.File APIs to DigestUtils</action>         

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

@@ -39,6 +39,22 @@ public class DigestUtils {
 
     private static final int STREAM_BUFFER_LENGTH = 1024;
 
+    /**
+     * Read through an ByteBuffer and returns the digest for the data. Provided for symmetry with other methods.
+     *
+     * @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.11
+     */
+    public static byte[] digest(final MessageDigest messageDigest, final byte[] data) {
+        return messageDigest.digest(data);
+    }
+
     /**
      * Read through an ByteBuffer and returns the digest for the data
      *
@@ -110,14 +126,16 @@ public static MessageDigest getDigest(final String algorithm) {
     }
 
     /**
-     * Returns a <code>MessageDigest</code> for the given <code>algorithm</code> or a default if there is a problem getting the algorithm.
+     * Returns a <code>MessageDigest</code> for the given <code>algorithm</code> or a default if there is a problem
+     * getting the algorithm.
      *
      * @param algorithm
-     *            the name of the algorithm requested. See <a
-     *            href="http://docs.oracle.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html#AppA"
-     *            >Appendix A in the Java Cryptography Architecture Reference Guide</a> for information about standard
+     *            the name of the algorithm requested. See
+     *            <a href="http://docs.oracle.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html#AppA" >
+     *            Appendix A in the Java Cryptography Architecture Reference Guide</a> for information about standard
      *            algorithm names.
-     * @param defaultMessageDigest The default MessageDigest.
+     * @param defaultMessageDigest
+     *            The default MessageDigest.
      * @return A digest instance.
      * @see MessageDigest#getInstance(String)
      * @throws IllegalArgumentException
@@ -143,7 +161,7 @@ public static MessageDigest getDigest(final String algorithm, MessageDigest defa
      * @since 1.7
      */
     public static MessageDigest getMd2Digest() {
-        return getDigest(MessageDigestAlgorithms.MD2);
+        return MessageDigestAlgorithm.MD2.getMessageDigest();
     }
 
     /**
@@ -156,7 +174,7 @@ public static MessageDigest getMd2Digest() {
      * @see MessageDigestAlgorithms#MD5
      */
     public static MessageDigest getMd5Digest() {
-        return getDigest(MessageDigestAlgorithms.MD5);
+        return MessageDigestAlgorithm.MD5.getMessageDigest();
     }
 
     /**
@@ -170,7 +188,7 @@ public static MessageDigest getMd5Digest() {
      * @since 1.7
      */
     public static MessageDigest getSha1Digest() {
-        return getDigest(MessageDigestAlgorithms.SHA_1);
+        return MessageDigestAlgorithm.SHA_1.getMessageDigest();
     }
 
     /**
@@ -186,7 +204,7 @@ public static MessageDigest getSha1Digest() {
      * @see MessageDigestAlgorithms#SHA_224
      */
     public static MessageDigest getSha224Digest() {
-        return getDigest(MessageDigestAlgorithms.SHA_224);
+        return MessageDigestAlgorithm.SHA_224.getMessageDigest();
     }
 
     /**
@@ -202,7 +220,7 @@ public static MessageDigest getSha224Digest() {
      * @see MessageDigestAlgorithms#SHA_256
      */
     public static MessageDigest getSha256Digest() {
-        return getDigest(MessageDigestAlgorithms.SHA_256);
+        return MessageDigestAlgorithm.SHA_256.getMessageDigest();
     }
 
     /**
@@ -218,7 +236,7 @@ public static MessageDigest getSha256Digest() {
      * @see MessageDigestAlgorithms#SHA_384
      */
     public static MessageDigest getSha384Digest() {
-        return getDigest(MessageDigestAlgorithms.SHA_384);
+        return MessageDigestAlgorithm.SHA_384.getMessageDigest();
     }
 
     /**
@@ -234,7 +252,7 @@ public static MessageDigest getSha384Digest() {
      * @see MessageDigestAlgorithms#SHA_512
      */
     public static MessageDigest getSha512Digest() {
-        return getDigest(MessageDigestAlgorithms.SHA_512);
+        return MessageDigestAlgorithm.SHA_512.getMessageDigest();
     }
 
     /**

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

@@ -0,0 +1,167 @@
+/*
+ * 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.codec.digest;
+
+import java.io.File;
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.ByteBuffer;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+
+/**
+ * Standard {@link MessageDigest} algorithm names from the <cite>Java Cryptography Architecture Standard Algorithm Name
+ * Documentation</cite>.
+ * <p>
+ * This enum is immutable and thread-safe.
+ * </p>
+ *
+ * @see <a href="http://docs.oracle.com/javase/6/docs/technotes/guides/security/StandardNames.html">Java Cryptography
+ *      Architecture Standard Algorithm Name Documentation</a>
+ * @since 1.11
+ * @version $Id: MessageDigestAlgorithm.java 1637936 2014-11-10 16:47:29Z ggregory $
+ */
+public enum MessageDigestAlgorithm {
+
+    /**
+     * The MD2 message digest algorithm defined in RFC 1319.
+     */
+    MD2("MD2"),
+
+    /**
+     * The MD5 message digest algorithm defined in RFC 1321.
+     */
+    MD5("MD5"),
+
+    /**
+     * The SHA-1 hash algorithm defined in the FIPS PUB 180-2.
+     */
+    SHA_1("SHA-1"),
+
+    /**
+     * The SHA-224 hash algorithm defined in the FIPS PUB 180-4.
+     * <p>
+     * Java 8 only.
+     * </p>
+     */
+    SHA_224("SHA-224"),
+
+    /**
+     * The SHA-256 hash algorithm defined in the FIPS PUB 180-2.
+     */
+    SHA_256("SHA-256"),
+
+    /**
+     * The SHA-384 hash algorithm defined in the FIPS PUB 180-2.
+     */
+    SHA_384("SHA-384"),
+
+    /**
+     * The SHA-512 hash algorithm defined in the FIPS PUB 180-2.
+     */
+    SHA_512("SHA-512");
+
+    private final String algorithm;
+
+    private MessageDigestAlgorithm(String algorithm) {
+        this.algorithm = algorithm;
+    }
+
+    /**
+     * Read through a byte[] and returns the digest for the data
+     *
+     * @param data
+     *            Data to digest
+     * @return the digest
+     * @throws IOException
+     *             On error reading from the stream
+     */
+    public byte[] digest(byte[] data) throws IOException {
+        return getMessageDigest().digest(data);
+    }
+
+    /**
+     * Read through a ByteBuffer and returns the digest for the data
+     *
+     * @param data
+     *            Data to digest
+     * @return the digest
+     * @throws IOException
+     *             On error reading from the stream
+     */
+    public byte[] digest(ByteBuffer data) throws IOException {
+        return DigestUtils.digest(getMessageDigest(), data);
+    }
+
+    /**
+     * Read through a File and returns the digest for the data
+     *
+     * @param data
+     *            Data to digest
+     * @return the digest
+     * @throws IOException
+     *             On error reading from the stream
+     */
+    public byte[] digest(File data) throws IOException {
+        return DigestUtils.digest(getMessageDigest(), data);
+    }
+
+    /**
+     * Read through an InputStream and returns the digest for the data
+     *
+     * @param data
+     *            Data to digest
+     * @return the digest
+     * @throws IOException
+     *             On error reading from the stream
+     */
+    public byte[] digest(InputStream data) throws IOException {
+        return DigestUtils.digest(getMessageDigest(), data);
+    }
+
+    /**
+     * Gets the algorithm name.
+     *
+     * @return the algorithm name.
+     */
+    public String getAlgorithm() {
+        return algorithm;
+    }
+
+    /**
+     * Returns a <code>MessageDigest</code> for this <code>algorithm</code>.
+     *
+     * @return A digest instance.
+     * @see MessageDigest#getInstance(String)
+     * @throws IllegalArgumentException
+     *             when a {@link NoSuchAlgorithmException} is caught.
+     */
+    public MessageDigest getMessageDigest() {
+        return DigestUtils.getDigest(algorithm);
+    }
+
+    /**
+     * Whether a MessageDigest for this algorithm can be created.
+     *
+     * @return Whether a MessageDigest for this algorithm can be created.
+     */
+    public boolean isAvailable() {
+        return DigestUtils.getDigest(algorithm, null) != null;
+    }
+
+}

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

@@ -25,13 +25,14 @@
  * <p>
  * This class is immutable and thread-safe.
  * </p>
- * TODO 2.0 This should be an enum.
  *
  * @see <a href="http://docs.oracle.com/javase/6/docs/technotes/guides/security/StandardNames.html">Java Cryptography
  *      Architecture Standard Algorithm Name Documentation</a>
  * @since 1.7
+ * @deprecated Use the enum {@link MessageDigestAlgorithm}.
  * @version $Id$
  */
+@Deprecated
 public class MessageDigestAlgorithms {
 
     private MessageDigestAlgorithms() {
@@ -54,11 +55,11 @@ private MessageDigestAlgorithms() {
     public static final String SHA_1 = "SHA-1";
 
     /**
-     * The SHA-224 hash algorithm defined in the FIPS PUB 180-4. 
+     * The SHA-224 hash algorithm defined in the FIPS PUB 180-4.
      * <p>
      * Java 8 only.
      * </p>
-     * 
+     *
      * @since 1.11
      */
     public static final String SHA_224 = "SHA-224";

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

@@ -50,6 +50,18 @@ public class DigestUtilsTest {
 
     private File testFile;
 
+    private void assumeJava8() {
+        Assume.assumeTrue(SystemUtils.isJavaVersionAtLeast(JavaVersion.JAVA_1_8));
+    }
+
+    byte[] getTestData() {
+        return testData;
+    }
+
+    File getTestFile() {
+        return testFile;
+    }
+
     @Before
     public void setUp() throws Exception {
         new Random().nextBytes(testData);
@@ -311,10 +323,6 @@ public void testSha224() throws IOException {
         // Examples from FIPS 180-4?
     }
 
-    private void assumeJava8() {
-        Assume.assumeTrue(SystemUtils.isJavaVersionAtLeast(JavaVersion.JAVA_1_8));
-    }
-
     @Test
     public void testSha224HexFile() throws IOException {
         assumeJava8();