[Nestmates] Draft core reflection API

[David Holmes]

Hi Michael,

On 8/11/2017 12:03 AM, Michael Rasmussen wrote:
> Just a stray observation (from an observer).
> 
> Isn't using two different terms in the API bound to cause confusion for 
> users?
> getNestMembers vs isNestmateOf

Maybe it's just familiarity but I don't have an issue with saying that 
two members of the same nest are nest mates (like having a ships crew 
where two members are ship-mates; or being a member of a team and 
referring to team-mates :) ). Whether I then refer to "members" or 
"mates" depends on the context - the set as a whole relates to 
"members", while relationships between members is "mates".

Happy to hear further opinions though.

Thanks,
David

> Wouldn't it be more intuitive if they used the same term, getNestmates & 
> isNestmateOf, or partly removed the term, something like getNestMembers 
> & isNestedWith
> 
> Kind regards
> Michael Rasmussen
> 
> 
> On 7 November 2017 at 14:25, Brian Goetz <brian.goetz at oracle.com 
> <mailto:brian.goetz at oracle.com>> wrote:
> 
>     That's a good description of what a nest mate is.  What could be
>     added is a reference the the jvms section that defines it, and a
>     comment that says it is up to the source language compiler to decide
>     what classes are nest mates , and that java puts inner classes in
>     the nest of their enclosing class (w jlink ref).  This could be
>     moved to a section in the package javadoc and referenced from the
>     Class doc.
> 
>     Sent from my MacBook Wheel
> 
>      > On Nov 7, 2017, at 11:31 AM, David Holmes
>     <david.holmes at oracle.com <mailto:david.holmes at oracle.com>> wrote:
>      >
>      > Hi Brian,
>      >
>      > Thanks for the prompt review!
>      >
>      >> On 7/11/2017 6:41 PM, Brian Goetz wrote:
>      >> The specs are fine. But a reader who doesn't know what a nest is
>     will never figure it out from the docs.  Would be good if nest host
>     had an API note that explained how classes become nestmantes.
>      >
>      > True - though I would prefer it if there were some definitive
>     source we could refer to that explains this rather than putting an
>     ad-hoc definition into the API docs. Perhaps we need something in
>     the JLS (as API docs tend not to reference the JVMS). ??
>      >
>      > Otherwise ...
>      >
>      > "A nest is a set of classes (nest mates) that form an access
>     control context in which each class has access to the private
>     members of the other classes in the nest. The set of classes
>     consisting of a top-level class plus all of its nested classes, is
>     an example of a nest. The nest host is the class designated to hold
>     the list of classes that make up the nest, and to which each of the
>     other nest mates refer - a top-level class is always a nest host."
>      >
>      > But it gets messy if you then have to explain that unless
>     compiled for nest mates, every class is considered its own nest and
>     nest host.
>      >
>      > Thanks,
>      > David
>      >
>      >
>      >
>      >> Sent from my MacBook Wheel
>      >>> On Nov 7, 2017, at 7:26 AM, David Holmes
>     <david.holmes at oracle.com <mailto:david.holmes at oracle.com>> wrote:
>      >>>
>      >>> For comment:
>      >>>
>      >>>
>     http://cr.openjdk.java.net/~dholmes/8188075/webrev/raw_files/new/java/lang/Class.html#getNestHost()
>     <http://cr.openjdk.java.net/~dholmes/8188075/webrev/raw_files/new/java/lang/Class.html#getNestHost()>
>      >>>
>      >>> Three functions added:
>      >>> - getNestHost
>      >>> - isNestmateOf
>      >>> - getNestMembers
>      >>>
>      >>> The first two never throw exceptions related to nest hosts or
>     nest membership. The third does.
>      >>>
>      >>> Thanks,
>      >>> David
> 
>