[CODEC-185] Added clarification concerning the use of the urlSafe parameter to Base64.

netomi · netomi · commit 2cb32b82b22d · 2014-11-01T16:27:52.000Z
git-svn-id: https://svn.apache.org/repos/asf/commons/proper/codec/trunk@1635986 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
@@ -43,6 +43,7 @@ The <action> type attribute can be add,update,fix,remove.
   </properties>
   <body>
     <release version="1.10" date="DD Mmmm 2014" description="Feature and fix release.">
+      <action dev="tn" type="fix" issue="CODEC-185" due-to="Sean Busbey">Added clarification to javadoc of Base64 concerning the use of the urlSafe parameter</action>   
       <action dev="tn" type="fix" issue="CODEC-191" due-to="Igor Savin">Added clarification to the javadoc of Base[32|64]OutputStream that it is mandatory to call close()</action>   
       <action dev="ggregory" type="fix" issue="CODEC-188" due-to="Hendrik Saly">Add support for HMAC Message Authentication Code (MAC) digests</action>   
       <action dev="ggregory" type="fix" issue="CODEC-187" due-to="Michael Tobias, Thomas Neidhart">Beider Morse Phonetic Matching producing incorrect tokens</action>   
diff --git a/src/main/java/org/apache/commons/codec/binary/Base64.java b/src/main/java/org/apache/commons/codec/binary/Base64.java
@@ -36,6 +36,9 @@
  * <li>Line separator: Default is CRLF ("\r\n")</li>
  * </ul>
  * <p>
+ * The URL-safe parameter is only applied to encode operations. Decoding seamlessly handles both modes.
+ * </p>
+ * <p>
  * Since this class operates directly on byte streams, and not character streams, it is hard-coded to only
  * encode/decode character encodings which are compatible with the lower 127 ASCII chart (ISO-8859-1, Windows-1252,
  * UTF-8, etc).
@@ -675,7 +678,10 @@ public static byte[] encodeBase64(final byte[] binaryData, final boolean isChunk
     }
 
     /**
-     * Decodes a Base64 String into octets
+     * Decodes a Base64 String into octets.
+     * <p>
+     * <b>Note:</b> this method seamlessly handles data encoded in URL-safe or normal mode.
+     * </p>
      *
      * @param base64String
      *            String containing Base64 data
@@ -687,7 +693,10 @@ public static byte[] decodeBase64(final String base64String) {
     }
 
     /**
-     * Decodes Base64 data into octets
+     * Decodes Base64 data into octets.
+     * <p>
+     * <b>Note:</b> this method seamlessly handles data encoded in URL-safe or normal mode.
+     * </p>
      *
      * @param base64Data
      *            Byte array containing Base64 data
@@ -701,7 +710,7 @@ public static byte[] decodeBase64(final byte[] base64Data) {
 
     // Implementation of integer encoding used for crypto
     /**
-     * Decodes a byte64-encoded integer according to crypto standards such as W3C's XML-Signature
+     * Decodes a byte64-encoded integer according to crypto standards such as W3C's XML-Signature.
      *
      * @param pArray
      *            a byte array containing base64 character data
@@ -713,7 +722,7 @@ public static BigInteger decodeInteger(final byte[] pArray) {
     }
 
     /**
-     * Encodes to a byte64-encoded integer according to crypto standards such as W3C's XML-Signature
+     * Encodes to a byte64-encoded integer according to crypto standards such as W3C's XML-Signature.
      *
      * @param bigInt
      *            a BigInteger
