Summary

Provide more precise information on the value of Element.asType() by providing overrides in subinterfaces.

Problem

The behavior of the asType() method on more specific subinterfaces of javax.lang.model.Element, such as PackageElement and TypeElement is not always obviously constrained.

Solution

Provide overridden versions of the method in the subinterfaces.

Specification

diff -r b6418e5aad70 src/java.compiler/share/classes/javax/lang/model/element/Element.java
--- a/src/java.compiler/share/classes/javax/lang/model/element/Element.java Thu May 30 15:55:16 2019 -0700
+++ b/src/java.compiler/share/classes/javax/lang/model/element/Element.java Thu May 30 16:11:05 2019 -0700
@@ -63,20 +63,15 @@
 public interface Element extends javax.lang.model.AnnotatedConstruct {
     /**
      * Returns the type defined by this element.
-     *
-     * <p> A generic element defines a family of types, not just one.
-     * If this is a generic element, a <i>prototypical</i> type is
-     * returned.  This is the element's invocation on the
-     * type variables corresponding to its own formal type parameters.
-     * For example,
-     * for the generic class element {@code C<N extends Number>},
-     * the parameterized type {@code C<N>} is returned.
-     * The {@link Types} utility interface has more general methods
-     * for obtaining the full range of types defined by an element.
+     * @return the type defined by this element
      *
      * @see Types
-     *
-     * @return the type defined by this element
+     * @see ExecutableElement#asType
+     * @see ModuleElement#asType
+     * @see PackageElement#asType
+     * @see TypeElement#asType
+     * @see TypeParameterElement#asType
+     * @see VariableElement#asType
      */
     TypeMirror asType();

diff -r b6418e5aad70 src/java.compiler/share/classes/javax/lang/model/element/ExecutableElement.java
--- a/src/java.compiler/share/classes/javax/lang/model/element/ExecutableElement.java   Thu May 30 15:55:16 2019 -0700
+++ b/src/java.compiler/share/classes/javax/lang/model/element/ExecutableElement.java   Thu May 30 16:11:05 2019 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -41,6 +41,17 @@
  */
 public interface ExecutableElement extends Element, Parameterizable {
     /**
+     * Returns the {@linkplain ExecutableType executable type} defined
+     * by this executable element.
+     *
+     * @return the executable type defined by this executable element
+     *
+     * @see ExecutableType
+     */
+    @Override
+    TypeMirror asType();
+
+    /**
      * Returns the formal type parameters of this executable
      * in declaration order.
      *
diff -r b6418e5aad70 src/java.compiler/share/classes/javax/lang/model/element/ModuleElement.java
--- a/src/java.compiler/share/classes/javax/lang/model/element/ModuleElement.java   Thu May 30 15:55:16 2019 -0700
+++ b/src/java.compiler/share/classes/javax/lang/model/element/ModuleElement.java   Thu May 30 16:11:05 2019 -0700
@@ -26,6 +26,7 @@
 package javax.lang.model.element;

 import java.util.List;
+import javax.lang.model.type.TypeMirror;

 /**
  * Represents a module program element.  Provides access to
@@ -37,6 +38,16 @@
  * @spec JPMS
  */
 public interface ModuleElement extends Element, QualifiedNameable {
+    /**
+     * Returns a {@linkplain javax.lang.model.type.NoType pseudo-type}
+     * for this module.
+     * @return a pseudo-type for this module
+     *
+     * @see javax.lang.model.type.NoType
+     * @see javax.lang.model.type.TypeKind#MODULE
+     */
+    @Override
+    TypeMirror asType();

     /**
      * Returns the fully qualified name of this module.  For an
diff -r b6418e5aad70 src/java.compiler/share/classes/javax/lang/model/element/PackageElement.java
--- a/src/java.compiler/share/classes/javax/lang/model/element/PackageElement.java  Thu May 30 15:55:16 2019 -0700
+++ b/src/java.compiler/share/classes/javax/lang/model/element/PackageElement.java  Thu May 30 16:11:05 2019 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -26,6 +26,7 @@
 package javax.lang.model.element;

 import java.util.List;
+import javax.lang.model.type.TypeMirror;

 /**
  * Represents a package program element.  Provides access to information
@@ -38,6 +39,16 @@
  * @since 1.6
  */
 public interface PackageElement extends Element, QualifiedNameable {
+    /**
+     * Returns a {@linkplain javax.lang.model.type.NoType pseudo-type}
+     * for this package.
+     * @return a pseudo-type for this package
+     *
+     * @see javax.lang.model.type.NoType
+     * @see javax.lang.model.type.TypeKind#PACKAGE
+     */
+    @Override
+    TypeMirror asType();

     /**
      * Returns the fully qualified name of this package.
diff -r b6418e5aad70 src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java
--- a/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java Thu May 30 15:55:16 2019 -0700
+++ b/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java Thu May 30 16:11:05 2019 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -60,6 +60,28 @@
  */
 public interface TypeElement extends Element, Parameterizable, QualifiedNameable {
     /**
+     * Returns the type defined by this type element, returning the
+     * <i>prototypical</i> type for an element representing a generic type.
+     *
+     * <p>A generic element defines a family of types, not just one.
+     * If this is a generic element, a prototypical type is
+     * returned which has the element's invocation on the
+     * type variables corresponding to its own formal type parameters.
+     * For example,
+     * for the generic class element {@code C<N extends Number>},
+     * the parameterized type {@code C<N>} is returned.
+     * The {@link Types} utility interface has more general methods
+     * for obtaining the full range of types defined by an element.
+     *
+     * @return the type defined by this type element
+     * 
+     * @see Types#asMemberOf(DeclaredType, Element)
+     * @see Types#getDeclaredType(TypeElement, TypeMirror...)
+     */
+    @Override
+    TypeMirror asType();
+
+    /**
      * Returns the fields, methods, constructors, and member types
      * that are directly declared in this class or interface.
      *
diff -r b6418e5aad70 src/java.compiler/share/classes/javax/lang/model/element/TypeParameterElement.java
--- a/src/java.compiler/share/classes/javax/lang/model/element/TypeParameterElement.java    Thu May 30 15:55:16 2019 -0700
+++ b/src/java.compiler/share/classes/javax/lang/model/element/TypeParameterElement.java    Thu May 30 16:11:05 2019 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -41,6 +41,15 @@
  * @since 1.6
  */
 public interface TypeParameterElement extends Element {
+    /**
+     * Returns the {@linkplain TypeVariable type variable} corresponding to this type parameter element.
+     *
+     * @see TypeVariable
+     *
+     * @return the type variable corresponding to this type parameter element
+     */
+    @Override
+    TypeMirror asType();

     /**
      * Returns the generic class, interface, method, or constructor that is
diff -r b6418e5aad70 src/java.compiler/share/classes/javax/lang/model/element/VariableElement.java
--- a/src/java.compiler/share/classes/javax/lang/model/element/VariableElement.java Thu May 30 15:55:16 2019 -0700
+++ b/src/java.compiler/share/classes/javax/lang/model/element/VariableElement.java Thu May 30 16:11:05 2019 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -26,6 +26,8 @@
 package javax.lang.model.element;

 import javax.lang.model.util.Elements;
+import javax.lang.model.type.TypeMirror;
+import javax.lang.model.type.TypeKind;

 /**
  * Represents a field, {@code enum} constant, method or constructor
@@ -38,6 +40,19 @@
  * @since 1.6
  */
 public interface VariableElement extends Element {
+    /**
+     * Returns the type of this variable.
+     *
+     * Note that the types of variables range over {@linkplain
+     * TypeKind many kinds} of types, including primitive types,
+     * declared types, and array types, among others.
+     *
+     * @return the type of this variable
+     *
+     * @see TypeKind
+     */
+    @Override
+    TypeMirror asType();

     /**
      * Returns the value of this variable if this is a {@code final}