[CODEC-194] Support java.nio.ByteBuffer in org.apache.commons.codec.binary.Hex.

garydgregory · garydgregory · commit c5154bc58484 · 2014-11-10T15:29:02.000Z
git-svn-id: https://svn.apache.org/repos/asf/commons/proper/codec/trunk@1637888 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
@@ -43,7 +43,7 @@ The <action> type attribute can be add,update,fix,remove.
   </properties>
   <body>
     <release version="1.11" date="DD MM 2014" description="Feature and fix release.">
-      
+      <action dev="ggregory" type="add" issue="CODEC-194">Support java.nio.ByteBuffer in org.apache.commons.codec.binary.Hex</action>         
     </release>   
     <release version="1.10" date="5 November 2014" description="Feature and fix release.">
       <action dev="ggregory" type="add" issue="CODEC-192" due-to="Thomas Neidhart">Add Daitch-Mokotoff Soundex</action>   
diff --git a/src/main/java/org/apache/commons/codec/binary/Hex.java b/src/main/java/org/apache/commons/codec/binary/Hex.java
@@ -17,6 +17,7 @@
 
 package org.apache.commons.codec.binary;
 
+import java.nio.ByteBuffer;
 import java.nio.charset.Charset;
 
 import org.apache.commons.codec.BinaryDecoder;
@@ -109,6 +110,20 @@ public static char[] encodeHex(final byte[] data) {
         return encodeHex(data, true);
     }
 
+    /**
+     * Converts a byte buffer 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
+     * given byte.
+     *
+     * @param data
+     *            a byte buffer to convert to Hex characters
+     * @return A char[] containing hexadecimal characters
+     * @since 1.11
+     */
+    public static char[] encodeHex(final ByteBuffer data) {
+        return encodeHex(data, true);
+    }
+
     /**
      * 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
@@ -125,6 +140,22 @@ public static char[] encodeHex(final byte[] data, final boolean toLowerCase) {
         return encodeHex(data, toLowerCase ? DIGITS_LOWER : DIGITS_UPPER);
     }
 
+    /**
+     * Converts a byte buffer 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
+     * given byte.
+     *
+     * @param data
+     *            a byte buffer to convert to Hex characters
+     * @param toLowerCase
+     *            <code>true</code> converts to lowercase, <code>false</code> to uppercase
+     * @return A char[] containing hexadecimal characters
+     * @since 1.11
+     */
+    public static char[] encodeHex(final ByteBuffer data, final boolean toLowerCase) {
+        return encodeHex(data, toLowerCase ? DIGITS_LOWER : DIGITS_UPPER);
+    }
+
     /**
      * 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
@@ -148,6 +179,22 @@ protected static char[] encodeHex(final byte[] data, final char[] toDigits) {
         return out;
     }
 
+    /**
+     * Converts a byte buffer 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
+     * given byte.
+     *
+     * @param data
+     *            a byte buffer to convert to Hex characters
+     * @param toDigits
+     *            the output alphabet
+     * @return A char[] containing hexadecimal characters
+     * @since 1.11
+     */
+    protected static char[] encodeHex(final ByteBuffer data, final char[] toDigits) {
+        return encodeHex(data.array(), toDigits);
+    }
+
     /**
      * 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.
@@ -161,6 +208,19 @@ public static String encodeHexString(final byte[] data) {
         return new String(encodeHex(data));
     }
 
+    /**
+     * Converts a byte buffer 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 buffer to convert to Hex characters
+     * @return A String containing hexadecimal characters
+     * @since 1.11
+     */
+    public static String encodeHexString(final ByteBuffer data) {
+        return new String(encodeHex(data));
+    }
+
     /**
      * Converts a hexadecimal character to an integer.
      *
@@ -232,13 +292,30 @@ public byte[] decode(final byte[] array) throws DecoderException {
         return decodeHex(new String(array, getCharset()).toCharArray());
     }
 
+    /**
+     * Converts a buffer 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 buffer
+     *            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[])
+     * @since 1.11
+     */
+    public byte[] decode(final ByteBuffer buffer) throws DecoderException {
+        return decodeHex(new String(buffer.array(), getCharset()).toCharArray());
+    }
+
     /**
      * 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
+     *            A String, ByteBuffer, byte[], 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
@@ -247,11 +324,18 @@ public byte[] decode(final byte[] array) throws DecoderException {
      */
     @Override
     public Object decode(final Object object) throws DecoderException {
-        try {
-            final char[] charArray = object instanceof String ? ((String) object).toCharArray() : (char[]) object;
-            return decodeHex(charArray);
-        } catch (final ClassCastException e) {
-            throw new DecoderException(e.getMessage(), e);
+        if (object instanceof String) {
+            return decode(((String) object).toCharArray());
+        } else if (object instanceof byte[]) {
+            return decode((byte[]) object);
+        } else if (object instanceof ByteBuffer) {
+            return decode((ByteBuffer) object);
+        } else {
+            try {
+                return decodeHex((char[]) object);
+            } catch (final ClassCastException e) {
+                throw new DecoderException(e.getMessage(), e);
+            }
         }
     }
 
@@ -275,6 +359,25 @@ public byte[] encode(final byte[] array) {
         return encodeHexString(array).getBytes(this.getCharset());
     }
 
+    /**
+     * Converts byte buffer 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.
+     * <p>
+     * The conversion from hexadecimal characters to the returned bytes is performed with the charset named by
+     * {@link #getCharset()}.
+     * </p>
+     *
+     * @param array
+     *            a byte buffer to convert to Hex characters
+     * @return A byte[] containing the bytes of the hexadecimal characters
+     * @see #encodeHex(byte[])
+     * @since 1.11
+     */
+    public byte[] encode(final ByteBuffer array) {
+        return encodeHexString(array).getBytes(this.getCharset());
+    }
+
     /**
      * 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
@@ -285,21 +388,27 @@ public byte[] encode(final byte[] array) {
      * </p>
      *
      * @param object
-     *            a String, or byte[] to convert to Hex characters
+     *            a String, ByteBuffer, 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[]
      * @see #encodeHex(byte[])
      */
     @Override
     public Object encode(final Object object) throws EncoderException {
-        try {
-            final byte[] byteArray = object instanceof String ?
-                                   ((String) object).getBytes(this.getCharset()) : (byte[]) object;
-            return encodeHex(byteArray);
-        } catch (final ClassCastException e) {
-            throw new EncoderException(e.getMessage(), e);
+        byte[] byteArray;
+        if (object instanceof String) {
+            byteArray = ((String) object).getBytes(this.getCharset());
+        } else if (object instanceof ByteBuffer) {
+            byteArray = ((ByteBuffer) object).array();
+        } else {
+            try {
+                byteArray = (byte[]) object;
+            } catch (final ClassCastException e) {
+                throw new EncoderException(e.getMessage(), e);
+            }
         }
+        return encodeHex(byteArray);
     }
 
     /**
diff --git a/src/main/java/org/apache/commons/codec/binary/StringUtils.java b/src/main/java/org/apache/commons/codec/binary/StringUtils.java
@@ -18,6 +18,7 @@
 package org.apache.commons.codec.binary;
 
 import java.io.UnsupportedEncodingException;
+import java.nio.ByteBuffer;
 import java.nio.charset.Charset;
 
 import org.apache.commons.codec.CharEncoding;
@@ -96,6 +97,41 @@ private static byte[] getBytes(final String string, final Charset charset) {
         return string.getBytes(charset);
     }
 
+    /**
+     * Calls {@link String#getBytes(Charset)}
+     *
+     * @param string
+     *            The string to encode (if null, return null).
+     * @param charset
+     *            The {@link Charset} to encode the <code>String</code>
+     * @return the encoded bytes
+     * @since 1.11
+     */
+    private static ByteBuffer getByteBuffer(final String string, final Charset charset) {
+        if (string == null) {
+            return null;
+        }
+        return ByteBuffer.wrap(string.getBytes(charset));
+    }
+
+    /**
+     * Encodes the given string into a byte buffer using the UTF-8 charset, storing the result into a new byte
+     * array.
+     *
+     * @param string
+     *            the String to encode, may be <code>null</code>
+     * @return encoded bytes, or <code>null</code> if the input string was <code>null</code>
+     * @throws NullPointerException
+     *             Thrown if {@link Charsets#UTF_8} is not initialized, which should never happen since it is
+     *             required by the Java platform specification.
+     * @see <a href="http://download.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
+     * @see #getBytesUnchecked(String, String)
+     * @since 1.11
+     */
+    public static ByteBuffer getByteBufferUtf8(final String string) {
+        return getByteBuffer(string, Charsets.UTF_8);
+    }
+
     /**
      * Encodes the given string into a sequence of bytes using the ISO-8859-1 charset, storing the result into a new
      * byte array.
diff --git a/src/test/java/org/apache/commons/codec/binary/HexTest.java b/src/test/java/org/apache/commons/codec/binary/HexTest.java
