RFR: 8323707: Adjust Classfile API's type arg model to better represent the embodied type [v3]

[Chen Liang]

On Mon, 19 Feb 2024 15:28:23 GMT, David M. Lloyd <duke at openjdk.org> wrote:

>> src/java.base/share/classes/java/lang/classfile/Signature.java line 219:
>> 
>>> 217:                  * no wildcard (empty), an exact type
>>> 218:                  */
>>> 219:                 DEFAULT,
>> 
>> I’m personally in favour of naming this `NONE`.
>
> A belated +1 to this, at least not calling it `DEFAULT` because that has at best no meaning, and at worst it's outright confusing. If not `NONE`, then what about `EXACT`?
> 
> In my own old parsing code I have an enum called `Variance` with values `INVARIANT`, `COVARIANT`, and `CONTRAVARIANT`, but that might be a bit confusing considering that `EXTENDS` and `SUPER` match the Java language keywords directly.
> 
> As an aside, the javadoc here could be a little better IMO.

Performed the rename. `NONE` is better than `EXACT`, as there indeed is no indicator char for this bounded type argument.

I have added the terms of `invariant` `covariant` `contravariant` to the docs, so that they can be searched with the Javadoc search function. (These are official CS terms so shouldn't be ambiguous)

I decided not too add exact descriptions, like "method parameters EXTENDS can only accept null" or "method return type SUPER can only return Object". These details of Java type system may be subject to change in the future, and this is really describing details of a ClassFile attribute instead of the Java type system.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16517#discussion_r1498670793