API Update: 8193408: [Nestmates] Update Class.getNestMembers to allow for duplicates

[David Holmes]

webrev: 
http://cr.openjdk.java.net/~dholmes/8193408/webrev/src/java.base/share/classes/java/lang/Class.java.cdiff.html 
(and inlined below)

Further to earlier discussions:

http://mail.openjdk.java.net/pipermail/valhalla-spec-experts/2017-December/000464.html

This is the proposed minor update to the specification for 
Class.getNestMembers()

There are three changes:

1. Don't link to getNestHost when discussing nest membership validation 
and exceptions, because getNestHost() doesn't throw exceptions.

2. Note that duplicate nest member entries are permitted (including the 
nest host) and need not be removed.

3. Document that this implementation does not remove duplicates.

Thanks,
David

--- old/src/java.base/share/classes/java/lang/Class.java	2018-01-25 
00:26:45.139747770 -0500
+++ new/src/java.base/share/classes/java/lang/Class.java	2018-01-25 
00:26:43.115631664 -0500
@@ -3904,8 +3904,15 @@
       * of its nest. The nest host will always be the zeroeth element.
       *
       * <p>Each listed nest member must be validated by checking its own
-     * declared {@linkplain #getNestHost() nest host}. Any exceptions 
that occur
-     * as part of this process will be thrown.
+     * declared nest host. Any exceptions that occur as part of this 
process
+     * will be thrown.
+     *
+     * <p>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.
+     *
+     * @implNote This implementation does not remove duplicate nest 
members if they
+     * are present.
       *
       * @return an array of all classes and interfaces in the same nest as
       * this class