[CODEC-278] Deprecate Charset constants in

org.apache.commons.codec.Charsets in favor of
java.nio.charset.StandardCharsets.

Author: garydgregory

src/changes/changes.xml

@@ -57,6 +57,7 @@ The <action> type attribute can be add,update,fix,remove.
       <action issue="CODEC-275" dev="ggregory" type="add" due-to="Claude Warren">Add missing note in javadoc when sign extension error is present #34.</action>
       <action issue="CODEC-276" dev="ggregory" type="fix" due-to="Gary Gregory">Reliance on default encoding in MurmurHash2 and MurmurHash3.</action>
       <action issue="CODEC-277" dev="ggregory" type="update" due-to="Gary Gregory">Don't reload standard Charsets in org.apache.commons.codec.Charsets.</action>
+      <action issue="CODEC-278" dev="ggregory" type="update" due-to="Gary Gregory">Deprecate Charset constants in org.apache.commons.codec.Charsets in favor of java.nio.charset.StandardCharsets.</action>
     </release>
 
     <release version="1.13" date="2019-07-20" description="Feature and fix release.">

src/main/java/org/apache/commons/codec/Charsets.java

@@ -92,25 +92,23 @@ public static Charset toCharset(final String charset) {
      * <p>
      * Every implementation of the Java platform is required to support this character encoding.
      * </p>
-     * <p>
-     * On Java 7 or later, use {@link java.nio.charset.StandardCharsets#ISO_8859_1} instead.
-     * </p>
      *
+     * @deprecated Use {@link java.nio.charset.StandardCharsets#ISO_8859_1} instead.
      * @see <a href="http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
      */
+    @Deprecated
     public static final Charset ISO_8859_1 = StandardCharsets.ISO_8859_1;
 
     /**
      * Seven-bit ASCII, also known as ISO646-US, also known as the Basic Latin block of the Unicode character set.
      * <p>
      * Every implementation of the Java platform is required to support this character encoding.
      * </p>
-     * <p>
-     * On Java 7 or later, use {@link java.nio.charset.StandardCharsets#ISO_8859_1} instead.
-     * </p>
      *
+     * @deprecated Use {@link java.nio.charset.StandardCharsets#US_ASCII} instead.
      * @see <a href="http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
      */
+    @Deprecated
     public static final Charset US_ASCII = StandardCharsets.US_ASCII;
 
     /**
@@ -119,50 +117,46 @@ public static Charset toCharset(final String charset) {
      * <p>
      * Every implementation of the Java platform is required to support this character encoding.
      * </p>
-     * <p>
-     * On Java 7 or later, use {@link java.nio.charset.StandardCharsets#ISO_8859_1} instead.
-     * </p>
      *
+     * @deprecated Use {@link java.nio.charset.StandardCharsets#UTF_16} instead.
      * @see <a href="http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
      */
+    @Deprecated
     public static final Charset UTF_16 = StandardCharsets.UTF_16;
 
     /**
      * Sixteen-bit Unicode Transformation Format, big-endian byte order.
      * <p>
      * Every implementation of the Java platform is required to support this character encoding.
      * </p>
-     * <p>
-     * On Java 7 or later, use {@link java.nio.charset.StandardCharsets#ISO_8859_1} instead.
-     * </p>
      *
+     * @deprecated Use {@link java.nio.charset.StandardCharsets#UTF_16BE} instead.
      * @see <a href="http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
      */
+    @Deprecated
     public static final Charset UTF_16BE = StandardCharsets.UTF_16BE;
 
     /**
      * Sixteen-bit Unicode Transformation Format, little-endian byte order.
      * <p>
      * Every implementation of the Java platform is required to support this character encoding.
      * </p>
-     * <p>
-     * On Java 7 or later, use {@link java.nio.charset.StandardCharsets#ISO_8859_1} instead.
-     * </p>
      *
+     * @deprecated Use {@link java.nio.charset.StandardCharsets#UTF_16LE} instead.
      * @see <a href="http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
      */
+    @Deprecated
     public static final Charset UTF_16LE = StandardCharsets.UTF_16LE;
 
     /**
      * Eight-bit Unicode Transformation Format.
      * <p>
      * Every implementation of the Java platform is required to support this character encoding.
      * </p>
-     * <p>
-     * On Java 7 or later, use {@link java.nio.charset.StandardCharsets#ISO_8859_1} instead.
-     * </p>
      *
+     * @deprecated Use {@link java.nio.charset.StandardCharsets#UTF_8} instead.
      * @see <a href="http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
      */
+    @Deprecated
     public static final Charset UTF_8 = StandardCharsets.UTF_8;
 }

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

@@ -29,7 +29,7 @@
 import org.apache.commons.codec.EncoderException;
 
 /**
- * Converts hexadecimal Strings. The charset used for certain operation can be set, the default is set in
+ * Converts hexadecimal Strings. The Charset used for certain operation can be set, the default is set in
  * {@link #DEFAULT_CHARSET_NAME}
  *
  * This class is thread-safe.
@@ -39,7 +39,7 @@
 public class Hex implements BinaryEncoder, BinaryDecoder {
 
     /**
-     * Default charset is {@link Charsets#UTF_8}
+     * Default charset is {@link StandardCharsets#UTF_8}
      *
      * @since 1.7
      */

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

@@ -121,7 +121,7 @@ private static ByteBuffer getByteBuffer(final String string, final Charset chars
      *            the String to encode, may be {@code null}
      * @return encoded bytes, or {@code null} if the input string was {@code null}
      * @throws NullPointerException
-     *             Thrown if {@link Charsets#UTF_8} is not initialized, which should never happen since it is
+     *             Thrown if {@link StandardCharsets#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/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
      * @see #getBytesUnchecked(String, String)
@@ -139,7 +139,7 @@ public static ByteBuffer getByteBufferUtf8(final String string) {
      *            the String to encode, may be {@code null}
      * @return encoded bytes, or {@code null} if the input string was {@code null}
      * @throws NullPointerException
-     *             Thrown if {@link Charsets#ISO_8859_1} is not initialized, which should never happen since it is
+     *             Thrown if {@link StandardCharsets#ISO_8859_1} is not initialized, which should never happen since it is
      *             required by the Java platform specification.
      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException
      * @see <a href="http://download.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
@@ -188,7 +188,7 @@ public static byte[] getBytesUnchecked(final String string, final String charset
      *            the String to encode, may be {@code null}
      * @return encoded bytes, or {@code null} if the input string was {@code null}
      * @throws NullPointerException
-     *             Thrown if {@link Charsets#US_ASCII} is not initialized, which should never happen since it is
+     *             Thrown if {@link StandardCharsets#US_ASCII} is not initialized, which should never happen since it is
      *             required by the Java platform specification.
      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException
      * @see <a href="http://download.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
@@ -206,7 +206,7 @@ public static byte[] getBytesUsAscii(final String string) {
      *            the String to encode, may be {@code null}
      * @return encoded bytes, or {@code null} if the input string was {@code null}
      * @throws NullPointerException
-     *             Thrown if {@link Charsets#UTF_16} is not initialized, which should never happen since it is
+     *             Thrown if {@link StandardCharsets#UTF_16} is not initialized, which should never happen since it is
      *             required by the Java platform specification.
      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException
      * @see <a href="http://download.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
@@ -224,7 +224,7 @@ public static byte[] getBytesUtf16(final String string) {
      *            the String to encode, may be {@code null}
      * @return encoded bytes, or {@code null} if the input string was {@code null}
      * @throws NullPointerException
-     *             Thrown if {@link Charsets#UTF_16BE} is not initialized, which should never happen since it is
+     *             Thrown if {@link StandardCharsets#UTF_16BE} is not initialized, which should never happen since it is
      *             required by the Java platform specification.
      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException
      * @see <a href="http://download.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
@@ -242,7 +242,7 @@ public static byte[] getBytesUtf16Be(final String string) {
      *            the String to encode, may be {@code null}
      * @return encoded bytes, or {@code null} if the input string was {@code null}
      * @throws NullPointerException
-     *             Thrown if {@link Charsets#UTF_16LE} is not initialized, which should never happen since it is
+     *             Thrown if {@link StandardCharsets#UTF_16LE} is not initialized, which should never happen since it is
      *             required by the Java platform specification.
      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException
      * @see <a href="http://download.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
@@ -260,7 +260,7 @@ public static byte[] getBytesUtf16Le(final String string) {
      *            the String to encode, may be {@code null}
      * @return encoded bytes, or {@code null} if the input string was {@code null}
      * @throws NullPointerException
-     *             Thrown if {@link Charsets#UTF_8} is not initialized, which should never happen since it is
+     *             Thrown if {@link StandardCharsets#UTF_8} is not initialized, which should never happen since it is
      *             required by the Java platform specification.
      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException
      * @see <a href="http://download.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
@@ -329,7 +329,7 @@ public static String newString(final byte[] bytes, final String charsetName) {
      * @return A new {@code String} decoded from the specified array of bytes using the ISO-8859-1 charset, or
      *         {@code null} if the input byte array was {@code null}.
      * @throws NullPointerException
-     *             Thrown if {@link Charsets#ISO_8859_1} is not initialized, which should never happen since it is
+     *             Thrown if {@link StandardCharsets#ISO_8859_1} is not initialized, which should never happen since it is
      *             required by the Java platform specification.
      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException
      */
@@ -345,7 +345,7 @@ public static String newStringIso8859_1(final byte[] bytes) {
      * @return A new {@code String} decoded from the specified array of bytes using the US-ASCII charset,
      *         or {@code null} if the input byte array was {@code null}.
      * @throws NullPointerException
-     *             Thrown if {@link Charsets#US_ASCII} is not initialized, which should never happen since it is
+     *             Thrown if {@link StandardCharsets#US_ASCII} is not initialized, which should never happen since it is
      *             required by the Java platform specification.
      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException
      */
@@ -361,7 +361,7 @@ public static String newStringUsAscii(final byte[] bytes) {
      * @return A new {@code String} decoded from the specified array of bytes using the UTF-16 charset
      *         or {@code null} if the input byte array was {@code null}.
      * @throws NullPointerException
-     *             Thrown if {@link Charsets#UTF_16} is not initialized, which should never happen since it is
+     *             Thrown if {@link StandardCharsets#UTF_16} is not initialized, which should never happen since it is
      *             required by the Java platform specification.
      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException
      */
@@ -377,7 +377,7 @@ public static String newStringUtf16(final byte[] bytes) {
      * @return A new {@code String} decoded from the specified array of bytes using the UTF-16BE charset,
      *         or {@code null} if the input byte array was {@code null}.
      * @throws NullPointerException
-     *             Thrown if {@link Charsets#UTF_16BE} is not initialized, which should never happen since it is
+     *             Thrown if {@link StandardCharsets#UTF_16BE} is not initialized, which should never happen since it is
      *             required by the Java platform specification.
      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException
      */
@@ -393,7 +393,7 @@ public static String newStringUtf16Be(final byte[] bytes) {
      * @return A new {@code String} decoded from the specified array of bytes using the UTF-16LE charset,
      *         or {@code null} if the input byte array was {@code null}.
      * @throws NullPointerException
-     *             Thrown if {@link Charsets#UTF_16LE} is not initialized, which should never happen since it is
+     *             Thrown if {@link StandardCharsets#UTF_16LE} is not initialized, which should never happen since it is
      *             required by the Java platform specification.
      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException
      */
@@ -409,7 +409,7 @@ public static String newStringUtf16Le(final byte[] bytes) {
      * @return A new {@code String} decoded from the specified array of bytes using the UTF-8 charset,
      *         or {@code null} if the input byte array was {@code null}.
      * @throws NullPointerException
-     *             Thrown if {@link Charsets#UTF_8} is not initialized, which should never happen since it is
+     *             Thrown if {@link StandardCharsets#UTF_8} is not initialized, which should never happen since it is
      *             required by the Java platform specification.
      * @since As of 1.7, throws {@link NullPointerException} instead of UnsupportedEncodingException
      */

src/main/java/org/apache/commons/codec/net/QuotedPrintableCodec.java

@@ -108,7 +108,7 @@ public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, Strin
     }
 
     /**
-     * Default constructor, assumes default Charset of {@link Charsets#UTF_8}
+     * Default constructor, assumes default Charset of {@link StandardCharsets#UTF_8}
      */
     public QuotedPrintableCodec() {
         this(StandardCharsets.UTF_8, false);

src/test/java/org/apache/commons/codec/CharsetsTest.java

@@ -37,31 +37,37 @@ public void testToCharset() {
         Assert.assertEquals(Charset.forName("UTF-8"), Charsets.toCharset(Charset.forName("UTF-8")));
     }
 
+    @SuppressWarnings("deprecation")
     @Test
     public void testIso8859_1() {
         Assert.assertEquals("ISO-8859-1", Charsets.ISO_8859_1.name());
     }
 
+    @SuppressWarnings("deprecation")
     @Test
     public void testUsAscii() {
         Assert.assertEquals("US-ASCII", Charsets.US_ASCII.name());
     }
 
+    @SuppressWarnings("deprecation")
     @Test
     public void testUtf16() {
         Assert.assertEquals("UTF-16", Charsets.UTF_16.name());
     }
 
+    @SuppressWarnings("deprecation")
     @Test
     public void testUtf16Be() {
         Assert.assertEquals("UTF-16BE", Charsets.UTF_16BE.name());
     }
 
+    @SuppressWarnings("deprecation")
     @Test
     public void testUtf16Le() {
         Assert.assertEquals("UTF-16LE", Charsets.UTF_16LE.name());
     }
 
+    @SuppressWarnings("deprecation")
     @Test
     public void testUtf8() {
         Assert.assertEquals("UTF-8", Charsets.UTF_8.name());