8145468: update java.lang APIs with new deprecations

Reviewed-by: alanb, psandoz, lancea, forax, scolebourne, chegar, martin

jdk/src/java.base/share/classes/java/lang/Boolean.java

@@ -79,13 +79,16 @@ public final class Boolean implements java.io.Serializable,
      * Allocates a {@code Boolean} object representing the
      * {@code value} argument.
      *
-     * <p><b>Note: It is rarely appropriate to use this constructor.
-     * Unless a <i>new</i> instance is required, the static factory
-     * {@link #valueOf(boolean)} is generally a better choice. It is
-     * likely to yield significantly better space and time performance.</b>
-     *
      * @param   value   the value of the {@code Boolean}.
+     *
+     * @deprecated
+     * It is rarely appropriate to use this constructor. The static factory
+     * {@link #valueOf(boolean)} is generally a better choice, as it is
+     * likely to yield significantly better space and time performance.
+     * Also consider using the final fields {@link #TRUE} and {@link #FALSE}
+     * if possible.
      */
+    @Deprecated(since="9")
     public Boolean(boolean value) {
         this.value = value;
     }
@@ -94,15 +97,18 @@ public final class Boolean implements java.io.Serializable,
      * Allocates a {@code Boolean} object representing the value
      * {@code true} if the string argument is not {@code null}
      * and is equal, ignoring case, to the string {@code "true"}.
-     * Otherwise, allocate a {@code Boolean} object representing the
+     * Otherwise, allocates a {@code Boolean} object representing the
-     * value {@code false}. Examples:<p>
+     * value {@code false}.
-     * {@code new Boolean("True")} produces a {@code Boolean} object
-     * that represents {@code true}.<br>
-     * {@code new Boolean("yes")} produces a {@code Boolean} object
-     * that represents {@code false}.
      *
      * @param   s   the string to be converted to a {@code Boolean}.
+     *
+     * @deprecated
+     * It is rarely appropriate to use this constructor.
+     * Use {@link #parseBoolean(String)} to convert a string to a
+     * {@code boolean} primitive, or use {@link #valueOf(String)}
+     * to convert a string to a {@code Boolean} object.
      */
+    @Deprecated(since="9")
     public Boolean(String s) {
         this(parseBoolean(s));
     }

jdk/src/java.base/share/classes/java/lang/Byte.java

@@ -297,7 +297,13 @@ public final class Byte extends Number implements Comparable<Byte> {
      *
      * @param value     the value to be represented by the
      *                  {@code Byte}.
+     *
+     * @deprecated
+     * It is rarely appropriate to use this constructor. The static factory
+     * {@link #valueOf(byte)} is generally a better choice, as it is
+     * likely to yield significantly better space and time performance.
      */
+    @Deprecated(since="9")
     public Byte(byte value) {
         this.value = value;
     }
@@ -311,10 +317,16 @@ public final class Byte extends Number implements Comparable<Byte> {
      *
      * @param s         the {@code String} to be converted to a
      *                  {@code Byte}
-     * @throws           NumberFormatException If the {@code String}
+     * @throws          NumberFormatException if the {@code String}
      *                  does not contain a parsable {@code byte}.
-     * @see        java.lang.Byte#parseByte(java.lang.String, int)
+     *
+     * @deprecated
+     * It is rarely appropriate to use this constructor.
+     * Use {@link #parseByte(String)} to convert a string to a
+     * {@code byte} primitive, or use {@link #valueOf(String)}
+     * to convert a string to a {@code Byte} object.
      */
+    @Deprecated(since="9")
     public Byte(String s) throws NumberFormatException {
         this.value = parseByte(s, 10);
     }

jdk/src/java.base/share/classes/java/lang/Character.java

@@ -1256,14 +1256,14 @@ class Character implements java.io.Serializable, Comparable<Character> {
             new UnicodeBlock("SPECIALS");
 
         /**
-         * @deprecated As of J2SE 5, use {@link #HIGH_SURROGATES},
+         * @deprecated
-         *             {@link #HIGH_PRIVATE_USE_SURROGATES}, and
+         * Instead of {@code SURROGATES_AREA}, use {@link #HIGH_SURROGATES},
-         *             {@link #LOW_SURROGATES}. These new constants match
+         * {@link #HIGH_PRIVATE_USE_SURROGATES}, and {@link #LOW_SURROGATES}.
-         *             the block definitions of the Unicode Standard.
+         * These constants match the block definitions of the Unicode Standard.
-         *             The {@link #of(char)} and {@link #of(int)} methods
+         * The {@link #of(char)} and {@link #of(int)} methods return the
-         *             return the new constants, not SURROGATES_AREA.
+         * standard constants.
          */
-        @Deprecated
+        @Deprecated(since="1.5")
         public static final UnicodeBlock SURROGATES_AREA =
             new UnicodeBlock("SURROGATES_AREA");
 
@@ -7451,7 +7451,13 @@ class Character implements java.io.Serializable, Comparable<Character> {
      *
      * @param  value   the value to be represented by the
      *                  {@code Character} object.
+     *
+     * @deprecated
+     * It is rarely appropriate to use this constructor. The static factory
+     * {@link #valueOf(char)} is generally a better choice, as it is
+     * likely to yield significantly better space and time performance.
      */
+    @Deprecated(since="9")
     public Character(char value) {
         this.value = value;
     }
@@ -8799,7 +8805,7 @@ class Character implements java.io.Serializable, Comparable<Character> {
      * @since   1.0.2
      * @deprecated Replaced by isJavaIdentifierStart(char).
      */
-    @Deprecated
+    @Deprecated(since="1.1")
     public static boolean isJavaLetter(char ch) {
         return isJavaIdentifierStart(ch);
     }
@@ -8835,7 +8841,7 @@ class Character implements java.io.Serializable, Comparable<Character> {
      * @since   1.0.2
      * @deprecated Replaced by isJavaIdentifierPart(char).
      */
-    @Deprecated
+    @Deprecated(since="1.1")
     public static boolean isJavaLetterOrDigit(char ch) {
         return isJavaIdentifierPart(ch);
     }
@@ -9580,7 +9586,7 @@ class Character implements java.io.Serializable, Comparable<Character> {
      * @see        Character#isWhitespace(char)
      * @deprecated Replaced by isWhitespace(char).
      */
-    @Deprecated
+    @Deprecated(since="1.1")
     public static boolean isSpace(char ch) {
         return (ch <= 0x0020) &&
             (((((1L << 0x0009) |

jdk/src/java.base/share/classes/java/lang/ClassLoader.java

@@ -727,7 +727,7 @@ public abstract class ClassLoader {
      * @deprecated  Replaced by {@link #defineClass(String, byte[], int, int)
      * defineClass(String, byte[], int, int)}
      */
-    @Deprecated
+    @Deprecated(since="1.1")
     protected final Class<?> defineClass(byte[] b, int off, int len)
         throws ClassFormatError
     {
@@ -2012,7 +2012,7 @@ public abstract class ClassLoader {
      *
      * @since  1.2
      */
-    @Deprecated
+    @Deprecated(since="9")
     protected Package getPackage(String name) {
         Package pkg = getDefinedPackage(name);
         if (pkg == null) {

jdk/src/java.base/share/classes/java/lang/Double.java

@@ -589,7 +589,13 @@ public final class Double extends Number implements Comparable<Double> {
      * represents the primitive {@code double} argument.
      *
      * @param   value   the value to be represented by the {@code Double}.
+     *
+     * @deprecated
+     * It is rarely appropriate to use this constructor. The static factory
+     * {@link #valueOf(double)} is generally a better choice, as it is
+     * likely to yield significantly better space and time performance.
      */
+    @Deprecated(since="9")
     public Double(double value) {
         this.value = value;
     }
@@ -601,10 +607,16 @@ public final class Double extends Number implements Comparable<Double> {
      * {@code double} value as if by the {@code valueOf} method.
      *
      * @param  s  a string to be converted to a {@code Double}.
-     * @throws    NumberFormatException  if the string does not contain a
+     * @throws    NumberFormatException if the string does not contain a
      *            parsable number.
-     * @see       java.lang.Double#valueOf(java.lang.String)
+     *
+     * @deprecated
+     * It is rarely appropriate to use this constructor.
+     * Use {@link #parseDouble(String)} to convert a string to a
+     * {@code double} primitive, or use {@link #valueOf(String)}
+     * to convert a string to a {@code Double} object.
      */
+    @Deprecated(since="9")
     public Double(String s) throws NumberFormatException {
         value = parseDouble(s);
     }

jdk/src/java.base/share/classes/java/lang/Float.java

@@ -502,7 +502,13 @@ public final class Float extends Number implements Comparable<Float> {
      * represents the primitive {@code float} argument.
      *
      * @param   value   the value to be represented by the {@code Float}.
+     *
+     * @deprecated
+     * It is rarely appropriate to use this constructor. The static factory
+     * {@link #valueOf(float)} is generally a better choice, as it is
+     * likely to yield significantly better space and time performance.
      */
+    @Deprecated(since="9")
     public Float(float value) {
         this.value = value;
     }
@@ -512,7 +518,13 @@ public final class Float extends Number implements Comparable<Float> {
      * represents the argument converted to type {@code float}.
      *
      * @param   value   the value to be represented by the {@code Float}.
+     *
+     * @deprecated
+     * It is rarely appropriate to use this constructor. Instead, use the
+     * static factory method {@link #valueOf(float)} method as follows:
+     * {@code Float.valueOf((float)value)}.
      */
+    @Deprecated(since="9")
     public Float(double value) {
         this.value = (float)value;
     }
@@ -523,11 +535,17 @@ public final class Float extends Number implements Comparable<Float> {
      * represented by the string. The string is converted to a
      * {@code float} value as if by the {@code valueOf} method.
      *
-     * @param      s   a string to be converted to a {@code Float}.
+     * @param   s   a string to be converted to a {@code Float}.
-     * @throws  NumberFormatException  if the string does not contain a
+     * @throws      NumberFormatException if the string does not contain a
-     *               parsable number.
+     *              parsable number.
-     * @see        java.lang.Float#valueOf(java.lang.String)
+     *
+     * @deprecated
+     * It is rarely appropriate to use this constructor.
+     * Use {@link #parseFloat(String)} to convert a string to a
+     * {@code float} primitive, or use {@link #valueOf(String)}
+     * to convert a string to a {@code Float} object.
      */
+    @Deprecated(since="9")
     public Float(String s) throws NumberFormatException {
         value = parseFloat(s);
     }

jdk/src/java.base/share/classes/java/lang/Integer.java

@@ -1106,7 +1106,13 @@ public final class Integer extends Number implements Comparable<Integer> {
      *
      * @param   value   the value to be represented by the
      *                  {@code Integer} object.
+     *
+     * @deprecated
+     * It is rarely appropriate to use this constructor. The static factory
+     * {@link #valueOf(int)} is generally a better choice, as it is
+     * likely to yield significantly better space and time performance.
      */
+    @Deprecated(since="9")
     public Integer(int value) {
         this.value = value;
     }
@@ -1118,12 +1124,17 @@ public final class Integer extends Number implements Comparable<Integer> {
      * {@code int} value in exactly the manner used by the
      * {@code parseInt} method for radix 10.
      *
-     * @param      s   the {@code String} to be converted to an
+     * @param   s   the {@code String} to be converted to an {@code Integer}.
-     *                 {@code Integer}.
+     * @throws      NumberFormatException if the {@code String} does not
-     * @exception  NumberFormatException  if the {@code String} does not
+     *              contain a parsable integer.
-     *               contain a parsable integer.
+     *
-     * @see        java.lang.Integer#parseInt(java.lang.String, int)
+     * @deprecated
+     * It is rarely appropriate to use this constructor.
+     * Use {@link #parseInt(String)} to convert a string to a
+     * {@code int} primitive, or use {@link #valueOf(String)}
+     * to convert a string to an {@code Integer} object.
      */
+    @Deprecated(since="9")
     public Integer(String s) throws NumberFormatException {
         this.value = parseInt(s, 10);
     }

jdk/src/java.base/share/classes/java/lang/Long.java

@@ -1340,7 +1340,13 @@ public final class Long extends Number implements Comparable<Long> {
      *
      * @param   value   the value to be represented by the
      *          {@code Long} object.
+     *
+     * @deprecated
+     * It is rarely appropriate to use this constructor. The static factory
+     * {@link #valueOf(long)} is generally a better choice, as it is
+     * likely to yield significantly better space and time performance.
      */
+    @Deprecated(since="9")
     public Long(long value) {
         this.value = value;
     }
@@ -1356,8 +1362,14 @@ public final class Long extends Number implements Comparable<Long> {
      *             {@code Long}.
      * @throws     NumberFormatException  if the {@code String} does not
      *             contain a parsable {@code long}.
-     * @see        java.lang.Long#parseLong(java.lang.String, int)
+     *
+     * @deprecated
+     * It is rarely appropriate to use this constructor.
+     * Use {@link #parseLong(String)} to convert a string to a
+     * {@code long} primitive, or use {@link #valueOf(String)}
+     * to convert a string to a {@code Long} object.
      */
+    @Deprecated(since="9")
     public Long(String s) throws NumberFormatException {
         this.value = parseLong(s, 10);
     }

jdk/src/java.base/share/classes/java/lang/Package.java

@@ -333,7 +333,7 @@ public class Package extends NamedPackage implements java.lang.reflect.Annotated
      * @see ClassLoader#getDefinedPackage
      */
     @CallerSensitive
-    @Deprecated
+    @Deprecated(since="9")
     @SuppressWarnings("deprecation")
     public static Package getPackage(String name) {
         ClassLoader l = ClassLoader.getClassLoader(Reflection.getCallerClass());

jdk/src/java.base/share/classes/java/lang/Runtime.java

@@ -289,6 +289,7 @@ public class Runtime {
      *      finalizers being called on live objects while other threads are
      *      concurrently manipulating those objects, resulting in erratic
      *      behavior or deadlock.
+     *      This method is subject to removal in a future version of Java SE.
      *
      * @throws  SecurityException
      *        if a security manager exists and its {@code checkExit}
@@ -299,7 +300,7 @@ public class Runtime {
      * @see     java.lang.SecurityManager#checkExit(int)
      * @since   1.1
      */
-    @Deprecated
+    @Deprecated(since="1.2", forRemoval=true)
     public static void runFinalizersOnExit(boolean value) {
         SecurityManager security = System.getSecurityManager();
         if (security != null) {
@@ -894,8 +895,9 @@ public class Runtime {
      * stream in the local encoding into a character stream in Unicode is via
      * the {@code InputStreamReader} and {@code BufferedReader}
      * classes.
+     * This method is subject to removal in a future version of Java SE.
      */
-    @Deprecated
+    @Deprecated(since="1.1", forRemoval=true)
     public InputStream getLocalizedInputStream(InputStream in) {
         return in;
     }
@@ -915,6 +917,7 @@ public class Runtime {
      * Unicode character stream into a byte stream in the local encoding is via
      * the {@code OutputStreamWriter}, {@code BufferedWriter}, and
      * {@code PrintWriter} classes.
+     * This method is subject to removal in a future version of Java SE.
      *
      * @param      out OutputStream to localize
      * @return     a localized output stream
@@ -923,7 +926,7 @@ public class Runtime {
      * @see        java.io.OutputStreamWriter#OutputStreamWriter(java.io.OutputStream)
      * @see        java.io.PrintWriter#PrintWriter(java.io.OutputStream)
      */
-    @Deprecated
+    @Deprecated(since="1.1", forRemoval=true)
     public OutputStream getLocalizedOutputStream(OutputStream out) {
         return out;
     }

jdk/src/java.base/share/classes/java/lang/SecurityManager.java

@@ -229,7 +229,7 @@ class SecurityManager {
      *  It is recommended that the <code>checkPermission</code>
      *  call be used instead.
      */
-    @Deprecated
+    @Deprecated(since="1.2")
     protected boolean inCheck;
 
     /*
@@ -262,7 +262,7 @@ class SecurityManager {
      *  It is recommended that the <code>checkPermission</code>
      *  call be used instead.
      */
-    @Deprecated
+    @Deprecated(since="1.2")
     public boolean getInCheck() {
         return inCheck;
     }
@@ -345,7 +345,7 @@ class SecurityManager {
      * @see  java.lang.ClassLoader#getSystemClassLoader() getSystemClassLoader
      * @see  #checkPermission(java.security.Permission) checkPermission
      */
-    @Deprecated
+    @Deprecated(since="1.2")
     protected ClassLoader currentClassLoader() {
         ClassLoader cl = currentClassLoader0();
         if ((cl != null) && hasAllPermission())
@@ -391,7 +391,7 @@ class SecurityManager {
      * @see  java.lang.ClassLoader#getSystemClassLoader() getSystemClassLoader
      * @see  #checkPermission(java.security.Permission) checkPermission
      */
-    @Deprecated
+    @Deprecated(since="1.2")
     protected Class<?> currentLoadedClass() {
         Class<?> c = currentLoadedClass0();
         if ((c != null) && hasAllPermission())
@@ -411,7 +411,7 @@ class SecurityManager {
      *  call be used instead.
      *
      */
-    @Deprecated
+    @Deprecated(since="1.2")
     protected native int classDepth(String name);
 
     /**
@@ -449,7 +449,7 @@ class SecurityManager {
      * @see   java.lang.ClassLoader#getSystemClassLoader() getSystemClassLoader
      * @see   #checkPermission(java.security.Permission) checkPermission
      */
-    @Deprecated
+    @Deprecated(since="1.2")
     protected int classLoaderDepth() {
         int depth = classLoaderDepth0();
         if (depth != -1) {
@@ -474,7 +474,7 @@ class SecurityManager {
      *  It is recommended that the <code>checkPermission</code>
      *  call be used instead.
      */
-    @Deprecated
+    @Deprecated(since="1.2")
     protected boolean inClass(String name) {
         return classDepth(name) >= 0;
     }
@@ -491,7 +491,7 @@ class SecurityManager {
      *  call be used instead.
      * @see        #currentClassLoader() currentClassLoader
      */
-    @Deprecated
+    @Deprecated(since="1.2")
     protected boolean inClassLoader() {
         return currentClassLoader() != null;
     }
@@ -1217,7 +1217,7 @@ class SecurityManager {
      * @deprecated Use #checkPermission(java.security.Permission) instead
      * @see        #checkPermission(java.security.Permission) checkPermission
      */
-    @Deprecated
+    @Deprecated(since="1.4")
     public void checkMulticast(InetAddress maddr, byte ttl) {
         String host = maddr.getHostAddress();
         if (!host.startsWith("[") && host.indexOf(':') != -1) {
@@ -1297,9 +1297,10 @@ class SecurityManager {
      *             was trusted to bring up a top-level window. The method has been
      *             obsoleted and code should instead use {@link #checkPermission}
      *             to check {@code AWTPermission("showWindowWithoutWarningBanner")}.
+     *             This method is subject to removal in a future version of Java SE.
      * @see        #checkPermission(java.security.Permission) checkPermission
      */
-    @Deprecated
+    @Deprecated(since="1.8", forRemoval=true)
     public boolean checkTopLevelWindow(Object window) {
         if (window == null) {
             throw new NullPointerException("window can't be null");
@@ -1340,9 +1341,10 @@ class SecurityManager {
      *             thread could access the system clipboard. The method has been
      *             obsoleted and code should instead use {@link #checkPermission}
      *             to check {@code AWTPermission("accessClipboard")}.
+     *             This method is subject to removal in a future version of Java SE.
      * @see        #checkPermission(java.security.Permission) checkPermission
      */
-    @Deprecated
+    @Deprecated(since="1.8", forRemoval=true)
     public void checkSystemClipboardAccess() {
         checkPermission(SecurityConstants.ALL_PERMISSION);
     }
@@ -1358,9 +1360,10 @@ class SecurityManager {
      *             thread could access the AWT event queue. The method has been
      *             obsoleted and code should instead use {@link #checkPermission}
      *             to check {@code AWTPermission("accessEventQueue")}.
+     *             This method is subject to removal in a future version of Java SE.
      * @see        #checkPermission(java.security.Permission) checkPermission
      */
-    @Deprecated
+    @Deprecated(since="1.8", forRemoval=true)
     public void checkAwtEventQueueAccess() {
         checkPermission(SecurityConstants.ALL_PERMISSION);
     }
@@ -1626,12 +1629,13 @@ class SecurityManager {
      *             Users of this method should instead invoke {@link #checkPermission}
      *             directly.  This method will be changed in a future release
      *             to check the permission {@code java.security.AllPermission}.
+     *             This method is subject to removal in a future version of Java SE.
      *
      * @see java.lang.reflect.Member
      * @since 1.1
      * @see        #checkPermission(java.security.Permission) checkPermission
      */
-    @Deprecated
+    @Deprecated(since="1.8", forRemoval=true)
     @CallerSensitive
     public void checkMemberAccess(Class<?> clazz, int which) {
         if (clazz == null) {

jdk/src/java.base/share/classes/java/lang/Short.java

@@ -302,7 +302,13 @@ public final class Short extends Number implements Comparable<Short> {
      *
      * @param value     the value to be represented by the
      *                  {@code Short}.
+     *
+     * @deprecated
+     * It is rarely appropriate to use this constructor. The static factory
+     * {@link #valueOf(short)} is generally a better choice, as it is
+     * likely to yield significantly better space and time performance.
      */
+    @Deprecated(since="9")
     public Short(short value) {
         this.value = value;
     }
@@ -318,8 +324,14 @@ public final class Short extends Number implements Comparable<Short> {
      *          {@code Short}
      * @throws  NumberFormatException If the {@code String}
      *          does not contain a parsable {@code short}.
-     * @see     java.lang.Short#parseShort(java.lang.String, int)
+     *
+     * @deprecated
+     * It is rarely appropriate to use this constructor.
+     * Use {@link #parseShort(String)} to convert a string to a
+     * {@code short} primitive, or use {@link #valueOf(String)}
+     * to convert a string to a {@code Short} object.
      */
+    @Deprecated(since="9")
     public Short(String s) throws NumberFormatException {
         this.value = parseShort(s, 10);
     }

jdk/src/java.base/share/classes/java/lang/String.java

@@ -363,7 +363,7 @@ public final class String
      * @see  #String(byte[], java.nio.charset.Charset)
      * @see  #String(byte[])
      */
-    @Deprecated
+    @Deprecated(since="1.1")
     public String(byte ascii[], int hibyte, int offset, int count) {
         checkBoundsOffCount(offset, count, ascii.length);
         if (count == 0) {
@@ -415,7 +415,7 @@ public final class String
      * @see  #String(byte[], java.nio.charset.Charset)
      * @see  #String(byte[])
      */
-    @Deprecated
+    @Deprecated(since="1.1")
     public String(byte ascii[], int hibyte) {
         this(ascii, hibyte, 0, ascii.length);
     }
@@ -911,7 +911,7 @@ public final class String
      *                 dst.length}
      *          </ul>
      */
-    @Deprecated
+    @Deprecated(since="1.1")
     public void getBytes(int srcBegin, int srcEnd, byte dst[], int dstBegin) {
         checkBoundsBeginEnd(srcBegin, srcEnd, length());
         Objects.requireNonNull(dst);

jdk/src/java.base/share/classes/java/lang/System.java

@@ -1715,6 +1715,7 @@ public final class System {
      *      finalizers being called on live objects while other threads are
      *      concurrently manipulating those objects, resulting in erratic
      *      behavior or deadlock.
+     *      This method is subject to removal in a future version of Java SE.
      * @param value indicating enabling or disabling of finalization
      * @throws  SecurityException
      *        if a security manager exists and its <code>checkExit</code>
@@ -1725,7 +1726,7 @@ public final class System {
      * @see     java.lang.SecurityManager#checkExit(int)
      * @since   1.1
      */
-    @Deprecated
+    @Deprecated(since="1.2", forRemoval=true)
     public static void runFinalizersOnExit(boolean value) {
         Runtime.runFinalizersOnExit(value);
     }

jdk/src/java.base/share/classes/java/lang/Thread.java

@@ -890,7 +890,7 @@ class Thread implements Runnable {
      *       <a href="{@docRoot}/../technotes/guides/concurrency/threadPrimitiveDeprecation.html">Why
      *       are Thread.stop, Thread.suspend and Thread.resume Deprecated?</a>.
      */
-    @Deprecated
+    @Deprecated(since="1.2")
     public final void stop() {
         SecurityManager security = System.getSecurityManager();
         if (security != null) {
@@ -922,8 +922,9 @@ class Thread implements Runnable {
      *        For more information, see
      *        <a href="{@docRoot}/../technotes/guides/concurrency/threadPrimitiveDeprecation.html">Why
      *        are Thread.stop, Thread.suspend and Thread.resume Deprecated?</a>.
+     *        This method is subject to removal in a future version of Java SE.
      */
-    @Deprecated
+    @Deprecated(since="1.2", forRemoval=true)
     public final synchronized void stop(Throwable obj) {
         throw new UnsupportedOperationException();
     }
@@ -1043,9 +1044,10 @@ class Thread implements Runnable {
      *     "frozen" processes. For more information, see
      *     <a href="{@docRoot}/../technotes/guides/concurrency/threadPrimitiveDeprecation.html">
      *     Why are Thread.stop, Thread.suspend and Thread.resume Deprecated?</a>.
+     *     This method is subject to removal in a future version of Java SE.
      * @throws NoSuchMethodError always
      */
-    @Deprecated
+    @Deprecated(since="1.5", forRemoval=true)
     public void destroy() {
         throw new NoSuchMethodError();
     }
@@ -1083,7 +1085,7 @@ class Thread implements Runnable {
      *   <a href="{@docRoot}/../technotes/guides/concurrency/threadPrimitiveDeprecation.html">Why
      *   are Thread.stop, Thread.suspend and Thread.resume Deprecated?</a>.
      */
-    @Deprecated
+    @Deprecated(since="1.2")
     public final void suspend() {
         checkAccess();
         suspend0();
@@ -1109,7 +1111,7 @@ class Thread implements Runnable {
      *     <a href="{@docRoot}/../technotes/guides/concurrency/threadPrimitiveDeprecation.html">Why
      *     are Thread.stop, Thread.suspend and Thread.resume Deprecated?</a>.
      */
-    @Deprecated
+    @Deprecated(since="1.2")
     public final void resume() {
         checkAccess();
         resume0();
@@ -1270,8 +1272,10 @@ class Thread implements Runnable {
      * @deprecated The definition of this call depends on {@link #suspend},
      *             which is deprecated.  Further, the results of this call
      *             were never well-defined.
+     *             This method is subject to removal in a future version of Java SE.
+     * @see        StackWalker
      */
-    @Deprecated
+    @Deprecated(since="1.2", forRemoval=true)
     public native int countStackFrames();
 
     /**

jdk/src/java.base/share/classes/java/lang/ThreadGroup.java

@@ -607,7 +607,7 @@ class ThreadGroup implements Thread.UncaughtExceptionHandler {
      * @deprecated    This method is inherently unsafe.  See
      *     {@link Thread#stop} for details.
      */
-    @Deprecated
+    @Deprecated(since="1.2")
     public final void stop() {
         if (stopOrSuspend(false))
             Thread.currentThread().stop();
@@ -669,7 +669,7 @@ class ThreadGroup implements Thread.UncaughtExceptionHandler {
      * @deprecated    This method is inherently deadlock-prone.  See
      *     {@link Thread#suspend} for details.
      */
-    @Deprecated
+    @Deprecated(since="1.2")
     @SuppressWarnings("deprecation")
     public final void suspend() {
         if (stopOrSuspend(true))
@@ -732,7 +732,7 @@ class ThreadGroup implements Thread.UncaughtExceptionHandler {
      *       both of which have been deprecated, as they are inherently
      *       deadlock-prone.  See {@link Thread#suspend} for details.
      */
-    @Deprecated
+    @Deprecated(since="1.2")
     @SuppressWarnings("deprecation")
     public final void resume() {
         int ngroupsSnapshot;
@@ -1073,7 +1073,7 @@ class ThreadGroup implements Thread.UncaughtExceptionHandler {
      *             which is deprecated.  Further, the behavior of this call
      *             was never specified.
      */
-    @Deprecated
+    @Deprecated(since="1.2")
     public boolean allowThreadSuspension(boolean b) {
         this.vmAllowSuspension = b;
         if (!b) {

jdk/src/java.base/share/classes/java/lang/invoke/MemberName.java

@@ -733,6 +733,7 @@ import java.util.Objects;
     }
 
     @Override
+    @SuppressWarnings("deprecation")
     public int hashCode() {
         // Avoid autoboxing getReferenceKind(), since this is used early and will force
         // early initialization of Byte$ByteCache

jdk/src/java.base/share/classes/java/lang/reflect/ProxyGenerator.java

@@ -1750,7 +1750,7 @@ class ProxyGenerator {
          * Get or assign the index for a CONSTANT_Float entry.
          */
         public short getFloat(float f) {
-            return getValue(new Float(f));
+            return getValue(f);
         }
 
         /**

jdk/src/java.base/share/classes/java/text/ChoiceFormat.java

@@ -437,7 +437,7 @@ public class ChoiceFormat extends NumberFormat {
         if (status.index == start) {
             status.errorIndex = furthest;
         }
-        return new Double(bestNumber);
+        return Double.valueOf(bestNumber);
     }
 
     /**

jdk/src/java.base/share/classes/java/text/DecimalFormat.java

@@ -1996,7 +1996,7 @@ public class DecimalFormat extends NumberFormat {
         // special case NaN
         if (text.regionMatches(pos.index, symbols.getNaN(), 0, symbols.getNaN().length())) {
             pos.index = pos.index + symbols.getNaN().length();
-            return new Double(Double.NaN);
+            return Double.valueOf(Double.NaN);
         }
 
         boolean[] status = new boolean[STATUS_LENGTH];
@@ -2007,19 +2007,19 @@ public class DecimalFormat extends NumberFormat {
         // special case INFINITY
         if (status[STATUS_INFINITE]) {
             if (status[STATUS_POSITIVE] == (multiplier >= 0)) {
-                return new Double(Double.POSITIVE_INFINITY);
+                return Double.valueOf(Double.POSITIVE_INFINITY);
             } else {
-                return new Double(Double.NEGATIVE_INFINITY);
+                return Double.valueOf(Double.NEGATIVE_INFINITY);
             }
         }
 
         if (multiplier == 0) {
             if (digitList.isZero()) {
-                return new Double(Double.NaN);
+                return Double.valueOf(Double.NaN);
             } else if (status[STATUS_POSITIVE]) {
-                return new Double(Double.POSITIVE_INFINITY);
+                return Double.valueOf(Double.POSITIVE_INFINITY);
             } else {
-                return new Double(Double.NEGATIVE_INFINITY);
+                return Double.valueOf(Double.NEGATIVE_INFINITY);
             }
         }
 
@@ -2093,8 +2093,8 @@ public class DecimalFormat extends NumberFormat {
                             !isParseIntegerOnly();
             }
 
-            return gotDouble ?
+            // cast inside of ?: because of binary numeric promotion, JLS 15.25
-                (Number)new Double(doubleResult) : (Number)Long.valueOf(longResult);
+            return gotDouble ? (Number)doubleResult : (Number)longResult;
         }
     }
 

jdk/src/java.base/share/classes/java/util/concurrent/ThreadLocalRandom.java

@@ -455,7 +455,7 @@ public class ThreadLocalRandom extends Random {
             s = v1 * v1 + v2 * v2;
         } while (s >= 1 || s == 0);
         double multiplier = StrictMath.sqrt(-2 * StrictMath.log(s)/s);
-        nextLocalGaussian.set(new Double(v2 * multiplier));
+        nextLocalGaussian.set(Double.valueOf(v2 * multiplier));
         return v1 * multiplier;
     }
 

jdk/src/java.base/share/classes/jdk/internal/org/objectweb/asm/Opcodes.java

@@ -70,6 +70,7 @@ package jdk.internal.org.objectweb.asm;
  * @author Eric Bruneton
  * @author Eugene Kuleshov
  */
+@SuppressWarnings("deprecation") // for Integer(int) constructor
 public interface Opcodes {
 
     // ASM API versions
@@ -176,6 +177,8 @@ public interface Opcodes {
      */
     int F_SAME1 = 4;
 
+    // For reference comparison purposes, construct new instances
+    // instead of using valueOf() or autoboxing.
     Integer TOP = new Integer(0);
     Integer INTEGER = new Integer(1);
     Integer FLOAT = new Integer(2);

jdk/src/java.base/unix/classes/sun/nio/ch/InheritedChannel.java

@@ -168,7 +168,7 @@ class InheritedChannel {
         Class<?> paramTypes[] = { int.class };
         Constructor<?> ctr = Reflect.lookupConstructor("java.io.FileDescriptor",
                                                        paramTypes);
-        Object args[] = { new Integer(fdVal) };
+        Object args[] = { Integer.valueOf(fdVal) };
         FileDescriptor fd = (FileDescriptor)Reflect.invoke(ctr, args);
 
 

jdk/src/java.base/windows/classes/java/net/DualStackPlainDatagramSocketImpl.java

@@ -220,7 +220,7 @@ class DualStackPlainDatagramSocketImpl extends AbstractPlainDatagramSocketImpl
             case IP_TOS :
             case SO_RCVBUF :
             case SO_SNDBUF :
-                returnValue = new Integer(value);
+                returnValue = Integer.valueOf(value);
                 break;
             default: /* shouldn't get here */
                 throw new SocketException("Option not supported");

jdk/src/java.base/windows/classes/sun/nio/ch/WindowsSelectorImpl.java

@@ -87,13 +87,13 @@ final class WindowsSelectorImpl extends SelectorImpl {
     private static final class FdMap extends HashMap<Integer, MapEntry> {
         static final long serialVersionUID = 0L;
         private MapEntry get(int desc) {
-            return get(new Integer(desc));
+            return get(Integer.valueOf(desc));
         }
         private MapEntry put(SelectionKeyImpl ski) {
-            return put(new Integer(ski.channel.getFDVal()), new MapEntry(ski));
+            return put(Integer.valueOf(ski.channel.getFDVal()), new MapEntry(ski));
         }
         private MapEntry remove(SelectionKeyImpl ski) {
-            Integer fd = new Integer(ski.channel.getFDVal());
+            Integer fd = Integer.valueOf(ski.channel.getFDVal());
             MapEntry x = get(fd);
             if ((x != null) && (x.ski.channel == ski.channel))
                 return remove(fd);

jdk/src/java.security.jgss/windows/classes/sun/security/krb5/internal/tools/Klist.java

@@ -134,7 +134,7 @@ public class Klist {
         Character arg;
         for (int i = 0; i < args.length; i++) {
             if ((args[i].length() >= 2) && (args[i].startsWith("-"))) {
-                arg = new Character(args[i].charAt(1));
+                arg = Character.valueOf(args[i].charAt(1));
                 switch (arg.charValue()) {
                 case 'c':
                     action = 'c';

jdk/src/java.sql.rowset/share/classes/com/sun/rowset/CachedRowSetImpl.java

@@ -1963,7 +1963,7 @@ public class CachedRowSetImpl extends BaseRowSet implements RowSet, RowSetIntern
             return (float)0;
         }
         try {
-            return ((new Float(value.toString())).floatValue());
+            return Float.parseFloat(value.toString());
         } catch (NumberFormatException ex) {
             throw new SQLException(MessageFormat.format(resBundle.handleGetObject("cachedrowsetimpl.floatfail").toString(),
                   new Object[] {value.toString().trim(), columnIndex}));
@@ -2007,7 +2007,7 @@ public class CachedRowSetImpl extends BaseRowSet implements RowSet, RowSetIntern
             return (double)0;
         }
         try {
-            return ((new Double(value.toString().trim())).doubleValue());
+            return Double.parseDouble(value.toString().trim());
         } catch (NumberFormatException ex) {
             throw new SQLException(MessageFormat.format(resBundle.handleGetObject("cachedrowsetimpl.doublefail").toString(),
                   new Object[] {value.toString().trim(), columnIndex}));
@@ -4017,9 +4017,9 @@ public class CachedRowSetImpl extends BaseRowSet implements RowSet, RowSetIntern
                     return new BigDecimal(srcObj.toString().trim());
                 case java.sql.Types.REAL:
                 case java.sql.Types.FLOAT:
-                    return new Float(srcObj.toString().trim());
+                    return Float.valueOf(srcObj.toString().trim());
                 case java.sql.Types.DOUBLE:
-                    return new Double(srcObj.toString().trim());
+                    return Double.valueOf(srcObj.toString().trim());
                 case java.sql.Types.CHAR:
                 case java.sql.Types.VARCHAR:
                 case java.sql.Types.LONGVARCHAR:

jdk/src/jdk.jcmd/share/classes/sun/tools/jstat/ExpressionExecuter.java

@@ -83,14 +83,14 @@ public class ExpressionExecuter implements ExpressionEvaluator {
         if (op == null) {
             return evaluate(l);
         } else {
-            Double lval = new Double(((Number)evaluate(l)).doubleValue());
+            double lval = ((Number)evaluate(l)).doubleValue();
-            Double rval = new Double(((Number)evaluate(r)).doubleValue());
+            double rval = ((Number)evaluate(r)).doubleValue();
-            double result = op.eval(lval.doubleValue(), rval.doubleValue());
+            double result = op.eval(lval, rval);
             if (debug) {
                 System.out.println("Performed Operation: " + lval + op + rval
                                    + " = " + result);
             }
-            return new Double(result);
+            return Double.valueOf(result);
         }
     }
 }

jdk/src/jdk.jcmd/share/classes/sun/tools/jstat/ExpressionResolver.java

@@ -71,7 +71,7 @@ public class ExpressionResolver implements ExpressionEvaluator {
             if (m == null) {
                 System.err.println("Warning: Unresolved Symbol: "
                                    + id.getName() + " substituted NaN");
-                return new Literal(new Double(Double.NaN));
+                return new Literal(Double.valueOf(Double.NaN));
             }
             if (m.getVariability() == Variability.CONSTANT) {
                 if (debug) {
@@ -105,7 +105,7 @@ public class ExpressionResolver implements ExpressionEvaluator {
                 Literal rl = (Literal)r;
                 boolean warn = false;
 
-                Double nan = new Double(Double.NaN);
+                Double nan = Double.valueOf(Double.NaN);
                 if (ll.getValue() instanceof String) {
                     warn = true; ll.setValue(nan);
                 }
@@ -129,7 +129,7 @@ public class ExpressionResolver implements ExpressionEvaluator {
                                        + " (right = " + rn.doubleValue() + ")"
                                        + " to literal value " + result);
                 }
-                return new Literal(new Double(result));
+                return new Literal(Double.valueOf(result));
             }
         }
 

jdk/src/jdk.jcmd/share/classes/sun/tools/jstat/Parser.java

@@ -324,7 +324,7 @@ public class Parser {
         case StreamTokenizer.TT_NUMBER:
             double literal = lookahead.nval;
             matchNumber();
-            e = new Literal(new Double(literal));
+            e = new Literal(Double.valueOf(literal));
             log(pdebug, "Parsed: number -> " + literal);
             break;
         default:
@@ -360,7 +360,7 @@ public class Parser {
             e1.setOperator(op);
             e1.setRight(e);
             log(pdebug, "Parsed: unary -> " + e1);
-            e1.setLeft(new Literal(new Double(0)));
+            e1.setLeft(new Literal(Double.valueOf(0)));
             e = e1;
         }
     }

jdk/src/jdk.jdi/share/classes/com/sun/tools/example/debug/tty/Commands.java

@@ -478,7 +478,7 @@ class Commands {
             ThreadGroupReference tg = it.nextThreadGroup();
             ++cnt;
             MessageOutput.println("thread group number description name",
-                                  new Object [] { new Integer (cnt),
+                                  new Object [] { Integer.valueOf(cnt),
                                                   Env.description(tg),
                                                   tg.name()});
         }
@@ -1014,7 +1014,7 @@ class Commands {
         return MessageOutput.format("locationString",
                                     new Object [] {loc.declaringType().name(),
                                                    loc.method().name(),
-                                                   new Integer (loc.lineNumber()),
+                                                   Integer.valueOf(loc.lineNumber()),
                                                    Long.valueOf(loc.codeIndex())});
     }
 
@@ -1467,7 +1467,7 @@ class Commands {
                 MessageOutput.println("Line number information not available for");
             } else if (Env.sourceLine(loc, lineno) == null) {
                 MessageOutput.println("is an invalid line number for",
-                                      new Object [] {new Integer (lineno),
+                                      new Object [] {Integer.valueOf(lineno),
                                                      refType.name()});
             } else {
                 for (int i = startLine; i <= endLine; i++) {
@@ -1477,11 +1477,11 @@ class Commands {
                     }
                     if (i == lineno) {
                         MessageOutput.println("source line number current line and line",
-                                              new Object [] {new Integer (i),
+                                              new Object [] {Integer.valueOf(i),
                                                              sourceLine});
                     } else {
                         MessageOutput.println("source line number and line",
-                                              new Object [] {new Integer (i),
+                                              new Object [] {Integer.valueOf(i),
                                                              sourceLine});
                     }
                 }
@@ -1725,7 +1725,7 @@ class Commands {
                 } else {
                     MessageOutput.println("Owned by:",
                                           new Object [] {owner.name(),
-                                                         new Integer (object.entryCount())});
+                                                         Integer.valueOf(object.entryCount())});
                 }
                 List<ThreadReference> waiters = object.waitingThreads();
                 if (waiters.size() == 0) {

jdk/src/jdk.jdi/share/classes/com/sun/tools/example/debug/tty/MessageOutput.java

@@ -198,7 +198,7 @@ public class MessageOutput {
                 (MessageOutput.format("jdb prompt thread name and current stack frame",
                                       new Object [] {
                                           threadInfo.getThread().name(),
-                                          new Integer (threadInfo.getCurrentFrameIndex() + 1)}));
+                                          Integer.valueOf(threadInfo.getCurrentFrameIndex() + 1)}));
         }
         System.out.flush();
     }