Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8225027

Add clarifying overrides of Element.asType to more specific subinterfaces

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 13
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      Largely explicitly documenting what should be expected behavior that could be inferred from other parts of the spec, such as a ModuleElement should get mapped to a NoType of TypeKind MODULE, etc.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      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}

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                darcy Joe Darcy
                Reporter:
                darcy Joe Darcy
                Reviewed By:
                Jonathan Gibbons
              • Votes:
                0 Vote for this issue
                Watchers:
                1 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: