JDK 9 RFR of JDK-8168681: Correct deprecation text for Class.newInstance

[joe darcy]

Hello,

As found by Phil Race, the original substitution text for 
Class.newInstance (JDK-8159330) is not equivalent in all cases. This 
should be addressed. The current suggested replacement text is

"The call

 clazz.newInstance()

can be replaced by

 clazz.getConstructor().newInstance()"

The getConstructor call only returns *public* constructors while 
newInstance can call non-public constructors too, subject to the 
appropriate security checks.


Therefore, using "getDeclaredConstructor()" is a better replacement 
since it should be able to find and call non-public constructors when 
that is permissible. The patch for this is:

--- a/src/java.base/share/classes/java/lang/Class.java    Wed Nov 02 
16:24:43 2016 -0700
+++ b/src/java.base/share/classes/java/lang/Class.java    Wed Nov 02 
17:36:25 2016 -0700
@@ -485,7 +485,7 @@
      * can be replaced by
      *
      * <pre>{@code
-     * clazz.getConstructor().newInstance()
+     * clazz.getDeclaredConstructor().newInstance()
      * }</pre>
      *
      * The latter sequence of calls is inferred to be able to throw

I wrote a simple program to try calling constructors with different 
access levels private, protected, package (default), and public in 
different settings and in the cases I tested clazz.newInstance() and   
clazz.getConstructor().newInstance() agreed on both returning an object 
or both throwing an exception. This property also held when a security 
manager was enabled.

Doing a quick examination of the sources of java.lang.Class,

    public T newInstance()
        throws InstantiationException, IllegalAccessException
    {
        if (System.getSecurityManager() != null) {
            checkMemberAccess(Member.PUBLIC, 
Reflection.getCallerClass(), false);
        }

            // various things elided...
            try {
                Class<?>[] empty = {};
                final Constructor<T> c = getConstructor0(empty, 
Member.DECLARED);
                // various more things elided...
            } catch (NoSuchMethodException e) {
                throw (InstantiationException)
                    new InstantiationException(getName()).initCause(e);
            }
        }
            // still more things elided
    }

compared to

    public Constructor<T> getDeclaredConstructor(Class<?>... 
parameterTypes)
        throws NoSuchMethodException, SecurityException {
        checkMemberAccess(Member.DECLARED, Reflection.getCallerClass(), 
true);
        return getConstructor0(parameterTypes, Member.DECLARED);
    }

Both alternatives are wrappers around the lower-level getConstructor0 
method.

Thanks to Phil for noticing the problem with the existing text.

Cheers,

-Joe