Nestmates: JEP 181 CSR request is ready for review

[David Holmes]

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