JDK 9 RFR of JDK-8159330: Improve deprecation text for Class.newInstance

[joe darcy]

Hello,

After deprecating Class.newInstance recently (JDK-6850612), the 
deprecation text for it could be a bit more helpful by listing the exact 
replacement code.

Please review the patch below which does this.

Thanks,

-Joe

--- a/src/java.base/share/classes/java/lang/Class.java    Sun Jun 12 
12:14:52 2016 -0700
+++ b/src/java.base/share/classes/java/lang/Class.java    Sun Jun 12 
19:11:34 2016 -0700
@@ -480,6 +480,24 @@
       * any exception thrown by the constructor in a (checked) {@link
       * java.lang.reflect.InvocationTargetException}.
       *
+     * <p>The call
+     *
+     * <pre>{@code
+     * clazz.newInstance();
+     * }</pre>
+     *
+     * can be replaced by
+     *
+     * <pre>{@code
+     * clazz.getConstructor(new Class<?>[0]).newInstance((Object[])null);
+     * }</pre>
+     *
+     * The latter sequence of calls is inferred to be able to throw
+     * the additional exception types {@link
+     * InvocationTargetException} and {@link
+     * NoSuchMethodException}. Both of these exception types are
+     * subclasses of {@link ReflectiveOperationException}.
+     *
       * @return  a newly allocated instance of the class represented by 
this
       *          object.
       * @throws  IllegalAccessException  if the class or its nullary