RFR(m): 8145468 deprecations for java.lang

[Stuart Marks]

Hi all,

Please review this first round of deprecation changes for the java.lang package. 
This changeset includes the following:

  - a set of APIs being newly deprecated
  - a set of already-deprecated APIs that are "upgraded" to forRemoval=true
  - addition of the "since" element to all deprecations
  - cleanup of some of the warnings caused by new deprecations

Webrevs:

   http://cr.openjdk.java.net/~smarks/reviews/8145468/webrev.0.jdk/

   http://cr.openjdk.java.net/~smarks/reviews/8145468/webrev.0.langtools/

   http://cr.openjdk.java.net/~smarks/reviews/8145468/webrev.0.top/

The newly deprecated APIs include all of the constructors for the boxed 
primitives. We don't intend to remove these yet, so they don't declare a value 
for the forRemoval element, implying the default value of false. The 
constructors being deprecated are as follows:

   Boolean(boolean)
   Boolean(String)
   Byte(byte)
   Byte(String)
   Character(char)
   Double(double)
   Double(String)
   Float(float)
   Float(double)
   Float(String)
   Integer(int)
   Integer(String)
   Long(long)
   Long(String)
   Short(short)
   Short(String)

The methods being deprecated with forRemoval=true are listed below. All of these 
methods have already been deprecated. They are all ill-defined, or they don't 
work, or they don't do anything useful.

   Runtime.getLocalizedInputStream(InputStream)
   Runtime.getLocalizedOutputStream(OutputStream)
   Runtime.runFinalizersOnExit(boolean)
   SecurityManager.checkAwtEventQueueAccess()
   SecurityManager.checkMemberAccess(Class<?>, int)
   SecurityManager.checkSystemClipboardAccess()
   SecurityManager.checkTopLevelWindow(Object)
   System.runFinalizersOnExit(boolean)
   Thread.countStackFrames()
   Thread.destroy()
   Thread.stop(Throwable)

Most of the files in the changeset are cleanups. Some of them are simply the 
addition of the "since" element to the @Deprecated annotation, to indicate the 
version in which the API became deprecated.

The rest of the changes are cleanup of warnings that were created by the 
deprecation of the boxed primitive constructors. There are a total of a couple 
hundred such uses sprinkled around the JDK. I've taken care of a portion of 
them, with the exception of the java.desktop module, which alone has over 100 
uses of boxed primitive constructors. I've disabled deprecation warnings for the 
java.desktop module for the time being; these uses can be cleaned up later. I've 
filed JDK-8154213 to cover this cleanup task.

For the warnings cleanups I did, I mostly did conversions of the form:

    new Double(dval)

to

    Double.valueOf(dval)

This is a very safe transformation. It changes the behavior only in the cases 
where the code relies on getting a new instance of the box object instead of one 
that might come out of a cache. I didn't see any such code (and I should hope 
there's no such code in the JDK!).

I applied autoboxing only sparingly, in the cases where it was an obviously safe 
thing to do, or where nearby code already uses autoboxing. Autoboxing actually 
generates a call to the appropriate valueOf() method, so the bytecode would be 
the same in most cases. The only difference is clutter in the source code. On 
the other hand, there's some risk in converting to autoboxing, as the implicitly 
autoboxed type might end up different from an explicit call to valueOf(). This 
isn't always obvious, so that's why I mostly avoided autoboxing.

Thanks,

s'marks