From b4934af2e23afa807a6db1ddabe272c57359281f Mon Sep 17 00:00:00 2001
From: Joe Darcy <darcy@openjdk.org>
Date: Tue, 14 Jun 2016 09:03:12 -0700
Subject: [PATCH] 8159330: Improve deprecation text for Class.newInstance

Reviewed-by: rriggs, weijun
---
 .../share/classes/java/lang/Class.java         | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/jdk/src/java.base/share/classes/java/lang/Class.java b/jdk/src/java.base/share/classes/java/lang/Class.java
index 2327b7699d7..4649b04b135 100644
--- a/jdk/src/java.base/share/classes/java/lang/Class.java
+++ b/jdk/src/java.base/share/classes/java/lang/Class.java
@@ -480,6 +480,24 @@ public final class Class<T> implements java.io.Serializable,
      * 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().newInstance()
+     * }</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