--- a/langtools/src/java.compiler/share/classes/javax/annotation/processing/Filer.java Tue Dec 13 10:48:18 2016 +0100
+++ b/langtools/src/java.compiler/share/classes/javax/annotation/processing/Filer.java Tue Dec 13 10:49:28 2016 +0100
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2005, 2006, 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
@@ -66,7 +66,8 @@
* allow the <em>originating elements</em> to be provided as hints to
* the tool infrastructure to better manage dependencies. The
* originating elements are the types or packages (representing {@code
- * package-info} files) which caused an annotation processor to
+ * package-info} files) or modules (representing {@code
+ * module-info} files) which caused an annotation processor to
* attempt to create a new file. For example, if an annotation
* processor tries to create a source file, {@code
* GeneratedFromUserSource}, in response to processing
@@ -111,10 +112,10 @@
* to overwrite existing files that were not generated.
*
* <p> 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.
*
- * <p> 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 <i>decorator</i>-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,35 @@
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, or a package 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).
+ *
+ * <p>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"}.
*
- * <p> Note that to use a particular {@linkplain
+ * <p>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"}.
+ *
+ * <p>Creating a source file in or for an unnamed package in a named
+ * module is <em>not</em> 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 +179,51 @@
* @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
+ * @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, or a package 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).
+ *
+ * <p>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.
*
- * <p>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.
+ * <p>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"}.
+ *
+ * <p>Creating a class file in or for an unnamed package in a named
+ * module is <em>not</em> 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
+ * @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 +242,27 @@
* 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}.
*
- * <p>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. If {@code moduleAndPkg}
+ * does not contain a "{@code /}" character, the entire argument
+ * is interpreted as a package name.
+ *
+ * <p>Files created via this method are <em>not</em> 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 +272,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 +286,27 @@
* and {@link StandardLocation#SOURCE_OUTPUT SOURCE_OUTPUT} must
* be supported.
*
+ * <p>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;
}