[CODEC-73] Hex: Make string2byte conversions indepedent of platform default encoding.

Also refactor DigestUtils to call a new method on Hex.

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

Author: garydgregory

src/java/org/apache/commons/codec/binary/Hex.java

@@ -17,48 +17,49 @@
 
 package org.apache.commons.codec.binary;
 
+import java.io.UnsupportedEncodingException;
+
 import org.apache.commons.codec.BinaryDecoder;
 import org.apache.commons.codec.BinaryEncoder;
+import org.apache.commons.codec.CharEncoding;
 import org.apache.commons.codec.DecoderException;
 import org.apache.commons.codec.EncoderException;
 
 /**
- * Hex encoder and decoder.
+ * Hex encoder and decoder. The charset used for certain operation can be set, the default is set in
+ * {@link #DEFAULT_CHARSET_NAME}
  * 
  * @since 1.1
  * @author Apache Software Foundation
  * @version $Id$
  */
 public class Hex implements BinaryEncoder, BinaryDecoder {
 
-    /** 
-     * Used to build output as Hex 
+    /**
+     * Default charset name is {@link CharEncoding#UTF_8}
      */
-    private static final char[] DIGITS_LOWER = {
-        '0', '1', '2', '3', '4', '5', '6', '7',
-           '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'
-    };
+    public static final String DEFAULT_CHARSET_NAME = CharEncoding.UTF_8;
 
-    /** 
-     * Used to build output as Hex 
+    /**
+     * Used to build output as Hex
      */
-    private static final char[] DIGITS_UPPER = {
-        '0', '1', '2', '3', '4', '5', '6', '7',
-           '8', '9', 'A', 'B', 'C', 'D', 'E', 'F'
-    };
+    private static final char[] DIGITS_LOWER = {'0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'};
 
     /**
-     * Converts an array of characters representing hexadecimal values into an
-     * array of bytes of those same values. The returned array will be half the
-     * length of the passed array, as it takes two characters to represent any
-     * given byte. An exception is thrown if the passed char array has an odd
-     * number of elements.
+     * Used to build output as Hex
+     */
+    private static final char[] DIGITS_UPPER = {'0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', 'B', 'C', 'D', 'E', 'F'};
+
+    /**
+     * Converts an array of characters representing hexadecimal values into an array of bytes of those same values. The
+     * returned array will be half the length of the passed array, as it takes two characters to represent any given
+     * byte. An exception is thrown if the passed char array has an odd number of elements.
      * 
-     * @param data An array of characters containing hexadecimal digits
-     * @return A byte array containing binary data decoded from
-     *         the supplied char array.
-     * @throws DecoderException Thrown if an odd number or illegal of characters 
-     *         is supplied
+     * @param data
+     *            An array of characters containing hexadecimal digits
+     * @return A byte array containing binary data decoded from the supplied char array.
+     * @throws DecoderException
+     *             Thrown if an odd number or illegal of characters is supplied
      */
     public static byte[] decodeHex(char[] data) throws DecoderException {
 
@@ -82,22 +83,6 @@ public static byte[] decodeHex(char[] data) throws DecoderException {
         return out;
     }
 
-    /**
-     * Converts a hexadecimal character to an integer.
-     *  
-     * @param ch A character to convert to an integer digit
-     * @param index The index of the character in the source
-     * @return An integer
-     * @throws DecoderException Thrown if ch is an illegal hex character
-     */
-    protected static int toDigit(char ch, int index) throws DecoderException {
-        int digit = Character.digit(ch, 16);
-        if (digit == -1) {
-            throw new DecoderException("Illegal hexadecimal charcter " + ch + " at index " + index);
-        }
-        return digit;
-    }
-
     /**
      * Converts an array of bytes into an array of characters representing the hexadecimal values of each byte in order.
      * The returned array will be double the length of the passed array, as it takes two characters to represent any
@@ -151,35 +136,87 @@ protected static char[] encodeHex(byte[] data, char[] toDigits) {
     }
 
     /**
-     * Converts an array of character bytes representing hexadecimal values into an
-     * array of bytes of those same values. The returned array will be half the
-     * length of the passed array, as it takes two characters to represent any
-     * given byte. An exception is thrown if the passed char array has an odd
-     * number of elements.
+     * Converts an array of bytes into a String representing the hexadecimal values of each byte in order. The returned
+     * String will be double the length of the passed array, as it takes two characters to represent any given byte.
+     * 
+     * @param data
+     *            a byte[] to convert to Hex characters
+     * @return A String containing hexadecimal characters
+     * @since 1.4
+     */
+    public static String encodeHexString(byte[] data) {
+        return new String(encodeHex(data));
+    }
+
+    /**
+     * Converts a hexadecimal character to an integer.
      * 
-     * @param array An array of character bytes containing hexadecimal digits
-     * @return A byte array containing binary data decoded from
-     *         the supplied byte array (representing characters).
-     * @throws DecoderException Thrown if an odd number of characters is supplied
-     *                   to this function
+     * @param ch
+     *            A character to convert to an integer digit
+     * @param index
+     *            The index of the character in the source
+     * @return An integer
+     * @throws DecoderException
+     *             Thrown if ch is an illegal hex character
+     */
+    protected static int toDigit(char ch, int index) throws DecoderException {
+        int digit = Character.digit(ch, 16);
+        if (digit == -1) {
+            throw new DecoderException("Illegal hexadecimal charcter " + ch + " at index " + index);
+        }
+        return digit;
+    }
+
+    private String charsetName = DEFAULT_CHARSET_NAME;
+
+    /**
+     * Creates a new codec with the default charset name {@link #DEFAULT_CHARSET_NAME}
+     */
+    public Hex() {
+        // use default encoding
+    }
+
+    /**
+     * Creates a new codec with the given charset name.
+     * 
+     * @param csName
+     *            the charset name.
+     */
+    public Hex(String csName) {
+        setCharsetName(csName);
+    }
+
+    /**
+     * Converts an array of character bytes representing hexadecimal values into an array of bytes of those same values.
+     * The returned array will be half the length of the passed array, as it takes two characters to represent any given
+     * byte. An exception is thrown if the passed char array has an odd number of elements.
+     * 
+     * @param array
+     *            An array of character bytes containing hexadecimal digits
+     * @return A byte array containing binary data decoded from the supplied byte array (representing characters).
+     * @throws DecoderException
+     *             Thrown if an odd number of characters is supplied to this function
      * @see #decodeHex(char[])
      */
     public byte[] decode(byte[] array) throws DecoderException {
-        return decodeHex(new String(array).toCharArray());
+        try {
+            return decodeHex(new String(array, getCharsetName()).toCharArray());
+        } catch (UnsupportedEncodingException e) {
+            throw new DecoderException(e.getMessage(), e);
+        }
     }
-    
+
     /**
-     * Converts a String or an array of character bytes representing hexadecimal values into an
-     * array of bytes of those same values. The returned array will be half the
-     * length of the passed String or array, as it takes two characters to represent any
-     * given byte. An exception is thrown if the passed char array has an odd
-     * number of elements.
+     * Converts a String or an array of character bytes representing hexadecimal values into an array of bytes of those
+     * same values. The returned array will be half the length of the passed String or array, as it takes two characters
+     * to represent any given byte. An exception is thrown if the passed char array has an odd number of elements.
      * 
-     * @param object A String or, an array of character bytes containing hexadecimal digits
-     * @return A byte array containing binary data decoded from
-     *         the supplied byte array (representing characters).
-     * @throws DecoderException Thrown if an odd number of characters is supplied
-     *                   to this function or the object is not a String or char[]
+     * @param object
+     *            A String or, an array of character bytes containing hexadecimal digits
+     * @return A byte array containing binary data decoded from the supplied byte array (representing characters).
+     * @throws DecoderException
+     *             Thrown if an odd number of characters is supplied to this function or the object is not a String or
+     *             char[]
      * @see #decodeHex(char[])
      */
     public Object decode(Object object) throws DecoderException {
@@ -192,38 +229,73 @@ public Object decode(Object object) throws DecoderException {
     }
 
     /**
-     * Converts an array of bytes into an array of bytes for the characters representing the
-     * hexadecimal values of each byte in order. The returned array will be
-     * double the length of the passed array, as it takes two characters to
+     * Converts an array of bytes into an array of bytes for the characters representing the hexadecimal values of each
+     * byte in order. The returned array will be double the length of the passed array, as it takes two characters to
      * represent any given byte.
-     *
-     * @param array a byte[] to convert to Hex characters
+     * <p>
+     * The conversion from hexadecimal characters to the returned bytes is performed with the charset named by
+     * {@link #getCharsetName()}.
+     * </p>
+     * 
+     * @param array
+     *            a byte[] to convert to Hex characters
      * @return A byte[] containing the bytes of the hexadecimal characters
+     * @throws IllegalStateException
+     *             if the charsetName is invalid. This API throws {@link IllegalStateException} instead of
+     *             {@link UnsupportedEncodingException} for backward compatibility.
      * @see #encodeHex(byte[])
      */
     public byte[] encode(byte[] array) {
-        return new String(encodeHex(array)).getBytes();
+        return StringUtils.getBytesUnchecked(encodeHexString(array), getCharsetName());
     }
 
     /**
-     * Converts a String or an array of bytes into an array of characters representing the
-     * hexadecimal values of each byte in order. The returned array will be
-     * double the length of the passed String or array, as it takes two characters to
-     * represent any given byte.
-     *
-     * @param object a String, or byte[] to convert to Hex characters
+     * Converts a String or an array of bytes into an array of characters representing the hexadecimal values of each
+     * byte in order. The returned array will be double the length of the passed String or array, as it takes two
+     * characters to represent any given byte.
+     * <p>
+     * The conversion from hexadecimal characters to bytes to be encoded to performed with the charset named by
+     * {@link #getCharsetName()}.
+     * </p>
+     * 
+     * @param object
+     *            a String, or byte[] to convert to Hex characters
      * @return A char[] containing hexadecimal characters
-     * @throws EncoderException Thrown if the given object is not a String or byte[]
+     * @throws EncoderException
+     *             Thrown if the given object is not a String or byte[]
      * @see #encodeHex(byte[])
      */
-    public Object encode(Object object) throws EncoderException {    
+    public Object encode(Object object) throws EncoderException {
         try {
-            byte[] byteArray = object instanceof String ? ((String) object).getBytes() : (byte[]) object;
+            byte[] byteArray = object instanceof String ? ((String) object).getBytes(getCharsetName()) : (byte[]) object;
             return encodeHex(byteArray);
         } catch (ClassCastException e) {
             throw new EncoderException(e.getMessage(), e);
+        } catch (UnsupportedEncodingException e) {
+            throw new EncoderException(e.getMessage(), e);
         }
     }
 
-}
+    /**
+     * Gets the charset name.
+     * 
+     * @return the charset name.
+     */
+    public String getCharsetName() {
+        return this.charsetName;
+    }
+
+    /**
+     * Sets the charset name.
+     * 
+     * @param charsetName
+     *            the charset name.
+     */
+    public void setCharsetName(String charsetName) {
+        this.charsetName = charsetName;
+    }
 
+    public String toString() {
+        return super.toString() + "[charsetName=" + this.charsetName + "]";
+    }
+}

src/java/org/apache/commons/codec/binary/StringUtils.java

@@ -43,10 +43,10 @@ public class StringUtils {
      * @throws IllegalStateException
      *             Thrown when the charset is missing, which should be never according the the Java specification.
      * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
-     * @see #getSupportedBytes(String, String)
+     * @see #getBytesUnchecked(String, String)
      */
     public static byte[] getBytesIso8859_1(String string) {
-        return StringUtils.getSupportedBytes(string, CharEncoding.ISO_8859_1);
+        return StringUtils.getBytesUnchecked(string, CharEncoding.ISO_8859_1);
     }
 
     /**
@@ -59,10 +59,10 @@ public static byte[] getBytesIso8859_1(String string) {
      * @throws IllegalStateException
      *             Thrown when the charset is missing, which should be never according the the Java specification.
      * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
-     * @see #getSupportedBytes(String, String)
+     * @see #getBytesUnchecked(String, String)
      */
     public static byte[] getBytesUsAscii(String string) {
-        return StringUtils.getSupportedBytes(string, CharEncoding.US_ASCII);
+        return StringUtils.getBytesUnchecked(string, CharEncoding.US_ASCII);
     }
 
     /**
@@ -75,10 +75,10 @@ public static byte[] getBytesUsAscii(String string) {
      * @throws IllegalStateException
      *             Thrown when the charset is missing, which should be never according the the Java specification.
      * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
-     * @see #getSupportedBytes(String, String)
+     * @see #getBytesUnchecked(String, String)
      */
     public static byte[] getBytesUtf16(String string) {
-        return StringUtils.getSupportedBytes(string, CharEncoding.UTF_16);
+        return StringUtils.getBytesUnchecked(string, CharEncoding.UTF_16);
     }
 
     /**
@@ -91,10 +91,10 @@ public static byte[] getBytesUtf16(String string) {
      * @throws IllegalStateException
      *             Thrown when the charset is missing, which should be never according the the Java specification.
      * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
-     * @see #getSupportedBytes(String, String)
+     * @see #getBytesUnchecked(String, String)
      */
     public static byte[] getBytesUtf16Be(String string) {
-        return StringUtils.getSupportedBytes(string, CharEncoding.UTF_16BE);
+        return StringUtils.getBytesUnchecked(string, CharEncoding.UTF_16BE);
     }
 
     /**
@@ -107,10 +107,10 @@ public static byte[] getBytesUtf16Be(String string) {
      * @throws IllegalStateException
      *             Thrown when the charset is missing, which should be never according the the Java specification.
      * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
-     * @see #getSupportedBytes(String, String)
+     * @see #getBytesUnchecked(String, String)
      */
     public static byte[] getBytesUtf16Le(String string) {
-        return StringUtils.getSupportedBytes(string, CharEncoding.UTF_16LE);
+        return StringUtils.getBytesUnchecked(string, CharEncoding.UTF_16LE);
     }
 
     /**
@@ -123,10 +123,10 @@ public static byte[] getBytesUtf16Le(String string) {
      * @throws IllegalStateException
      *             Thrown when the charset is missing, which should be never according the the Java specification.
      * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
-     * @see #getSupportedBytes(String, String)
+     * @see #getBytesUnchecked(String, String)
      */
     public static byte[] getBytesUtf8(String string) {
-        return StringUtils.getSupportedBytes(string, CharEncoding.UTF_8);
+        return StringUtils.getBytesUnchecked(string, CharEncoding.UTF_8);
     }
 
     /**
@@ -148,7 +148,7 @@ public static byte[] getBytesUtf8(String string) {
      * @see CharEncoding
      * @see String#getBytes(String)
      */
-    public static byte[] getSupportedBytes(String string, String charsetName) {
+    public static byte[] getBytesUnchecked(String string, String charsetName) {
         if (string == null) {
             return null;
         }