Summary

Update notes in ParameterizedType.getRawType() about core reflection implementation always returning a Class and the rationale for a Type return type.

Problem

All ParameterizedType instances created by core reflection return a Class for ParameterizedType.getRawType(), yet this is not described in any documentation and is confusing to users.

Solution

Add a note that ParameterizedType.getRawType() always return a Class for core reflection ParameterizedType objects, and that external implementations (such as those modeling unloaded types) can return other Type implementations modeling classes and interfaces.

Specification

--- a/src/java.base/share/classes/java/lang/reflect/ParameterizedType.java
+++ b/src/java.base/share/classes/java/lang/reflect/ParameterizedType.java
@@ -66,11 +66,16 @@ public interface ParameterizedType extends Type {
     Type[] getActualTypeArguments();

     /**
-     * Returns the {@code Type} object representing the class or interface
-     * that declared this type.
+     * {@return the {@code Type} object representing the class or interface
+     * that declared this type}
+     *
+     * @apiNote
+     * Returns a {@link Class} object for all {@code ParameterizedType}
+     * objects from core reflection, which models types in this running VM.
+     * The return type is {@code Type} because {@code ParameterizedType}
+     * objects from other implementations may represent types not in
+     * this running VM.
      *
-     * @return the {@code Type} object representing the class or interface
-     *     that declared this type
      * @since 1.5
      */
     Type getRawType();