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

[David Holmes]

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


      java.lang.Class::getNestHost()

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

    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 anylinkage 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
      o 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."
      o 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, ..."
      o 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"



-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/valhalla-spec-experts/attachments/20180523/4cf0032a/attachment.html>