RFR: 8256867: Classes with empty PermittedSubclasses attribute cannot be extended [v2]

[Harold Seigel]

On Tue, 8 Dec 2020 09:30:59 GMT, Chris Hegarty <chegar at openjdk.org> wrote:

>> src/java.base/share/classes/java/lang/Class.java line 4396:
>> 
>>> 4394:      * is unspecified. If this {@code Class} object represents a primitive type,
>>> 4395:      * {@code void}, an array type, or a class or interface that is not sealed,
>>> 4396:      * then null is returned.
>> 
>> nit: s/null/`{@code null}`
>> 
>> I'd suggest to clarify if this sealed class or interface has no permitted subclass, something like this:
>> Returns an array containing {@code Class} objects representing the
>> direct subinterfaces or subclasses permitted to extend or
>> implement this class or interface if it is sealed.  The order of such elements
>> is unspecified.   The array is empty if this sealed class or interface has no
>> permitted subclass. 
>> 
>> `@return` needs to be revised as well:
>> @return an array of {@code Class} objects of the permitted subclasses of this sealed class or interface,
>>      or {@null} if this class or interface is not sealed
>
> Mandy's suggested wording is good.
> 
> I would like to add one more additional point of clarification. It would
> be good to strongly connect `isSealed` and `getPermittedClasses` in a
> first-class way in normative spec ( similar to isRecord and
> getRecordComponents ).
> 
> For example, 
> 
>   to `isSealed` add: "getPermittedSubclasses returns a non-null but possibly
>        empty value for a sealed class."
> 
>   to `getPermittedSubclasses`: "If this class is not a sealed class, that is {@link
>      * #isSealed()} returns {@code false}, then this method returns {@code null}.
>      * Conversely, if {@link #isSealed()} returns {@code true}, then this method
>      * returns a non-null value."

Please review the updated commit.  It incorporates the changes to the comments in Class.java suggested by Mandy and Chris.
Thanks, Harold

-------------

PR: https://git.openjdk.java.net/jdk/pull/1675