stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8257638: Update usage of "type" terminology in javax.lang.model

Browse Source 
Reviewed-by: jjg
This commit is contained in:
Joe Darcy 2020-12-10 02:59:26 +00:00
parent f631a9901f
commit d2f9e31ae4
17 changed files with 176 additions and 164 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
src/java.compiler/share/classes/javax/annotation/processing/AbstractProcessor.java
View File

@ -39,9 +39,9 @@ import javax.tools.Diagnostic;
* superclass for most concrete annotation processors. This class * superclass for most concrete annotation processors. This class
* examines annotation values to compute the {@linkplain * examines annotation values to compute the {@linkplain
* #getSupportedOptions options}, {@linkplain * #getSupportedOptions options}, {@linkplain
* #getSupportedAnnotationTypes annotation types}, and {@linkplain * #getSupportedAnnotationTypes annotation interfaces}, and
* #getSupportedSourceVersion source version} supported by its * {@linkplain #getSupportedSourceVersion source version} supported by
* subtypes. * its subtypes.
* *
* <p>The getter methods may {@linkplain Messager#printMessage issue * <p>The getter methods may {@linkplain Messager#printMessage issue
* warnings} about noteworthy conditions using the facilities available * warnings} about noteworthy conditions using the facilities available
@ -98,8 +98,8 @@ public abstract class AbstractProcessor implements Processor {
* then any leading {@linkplain Processor#getSupportedAnnotationTypes * then any leading {@linkplain Processor#getSupportedAnnotationTypes
* module prefixes} are stripped from the names. * module prefixes} are stripped from the names.
* *
* @return the names of the annotation types supported by this * @return the names of the annotation interfaces supported by
* processor, or an empty set if none * this processor, or an empty set if none
*/ */
public Set<String> getSupportedAnnotationTypes() { public Set<String> getSupportedAnnotationTypes() {
SupportedAnnotationTypes sat = this.getClass().getAnnotation(SupportedAnnotationTypes.class); SupportedAnnotationTypes sat = this.getClass().getAnnotation(SupportedAnnotationTypes.class);

57
src/java.compiler/share/classes/javax/annotation/processing/Filer.java
View File

@ -66,9 +66,9 @@ import java.io.IOException;
* <p>The file creation methods take a variable number of arguments to * <p>The file creation methods take a variable number of arguments to
* allow the <em>originating elements</em> to be provided as hints to * allow the <em>originating elements</em> to be provided as hints to
* the tool infrastructure to better manage dependencies. The * the tool infrastructure to better manage dependencies. The
* originating elements are the types or packages (representing {@code * originating elements are the classes or interfaces or packages
* package-info} files) or modules (representing {@code * (representing {@code package-info} files) or modules (representing
* module-info} files) which caused an annotation processor to * {@code module-info} files) which caused an annotation processor to
* attempt to create a new file. For example, if an annotation * attempt to create a new file. For example, if an annotation
* processor tries to create a source file, {@code * processor tries to create a source file, {@code
* GeneratedFromUserSource}, in response to processing * GeneratedFromUserSource}, in response to processing
@ -107,14 +107,15 @@ import java.io.IOException;
* <p> In general, processors must not knowingly attempt to overwrite * <p> In general, processors must not knowingly attempt to overwrite
* existing files that were not generated by some processor. A {@code * existing files that were not generated by some processor. A {@code
* Filer} may reject attempts to open a file corresponding to an * Filer} may reject attempts to open a file corresponding to an
* existing type, like {@code java.lang.Object}. Likewise, the * existing class or interface, like {@code java.lang.Object}. Likewise, the
* invoker of the annotation processing tool must not knowingly * invoker of the annotation processing tool must not knowingly
* configure the tool such that the discovered processors will attempt * configure the tool such that the discovered processors will attempt
* to overwrite existing files that were not generated. * to overwrite existing files that were not generated.
* *
* <p> Processors can indicate a source or class file is generated by * <p> Processors can indicate a source or class file is generated by
* including a {@link javax.annotation.processing.Generated} annotation if the * including a {@link javax.annotation.processing.Generated}
* environment is configured so that that type is accessible. * annotation if the environment is configured so that that class or
* interface is accessible.
* *
* @apiNote Some of the effect of overwriting a file can be * @apiNote Some of the effect of overwriting a file can be
* achieved by using a <i>decorator</i>-style pattern. Instead of * achieved by using a <i>decorator</i>-style pattern. Instead of
@ -133,8 +134,8 @@ import java.io.IOException;
public interface Filer { public interface Filer {
/** /**
* Creates a new source file and returns an object to allow * Creates a new source file and returns an object to allow
* writing to it. A source file for a type, or a package can * writing to it. A source file for a class, interface, or a
* be created. * package can be created.
* *
* The file's name and path (relative to the {@linkplain * The file's name and path (relative to the {@linkplain
* StandardLocation#SOURCE_OUTPUT root output location for source * StandardLocation#SOURCE_OUTPUT root output location for source
@ -142,9 +143,9 @@ public interface Filer {
* that file as well as the specified module for the item (if * that file as well as the specified module for the item (if
* any). * any).
* *
* If more than one type is being declared in a single file (that * If more than one class or interface is being declared in a single file (that
* is, a single compilation unit), the name of the file should * is, a single compilation unit), the name of the file should
* correspond to the name of the principal top-level type (the * correspond to the name of the principal top-level class or interface (the
* public one, for example). * public one, for example).
* *
* <p>A source file can also be created to hold information about * <p>A source file can also be created to hold information about
@ -155,7 +156,7 @@ public interface Filer {
* *
* <p>The optional module name is prefixed to the type name or * <p>The optional module name is prefixed to the type name or
* package name and separated using a "{@code /}" character. For * package name and separated using a "{@code /}" character. For
* example, to create a source file for type {@code a.B} in module * example, to create a source file for class {@code a.B} in module
* {@code foo}, use a {@code name} argument of {@code "foo/a.B"}. * {@code foo}, use a {@code name} argument of {@code "foo/a.B"}.
* *
* <p>If no explicit module prefix is given and modules are supported * <p>If no explicit module prefix is given and modules are supported
@ -194,15 +195,15 @@ public interface Filer {
* as the target module. A separate option may be used to provide the target * as the target module. A separate option may be used to provide the target
* module if it cannot be determined using the above rules. * module if it cannot be determined using the above rules.
* *
* @param name canonical (fully qualified) name of the principal type * @param name canonical (fully qualified) name of the principal class or interface
* being declared in this file or a package name followed by * being declared in this file or a package name followed by
* {@code ".package-info"} for a package information file * {@code ".package-info"} for a package information file
* @param originatingElements type or package or module elements causally * @param originatingElements class, interface, package, or module
* associated with the creation of this file, may be elided or * elements causally associated with the creation of this file,
* {@code null} * may be elided or {@code null}
* @return a {@code JavaFileObject} to write the new source file * @return a {@code JavaFileObject} to write the new source file
* @throws FilerException if the same pathname has already been * @throws FilerException if the same pathname has already been
* created, the same type has already been created, the name is * created, the same class or interface has already been created, the name is
* otherwise not valid for the entity requested to being created, * otherwise not valid for the entity requested to being created,
* if the target module cannot be determined, if the target * if the target module cannot be determined, if the target
* module is not writable, or a module is specified when the environment * module is not writable, or a module is specified when the environment
@ -215,7 +216,7 @@ public interface Filer {
/** /**
* Creates a new class file, and returns an object to allow * Creates a new class file, and returns an object to allow
* writing to it. A class file for a type, or a package can * writing to it. A class file for a class, interface, or a package can
* be created. * be created.
* *
* The file's name and path (relative to the {@linkplain * The file's name and path (relative to the {@linkplain
@ -231,7 +232,7 @@ public interface Filer {
* *
* <p>The optional module name is prefixed to the type name or * <p>The optional module name is prefixed to the type name or
* package name and separated using a "{@code /}" character. For * package name and separated using a "{@code /}" character. For
* example, to create a class file for type {@code a.B} in module * example, to create a class file for class {@code a.B} in module
* {@code foo}, use a {@code name} argument of {@code "foo/a.B"}. * {@code foo}, use a {@code name} argument of {@code "foo/a.B"}.
* *
* <p>If no explicit module prefix is given and modules are supported * <p>If no explicit module prefix is given and modules are supported
@ -259,15 +260,16 @@ public interface Filer {
* as the target module. A separate option may be used to provide the target * as the target module. A separate option may be used to provide the target
* module if it cannot be determined using the above rules. * module if it cannot be determined using the above rules.
* *
* @param name binary name of the type being written or a package name followed by * @param name binary name of the class or interface being written
* {@code ".package-info"} for a package information file * or a package name followed by {@code ".package-info"} for a
* @param originatingElements type or package or module elements causally * package information file
* associated with the creation of this file, may be elided or * @param originatingElements class or interface or package or
* {@code null} * module elements causally associated with the creation of this
* file, may be elided or {@code null}
* @return a {@code JavaFileObject} to write the new class file * @return a {@code JavaFileObject} to write the new class file
* @throws FilerException if the same pathname has already been * @throws FilerException if the same pathname has already been
* created, the same type has already been created, the name is * created, the same class or interface has already been created, the name is
* not valid for a type, if the target module cannot be determined, * not valid for a class or interface, if the target module cannot be determined,
* if the target module is not writable, or a module is specified when * if the target module is not writable, or a module is specified when
* the environment doesn't support modules. * the environment doesn't support modules.
* @throws IOException if the file cannot be created * @throws IOException if the file cannot be created
@ -330,8 +332,9 @@ public interface Filer {
* @param moduleAndPkg module and/or package relative to which the file * @param moduleAndPkg module and/or package relative to which the file
* should be named, or the empty string if none * should be named, or the empty string if none
* @param relativeName final pathname components of the file * @param relativeName final pathname components of the file
* @param originatingElements type or package or module elements causally * @param originatingElements class or interface or package or
* associated with the creation of this file, may be elided or * module elements causally associated with the creation of this
* file, may be elided or
* {@code null} * {@code null}
* @return a {@code FileObject} to write the new resource * @return a {@code FileObject} to write the new resource
* @throws IOException if the file cannot be created * @throws IOException if the file cannot be created

7
src/java.compiler/share/classes/javax/annotation/processing/FilerException.java
View File

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 2005, 2020, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -31,8 +31,9 @@ import java.io.IOException;
* Indicates a {@link Filer} detected an attempt to open a file that * Indicates a {@link Filer} detected an attempt to open a file that
* would violate the guarantees provided by the {@code Filer}. Those * would violate the guarantees provided by the {@code Filer}. Those
* guarantees include not creating the same file more than once, not * guarantees include not creating the same file more than once, not
* creating multiple files corresponding to the same type or package, and not * creating multiple files corresponding to the same class or
* creating files for types with invalid names. * interface or package, and not creating files for classes or
* interfaces with invalid names.
* *
* @author Joseph D. Darcy * @author Joseph D. Darcy
* @author Scott Seligman * @author Scott Seligman

88
src/java.compiler/share/classes/javax/annotation/processing/Processor.java
View File

@ -90,45 +90,45 @@ import javax.lang.model.SourceVersion;
* configuration mechanisms, such as command line options; for * configuration mechanisms, such as command line options; for
* details, refer to the particular tool's documentation. Which * details, refer to the particular tool's documentation. Which
* processors the tool asks to {@linkplain #process run} is a function * processors the tool asks to {@linkplain #process run} is a function
* of the types of the annotations <em>{@linkplain AnnotatedConstruct present}</em> * of the interfaces of the annotations <em>{@linkplain
* on the {@linkplain * AnnotatedConstruct present}</em> on the {@linkplain
* RoundEnvironment#getRootElements root elements}, what {@linkplain * RoundEnvironment#getRootElements root elements}, what {@linkplain
* #getSupportedAnnotationTypes annotation types a processor * #getSupportedAnnotationTypes annotation interfaces a processor
* supports}, and whether or not a processor {@linkplain #process * supports}, and whether or not a processor {@linkplain #process
* claims the annotation types it processes}. A processor will be asked to * claims the annotation interfaces it processes}. A processor will
* process a subset of the annotation types it supports, possibly an * be asked to process a subset of the annotation interfaces it
* empty set. * supports, possibly an empty set.
* *
* For a given round, the tool computes the set of annotation types * For a given round, the tool computes the set of annotation
* that are present on the elements enclosed within the root elements. * interfaces that are present on the elements enclosed within the
* If there is at least one annotation type present, then as * root elements. If there is at least one annotation interface
* processors claim annotation types, they are removed from the set of * present, then as processors claim annotation interfaces, they are
* unmatched annotation types. When the set is empty or no more * removed from the set of unmatched annotation interfaces. When the
* processors are available, the round has run to completion. If * set is empty or no more processors are available, the round has run
* there are no annotation types present, annotation processing still * to completion. If there are no annotation interfaces present,
* occurs but only <i>universal processors</i> which support * annotation processing still occurs but only <i>universal
* processing all annotation types, {@code "*"}, can claim the (empty) * processors</i> which support processing all annotation interfaces,
* set of annotation types. * {@code "*"}, can claim the (empty) set of annotation interfaces.
* *
* <p>An annotation type is considered present if there is at least * <p>An annotation interface is considered present if there is at least
* one annotation of that type present on an element enclosed within * one annotation of that interface present on an element enclosed within
* the root elements of a round. For this purpose, a type parameter is * the root elements of a round. For this purpose, a type parameter is
* considered to be enclosed by its {@linkplain * considered to be enclosed by its {@linkplain
* TypeParameterElement#getGenericElement generic * TypeParameterElement#getGenericElement generic
* element}. * element}.
* For this purpose, a package element is <em>not</em> considered to * For this purpose, a package element is <em>not</em> considered to
* enclose the top-level types within that package. (A root element * enclose the top-level classes and interfaces within that
* representing a package is created when a {@code package-info} file * package. (A root element representing a package is created when a
* is processed.) Likewise, for this purpose, a module element is * {@code package-info} file is processed.) Likewise, for this
* <em>not</em> considered to enclose the packages within that * purpose, a module element is <em>not</em> considered to enclose the
* module. (A root element representing a module is created when a * packages within that module. (A root element representing a module
* {@code module-info} file is processed.) * is created when a {@code module-info} file is processed.)
* *
* Annotations on {@linkplain * Annotations on {@linkplain
* java.lang.annotation.ElementType#TYPE_USE type uses}, as opposed to * java.lang.annotation.ElementType#TYPE_USE type uses}, as opposed to
* annotations on elements, are ignored when computing whether or not * annotations on elements, are ignored when computing whether or not
* an annotation type is present. * an annotation interface is present.
* *
* <p>An annotation is <em>present</em> if it meets the definition of being * <p>An annotation is <em>present</em> if it meets the definition of being
* present given in {@link AnnotatedConstruct}. In brief, an * present given in {@link AnnotatedConstruct}. In brief, an
@ -141,10 +141,10 @@ import javax.lang.model.SourceVersion;
* Elements#getAllAnnotationMirrors(Element)} called on that element. Since * Elements#getAllAnnotationMirrors(Element)} called on that element. Since
* annotations inside container annotations are not considered * annotations inside container annotations are not considered
* present, to properly process {@linkplain * present, to properly process {@linkplain
* java.lang.annotation.Repeatable repeatable annotation types}, * java.lang.annotation.Repeatable repeatable annotation interfaces},
* processors are advised to include both the repeatable annotation * processors are advised to include both the repeatable annotation
* type and its containing annotation type in the set of {@linkplain * interface and its containing annotation interface in the set of {@linkplain
* #getSupportedAnnotationTypes() supported annotation types} of a * #getSupportedAnnotationTypes() supported annotation interfaces} of a
* processor. * processor.
* *
* <p>Note that if a processor supports {@code "*"} and returns {@code * <p>Note that if a processor supports {@code "*"} and returns {@code
@ -240,17 +240,17 @@ public interface Processor {
Set<String> getSupportedOptions(); Set<String> getSupportedOptions();
/** /**
* Returns the names of the annotation types supported by this * Returns the names of the annotation interfaces supported by this
* processor. An element of the result may be the canonical * processor. An element of the result may be the canonical
* (fully qualified) name of a supported annotation type. * (fully qualified) name of a supported annotation interface.
* Alternately it may be of the form &quot;<code><i>name</i>.*</code>&quot; * Alternately it may be of the form &quot;<code><i>name</i>.*</code>&quot;
* representing the set of all annotation types with canonical * representing the set of all annotation interfaces with canonical
* names beginning with &quot;<code><i>name.</i></code>&quot;. * names beginning with &quot;<code><i>name.</i></code>&quot;.
* *
* In either of those cases, the name of the annotation type can * In either of those cases, the name of the annotation interface can
* be optionally preceded by a module name followed by a {@code * be optionally preceded by a module name followed by a {@code
* "/"} character. For example, if a processor supports {@code * "/"} character. For example, if a processor supports {@code
* "a.B"}, this can include multiple annotation types named {@code * "a.B"}, this can include multiple annotation interfaces named {@code
* a.B} which reside in different modules. To only support {@code * a.B} which reside in different modules. To only support {@code
* a.B} in the {@code foo} module, instead use {@code "foo/a.B"}. * a.B} in the {@code foo} module, instead use {@code "foo/a.B"}.
* *
@ -259,11 +259,11 @@ public interface Processor {
* environment where modules are not supported, such as an * environment where modules are not supported, such as an
* annotation processing environment configured for a {@linkplain * annotation processing environment configured for a {@linkplain
* javax.annotation.processing.ProcessingEnvironment#getSourceVersion * javax.annotation.processing.ProcessingEnvironment#getSourceVersion
* source version} without modules, then the annotation types with * source version} without modules, then the annotation interfaces with
* a module name do <em>not</em> match. * a module name do <em>not</em> match.
* *
* Finally, {@code "*"} by itself represents the set of all * Finally, {@code "*"} by itself represents the set of all
* annotation types, including the empty set. Note that a * annotation interfaces, including the empty set. Note that a
* processor should not claim {@code "*"} unless it is actually * processor should not claim {@code "*"} unless it is actually
* processing all files; claiming unnecessary annotations may * processing all files; claiming unnecessary annotations may
* cause a performance slowdown in some environments. * cause a performance slowdown in some environments.
@ -291,13 +291,13 @@ public interface Processor {
* *
* @apiNote When running in an environment which supports modules, * @apiNote When running in an environment which supports modules,
* processors are encouraged to include the module prefix when * processors are encouraged to include the module prefix when
* describing their supported annotation types. The method {@link * describing their supported annotation interfaces. The method {@link
* AbstractProcessor#getSupportedAnnotationTypes * AbstractProcessor#getSupportedAnnotationTypes
* AbstractProcessor.getSupportedAnnotationTypes} provides support * AbstractProcessor.getSupportedAnnotationTypes} provides support
* for stripping off the module prefix when running in an * for stripping off the module prefix when running in an
* environment without modules. * environment without modules.
* *
* @return the names of the annotation types supported by this processor * @return the names of the annotation interfaces supported by this processor
* or an empty set if none * or an empty set if none
* @see javax.annotation.processing.SupportedAnnotationTypes * @see javax.annotation.processing.SupportedAnnotationTypes
* @jls 3.8 Identifiers * @jls 3.8 Identifiers
@ -322,12 +322,12 @@ public interface Processor {
void init(ProcessingEnvironment processingEnv); void init(ProcessingEnvironment processingEnv);
/** /**
* Processes a set of annotation types on type elements * Processes a set of annotation interfaces on type elements
* originating from the prior round and returns whether or not * originating from the prior round and returns whether or not
* these annotation types are claimed by this processor. If {@code * these annotation interfaces are claimed by this processor. If {@code
* true} is returned, the annotation types are claimed and subsequent * true} is returned, the annotation interfaces are claimed and subsequent
* processors will not be asked to process them; if {@code false} * processors will not be asked to process them; if {@code false}
* is returned, the annotation types are unclaimed and subsequent * is returned, the annotation interfaces are unclaimed and subsequent
* processors may be asked to process them. A processor may * processors may be asked to process them. A processor may
* always return the same boolean value or may vary the result * always return the same boolean value or may vary the result
* based on its own chosen criteria. * based on its own chosen criteria.
@ -336,9 +336,9 @@ public interface Processor {
* "*"} and the root elements have no annotations. A {@code * "*"} and the root elements have no annotations. A {@code
* Processor} must gracefully handle an empty set of annotations. * Processor} must gracefully handle an empty set of annotations.
* *
* @param annotations the annotation types requested to be processed * @param annotations the annotation interfaces requested to be processed
* @param roundEnv environment for information about the current and prior round * @param roundEnv environment for information about the current and prior round
* @return whether or not the set of annotation types are claimed by this processor * @return whether or not the set of annotation interfaces are claimed by this processor
*/ */
boolean process(Set<? extends TypeElement> annotations, boolean process(Set<? extends TypeElement> annotations,
RoundEnvironment roundEnv); RoundEnvironment roundEnv);
@ -381,7 +381,7 @@ public interface Processor {
* *
* (A Mersenne prime is prime number of the form * (A Mersenne prime is prime number of the form
* 2<sup><i>n</i></sup> - 1.) Given an {@code AnnotationMirror} * 2<sup><i>n</i></sup> - 1.) Given an {@code AnnotationMirror}
* for this annotation type, a list of all such primes in the * for this annotation interface, a list of all such primes in the
* {@code int} range could be returned without examining any other * {@code int} range could be returned without examining any other
* arguments to {@code getCompletions}: * arguments to {@code getCompletions}:
* *

6
src/java.compiler/share/classes/javax/annotation/processing/SupportedAnnotationTypes.java
View File

@ -30,8 +30,8 @@ import static java.lang.annotation.RetentionPolicy.*;
import static java.lang.annotation.ElementType.*; import static java.lang.annotation.ElementType.*;
/** /**
* An annotation used to indicate what annotation types an annotation * An annotation used to indicate what annotation interfaces an
* processor supports. The {@link * annotation processor supports. The {@link
* Processor#getSupportedAnnotationTypes} method can construct its * Processor#getSupportedAnnotationTypes} method can construct its
* result from the value of this annotation, as done by {@link * result from the value of this annotation, as done by {@link
* AbstractProcessor#getSupportedAnnotationTypes}. Only {@linkplain * AbstractProcessor#getSupportedAnnotationTypes}. Only {@linkplain
@ -48,7 +48,7 @@ import static java.lang.annotation.ElementType.*;
@Retention(RUNTIME) @Retention(RUNTIME)
public @interface SupportedAnnotationTypes { public @interface SupportedAnnotationTypes {
/** /**
* {@return the names of the supported annotation types} * {@return the names of the supported annotation interfaces}
*/ */
String [] value(); String [] value();
} }

2
src/java.compiler/share/classes/javax/lang/model/element/AnnotationMirror.java
View File

@ -30,7 +30,7 @@ import javax.lang.model.type.DeclaredType;
/** /**
* Represents an annotation. An annotation associates a value with * Represents an annotation. An annotation associates a value with
* each element of an annotation type. * each element of an annotation interface.
* *
* <p> Annotations should be compared using the {@code equals} * <p> Annotations should be compared using the {@code equals}
* method. There is no guarantee that any particular annotation will * method. There is no guarantee that any particular annotation will

2
src/java.compiler/share/classes/javax/lang/model/element/AnnotationValue.java
View File

@ -26,7 +26,7 @@
package javax.lang.model.element; package javax.lang.model.element;
/** /**
* Represents a value of an annotation type element. * Represents a value of an annotation interface element.
* A value is of one of the following types: * A value is of one of the following types:
* <ul><li> a wrapper class (such as {@link Integer}) for a primitive type * <ul><li> a wrapper class (such as {@link Integer}) for a primitive type
* <li> {@code String} * <li> {@code String}

2
src/java.compiler/share/classes/javax/lang/model/element/AnnotationValueVisitor.java
View File

@ -31,7 +31,7 @@ import javax.lang.model.type.TypeMirror;
import javax.lang.model.util.*; import javax.lang.model.util.*;
/** /**
* A visitor of the values of annotation type elements, using a * A visitor of the values of annotation interface elements, using a
* variant of the visitor design pattern. Unlike a standard visitor * variant of the visitor design pattern. Unlike a standard visitor
* which dispatches based on the concrete type of a member of a type * which dispatches based on the concrete type of a member of a type
* hierarchy, this visitor dispatches based on the type of data * hierarchy, this visitor dispatches based on the type of data

14
src/java.compiler/share/classes/javax/lang/model/element/Element.java
View File

@ -126,11 +126,11 @@ public interface Element extends javax.lang.model.AnnotatedConstruct {
/** /**
* {@return the simple (unqualified) name of this element} The * {@return the simple (unqualified) name of this element} The
* name of a generic type does not include any reference to its * name of a generic class or interface does not include any
* formal type parameters. * reference to its formal type parameters.
* *
* For example, the simple name of the type element {@code * For example, the simple name of the type element representing
* java.util.Set<E>} is {@code "Set"}. * {@code java.util.Set<E>} is {@code "Set"}.
* *
* If this element represents an unnamed {@linkplain * If this element represents an unnamed {@linkplain
* PackageElement#getSimpleName package} or unnamed {@linkplain * PackageElement#getSimpleName package} or unnamed {@linkplain
@ -166,7 +166,7 @@ public interface Element extends javax.lang.model.AnnotatedConstruct {
* element is returned. * element is returned.
* *
* <li> If this is a {@linkplain TypeElement#getEnclosingElement * <li> If this is a {@linkplain TypeElement#getEnclosingElement
* top-level type}, its package is returned. * top-level class or interface}, its package is returned.
* *
* <li> If this is a {@linkplain * <li> If this is a {@linkplain
* PackageElement#getEnclosingElement package}, its module is * PackageElement#getEnclosingElement package}, its module is
@ -184,7 +184,7 @@ public interface Element extends javax.lang.model.AnnotatedConstruct {
* *
* <li> If this is a {@linkplain * <li> If this is a {@linkplain
* RecordComponentElement#getEnclosingElement record component}, * RecordComponentElement#getEnclosingElement record component},
* {@linkplain TypeElement the type} which declares the * {@linkplain TypeElement the record class} which declares the
* record component is returned. * record component is returned.
* *
* <li> If this is a {@linkplain ModuleElement#getEnclosingElement * <li> If this is a {@linkplain ModuleElement#getEnclosingElement
@ -204,7 +204,7 @@ public interface Element extends javax.lang.model.AnnotatedConstruct {
* *
* A {@linkplain TypeElement#getEnclosedElements class or * A {@linkplain TypeElement#getEnclosedElements class or
* interface} is considered to enclose the fields, methods, * interface} is considered to enclose the fields, methods,
* constructors, record components, and member types that it directly declares. * constructors, record components, and member classes and interfaces that it directly declares.
* *
* A {@linkplain PackageElement#getEnclosedElements package} * A {@linkplain PackageElement#getEnclosedElements package}
* encloses the top-level classes and interfaces within it, but is * encloses the top-level classes and interfaces within it, but is

8
src/java.compiler/share/classes/javax/lang/model/element/ElementKind.java
View File

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 2005, 2020, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -44,7 +44,7 @@ public enum ElementKind {
PACKAGE, PACKAGE,
// Declared types // Declared types
/** An enum type. */ /** An enum class. */
ENUM, ENUM,
/** /**
* A class not described by a more specific kind (like {@code * A class not described by a more specific kind (like {@code
@ -52,7 +52,7 @@ public enum ElementKind {
*/ */
CLASS, CLASS,
/** An annotation type. */ /** An annotation interface. (Formerly known as an annotation type.) */
ANNOTATION_TYPE, ANNOTATION_TYPE,
/** /**
* An interface not described by a more specific kind (like * An interface not described by a more specific kind (like
@ -109,7 +109,7 @@ public enum ElementKind {
MODULE, MODULE,
/** /**
* A record type. * A record class.
* @since 16 * @since 16
*/ */
RECORD, RECORD,

6
src/java.compiler/share/classes/javax/lang/model/element/ExecutableElement.java
View File

@ -123,9 +123,9 @@ public interface ExecutableElement extends Element, Parameterizable {
/** /**
* Returns the default value if this executable is an annotation * Returns the default value if this executable is an annotation
* type element. Returns {@code null} if this method is not an * interface element. Returns {@code null} if this method is not
* annotation type element, or if it is an annotation type element * an annotation interface element, or if it is an annotation
* with no default value. * interface element with no default value.
* *
* @return the default value, or {@code null} if none * @return the default value, or {@code null} if none
*/ */

13
src/java.compiler/share/classes/javax/lang/model/element/NestingKind.java
View File

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 2005, 2020, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -83,24 +83,27 @@ package javax.lang.model.element;
*/ */
public enum NestingKind { public enum NestingKind {
/** /**
* A top-level type, not contained within another type. * A top-level class or interface, not contained within another
* class or interface.
*/ */
TOP_LEVEL, TOP_LEVEL,
/** /**
* A type that is a named member of another type. * A class or interface that is a named member of another class or
* interface.
* @jls 8.5 Member Type Declarations * @jls 8.5 Member Type Declarations
*/ */
MEMBER, MEMBER,
/** /**
* A named type declared within a construct other than a type. * A named class or interface declared within a construct other
* than a class or interface.
* @jls 14.3 Local Class Declarations * @jls 14.3 Local Class Declarations
*/ */
LOCAL, LOCAL,
/** /**
* A type without a name. * A class without a name.
* @jls 15.9.5 Anonymous Class Declarations * @jls 15.9.5 Anonymous Class Declarations
*/ */
ANONYMOUS; ANONYMOUS;

2
src/java.compiler/share/classes/javax/lang/model/element/RecordComponentElement.java
View File

@ -34,7 +34,7 @@ public interface RecordComponentElement extends Element {
/** /**
* {@return the enclosing element of this record component} * {@return the enclosing element of this record component}
* *
* The enclosing element of a record component is the type * The enclosing element of a record component is the record class
* declaring the record component. * declaring the record component.
*/ */
@Override @Override

71
src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java
View File

@ -31,8 +31,9 @@ import javax.lang.model.util.*;
/** /**
* Represents a class or interface program element. Provides access * Represents a class or interface program element. Provides access
* to information about the type and its members. Note that an enum * to information about the class or interface and its members. Note
* type and a record type are kinds of classes and an annotation type is a kind of * that an enum class and a record class are specialized kinds of
* classes and an annotation interface is a specialized kind of
* interface. * interface.
* *
* <p> While a {@code TypeElement} represents a class or interface * <p> While a {@code TypeElement} represents a class or interface
@ -60,8 +61,9 @@ import javax.lang.model.util.*;
*/ */
public interface TypeElement extends Element, Parameterizable, QualifiedNameable { public interface TypeElement extends Element, Parameterizable, QualifiedNameable {
/** /**
* Returns the type defined by this type element, returning the * Returns the type defined by this class or interface element,
* <i>prototypical</i> type for an element representing a generic type. * 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. * <p>A generic element defines a family of types, not just one.
* If this is a generic element, a prototypical type is * If this is a generic element, a prototypical type is
@ -83,24 +85,24 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
/** /**
* Returns the fields, methods, constructors, record components, * Returns the fields, methods, constructors, record components,
* and member types that are directly declared in this class or * and member classes and interfaces that are directly declared in
* interface. * this class or interface.
* *
* This includes any {@linkplain Elements.Origin#MANDATED * This includes any {@linkplain Elements.Origin#MANDATED
* mandated} elements such as the (implicit) default constructor * mandated} elements such as the (implicit) default constructor
* and the implicit {@code values} and {@code valueOf} methods of * and the implicit {@code values} and {@code valueOf} methods of
* an enum type. * an enum class.
* *
* @apiNote As a particular instance of the {@linkplain * @apiNote As a particular instance of the {@linkplain
* javax.lang.model.element general accuracy requirements} and the * javax.lang.model.element general accuracy requirements} and the
* ordering behavior required of this interface, the list of * ordering behavior required of this interface, the list of
* enclosed elements will be returned in the natural order for the * enclosed elements will be returned in the natural order for the
* originating source of information about the type. For example, * originating source of information about the class or interface.
* if the information about the type is originating from a source * For example, if the information about the class or interface is
* file, the elements will be returned in source code order. * originating from a source file, the elements will be returned
* (However, in that case the ordering of {@linkplain * in source code order. (However, in that case the ordering of
* Elements.Origin#MANDATED implicitly declared} elements, such as * {@linkplain Elements.Origin#MANDATED implicitly declared}
* default constructors, is not specified.) * elements, such as default constructors, is not specified.)
* *
* @return the enclosed elements in proper order, or an empty list if none * @return the enclosed elements in proper order, or an empty list if none
* *
@ -111,23 +113,24 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
List<? extends Element> getEnclosedElements(); List<? extends Element> getEnclosedElements();
/** /**
* Returns the <i>nesting kind</i> of this type element. * Returns the <i>nesting kind</i> of this class or interface element.
* *
* @return the nesting kind of this type element * @return the nesting kind of this class or interface element
*/ */
NestingKind getNestingKind(); NestingKind getNestingKind();
/** /**
* Returns the fully qualified name of this type element. More * Returns the fully qualified name of this class or interface
* precisely, it returns the <i>canonical</i> name. For local and * element. More precisely, it returns the <i>canonical</i> name.
* anonymous classes, which do not have canonical names, an <a * For local and anonymous classes, which do not have canonical
* href=Name.html#empty_name>empty name</a> is returned. * names, an <a href=Name.html#empty_name>empty name</a> is
* returned.
* *
* <p>The name of a generic type does not include any reference * <p>The name of a generic class or interface does not include any reference
* to its formal type parameters. * to its formal type parameters.
* For example, the fully qualified name of the interface * For example, the fully qualified name of the interface
* {@code java.util.Set<E>} is "{@code java.util.Set}". * {@code java.util.Set<E>} is "{@code java.util.Set}".
* Nested types use "{@code .}" as a separator, as in * Nested classes and interfaces use "{@code .}" as a separator, as in
* "{@code java.util.Map.Entry}". * "{@code java.util.Map.Entry}".
* *
* @return the fully qualified name of this class or interface, or * @return the fully qualified name of this class or interface, or
@ -139,7 +142,7 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
Name getQualifiedName(); Name getQualifiedName();
/** /**
* Returns the simple name of this type element. * Returns the simple name of this class or interface element.
* *
* For an anonymous class, an <a href=Name.html#empty_name> empty * For an anonymous class, an <a href=Name.html#empty_name> empty
* name</a> is returned. * name</a> is returned.
@ -152,8 +155,8 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
Name getSimpleName(); Name getSimpleName();
/** /**
* Returns the direct superclass of this type element. * Returns the direct superclass of this class or interface element.
* If this type element represents an interface or the class * If this class or interface element represents an interface or the class
* {@code java.lang.Object}, then a {@link NoType} * {@code java.lang.Object}, then a {@link NoType}
* with kind {@link TypeKind#NONE NONE} is returned. * with kind {@link TypeKind#NONE NONE} is returned.
* *
@ -171,7 +174,7 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
List<? extends TypeMirror> getInterfaces(); List<? extends TypeMirror> getInterfaces();
/** /**
* Returns the formal type parameters of this type element * Returns the formal type parameters of this class or interface element
* in declaration order. * in declaration order.
* *
* @return the formal type parameters, or an empty list * @return the formal type parameters, or an empty list
@ -180,8 +183,8 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
List<? extends TypeParameterElement> getTypeParameters(); List<? extends TypeParameterElement> getTypeParameters();
/** /**
* Returns the record components of this type element in * Returns the record components of this class or interface
* declaration order. * element in declaration order.
* *
* @implSpec The default implementations of this method returns an * @implSpec The default implementations of this method returns an
* empty and unmodifiable list. * empty and unmodifiable list.
@ -202,8 +205,8 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
* feature of the Java language. Preview features * feature of the Java language. Preview features
* may be removed in a future release, or upgraded to permanent * may be removed in a future release, or upgraded to permanent
* features of the Java language.} * features of the Java language.}
* Returns the permitted classes of this type element in * Returns the permitted classes of this class or interface
* declaration order. * element in declaration order.
* *
* @implSpec The default implementations of this method returns an * @implSpec The default implementations of this method returns an
* empty and unmodifiable list. * empty and unmodifiable list.
@ -219,12 +222,12 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
} }
/** /**
* Returns the package of a top-level type and returns the * Returns the package of a top-level class or interface and
* immediately lexically enclosing element for a {@linkplain * returns the immediately lexically enclosing element for a
* NestingKind#isNested nested} type. * {@linkplain NestingKind#isNested nested} class or interface.
* *
* @return the package of a top-level type, the immediately * @return the package of a top-level class or interface, the immediately
* lexically enclosing element for a nested type * lexically enclosing element for a nested class or interface
*/ */
@Override @Override
Element getEnclosingElement(); Element getEnclosingElement();

32
src/java.compiler/share/classes/javax/lang/model/element/package-info.java
View File

@ -50,7 +50,9 @@
* recovered from class files and class files might not be able to * recovered from class files and class files might not be able to
* provide source position information. * provide source position information.
* *
* Names of {@linkplain javax.lang.model.element.ExecutableElement#getParameters() parameters} may not be recoverable from class files. * Names of {@linkplain
* javax.lang.model.element.ExecutableElement#getParameters()
* parameters} may not be recoverable from class files.
* *
* The {@linkplain javax.lang.model.element.Modifier modifiers} on an * The {@linkplain javax.lang.model.element.Modifier modifiers} on an
* element created from a class file may differ in some cases from an * element created from a class file may differ in some cases from an
@ -82,20 +84,20 @@
* guarantees about the nature of the resulting model. If the source * guarantees about the nature of the resulting model. If the source
* code is not syntactically well-formed or has some other * code is not syntactically well-formed or has some other
* irrecoverable error that could not be removed by the generation of * irrecoverable error that could not be removed by the generation of
* new types, a model may or may not be provided as a quality of * new classes or interfaces, a model may or may not be provided as a
* implementation issue. * quality of implementation issue. If a program is syntactically
* If a program is syntactically valid but erroneous in some other * valid but erroneous in some other fashion, any returned model must
* fashion, any returned model must have no less information than if * have no less information than if all the method bodies in the
* all the method bodies in the program were replaced by {@code "throw * program were replaced by {@code "throw new RuntimeException();"}.
* new RuntimeException();"}. If a program refers to a missing type Xyz, * If a program refers to a missing class or interface Xyz, the
* the returned model must contain no less information than if the * returned model must contain no less information than if the
* declaration of type Xyz were assumed to be {@code "class Xyz {}"}, * declaration of class or interface Xyz were assumed to be {@code
* {@code "interface Xyz {}"}, {@code "enum Xyz {}"}, {@code * "class Xyz {}"}, {@code "interface Xyz {}"}, {@code "enum Xyz {}"},
* "@interface Xyz {}"}, or {@code "record Xyz {}"}. If a program refers to a missing type {@code * {@code "@interface Xyz {}"}, or {@code "record Xyz {}"}. If a
* Xyz<K1, ... ,Kn>}, the returned model must contain no less * program refers to a missing class or interface {@code Xyz<K1,
* information than if the declaration of Xyz were assumed to be * ... ,Kn>}, the returned model must contain no less information than
* {@code "class Xyz<T1, ... ,Tn> {}"} or {@code "interface Xyz<T1, * if the declaration of Xyz were assumed to be {@code "class Xyz<T1,
* ... ,Tn> {}"} * ... ,Tn> {}"} or {@code "interface Xyz<T1, ... ,Tn> {}"}
* *
* <p> Unless otherwise specified in a particular implementation, the * <p> Unless otherwise specified in a particular implementation, the
* collections returned by methods in this package should be expected * collections returned by methods in this package should be expected

2
src/java.compiler/share/classes/javax/lang/model/util/ElementFilter.java
View File

@ -166,7 +166,7 @@ public class ElementFilter {
} }
/** /**
* {@return a list of types in {@code elements}} * {@return a list of classes and interfaces in {@code elements}}
* @param elements the elements to filter * @param elements the elements to filter
*/ */
public static List<TypeElement> public static List<TypeElement>

16
src/java.compiler/share/classes/javax/lang/model/util/Elements.java
View File

@ -336,7 +336,7 @@ public interface Elements {
* An annotation mirror is {@linkplain Origin#MANDATED mandated} * An annotation mirror is {@linkplain Origin#MANDATED mandated}
* if it is an implicitly declared <em>container annotation</em> * if it is an implicitly declared <em>container annotation</em>
* used to hold repeated annotations of a repeatable annotation * used to hold repeated annotations of a repeatable annotation
* type. * interface.
* *
* <p>Note that if this method returns {@link Origin#EXPLICIT * <p>Note that if this method returns {@link Origin#EXPLICIT
* EXPLICIT} and the annotation mirror was created from a class * EXPLICIT} and the annotation mirror was created from a class
@ -423,7 +423,7 @@ public interface Elements {
* *
* Another example of a mandated construct is an implicitly * Another example of a mandated construct is an implicitly
* declared <em>container annotation</em> used to hold * declared <em>container annotation</em> used to hold
* multiple annotations of a repeatable annotation type. * multiple annotations of a repeatable annotation interface.
* *
* @jls 8.8.9 Default Constructor * @jls 8.8.9 Default Constructor
* @jls 8.9.3 Enum Members * @jls 8.9.3 Enum Members
@ -480,7 +480,7 @@ public interface Elements {
* itself. * itself.
* The package of a module is {@code null}. * The package of a module is {@code null}.
* *
* The package of a top-level type is its {@linkplain * The package of a top-level class or interface is its {@linkplain
* TypeElement#getEnclosingElement enclosing package}. Otherwise, * TypeElement#getEnclosingElement enclosing package}. Otherwise,
* the package of an element is equal to the package of the * the package of an element is equal to the package of the
* {@linkplain Element#getEnclosingElement enclosing element}. * {@linkplain Element#getEnclosingElement enclosing element}.
@ -559,7 +559,7 @@ public interface Elements {
boolean hides(Element hider, Element hidden); boolean hides(Element hider, Element hidden);
/** /**
* Tests whether one method, as a member of a given type, * Tests whether one method, as a member of a given class or interface,
* overrides another method. * overrides another method.
* When a non-abstract method overrides an abstract one, the * When a non-abstract method overrides an abstract one, the
* former is also said to <i>implement</i> the latter. * former is also said to <i>implement</i> the latter.
@ -578,8 +578,8 @@ public interface Elements {
* </blockquote> * </blockquote>
* *
* A more interesting case can be illustrated by the following example * A more interesting case can be illustrated by the following example
* in which a method in type {@code A} does not override a * in which a method in class {@code A} does not override a
* like-named method in type {@code B}: * like-named method in interface {@code B}:
* *
* <blockquote> * <blockquote>
* {@code class A { public void m() {} } }<br> * {@code class A { public void m() {} } }<br>
@ -591,7 +591,7 @@ public interface Elements {
* elements.getTypeElement("A")); } * elements.getTypeElement("A")); }
* </blockquote> * </blockquote>
* *
* When viewed as a member of a third type {@code C}, however, * When viewed as a member of a third class {@code C}, however,
* the method in {@code A} does override the one in {@code B}: * the method in {@code A} does override the one in {@code B}:
* *
* <blockquote> * <blockquote>
@ -603,7 +603,7 @@ public interface Elements {
* *
* @param overrider the first method, possible overrider * @param overrider the first method, possible overrider
* @param overridden the second method, possibly being overridden * @param overridden the second method, possibly being overridden
* @param type the type of which the first method is a member * @param type the class or interface of which the first method is a member
* @return {@code true} if and only if the first method overrides * @return {@code true} if and only if the first method overrides
* the second * the second
* @jls 8.4.8 Inheritance, Overriding, and Hiding * @jls 8.4.8 Inheritance, Overriding, and Hiding