Nestmates: JEP 181 CSR request is ready for review

[mandy chung]

On 3/7/18 11:28 PM, David Holmes wrote:
>
> That's an interesting point. Should they also be @CallerSensitive?
>

Yes.

I hope SM::checkPackageAccess check will be removed some day as we now 
have strong encapsulation. The security team has considered this and 
requires further investigation.

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

The SecurityException will only be thrown when security manager is 
installed and permission denies.   Users are responsible to configure 
the security policy to grant proper permission.

> 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.

The definition of a nest is a specification that has no issue to include 
in the javadoc.
>
>> 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.
>

This can be retained in @apiNote.

> 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 ..."
>

This is fine too.   I still think a @linkplain to Class#nestmates would 
be useful.

Mandy

> 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
>>