API Updates: 8191116: [Nestmates] Update core reflection, MethodHandle and varhandle APIs to allow for nestmate access

[Karen Kinnear]

David,

Re-reading these I had one suggestion:

> - java/lang/invoke/MethodHandles.java
> 
>       * <p>
> -     * In some cases, access between nested classes is obtained by the Java compiler by creating
> -     * an wrapper method to access a private method of another class
> -     * in the same top-level declaration.
> +     * Since JDK 11 the relationship between nested types can be expressed directly through the
> +     * {@code NestHost} and {@code NestMembers} attributes.
> +     * (See the Java Virtual Machine Specification, sections 4.7.28 and 4.7.29.)
> +     * In that case, the lookup class has direct access to private members of all its nestmates, and
> +     * that is true of the associated {@code Lookup} object as well.
> +     * Otherwise, access between nested classes is obtained by the Java compiler creating
> +     * a wrapper method to access a private method of another class in the same nest.
>       * For example, a nested class {@code C.D}
> Updated the nested classes description to cover legacy approach and new nestmate approach.
> 
> -     * {@code C.E} would be unable to those private members.
> +     * {@code C.E} would be unable to access those private members.
> Fixed typo: "access" was missing.
> 
>       * <em>Discussion of private access:</em>
>       * We say that a lookup has <em>private access</em>
>       * if its {@linkplain #lookupModes lookup modes}
> -     * include the possibility of accessing {@code private} members.
> +     * include the possibility of accessing {@code private} members
> +     * (which includes the private members of nestmates).
>       * As documented in the relevant methods elsewhere,
>       * only lookups with private access possess the following capabilities:
>       * <ul style="font-size:smaller;">
> -     * <li>access private fields, methods, and constructors of the lookup class
> +     * <li>access private fields, methods, and constructors of the lookup class and its nestmates
> Clarify that private access includes nestmate access.
> 
> -     *  access all members of the caller's class, all public types in the caller's module,
> +     *  access all members of the caller's class and nestmates, all public types in the caller's module,
For the above, I would change this to
* access all members of the caller’s class, all private members of nestmates, all types in the caller’s package, all public …

Specifically, we are extended the PRIVATE mode as above to include access to all private members of nestmates
and this description is trying to summarize access when all possible bits are set.
None of the settings give you access to default (package-private) members that a nestmate inherits from a
different package - since the Lookup model is based on the JVMS/bytecode behavior.

I added the types in the caller’s package since PACKAGE gives you that but it was missing from the existing list.

thanks,
Karen
> 
> Thanks,
> 
> David