Nestmates: JEP 181 CSR request is ready for review

[David Holmes]

After a number of minor editing tweaks to Class and MethodHandles, and 
the more significant addition of the Security manager checks to Class, 
the specs have again been updated.

http://cr.openjdk.java.net/~dholmes/8010319/specs/

I will propose the CSR request now so that we can start to get feedback 
from that process.

Thanks for all the feedback so far.

David

On 9/03/2018 6:45 AM, David Holmes wrote:
> Thanks Mandy. We'll take the javadoc editing discussion off-list and 
> I'll come back to the EG when any changes are made.
> 
> David
> 
> On 9/03/2018 5:33 AM, mandy chung wrote:
>>
>>
>> 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
>>>>
>>