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

[Paul Sandoz]

> On Feb 12, 2018, at 8:04 PM, David Holmes <david.holmes at oracle.com> wrote:
> 
> On 13/02/2018 12:51 PM, David Holmes wrote:
>> On 13/02/2018 12:39 PM, Paul Sandoz wrote:
>>>> On Feb 12, 2018, at 6:24 PM, David Holmes <david.holmes at oracle.com> wrote:
>>>> 
>>>> On 13/02/2018 11:45 AM, Paul Sandoz wrote:
>>>>>> On Feb 12, 2018, at 1:55 PM, David Holmes <david.holmes at oracle.com> wrote:
>>>>>>> getNestMembers
>>>>>>> —
>>>>>>> "The list of nest members in the classfile is permitted to contain duplicates, or to explicitly include the nest host. It is not required that an implementation of this method removes these duplicates."
>>>>>>> The "or to explicitly include the nest host” suggests it might not include the nest host, but a prior statement says it will be present in the zeroth element.
>>>>>> 
>>>>>> The "or" pertains to the list of nest members in the classfile - ie the contents of the NestMembers attribute. The returned array of nestmembers will always contain the nesthost as the zeroeth element, but may also contain it somewhere else if the classfile explicitly listed it in nestmembers.
>>>>>> 
>>>>> I see, it’s easy to misread, well i did :-) Perhaps call out the attribute and provide a link to the JVMS?
>>>> 
>>>> I can add a link to JVMS if that is what we normally do. As for misreading ... the subject of the sentence is "The list of nest members in the classfile". ;-)
>>>> 
>>> 
>>> I know :-) most developers will not be thinking at the classfile level so some link for those that are interested or care is helpful i think.
>> Okay will see what I can reasonably add.
> 
> Added JVMS ref:
> 
>     * <p>The list of nest members in the classfile (JVMS 4.1) is permitted to
>     * contain duplicates, or to explicitly include the nest host.
> 

Ok, you can also add @jvms, see examples in StackWalker (alas JavaDoc does not support generating links to the specification).

Paul.