Summary

Remodel the type arguments in Class-File API to make it an algebraic data type, so users can access the bound type more easily and reliably.

Problem

Currently, when the wildcard indicator in TypeArg is not UNBOUNDED, users can safely trust the bound, wrapped in optional, is non-null; but users still have to use a "risky" unwrap code.

Solution

Remodel the TypeArg to have Bounded and Unbounded subinterfaces; the wildcard indicator and bound will only be present in the Bounded subinterface. This model also more closely aligns with the model from JLS: https://docs.oracle.com/javase/specs/jvms/se21/html/jvms-4.html#jvms-4.7.9.1-300-B.4

Specification

--- a/src/java.base/share/classes/java/lang/classfile/Signature.java
+++ b/src/java.base/share/classes/java/lang/classfile/Signature.java
@@ -185,80 +185,92 @@ public static ClassTypeSig of(ClassTypeSig outerType, String className, TypeArg.
     /**
      * Models the type argument.
      *
+     * @sealedGraph
      * @since 22
      */
     @PreviewFeature(feature = PreviewFeature.Feature.CLASSFILE_API)
-    public sealed interface TypeArg
-            permits SignaturesImpl.TypeArgImpl {
+    public sealed interface TypeArg {

         /**
-         * Indicator for whether a wildcard has default bound, no bound,
-         * an upper bound, or a lower bound
-         *
-         * @since 22
+         * Models an unbounded type argument {@code *}.
+         * @since 23
          */
         @PreviewFeature(feature = PreviewFeature.Feature.CLASSFILE_API)
-        public enum WildcardIndicator {
-
-            /**
-             * default bound wildcard (empty)
-             */
-            DEFAULT,
-
-            /**
-             * unbounded indicator {@code *}
-             */
-            UNBOUNDED,
+        public sealed interface Unbounded extends TypeArg permits SignaturesImpl.UnboundedTypeArgImpl {
+        }

-            /**
-             * upper-bounded indicator {@code +}
-             */
-            EXTENDS,
+        /**
+         * Models a type argument with an explicit bound type.
+         * @since 23
+         */
+        @PreviewFeature(feature = PreviewFeature.Feature.CLASSFILE_API)
+        public sealed interface Bounded extends TypeArg permits SignaturesImpl.TypeArgImpl {

             /**
-             * lower-bounded indicator {@code -}
+             * Models a type argument's wildcard indicator.
+             * @since 23
              */
-            SUPER;
+            @PreviewFeature(feature = PreviewFeature.Feature.CLASSFILE_API)
+            public enum WildcardIndicator {
+
+                /**
+                 * No wildcard (empty), an exact type. Also known as
+                 * {@index invariant}.
+                 */
+                NONE,
+
+                /**
+                 * Upper-bound indicator {@code +}. Also known as
+                 * {@index covariant}.
+                 */
+                EXTENDS,
+
+                /**
+                 * Lower-bound indicator {@code -}. Also known as
+                 * {@index contravariant}.
+                 */
+                SUPER;
+            }
+
+            /** {@return the kind of wildcard} */
+            WildcardIndicator wildcardIndicator();
+
+            /** {@return the signature of the type bound} */
+            RefTypeSig boundType();
         }

-        /** {@return the wildcard indicator} */
-        WildcardIndicator wildcardIndicator();
-
-        /** {@return the signature of the type bound, if any} */
-        Optional<RefTypeSig> boundType();
-
         /**
          * {@return a bounded type arg}
          * @param boundType the bound
          */
-        public static TypeArg of(RefTypeSig boundType) {
+        public static TypeArg.Bounded of(RefTypeSig boundType) {
             requireNonNull(boundType);
-            return of(WildcardIndicator.DEFAULT, Optional.of(boundType));
+            return bounded(Bounded.WildcardIndicator.NONE, boundType);
         }

         /**
          * {@return an unbounded type arg}
          */
-        public static TypeArg unbounded() {
-            return of(WildcardIndicator.UNBOUNDED, Optional.empty());
+        public static TypeArg.Unbounded unbounded() {
+            return SignaturesImpl.UnboundedTypeArgImpl.INSTANCE;
         }

         /**
          * {@return an upper-bounded type arg}
          * @param boundType the upper bound
          */
-        public static TypeArg extendsOf(RefTypeSig boundType) {
+        public static TypeArg.Bounded extendsOf(RefTypeSig boundType) {
             requireNonNull(boundType);
-            return of(WildcardIndicator.EXTENDS, Optional.of(boundType));
+            return bounded(Bounded.WildcardIndicator.EXTENDS, boundType);
         }

         /**
          * {@return a lower-bounded type arg}
          * @param boundType the lower bound
          */
-        public static TypeArg superOf(RefTypeSig boundType) {
+        public static TypeArg.Bounded superOf(RefTypeSig boundType) {
             requireNonNull(boundType);
-            return of(WildcardIndicator.SUPER, Optional.of(boundType));
+            return bounded(Bounded.WildcardIndicator.SUPER, boundType);
         }

         /**
@@ -266,7 +278,9 @@ public static TypeArg superOf(RefTypeSig boundType) {
          * @param wildcard the wild card
          * @param boundType optional bound type
          */
-        public static TypeArg of(WildcardIndicator wildcard, Optional<RefTypeSig> boundType) {
+        public static TypeArg.Bounded bounded(Bounded.WildcardIndicator wildcard, RefTypeSig boundType) {
+            requireNonNull(wildcard);
+            requireNonNull(boundType);
             return new SignaturesImpl.TypeArgImpl(wildcard, boundType);
         }
     }