[Nestmates] Minor updates and clarifications to the Reflection API specification

[Karen Kinnear]

David,

The Valhalla EG met today May 23, 2018 and walked through the details of this proposal and how
they relate to the JVMS.

The EG was ok with these changes. Thank you for sending them for review.

thanks,
Karen

> On May 22, 2018, at 8:08 PM, David Holmes <david.holmes at oracle.com> wrote:
> 
> Code review found some minor issues that needed attention. Please advise if there are any concerns with these changes.
> 
> Thanks,
> 
> David
> 
> Full specs: http://cr.openjdk.java.net/~dholmes/8010319-JEP181/specs <http://cr.openjdk.java.net/~dholmes/8010319-JEP181/specs>
> java.lang.Class::getNestHost()
> 
> http://cr.openjdk.java.net/~dholmes/8010319-JEP181/specs/java.lang/java/lang/Class.html <http://cr.openjdk.java.net/~dholmes/8010319-JEP181/specs/java.lang/java/lang/Class.html>
> Error handling
> The original text stated:
> 
> "If there is any error  <http://cr.openjdk.java.net/%7Edholmes/8010319-JEP181/specs/java.lang/java/lang/LinkageError.html>accessing the nest host, or the nest host is in any way invalid, then this is returned."
> 
> but the implementation only catches LinkageErrors. In the original discussion:
> 
> http://mail.openjdk.java.net/pipermail/valhalla-spec-experts/2017-October/000386.html <http://mail.openjdk.java.net/pipermail/valhalla-spec-experts/2017-October/000386.html>
> 
> this wasn't discussed explicitly. It was mentioned by me in passing:
> 
> "Though a case can still be made to allow VME's to pass through."
> 
> and that is what has been happening with other API's (eg. MethodHandles). It is generally bad form to catch things like OutOfMemoryError and StackOverflow, so these should just propagate. So the text is updated to read:
> "If there is any linkage error  <http://cr.openjdk.java.net/%7Edholmes/8010319-JEP181/specs/java.lang/java/lang/LinkageError.html>accessing the nest host, or the nest host is in any way invalid, then this is returned."
> 
> where "linkage error" links to LinkageError.
> 
> Additional clarifying/explanatory text
> To the paragraph starting "A nest is a set of classes and interfaces ..", we add the final sentence: "
> All nestmates are implicitly defined in the same runtime package."
> In the sentence starting "A class or interface that is not explicitly a member of a nest, is a member of the nest consisting only of itself, ..." we insert a clarification concerning primitive and array classes: "A class or interface that is not explicitly a member of a nest (such as a primitive or array class), is a member of the nest consisting only of itself, ..."
> The @return text is reworded from: "the nest host of this class, or this if we cannot obtain a valid nest host" to "the nest host of this class, or this if a valid nest host cannot be obtained"
> 
>