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; }