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

Provide explicit specification for getKind methods of javax.lang.model

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 15
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      Document existing behavior, much of which is implied by the kind visitors.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      Add explicit specifications for the various getKind methods in the javax.lang.model API.

      Problem

      The getKind methods do not explicit state the constraints on the type-to-kind mapping. While many of the mappings are obvious , a "FooElement" has a kind of "FOO", some types have multiple possible kinds. For elements and types, the possible one-to-many mappings are captured in the FooKind visitor classes.

      Solution

      In the root interfaces, add lists describing the possible type-to-kind mapping. This is done in preference to adding getKind overrides in each type.

      Specification

      --- old/src/java.compiler/share/classes/javax/lang/model/element/Element.java   2020-02-14 09:29:39.476001000 -0800
      +++ new/src/java.compiler/share/classes/javax/lang/model/element/Element.java   2020-02-14 09:29:38.936001000 -0800
      @@ -78,6 +78,43 @@
           /**
            * Returns the {@code kind} of this element.
            *
      +     * <ul>
      +     *
      +     * <li> The kind of a {@linkplain PackageElement package} is
      +     * {@link ElementKind#PACKAGE PACKAGE}.
      +     *
      +     * <li> The kind of a {@linkplain ModuleElement module} is {@link
      +     * ElementKind#MODULE MODULE}.
      +     *
      +     * <li> The kind of a {@linkplain TypeElement type element} is one
      +     * of {@link ElementKind#ANNOTATION_TYPE ANNOTATION_TYPE}, {@link
      +     * ElementKind#CLASS CLASS}, {@link ElementKind#ENUM ENUM}, {@link
      +     * ElementKind#INTERFACE INTERFACE}, or {@link ElementKind#RECORD
      +     * RECORD}.
      +     *
      +     * <li> The kind of a {@linkplain VariableElement variable} is one
      +     * of {@link ElementKind#ENUM_CONSTANT ENUM_CONSTANT}, {@link
      +     * ElementKind#EXCEPTION_PARAMETER EXCEPTION_PARAMETER}, {@link
      +     * ElementKind#FIELD FIELD}, {@link ElementKind#LOCAL_VARIABLE
      +     * LOCAL_VARIABLE}, {@link ElementKind#PARAMETER PARAMETER},
      +     * {@link ElementKind#RESOURCE_VARIABLE RESOURCE_VARIABLE}, or
      +     * {@link ElementKind#BINDING_VARIABLE BINDING_VARIABLE}.
      +     *
      +     * <li> The kind of an {@linkplain ExecutableElement executable}
      +     * is one of {@link ElementKind#CONSTRUCTOR CONSTRUCTOR}, {@link
      +     * ElementKind#INSTANCE_INIT INSTANCE_INIT}, {@link
      +     * ElementKind#METHOD METHOD}, or {@link ElementKind#STATIC_INIT
      +     * STATIC_INIT}.
      +     *
      +     * <li> The kind of a {@linkplain TypeParameterElement type parameter} is
      +     * {@link ElementKind#TYPE_PARAMETER TYPE_PARAMETER}.
      +     *
      +     * <li> The kind of a {@linkplain RecordComponentElement record
      +     * component} is {@link ElementKind#RECORD_COMPONENT
      +     * RECORD_COMPONENT}.
      +     *
      +     * </ul>
      +     *
            * @return the kind of this element
            */
           ElementKind getKind();
      --- old/src/java.compiler/share/classes/javax/lang/model/element/ModuleElement.java 2020-02-14 09:29:40.424001000 -0800
      +++ new/src/java.compiler/share/classes/javax/lang/model/element/ModuleElement.java 2020-02-14 09:29:39.992001000 -0800
      @@ -161,6 +161,24 @@
           interface Directive {
               /**
                * Returns the {@code kind} of this directive.
      +         * <ul>
      +         *
      +         * <li>The kind of a {@linkplain RequiresDirective requires
      +         * directive} is {@link DirectiveKind#REQUIRES REQUIRES}.
      +         *
      +         * <li>The kind of an {@linkplain ExportsDirective exports
      +         * directive} is {@link DirectiveKind#EXPORTS EXPORTS}.
      +         *
      +         * <li>The kind of an {@linkplain OpensDirective opens
      +         * directive} is {@link DirectiveKind#OPENS OPENS}.
      +         *
      +         * <li>The kind of a {@linkplain UsesDirective uses
      +         * directive} is {@link DirectiveKind#USES USES}.
      +         *
      +         * <li>The kind of a {@linkplain ProvidesDirective provides
      +         * directive} is {@link DirectiveKind#PROVIDES PROVIDES}.
      +         *
      +         * </ul>
                *
                * @return the kind of this directive
                */
      --- old/src/java.compiler/share/classes/javax/lang/model/type/TypeMirror.java   2020-02-14 09:29:41.244001000 -0800
      +++ new/src/java.compiler/share/classes/javax/lang/model/type/TypeMirror.java   2020-02-14 09:29:40.844001000 -0800
      @@ -62,6 +62,47 @@
           /**
            * Returns the {@code kind} of this type.
            *
      +     * <ul>
      +     *
      +     * <li> The kind of a {@linkplain PrimitiveType primitive type} is
      +     * one of the kinds for which {@link TypeKind#isPrimitive} returns
      +     * {@code true}.
      +     *
      +     * <li> The kind of a {@linkplain NullType null type} is {@link
      +     * TypeKind#NULL NULL}.
      +     *
      +     * <li> The kind of an {@linkplain ArrayType array type} is {@link
      +     * TypeKind#ARRAY ARRAY}.
      +     *
      +     * <li> The kind of a {@linkplain DeclaredType declared type} is
      +     * {@link TypeKind#DECLARED DECLARED}.
      +     *
      +     * <li> The kind of an {@linkplain ErrorType error type} is {@link
      +     * TypeKind#ERROR ERROR}.
      +     *
      +     * <li> The kind of a {@linkplain TypeVariable type variable} is
      +     * {@link TypeKind#TYPEVAR TYPEVAR}.
      +     *
      +     * <li> The kind of a {@linkplain WildcardType wildcard type} is
      +     * {@link TypeKind#WILDCARD WILDCARD}.
      +     *
      +     *
      +     * <li> The kind of an {@linkplain ExecutableType executable type}
      +     * is {@link TypeKind#EXECUTABLE EXECUTABLE}.
      +     *
      +     * <li> The kind of a {@linkplain NoType pseudo-type type} is one
      +     * of {@link TypeKind#VOID VOID}, {@link TypeKind#PACKAGE
      +     * PACKAGE}, {@link TypeKind#MODULE MODULE}, or {@link
      +     * TypeKind#NONE NONE}.
      +     *
      +     * <li> The kind of an {@linkplain UnionType union type} is {@link
      +     * TypeKind#UNION UNION}.
      +     *
      +     * <li> The kind of an {@linkplain IntersectionType intersection
      +     * type} is {@link TypeKind#INTERSECTION INTERSECTION}.
      +     *
      +     * </ul>
      +     *
            * @return the kind of this type
            */
           TypeKind getKind();

        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: