In general, processors must not knowingly attempt to overwrite @@ -111,10 +112,10 @@ * to overwrite existing files that were not generated. * *
Processors can indicate a source or class file is generated by - * including an {@link javax.annotation.Generated @Generated} - * annotation. + * including a {@code javax.annotation.Generated} annotation if the + * environment is configured so that that type is accessible. * - *
Note that 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 decorator-style pattern. Instead of * modifying a class directly, the class is designed so that either * its superclass is generated by annotation processing or subclasses @@ -131,18 +132,39 @@ public interface Filer { /** * Creates a new source file and returns an object to allow - * writing to it. The file's name and path (relative to the - * {@linkplain StandardLocation#SOURCE_OUTPUT root output location - * for source files}) are based on the type to be declared in that - * file. If more than one type is being declared, the name of the - * principal top-level type (the public one, for example) should - * be used. A source file can also be created to hold information - * about a package, including package annotations. To create a - * source file for a named package, have {@code name} be the + * writing to it. A source file for a type, a package, or a module + * can be created. + * + * The file's name and path (relative to the {@linkplain + * StandardLocation#SOURCE_OUTPUT root output location for source + * files}) are based on the name of the item to be declared in + * that file as well as the specified module for the item (if + * any). + * + * If more than one type is being declared in a single file (that + * is, a single compilation unit), the name of the file should + * correspond to the name of the principal top-level type (the + * public one, for example). + * + *
A source file can also be created to hold information about + * a package, including package annotations. To create a source + * file for a named package, have the {@code name} argument be the * package's name followed by {@code ".package-info"}; to create a * source file for an unnamed package, use {@code "package-info"}. * - *
Note that to use a particular {@linkplain + *
The optional module name is prefixed to the type name or + * package name and separated using a "{@code /}" character. For + * example, to create a source file for type {@code a.B} in module + * {@code foo}, use a {@code name} argument of {@code "foo/a.B"}. + * + * To create a source file for a named module, have {@code name} + * be the modules's name followed by {@code "/module-info"} + * + *
Creating a source file for an unnamed package in a named + * module is not supported. Creating a source file for an + * unnamed module is not supported. + * + * @apiNote To use a particular {@linkplain * java.nio.charset.Charset charset} to encode the contents of the * file, an {@code OutputStreamWriter} with the chosen charset can * be created from the {@code OutputStream} from the returned @@ -161,37 +183,58 @@ * @param name canonical (fully qualified) name of the principal type * being declared in this file or a package name followed by * {@code ".package-info"} for a package information file - * @param originatingElements type or package elements causally + * or a module name followed by {@code "/module-info"} + * for a module information file + * @param originatingElements type or package or module elements causally * associated with the creation of this file, may be elided or * {@code null} * @return a {@code JavaFileObject} to write the new source file * @throws FilerException if the same pathname has already been * created, the same type has already been created, or the name is - * not valid for a type + * otherwise not valid for the entity requested to being created * @throws IOException if the file cannot be created + * @jls 7.3 Compilation Units */ JavaFileObject createSourceFile(CharSequence name, Element... originatingElements) throws IOException; /** * Creates a new class file, and returns an object to allow - * writing to it. The file's name and path (relative to the - * {@linkplain StandardLocation#CLASS_OUTPUT root output location - * for class files}) are based on the name of the type being - * written. A class file can also be created to hold information - * about a package, including package annotations. To create a - * class file for a named package, have {@code name} be the + * writing to it. A class file for a type, a package, or a module + * can be created. + * + * The file's name and path (relative to the {@linkplain + * StandardLocation#CLASS_OUTPUT root output location for class + * files}) are based on the name of the item to be declared as + * well as the specified module for the item (if any). + * + *
A class file can also be created to hold information about a + * package, including package annotations. To create a class file + * for a named package, have the {@code name} argument be the * package's name followed by {@code ".package-info"}; creating a * class file for an unnamed package is not supported. * - *
To avoid subsequent errors, the contents of the class file - * should be compatible with the {@linkplain - * ProcessingEnvironment#getSourceVersion source version} being used - * for this run. + *
The optional module name is prefixed to the type name or + * package name and separated using a "{@code /}" character. For + * example, to create a class file for type {@code a.B} in module + * {@code foo}, use a {@code name} argument of {@code "foo/a.B"}. + * + * To create a class file for a named module, have {@code name} + * be the modules's name followed by {@code "/module-info"} + * + *
Creating a class file for an unnamed package in a named + * module is not supported. Creating a class file for an + * unnamed module is not supported. + * + * @apiNote To avoid subsequent errors, the contents of the class + * file should be compatible with the {@linkplain + * ProcessingEnvironment#getSourceVersion source version} being + * used for this run. * * @param name binary name of the type being written or a package name followed by - * {@code ".package-info"} for a package information file - * @param originatingElements type or package elements causally + * {@code ".package-info"} for a package information file or a + * module name followed by {@code "/module-info"} for a module information file + * @param originatingElements type or package or 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 @@ -210,20 +253,28 @@ * other supported location. The locations {@link * StandardLocation#CLASS_OUTPUT CLASS_OUTPUT} and {@link * StandardLocation#SOURCE_OUTPUT SOURCE_OUTPUT} must be - * supported. The resource may be named relative to some package - * (as are source and class files), and from there by a relative - * pathname. In a loose sense, the full pathname of the new file - * will be the concatenation of {@code location}, {@code pkg}, and - * {@code relativeName}. + * supported. The resource may be named relative to some module + * and/or package (as are source and class files), and from there + * by a relative pathname. In a loose sense, the full pathname of + * the new file will be the concatenation of {@code location}, + * {@code moduleAndPkg}, and {@code relativeName}. * - *
Files created via this method are not registered for + * If {@code moduleAndPkg} contains a "{@code /}" character, the + * prefix before the "{@code /}" character is the module name and + * the suffix after the "{@code /}" character is the package + * name. The package suffix may be empty; however, if a module + * name is present, it must be nonempty. If {@code moduleAndPkg} + * does not contain a "{@code /}" character, the entire argument + * is interpreted as a package name. + * + *
Files created via this method are not registered for * annotation processing, even if the full pathname of the file * would correspond to the full pathname of a new source file * or new class file. * * @param location location of the new file - * @param pkg package relative to which the file should be named, - * or the empty string if none + * @param moduleAndPkg module and/or package relative to which the file + * should be named, or the empty string if none * @param relativeName final pathname components of the file * @param originatingElements type or package elements causally * associated with the creation of this file, may be elided or @@ -233,10 +284,11 @@ * @throws FilerException if the same pathname has already been * created * @throws IllegalArgumentException for an unsupported location + * @throws IllegalArgumentException if {@code moduleAndPkg} is ill-formed * @throws IllegalArgumentException if {@code relativeName} is not relative */ FileObject createResource(JavaFileManager.Location location, - CharSequence pkg, + CharSequence moduleAndPkg, CharSequence relativeName, Element... originatingElements) throws IOException; @@ -246,18 +298,27 @@ * and {@link StandardLocation#SOURCE_OUTPUT SOURCE_OUTPUT} must * be supported. * + *
If {@code moduleAndPkg} contains a "{@code /}" character, the + * prefix before the "{@code /}" character is the module name and + * the suffix after the "{@code /}" character is the package + * name. The package suffix may be empty; however, if a module + * name is present, it must be nonempty. If {@code moduleAndPkg} + * does not contain a "{@code /}" character, the entire argument + * is interpreted as a package name. + * * @param location location of the file - * @param pkg package relative to which the file should be searched, - * or the empty string if none + * @param moduleAndPkg module and/or package relative to which the file + * should be searched for, or the empty string if none * @param relativeName final pathname components of the file * @return an object to read the file * @throws FilerException if the same pathname has already been * opened for writing * @throws IOException if the file cannot be opened * @throws IllegalArgumentException for an unsupported location + * @throws IllegalArgumentException if {@code moduleAndPkg} is ill-formed * @throws IllegalArgumentException if {@code relativeName} is not relative */ FileObject getResource(JavaFileManager.Location location, - CharSequence pkg, + CharSequence moduleAndPkg, CharSequence relativeName) throws IOException; } --- old/src/java.compiler/share/classes/javax/annotation/processing/Processor.java 2016-08-19 15:50:16.304257428 -0700 +++ new/src/java.compiler/share/classes/javax/annotation/processing/Processor.java 2016-08-19 15:50:16.208257425 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2005, 2016, 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 @@ -115,7 +115,17 @@ * the root elements of a round. For this purpose, a type parameter is * considered to be enclosed by its {@linkplain * TypeParameterElement#getGenericElement generic - * element}. Annotations on {@linkplain + * element}. + + * For this purpose, a package element is not considered to + * enclose the top-level types within that package. (A root element + * representing a package is created when a {@code package-info} file + * is processed.) Likewise, for this purpose, a module element is + * not considered to enclose the packages within that + * module. (A root element representing a module is created when a + * {@code module-info} file is processed.) + * + * Annotations on {@linkplain * java.lang.annotation.ElementType#TYPE_USE type uses}, as opposed to * annotations on elements, are ignored when computing whether or not * an annotation type is present. @@ -235,12 +245,20 @@ * (fully qualified) name of a supported annotation type. * Alternately it may be of the form "name.*" * representing the set of all annotation types with canonical - * names beginning with "name.". Finally, {@code - * "*"} by itself represents the set of all annotation types, - * including the empty set. Note that a processor should not - * claim {@code "*"} unless it is actually processing all files; - * claiming unnecessary annotations may cause a performance - * slowdown in some environments. + * names beginning with "name.". + * + * In either of those cases, the name of the annotation type can + * be optionally preceded by a module name followed by a {@code + * "/"} character. For example, if a processor supports {@code + * "a.B"}, this can include multiple annotation types named {@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"}. + * + * Finally, {@code "*"} by itself represents the set of all + * annotation types, including the empty set. Note that a + * processor should not claim {@code "*"} unless it is actually + * processing all files; claiming unnecessary annotations may + * cause a performance slowdown in some environments. * *
Each string returned in the set must be accepted by the * following grammar: @@ -248,9 +266,12 @@ *
**
--- old/src/java.compiler/share/classes/javax/annotation/processing/RoundEnvironment.java 2016-08-19 15:50:16.596257438 -0700 +++ new/src/java.compiler/share/classes/javax/annotation/processing/RoundEnvironment.java 2016-08-19 15:50:16.504257435 -0700 @@ -76,14 +76,17 @@ /** * Returns the elements annotated with the given annotation type. * The annotation may appear directly or be inherited. Only - * package elements and type elements included in this + * package elements, module elements, and type elements included in this * round of annotation processing, or declarations of members, * constructors, parameters, or type parameters declared within * those, are returned. Included type elements are {@linkplain * #getRootElements root types} and any member types nested within - * them. Elements in a package are not considered included simply + * them. Elements of a package are not considered included simply * because a {@code package-info} file for that package was * created. + * Likewise, elements of a module are not considered included + * simply because a {@code module-info} file for that module was + * created * * @param a annotation type being requested * @return the elements annotated with the given annotation type, @@ -128,7 +131,7 @@ /** * Returns the elements annotated with the given annotation type. * The annotation may appear directly or be inherited. Only - * package elements and type elements included in this + * package elements, module elements, and type elements included in this * round of annotation processing, or declarations of members, * constructors, parameters, or type parameters declared within * those, are returned. Included type elements are {@linkplain @@ -136,6 +139,9 @@ * them. Elements in a package are not considered included simply * because a {@code package-info} file for that package was * created. + * Likewise, elements of a module are not considered included + * simply because a {@code module-info} file for that module was + * created * * @param a annotation type being requested * @return the elements annotated with the given annotation type, --- old/src/java.compiler/share/classes/javax/lang/model/element/package-info.java 2016-08-19 15:50:16.876257448 -0700 +++ new/src/java.compiler/share/classes/javax/lang/model/element/package-info.java 2016-08-19 15:50:16.792257445 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2005, 2016, 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 @@ -53,7 +53,9 @@ * Names of parameters may not be recoverable from class files. * * The {@linkplain javax.lang.model.element.Modifier modifiers} on an - * element may differ in some cases including: + * element created from a class file may differ in some cases from an + * element for the same declaration created from a source file + * including: * *- SupportedAnnotationTypeString: - *
- TypeName DotStaropt + *
- ModulePrefixopt TypeName DotStaropt *
- * * + *
- ModulePrefix: + *
- TypeName / + * *
- DotStar: *
- . * *
*
* - * Additionally, synthetic constructs in a class file, such as - * accessor methods used in implementing nested classes and bridge - * methods used in implementing covariant returns, are translation - * artifacts outside of this model. + * Some elements which are {@linkplain Elements.Naturalness#MANDATED + * mandated} may not be marked as such when created from class files. + * + * Additionally, {@linkplain Elements.Naturalness#SYNTHETIC synthetic} + * constructs in a class file, such as accessor methods used in + * implementing nested classes and {@linkplain + * Elements#isBridge(Element) bridge methods} used in implementing + * covariant returns, are translation artifacts strictly outside of + * this model. However, when operation on class files, it is helpful + * be able to operate on such elements, screening them out when + * appropriate. * *- {@code strictfp} on a class or interface @@ -61,10 +63,17 @@ *
- {@code protected}, {@code private}, and {@code static} on classes and interfaces *
During annotation processing, operating on incomplete or * erroneous programs is necessary; however, there are fewer --- old/src/java.compiler/share/classes/javax/lang/model/util/Elements.java 2016-08-19 15:50:17.164257458 -0700 +++ new/src/java.compiler/share/classes/javax/lang/model/util/Elements.java 2016-08-19 15:50:17.076257455 -0700 @@ -29,6 +29,7 @@ import java.util.List; import java.util.Map; +import javax.lang.model.AnnotatedConstruct; import javax.lang.model.element.*; @@ -136,6 +137,117 @@ boolean isDeprecated(Element e); /** + * Returns the naturalness of the given element. + * + * @implSpec The default implementation of this method returns + * {@link Naturalness#NATURAL NATURAL}. + * + * @param e the element being examined + * @return the naturalness of the given element + * @since 9 + */ + default Naturalness getNaturalness(Element e) { + return Naturalness.NATURAL; + } + + /** + * Returns the naturalness of the given annotation mirror. + * + * One example of a mandated construct is the + * implicitly declared container annotation used to hold + * repeated base annotations of a repeatable annotation type. + * + * @implSpec The default implementation of this method returns + * {@link Naturalness#NATURAL NATURAL}. + * + * @param c the construct the annotation mirror modifies + * @param a the annotation mirror being examined + * @return the naturalness of the given annotation mirror + * @jls 9.6.3 Repeatable Annotation Types + * @jls 9.7.5 Multiple Annotations of the Same Type + * @since 9 + */ + default Naturalness getNaturalness(AnnotatedConstruct c, AnnotationMirror a) { + return Naturalness.NATURAL; + } + + /** + * Returns the naturalness of the given module directive. + * + * @implSpec The default implementation of this method returns + * {@link Naturalness#NATURAL NATURAL}. + * + * @param m the module of the directive + * @param directive the module directive being examined + * @return the naturalness of the given directive + * @since 9 + */ + default Naturalness getNaturalness(ModuleElement m, ModuleElement.Directive directive) { + return Naturalness.NATURAL; + } + + /** + * The naturalness of a construct. The naturalness of a + * construct concerns the consistency between how a construct is + * declared in source code (explicitly, implicitly, or not at all) + * compared to how the construct is represented in this model. + * + * Note that it is possible additional kinds of naturalness will + * be added in future versions of the platform. + * + * @jls 13.1 The Form of a Binary + * @since 9 + */ + enum Naturalness { + /** + * A natural construct is explicitly declared in source code. + */ + NATURAL, + + /** + * A mandated construct is one not explicitly declared in the + * source code, but whose presence is mandated by the + * specification; such a construct is said to be implicitly declared. + * + * One example of a mandated element is a default + * constructor in a class that contains no explicit + * constructor declarations. + * + * Another example of a mandated construct is the implicitly + * declared container annotation used to hold + * multiple annotations of a repeatable annotation type. + * + * @jls 8.8.9 Default Constructor + * @jls 9.6.3 Repeatable Annotation Types + * @jls 9.7.5 Multiple Annotations of the Same Type + */ + MANDATED, + + /** + * A synthetic construct is one that is neither implicitly nor + * explicitly declared in the source code. Synthetic + * constructs are commonly translation artifacts created by + * compiler. + */ + SYNTHETIC; + } + + /** + * Returns {@code true} if the executable element is a bridge + * method, {@code false} otherwise. + * + * @implSpec The default implementation of this method returns {@code false}. + * + * @param e the executable being examined + * @return {@code true} if the executable element is a bridge + * method, {@code false} otherwise + * @since 9 + */ + default boolean isBridge(ExecutableElement e) { + return false; + } + + /** * Returns the binary name of a type element. * * @param type the type element being examined