jdk-sandbox: comparison langtools/src/java.compiler/share/classes/javax/annotation/processing/Filer.java

equal deleted inserted replaced

-:202973b2d1ae
+:e1b620ac6c98
 package javax.annotation.processing;
 import javax.tools.JavaFileManager;
 import javax.tools.*;
 import javax.lang.model.element.Element;
+import javax.lang.model.util.Elements;
 import java.io.IOException;
 /**
 * This interface supports the creation of new files by an annotation
 * processor.  Files created in this way will be known to the
 * <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>If no explicit module prefix is given and modules are supported
+* in the environment, a suitable module is inferred. If a suitable
+* module cannot be inferred {@link FilerException} is thrown.
+* An implementation may use information about the configuration of
+* the annotation processing tool as part of the inference.
+*
 * <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
 * <p>To avoid subsequent errors, the contents of the source file
 * should be compatible with the {@linkplain
 * ProcessingEnvironment#getSourceVersion source version} being used
 * for this run.
 *
+* @implNote In the reference implementation, if the annotation
+* processing tool is processing a single module <i>M</i>,
+* then <i>M</i> is used as the module for files created without
+* an explicit module prefix. If the tool is processing multiple
+* modules, and {@link
+* Elements#getPackageElement(java.lang.CharSequence)
+* Elements.getPackageElement(package-of(name))}
+* returns a package, the module that owns the returned package is used
+* as the target module. A separate option may be used to provide the target
+* module if it cannot be determined using the above rules.
+*
 * @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 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
+* created, the same type 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
+* module is not writable, or a module is specified when the environment
+* doesn't support modules.
 * @throws IOException if the file cannot be created
 * @jls 7.3 Compilation Units
 */
 JavaFileObject createSourceFile(CharSequence name,
 Element... originatingElements) throws IOException;
 * <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>If no explicit module prefix is given and modules are supported
+* in the environment, a suitable module is inferred. If a suitable
+* module cannot be inferred {@link FilerException} is thrown.
+* An implementation may use information about the configuration of
+* the annotation processing tool as part of the inference.
+*
 * <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.
+*
+* @implNote In the reference implementation, if the annotation
+* processing tool is processing a single module <i>M</i>,
+* then <i>M</i> is used as the module for files created without
+* an explicit module prefix. If the tool is processing multiple
+* modules, and {@link
+* Elements#getPackageElement(java.lang.CharSequence)
+* Elements.getPackageElement(package-of(name))}
+* returns a package, the module that owns the returned package is used
+* as the target module. A separate option may be used to provide the target
+* 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
 *          {@code ".package-info"} for a package 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
 * @throws FilerException if the same pathname has already been
-* created, the same type has already been created, or the name is
+* created, the same type has already been created, the name is
-* not valid for a type
+* not valid for a type, if the target module cannot be determined,
+* if the target module is not writable, or a module is specified when
+* the environment doesn't support modules.
 * @throws IOException if the file cannot be created
 */
 JavaFileObject createClassFile(CharSequence name,
 Element... originatingElements) throws IOException;
 * 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>If the given location is neither a {@linkplain
+* JavaFileManager.Location#isModuleOrientedLocation()
+* module oriented location}, nor an {@linkplain
+* JavaFileManager.Location#isOutputLocation()
+* output location containing multiple modules}, and the explicit
+* module prefix is given, {@link FilerException} is thrown.
+*
+* <p>If the given location is either a module oriented location,
+* or an output location containing multiple modules, and no explicit
+* modules prefix is given, a suitable module is
+* inferred. If a suitable module cannot be inferred {@link
+* FilerException} is thrown. An implementation may use information
+* about the configuration of the annotation processing tool
+* as part of the inference.
+*
 * <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.
+*
+* @implNote In the reference implementation, if the annotation
+* processing tool is processing a single module <i>M</i>,
+* then <i>M</i> is used as the module for files created without
+* an explicit module prefix. If the tool is processing multiple
+* modules, and {@link
+* Elements#getPackageElement(java.lang.CharSequence)
+* Elements.getPackageElement(package-of(name))}
+* returns a package, the module that owns the returned package is used
+* as the target module. A separate option may be used to provide the target
+* module if it cannot be determined using the above rules.
 *
 * @param location location of the new file
 * @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
 * associated with the creation of this file, may be elided or
 * {@code null}
 * @return a {@code FileObject} to write the new resource
 * @throws IOException if the file cannot be created
 * @throws FilerException if the same pathname has already been
-* created
+* created, if the target module cannot be determined,
+* or if the target module is not writable, or if an explicit
+* target module is specified and the location does not support it.
 * @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,
 * 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.
 *
+* <p>If the given location is neither a {@linkplain
+* JavaFileManager.Location#isModuleOrientedLocation()
+* module oriented location}, nor an {@linkplain
+* JavaFileManager.Location#isOutputLocation()
+* output location containing multiple modules}, and the explicit
+* module prefix is given, {@link FilerException} is thrown.
+*
+* <p>If the given location is either a module oriented location,
+* or an output location containing multiple modules, and no explicit
+* modules prefix is given, a suitable module is
+* inferred. If a suitable module cannot be inferred {@link
+* FilerException} is thrown. An implementation may use information
+* about the configuration of the annotation processing tool
+* as part of the inference.
+*
+* @implNote In the reference implementation, if the annotation
+* processing tool is processing a single module <i>M</i>,
+* then <i>M</i> is used as the module for files read without
+* an explicit module prefix. If the tool is processing multiple
+* modules, and {@link
+* Elements#getPackageElement(java.lang.CharSequence)
+* Elements.getPackageElement(package-of(name))}
+* returns a package, the module that owns the returned package is used
+* as the source module. A separate option may be used to provide the target
+* module if it cannot be determined using the above rules.
+*
 * @param location location of the file
 * @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
+* opened for writing, if the source module cannot be determined,
+* or if the target module is not writable, or if an explicit target
+* module is specified and the location does not support it.
 * @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
 */

changeset 44291	e1b620ac6c98
parent 43567	d0d89c3da7be