Improve exception messages for annotation-related methods on synthetic TypeVariable instances.

Fixes #7974

RELNOTES=n/a
PiperOrigin-RevId: 810604229

Author: lmcrean

android/guava/src/com/google/common/reflect/TypeResolver.java

@@ -368,10 +368,13 @@ Type resolveInternal(TypeVariable<?> var, TypeTable forDependants) {
          * by us. And that equality is guaranteed to hold because it doesn't involve the JDK
          * TypeVariable implementation at all.
          *
-         * TODO: b/147144588 - But what about when the TypeVariable has annotations? Our
-         * implementation currently doesn't support annotations _at all_. It could at least be made
-         * to respond to queries about annotations by returning null/empty, but are there situations
-         * in which it should return something else?
+         * NOTE: b/147144588 - Custom TypeVariables created by Guava do not preserve
+         * annotations. This is intentional. The semantics of annotation handling during
+         * type resolution are unclear and have changed across Java versions. Until there's
+         * a clear specification for what annotations should mean on resolved TypeVariables
+         * with modified bounds, annotation methods will throw
+         * UnsupportedOperationException. Frameworks requiring annotation preservation
+         * should use the original TypeVariable when bounds haven't changed.
          */
         if (Types.NativeTypeVariableEquals.NATIVE_TYPE_VARIABLE_ONLY
             && Arrays.equals(bounds, resolvedBounds)) {

android/guava/src/com/google/common/reflect/Types.java

@@ -382,6 +382,18 @@ private static final class TypeVariableInvocationHandler implements InvocationHa
       String methodName = method.getName();
       Method typeVariableMethod = typeVariableMethods.get(methodName);
       if (typeVariableMethod == null) {
+        if (methodName.equals("getAnnotatedBounds")
+            || methodName.equals("isAnnotationPresent")
+            // Each of these prefixes is shared by a family of methods:
+            || methodName.startsWith("getAnnotation")
+            || methodName.startsWith("getDeclaredAnnotation")) {
+          throw new UnsupportedOperationException(
+              "Annotation methods are not supported on synthetic TypeVariables created during type"
+                  + " resolution. The semantics of annotations on resolved types with modified"
+                  + " bounds are undefined. Use the original TypeVariable for annotation access."
+                  + " See b/147144588.");
+        }
+        // If any other method appears or if we forgot one, include it in the exception message:
         throw new UnsupportedOperationException(methodName);
       } else {
         try {

guava/src/com/google/common/reflect/TypeResolver.java

@@ -368,10 +368,13 @@ Type resolveInternal(TypeVariable<?> var, TypeTable forDependants) {
          * by us. And that equality is guaranteed to hold because it doesn't involve the JDK
          * TypeVariable implementation at all.
          *
-         * TODO: b/147144588 - But what about when the TypeVariable has annotations? Our
-         * implementation currently doesn't support annotations _at all_. It could at least be made
-         * to respond to queries about annotations by returning null/empty, but are there situations
-         * in which it should return something else?
+         * NOTE: b/147144588 - Custom TypeVariables created by Guava do not preserve
+         * annotations. This is intentional. The semantics of annotation handling during
+         * type resolution are unclear and have changed across Java versions. Until there's
+         * a clear specification for what annotations should mean on resolved TypeVariables
+         * with modified bounds, annotation methods will throw
+         * UnsupportedOperationException. Frameworks requiring annotation preservation
+         * should use the original TypeVariable when bounds haven't changed.
          */
         if (Types.NativeTypeVariableEquals.NATIVE_TYPE_VARIABLE_ONLY
             && Arrays.equals(bounds, resolvedBounds)) {

guava/src/com/google/common/reflect/Types.java

@@ -382,6 +382,18 @@ private static final class TypeVariableInvocationHandler implements InvocationHa
       String methodName = method.getName();
       Method typeVariableMethod = typeVariableMethods.get(methodName);
       if (typeVariableMethod == null) {
+        if (methodName.equals("getAnnotatedBounds")
+            || methodName.equals("isAnnotationPresent")
+            // Each of these prefixes is shared by a family of methods:
+            || methodName.startsWith("getAnnotation")
+            || methodName.startsWith("getDeclaredAnnotation")) {
+          throw new UnsupportedOperationException(
+              "Annotation methods are not supported on synthetic TypeVariables created during type"
+                  + " resolution. The semantics of annotations on resolved types with modified"
+                  + " bounds are undefined. Use the original TypeVariable for annotation access."
+                  + " See b/147144588.");
+        }
+        // If any other method appears or if we forgot one, include it in the exception message:
         throw new UnsupportedOperationException(methodName);
       } else {
         try {