Nestmates: JEP 181 CSR request is ready for review

[David Holmes]

Hi Mandy,

On 8/03/2018 6:12 AM, mandy chung wrote:
> Hi David,
> 
> I'm reviewing the core reflection and j.l.invoke spec change.

Thanks for looking at this.

> I think Class::getNestHost and Class::getNestMembers should do a security
> permission check as performed in other method e.g. getEnclosingClass.
> 
>       * @throws SecurityException
>       *         If a security manager, <i>s</i>, is present and
>       *         the caller's class loader is not the same as or an
>       *         ancestor of the class loader for the current class and
>       *         invocation of {@link SecurityManager#checkPackageAccess
>       *         s.checkPackageAccess()} denies access to the package
>       *         of this class
>       *

That's an interesting point. Should they also be @CallerSensitive?

It may be we have to perform the SM check, but throwing 
SecurityException is somewhat contrary to the "no exceptions" approach 
of getNestHost().

I filed an issue to track this:

https://bugs.openjdk.java.net/browse/JDK-8199309

> I suggest to make @apiNote in Class::getNestHost as just part of javadoc.
> It can define a section like "Nest Membership" that can be referenced

My understanding is that @apiNote et al were introduced to more clearly 
distinguish between the actual specification part of the Javadoc and 
other non-normative text. As this is non-normative then @apiNote seems 
most appropriate. I presume we can still add a tag to allow 
cross-referencing from inside Class itself.

> by Lookup class spec.  

Cross-referencing internal text fragments across distinct javadoc is 
something I thought was not done. ??

> I also have some suggested edits that you can
> consider:
> 
> http://cr.openjdk.java.net/~mchung/valhalla/webrevs/nestmates-spec/

Some of these are okay but this part:

   * The source language compiler is responsible for deciding which classes
   * and interfaces are nestmates. For example, the {@code javac} compiler

is quite significant and should not be lost. A source compiler is free 
to chose not to use the new attributes (and of course not benefit from 
the new access control rules but continue to rely on access-bridges.) So 
the user of the API has to be aware of this.

And in MethodHandles I know there is a dislike of versioning text "Since 
JDK 11 ..." (though I see this as no different to using @since!), but 
again this new behaviour may or may not be present depending on the 
version of the classfiles and the compiler used to create them, so it is 
critical to me that this is very clearly stated. I suppose this could be 
re-stated in the form:

"If the relationship between nested types is expressed directly through 
the {@code NestHost} and {@code NestMembers} attributes (see the Java 
Virtual Machine Specification, sections 4.7.28 and 4.7.29), then the 
associated {@code Lookup} object provides direct access to the lookup 
class and all of its nestmates. Otherwise, access between nested classes 
is obtained by the Java compiler creating a wrapper method to ..."

Thanks,
David

> Mandy
> 
> On 3/6/18 10:12 PM, David Holmes wrote:
>> The Nestmates CSR request:
>>
>> https://bugs.openjdk.java.net/browse/JDK-8197445
>>
>> has been prepared by Dan Smith and myself. Before Proposing this CSR 
>> request it needs to have Reviewers add themselves to it.
>>
>> (The first reviewer will need to edit the issue to enter their OpenJDK 
>> user name in the "Reviewed by" field. Subsequent reviewers can simply 
>> click on the "Reviewed by" field in the "People" section and add their 
>> user name.
>>
>> The CSR contains links to all the updated specification documents, all 
>> of which have been previously sent out for review/comment to the EG 
>> (and observers).
>>
>> Thanks,
>> David
>