src/java.compiler/share/classes/javax/annotation/processing/Filer.java

@@ -1,7 +1,7 @@
 /*
- * 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
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this

@@ -64,11 +64,12 @@
  *
  * <p>The file creation methods take a variable number of arguments to
  * 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
  *
  * <blockquote><pre>

@@ -94,14 +95,14 @@
  * given pathname may be created only once.  If that file already
  * exists before the first attempt to create it, the old contents will
  * be deleted.  Any subsequent attempt to create the same file during
  * a run will throw a {@link FilerException}, as will attempting to
  * create both a class file and source file for the same type name or
- * same package name.  The {@linkplain Processor initial inputs} to
- * the tool are considered to be created by the zeroth round;
- * therefore, attempting to create a source or class file
- * corresponding to one of those inputs will result in a {@link
+ * same package name or same module name.  The {@linkplain Processor
+ * initial inputs} to the tool are considered to be created by the
+ * zeroth round; therefore, attempting to create a source or class
+ * file corresponding to one of those inputs will result in a {@link
  * FilerException}.
  *
  * <p> In general, processors must not knowingly attempt to overwrite
  * existing files that were not generated by some processor.  A {@code
  * Filer} may reject attempts to open a file corresponding to an

@@ -109,14 +110,15 @@
  * invoker of the annotation processing tool must not knowingly
  * configure the tool such that the discovered processors will attempt
  * 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 {@link javax.annotation.Generated @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
  * of the class are generated by annotation processing.  If the
  * subclasses are generated, the parent class may be designed to use

@@ -129,22 +131,42 @@
  * @since 1.6
  */
 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
+     * 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 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
+     * file as well as the specified module for the type (if any).
+
+     * If more than one type is being declared, the name
+     * of the principal top-level type (the public one, for example)
+     * should be used.
+     *
+     * <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 {@code name} 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
+     * 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 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"}
+     *
+     * TOOD: For module m should {@code "m/package-info"} be rejected? 
+     * In other words, an unnamed package cannot be created at will in
+     * a named module? Is creating a source file for an unnamed module
+     * 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
      * object. If the {@code Writer} from the returned object is
      * directly used for writing, its charset is determined by the

@@ -159,17 +181,19 @@
      * for this run.
      *
      * @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
      */
     JavaFileObject createSourceFile(CharSequence name,
                                     Element... originatingElements) throws IOException;
 

@@ -182,14 +206,16 @@
      * about a package, including package annotations.  To create a
      * class file for a named package, have {@code name} 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>TODO:update in parallel to the above
+     *
+     * @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
      * associated with the creation of this file, may be elided or

@@ -208,24 +234,30 @@
      * file object for it.  The file may be located along with the
      * newly created source files, newly created binary files, or
      * 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}.
+     *
+     * If {@code moduleAndPkg} contains a "{@code /}" character, the
+     * prefix before "{@code /}" character is the module name and the
+     * suffix after the "{@code /}" character is package
+     * name. Otherwise, the entire argument is interpreted as a
+     * package name.
      *
-     * <p>Files created via this method are not registered for
+     * <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
      * {@code null}
      * @return a {@code FileObject} to write the new resource

@@ -234,30 +266,36 @@
      * created
      * @throws IllegalArgumentException for an unsupported location
      * @throws IllegalArgumentException if {@code relativeName} is not relative
      */
    FileObject createResource(JavaFileManager.Location location,
-                             CharSequence pkg,
+                             CharSequence moduleAndPkg,
                              CharSequence relativeName,
                              Element... originatingElements) throws IOException;
 
     /**
      * Returns an object for reading an existing resource.  The
      * locations {@link StandardLocation#CLASS_OUTPUT CLASS_OUTPUT}
      * and {@link StandardLocation#SOURCE_OUTPUT SOURCE_OUTPUT} must
      * be supported.
      *
+     * <p>If {@code moduleAndPkg} contains a "{@code /}" character, the
+     * prefix before "{@code /}" character is the module name and the
+     * suffix after the "{@code /}" character is package
+     * name. Otherwise, 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 relativeName} is not relative
      */
     FileObject getResource(JavaFileManager.Location location,
-                           CharSequence pkg,
+                           CharSequence moduleAndPkg,
                            CharSequence relativeName) throws IOException;
 }