diff --git a/src/java.base/share/classes/java/lang/reflect/AnnotatedParameterizedType.java b/src/java.base/share/classes/java/lang/reflect/AnnotatedParameterizedType.java index a460adf482aa5..2135662c60a70 100644 --- a/src/java.base/share/classes/java/lang/reflect/AnnotatedParameterizedType.java +++ b/src/java.base/share/classes/java/lang/reflect/AnnotatedParameterizedType.java @@ -68,7 +68,7 @@ public interface AnnotatedParameterizedType extends AnnotatedType { * {@return the potentially annotated use of the immediately enclosing class * of the parameterized type, or {@code null} if and only if the * parameterized type is not an inner member class} For example, if this - * use is {@code Outer<@TC Long>.@TA nner<@TB String>}, this method returns + * use is {@code Outer<@TC Long>.@TA Inner<@TB String>}, this method returns * a representation of {@code Outer<@TC Long>}. * * @throws TypeNotPresentException {@inheritDoc} diff --git a/src/java.base/share/classes/java/lang/reflect/AnnotatedType.java b/src/java.base/share/classes/java/lang/reflect/AnnotatedType.java index 3172cf0c3f8e1..8c860a8fb3cfb 100644 --- a/src/java.base/share/classes/java/lang/reflect/AnnotatedType.java +++ b/src/java.base/share/classes/java/lang/reflect/AnnotatedType.java @@ -28,38 +28,45 @@ import java.lang.annotation.Annotation; /** - * {@code AnnotatedType} represents the potentially annotated (JLS {@jls 9.7.4}) - * use of a type or type argument in the current runtime. See {@link Type} for - * the complete list of types and type arguments. - *

- * Here is a mapping from types and type arguments of the use, with examples, - * to the modeling interfaces. "{@code AnnotatedType} alone" means the modeling - * class does not implement any of the subinterfaces of {@code AnnotatedType}. - *

- *

- * For example, an annotated use {@code @TB Outer.@TA Inner}, represented by - * {@code AnnotatedType} alone, has an annotation {@code @TA} and represents the - * non-generic {@code Outer.Inner} class. The use of its immediately enclosing - * class is {@code @TB Outer}, with an annotation {@code @TB}, representing the - * non-generic {@code Outer} class. + * {@code AnnotatedType} represents the potentially annotated use of a type or + * type argument in the current runtime. The use of a type (JLS {@jls 4.1}) is + * the use of a primitive type or a reference type. The use of a type argument + * (JLS {@jls 4.5.1}) is the use of a reference type or a wildcard type + * argument. + * + * + * + * + * + * + *
+ * Types and Type Arguments Used to Modeling Interfaces + *
Type or Type Argument Used + * Example + * Modeling interface + *
Primitive Types (JLS {@jls 4.2}) + * {@code @TA int} + * {@link ##alone AnnotatedType} + *
Reference
Types
(JLS {@jls 4.3}) + *
Classes
and
Interfaces + *
Non-generic Classes and
Interfaces + * (JLS {@jls 8.1.3}, {@jls 9.1.3}) + *
{@code @TC String} + *
Raw Types (JLS {@jls 4.8}) + * {@code @TA List} + *
Parameterized Types (JLS {@jls 4.5}) + * {@code @TA List<@TB ? extends @TC String>} + * {@link AnnotatedParameterizedType} + *
Type Variables (JLS {@jls 4.4}) + * {@code @TA T} + * {@link AnnotatedTypeVariable} + *
Array Types (JLS {@jls 10.1}) + * {@code @TB int @TA []} + * {@link AnnotatedArrayType} + *
Wildcard Type Arguments (JLS {@jls 4.5.1}) + * {@code @TB ? extends @TC String} + * {@link AnnotatedWildcardType} + *
*

* Note that any annotations returned by methods on this interface are * type annotations (JLS {@jls 9.7.4}) as the entity being @@ -68,15 +75,22 @@ * Two {@code AnnotatedType} objects should be compared using the {@link * Object#equals equals} method. * + *

The {@code AnnotatedType} interface alone

+ * Some {@code AnnotatedType} objects are not instances of the {@link + * AnnotatedArrayType}, {@link AnnotatedParameterizedType}, {@link + * AnnotatedTypeVariable}, or {@link AnnotatedWildcardType} subinterfaces. + * Such a potentially annotated use represents a primitive type, a non-generic + * class or interface, or a raw type, and the {@link #getType() getType()} + * method returns a {@link Class}. + *

+ * For example, an annotated use {@code @TB Outer.@TA Inner} has an annotation + * {@code @TA} and represents the non-generic {@code Outer.Inner} class. The use + * of its immediately enclosing class is {@code @TB Outer}, with an annotation + * {@code @TB}, representing the non-generic {@code Outer} class. + * * @see Type - * @jls 4.1 The Kinds of Types and Values - * @jls 4.2 Primitive Types and Values - * @jls 4.3 Reference Types and Values - * @jls 4.4 Type Variables - * @jls 4.5 Parameterized Types - * @jls 4.8 Raw Types - * @jls 4.9 Intersection Types - * @jls 10.1 Array Types + * @jls 4.11 Where Types Are Used + * @jls 9.7.4 Where Annotations May Appear * @since 1.8 */ public interface AnnotatedType extends AnnotatedElement { @@ -106,9 +120,11 @@ default AnnotatedType getAnnotatedOwnerType() { /** * {@return the type that this potentially annotated use represents} *

- * If this object does not implement any of the subinterfaces of {@code - * AnnotatedType}, this use represents a primitive type, a non-generic class - * or interface, or a raw type, and this method returns a {@link Class}. + * If this object is not an instance of {@link AnnotatedArrayType}, {@link + * AnnotatedParameterizedType}, {@link AnnotatedTypeVariable}, or {@link + * AnnotatedWildcardType}, this method returns a {@link Class}. + * + * @see ##alone The {@code AnnotatedType} interface alone */ Type getType(); diff --git a/src/java.base/share/classes/java/lang/reflect/AnnotatedTypeVariable.java b/src/java.base/share/classes/java/lang/reflect/AnnotatedTypeVariable.java index e2f8729052f72..d93326b2a0582 100644 --- a/src/java.base/share/classes/java/lang/reflect/AnnotatedTypeVariable.java +++ b/src/java.base/share/classes/java/lang/reflect/AnnotatedTypeVariable.java @@ -54,6 +54,11 @@ public interface AnnotatedTypeVariable extends AnnotatedType { * // @end * } * + * @throws TypeNotPresentException if any of the bounds refers to a + * non-existent type declaration + * @throws MalformedParameterizedTypeException if any of the bounds refer to + * a parameterized type that cannot be instantiated for any reason + * @jls 4.9 Intersection Types * @see TypeVariable#getAnnotatedBounds() * @see TypeVariable#getBounds() */ diff --git a/src/java.base/share/classes/java/lang/reflect/AnnotatedWildcardType.java b/src/java.base/share/classes/java/lang/reflect/AnnotatedWildcardType.java index 2ec70a5215d61..5e07e678fc5e3 100644 --- a/src/java.base/share/classes/java/lang/reflect/AnnotatedWildcardType.java +++ b/src/java.base/share/classes/java/lang/reflect/AnnotatedWildcardType.java @@ -28,9 +28,11 @@ /** * {@code AnnotatedWildcardType} represents the potentially annotated use of a * wildcard type argument, whose upper or lower bounds may themselves represent - * annotated uses of types. Note that the use of a wildcard type argument is - * not the use of a type, and thus will only be returned by APIs where uses of - * type arguments may appear. + * annotated uses of types. Since the use of a wildcard type argument is not + * the use of a type, it will only be returned by APIs where uses of type + * arguments may appear, such as {@link + * AnnotatedParameterizedType#getAnnotatedActualTypeArguments() + * AnnotatedParameterizedType::getAnnotatedActualTypeArguments}. *

* For example, an annotated use {@code @TA ? extends @TB Number} has an * annotation {@code @TA} and represents the wildcard type argument {@code ? diff --git a/src/java.base/share/classes/java/lang/reflect/Type.java b/src/java.base/share/classes/java/lang/reflect/Type.java index d990094977a39..ad7ac28655d98 100644 --- a/src/java.base/share/classes/java/lang/reflect/Type.java +++ b/src/java.base/share/classes/java/lang/reflect/Type.java @@ -26,58 +26,70 @@ package java.lang.reflect; /** - * {@code Type} represents types in the Java programming language (JLS {@jls - * 4.1}) and type arguments (JLS {@jls 4.5.1}). Types are primitive types (JLS - * {@jls 4.2}) and reference types (JLS {@jls 4.3}). Reference types are - * non-generic classes (JLS {@jls 8.1.2}) (which must not be an {@linkplain - * ParameterizedType##inner-member-class inner member class} of a generic class) - * and interfaces (JLS {@jls 9.1.2}), raw types (JLS {@jls 4.8}) and - * parameterized types (JLS {@jls 4.5}) of generic classes and interfaces, - * type variables (JLS {@jls 4.4}), and array types (JLS {@jls 10.1}). Type - * arguments are reference types and wildcard type arguments. - *

- * Here is a mapping from types and type arguments to the modeling interfaces. - * "{@code Type} alone" means the modeling class does not implement any other - * {@code Type} subinterface. The modeling class is {@link Class} in core - * reflection representation of types in the current runtime. Other - * implementations may use different modeling classes to represent types not - * in the current runtime. - *

+ * {@code Type} represents types in the Java programming language and type + * arguments. Types (JLS {@jls 4.1}) are primitive types and reference types. + * Type arguments (JLS {@jls 4.5.1}) are reference types and wildcard type + * arguments. + * + * + * + * + * + * + *
+ * Types and Type Arguments to Modeling Interfaces + *
Type or Type Argument + * Example + * Modeling interface + *
Primitive Types (JLS {@jls 4.2}) + * {@code int} + * {@link ##alone Type} + *
Reference
Types
(JLS {@jls 4.3}) + *
Classes
and
Interfaces + *
Non-generic Classes and
Interfaces + * (JLS {@jls 8.1.3}, {@jls 9.1.3}) + *
{@code String} + *
Raw Types (JLS {@jls 4.8}) + * {@code List} + *
Parameterized Types (JLS {@jls 4.5}) + * {@code List} + * {@link ParameterizedType} + *
Type Variables (JLS {@jls 4.4}) + * {@code T} + * {@link TypeVariable} + *
Array
Types
(JLS {@jls 10.1}) + *
Primitive Type Elements + * {@code int[]} + * {@link ##alone Type} + *
Non-generic Class or
Interface Elements + *
{@code String[]} + *
Raw Type Elements + * {@code List[]} + *
Parameterized Type Elements + * {@code List[][]} + * {@link GenericArrayType} + *
Types Variable Elements + * {@code T[][][]} + *
Wildcard Type Arguments (JLS {@jls 4.5.1}) + * {@code ? extends String} + * {@link WildcardType} + *
*

* Two {@code Type} objects should be compared using the {@link Object#equals * equals} method. * + *

The {@code Type} interface alone

+ * Some {@code Type} objects are not instances of the {@link GenericArrayType}, + * {@link ParameterizedType}, {@link TypeVariable}, or {@link WildcardType} + * subinterfaces. Such a type is a primitive type, a non-generic class or + * interface, a raw type, or an array type with any of these types as its + * element type. In core reflection, they are all represented by {@link Class}. + *

+ * Examples include the primitive type {@code int}, the non-generic {@link + * Object} class, the raw type {@code List}, and the array type {@code int[]}. + * * @jls 4.1 The Kinds of Types and Values - * @jls 4.2 Primitive Types and Values - * @jls 4.3 Reference Types and Values - * @jls 4.4 Type Variables - * @jls 4.5 Parameterized Types - * @jls 4.8 Raw Types - * @jls 4.9 Intersection Types - * @jls 10.1 Array Types + * @jls 4.11 Where Types Are Used * @since 1.5 */ public interface Type { diff --git a/src/java.base/share/classes/java/lang/reflect/TypeVariable.java b/src/java.base/share/classes/java/lang/reflect/TypeVariable.java index 5524950c00380..dffe8b1a5a019 100644 --- a/src/java.base/share/classes/java/lang/reflect/TypeVariable.java +++ b/src/java.base/share/classes/java/lang/reflect/TypeVariable.java @@ -60,6 +60,7 @@ public interface TypeVariable extends Type, Annota * non-existent type declaration * @throws MalformedParameterizedTypeException if any of the bounds refer to * a parameterized type that cannot be instantiated for any reason + * @jls 4.9 Intersection Types */ Type[] getBounds(); @@ -81,6 +82,11 @@ public interface TypeVariable extends Type, Annota * this method returns an array containing exactly the unannotated use of * the {@code Object} class. * + * @throws TypeNotPresentException if any of the bounds refers to a + * non-existent type declaration + * @throws MalformedParameterizedTypeException if any of the bounds refer to + * a parameterized type that cannot be instantiated for any reason + * @jls 4.9 Intersection Types * @since 1.8 */ AnnotatedType[] getAnnotatedBounds(); diff --git a/src/java.base/share/classes/java/lang/reflect/WildcardType.java b/src/java.base/share/classes/java/lang/reflect/WildcardType.java index ace0e6bc4ef24..b5ef355f2ea8c 100644 --- a/src/java.base/share/classes/java/lang/reflect/WildcardType.java +++ b/src/java.base/share/classes/java/lang/reflect/WildcardType.java @@ -28,8 +28,9 @@ /** * {@code WildcardType} represents a wildcard type argument, such as {@code ?}, * {@code ? extends Number}, or {@code ? super Integer}. Since a wildcard type - * argument is not a type, and it will only be returned by APIs where type - * arguments may appear. + * argument is not a type, it will only be returned by APIs where type arguments + * may appear, such as {@link ParameterizedType#getActualTypeArguments() + * ParameterizedType::getActualTypeArguments}. *

* Two {@code WildcardType} objects should be compared using the {@link * Object#equals equals} method.