--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/java.compiler/share/classes/javax/tools/JavaFileManager.java Tue Sep 12 19:03:39 2017 +0200
@@ -0,0 +1,603 @@
+/*
+ * Copyright (c) 2005, 2017, 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
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package javax.tools;
+
+import java.io.Closeable;
+import java.io.Flushable;
+import java.io.IOException;
+import java.util.Iterator;
+import java.util.ServiceLoader;
+import java.util.Set;
+
+import static javax.tools.JavaFileObject.Kind;
+
+/**
+ * File manager for tools operating on Java™ programming language
+ * source and class files. In this context, <em>file</em> means an
+ * abstraction of regular files and other sources of data.
+ *
+ * <p>When constructing new JavaFileObjects, the file manager must
+ * determine where to create them. For example, if a file manager
+ * manages regular files on a file system, it would most likely have a
+ * current/working directory to use as default location when creating
+ * or finding files. A number of hints can be provided to a file
+ * manager as to where to create files. Any file manager might choose
+ * to ignore these hints.
+ *
+ * <p>Some methods in this interface use class names. Such class
+ * names must be given in the Java Virtual Machine internal form of
+ * fully qualified class and interface names. For convenience '.'
+ * and '/' are interchangeable. The internal form is defined in
+ * chapter four of
+ * <cite>The Java™ Virtual Machine Specification</cite>.
+
+ * <blockquote><p>
+ * <i>Discussion:</i> this means that the names
+ * "java/lang.package-info", "java/lang/package-info",
+ * "java.lang.package-info", are valid and equivalent. Compare to
+ * binary name as defined in
+ * <cite>The Java™ Language Specification</cite>,
+ * section 13.1 "The Form of a Binary".
+ * </p></blockquote>
+ *
+ * <p>The case of names is significant. All names should be treated
+ * as case-sensitive. For example, some file systems have
+ * case-insensitive, case-aware file names. File objects representing
+ * such files should take care to preserve case by using {@link
+ * java.io.File#getCanonicalFile} or similar means. If the system is
+ * not case-aware, file objects must use other means to preserve case.
+ *
+ * <p><em><a id="relative_name">Relative names</a>:</em> some
+ * methods in this interface use relative names. A relative name is a
+ * non-null, non-empty sequence of path segments separated by '/'.
+ * '.' or '..' are invalid path segments. A valid relative name must
+ * match the "path-rootless" rule of <a
+ * href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>,
+ * section 3.3. Informally, this should be true:
+ *
+ * <!-- URI.create(relativeName).normalize().getPath().equals(relativeName) -->
+ * <pre> URI.{@linkplain java.net.URI#create create}(relativeName).{@linkplain java.net.URI#normalize normalize}().{@linkplain java.net.URI#getPath getPath}().equals(relativeName)</pre>
+ *
+ * <p>All methods in this interface might throw a SecurityException.
+ *
+ * <p>An object of this interface is not required to support
+ * multi-threaded access, that is, be synchronized. However, it must
+ * support concurrent access to different file objects created by this
+ * object.
+ *
+ * <p><em>Implementation note:</em> a consequence of this requirement
+ * is that a trivial implementation of output to a {@linkplain
+ * java.util.jar.JarOutputStream} is not a sufficient implementation.
+ * That is, rather than creating a JavaFileObject that returns the
+ * JarOutputStream directly, the contents must be cached until closed
+ * and then written to the JarOutputStream.
+ *
+ * <p>Unless explicitly allowed, all methods in this interface might
+ * throw a NullPointerException if given a {@code null} argument.
+ *
+ * @author Peter von der Ahé
+ * @author Jonathan Gibbons
+ * @see JavaFileObject
+ * @see FileObject
+ * @since 1.6
+ */
+public interface JavaFileManager extends Closeable, Flushable, OptionChecker {
+
+ /**
+ * Interface for locations of file objects. Used by file managers
+ * to determine where to place or search for file objects.
+ *
+ * <p>Informally, a {@code Location} corresponds to a "search path", such as a class
+ * path or module path, as used by command-line tools that use the default file system.
+ *
+ * <p>Some locations are typically used to identify a place in which
+ * a tool can find files to be read; others are typically used to identify
+ * a place where a tool can write files. If a location is used to identify
+ * a place for reading files, those files may be organized in a simple
+ * <em>package/class</em> hierarchy: such locations are described as
+ * <strong>package-oriented</strong>.
+ * Alternatively, the files may be organized in a <em>module/package/class</em>
+ * hierarchy: such locations are described as <strong>module-oriented</strong>.
+ * If a location is typically used to identify a place where a tool can write files,
+ * it is up to the tool that writes the files to specify how those files will be
+ * organized.
+ *
+ * <p>You can access the classes in a package-oriented location using methods like
+ * {@link JavaFileManager#getJavaFileForInput} or {@link JavaFileManager#list}.
+ * It is not possible to directly list the classes in a module-oriented
+ * location. Instead, you can get a package-oriented location for any specific module
+ * using methods like {@link JavaFileManager#getLocationForModule} or
+ * {@link JavaFileManager#listLocationsForModules}.
+ */
+ interface Location {
+ /**
+ * Returns the name of this location.
+ *
+ * @return a name
+ */
+ String getName();
+
+ /**
+ * Determines if this is an output location.
+ * An output location is a location that is conventionally used for
+ * output.
+ *
+ * @apiNote An output location may be used to write files in either
+ * a package-oriented organization or in a module-oriented organization.
+ *
+ * @return true if this is an output location, false otherwise
+ */
+ boolean isOutputLocation();
+
+ /**
+ * Indicates if this location is module-oriented location, and therefore
+ * expected to contain classes in a <em>module/package/class</em>
+ * hierarchy, as compared to a package-oriented location, which
+ * is expected to contain classes in a <em>package/class</em> hierarchy.
+ * The result of this method is undefined if this is an output
+ * location.
+ *
+ * @implNote This implementation returns true if the name includes
+ * the word "MODULE".
+ *
+ * @return true if this location is expected to contain modules
+ * @since 9
+ * @spec JPMS
+ */
+ default boolean isModuleOrientedLocation() {
+ return getName().matches("\\bMODULE\\b");
+ }
+ }
+
+ /**
+ * Returns a class loader for loading plug-ins from the given
+ * package-oriented location.
+ * For example, to load annotation processors,
+ * a compiler will request a class loader for the {@link
+ * StandardLocation#ANNOTATION_PROCESSOR_PATH
+ * ANNOTATION_PROCESSOR_PATH} location.
+ *
+ * @param location a location
+ * @return a class loader for the given location; or {@code null}
+ * if loading plug-ins from the given location is disabled or if
+ * the location is not known
+ * @throws SecurityException if a class loader can not be created
+ * in the current security context
+ * @throws IllegalStateException if {@link #close} has been called
+ * and this file manager cannot be reopened
+ * @throws IllegalArgumentException if the location is a module-oriented location
+ */
+ ClassLoader getClassLoader(Location location);
+
+ /**
+ * Lists all file objects matching the given criteria in the given
+ * package-oriented location.
+ * List file objects in "subpackages" if recurse is true.
+ *
+ * <p>Note: even if the given location is unknown to this file
+ * manager, it may not return {@code null}. Also, an unknown
+ * location may not cause an exception.
+ *
+ * @param location a location
+ * @param packageName a package name
+ * @param kinds return objects only of these kinds
+ * @param recurse if true include "subpackages"
+ * @return an Iterable of file objects matching the given criteria
+ * @throws IOException if an I/O error occurred, or if {@link
+ * #close} has been called and this file manager cannot be
+ * reopened
+ * @throws IllegalArgumentException if the location is a module-oriented location
+ * @throws IllegalStateException if {@link #close} has been called
+ * and this file manager cannot be reopened
+ */
+ Iterable<JavaFileObject> list(Location location,
+ String packageName,
+ Set<Kind> kinds,
+ boolean recurse)
+ throws IOException;
+
+ /**
+ * Infers a binary name of a file object based on a package-oriented location.
+ * The binary name returned might not be a valid binary name according to
+ * <cite>The Java™ Language Specification</cite>.
+ *
+ * @param location a location
+ * @param file a file object
+ * @return a binary name or {@code null} the file object is not
+ * found in the given location
+ * @throws IllegalArgumentException if the location is a module-oriented location
+ * @throws IllegalStateException if {@link #close} has been called
+ * and this file manager cannot be reopened
+ */
+ String inferBinaryName(Location location, JavaFileObject file);
+
+ /**
+ * Compares two file objects and return true if they represent the
+ * same underlying object.
+ *
+ * @param a a file object
+ * @param b a file object
+ * @return true if the given file objects represent the same
+ * underlying object
+ *
+ * @throws IllegalArgumentException if either of the arguments
+ * were created with another file manager and this file manager
+ * does not support foreign file objects
+ */
+ boolean isSameFile(FileObject a, FileObject b);
+
+ /**
+ * Handles one option. If {@code current} is an option to this
+ * file manager it will consume any arguments to that option from
+ * {@code remaining} and return true, otherwise return false.
+ *
+ * @param current current option
+ * @param remaining remaining options
+ * @return true if this option was handled by this file manager,
+ * false otherwise
+ * @throws IllegalArgumentException if this option to this file
+ * manager is used incorrectly
+ * @throws IllegalStateException if {@link #close} has been called
+ * and this file manager cannot be reopened
+ */
+ boolean handleOption(String current, Iterator<String> remaining);
+
+ /**
+ * Determines if a location is known to this file manager.
+ *
+ * @param location a location
+ * @return true if the location is known
+ */
+ boolean hasLocation(Location location);
+
+ /**
+ * Returns a {@linkplain JavaFileObject file object} for input
+ * representing the specified class of the specified kind in the
+ * given package-oriented location.
+ *
+ * @param location a location
+ * @param className the name of a class
+ * @param kind the kind of file, must be one of {@link
+ * JavaFileObject.Kind#SOURCE SOURCE} or {@link
+ * JavaFileObject.Kind#CLASS CLASS}
+ * @return a file object, might return {@code null} if the
+ * file does not exist
+ * @throws IllegalArgumentException if the location is not known
+ * to this file manager and the file manager does not support
+ * unknown locations, or if the kind is not valid, or if the
+ * location is a module-oriented location
+ * @throws IOException if an I/O error occurred, or if {@link
+ * #close} has been called and this file manager cannot be
+ * reopened
+ * @throws IllegalStateException if {@link #close} has been called
+ * and this file manager cannot be reopened
+ */
+ JavaFileObject getJavaFileForInput(Location location,
+ String className,
+ Kind kind)
+ throws IOException;
+
+ /**
+ * Returns a {@linkplain JavaFileObject file object} for output
+ * representing the specified class of the specified kind in the
+ * given package-oriented location.
+ *
+ * <p>Optionally, this file manager might consider the sibling as
+ * a hint for where to place the output. The exact semantics of
+ * this hint is unspecified. The JDK compiler, javac, for
+ * example, will place class files in the same directories as
+ * originating source files unless a class file output directory
+ * is provided. To facilitate this behavior, javac might provide
+ * the originating source file as sibling when calling this
+ * method.
+ *
+ * @param location a package-oriented location
+ * @param className the name of a class
+ * @param kind the kind of file, must be one of {@link
+ * JavaFileObject.Kind#SOURCE SOURCE} or {@link
+ * JavaFileObject.Kind#CLASS CLASS}
+ * @param sibling a file object to be used as hint for placement;
+ * might be {@code null}
+ * @return a file object for output
+ * @throws IllegalArgumentException if sibling is not known to
+ * this file manager, or if the location is not known to this file
+ * manager and the file manager does not support unknown
+ * locations, or if the kind is not valid, or if the location is
+ * not an output location
+ * @throws IOException if an I/O error occurred, or if {@link
+ * #close} has been called and this file manager cannot be
+ * reopened
+ * @throws IllegalStateException {@link #close} has been called
+ * and this file manager cannot be reopened
+ */
+ JavaFileObject getJavaFileForOutput(Location location,
+ String className,
+ Kind kind,
+ FileObject sibling)
+ throws IOException;
+
+ /**
+ * Returns a {@linkplain FileObject file object} for input
+ * representing the specified <a href="JavaFileManager.html#relative_name">relative
+ * name</a> in the specified package in the given package-oriented location.
+ *
+ * <p>If the returned object represents a {@linkplain
+ * JavaFileObject.Kind#SOURCE source} or {@linkplain
+ * JavaFileObject.Kind#CLASS class} file, it must be an instance
+ * of {@link JavaFileObject}.
+ *
+ * <p>Informally, the file object returned by this method is
+ * located in the concatenation of the location, package name, and
+ * relative name. For example, to locate the properties file
+ * "resources/compiler.properties" in the package
+ * "com.sun.tools.javac" in the {@linkplain
+ * StandardLocation#SOURCE_PATH SOURCE_PATH} location, this method
+ * might be called like so:
+ *
+ * <pre>getFileForInput(SOURCE_PATH, "com.sun.tools.javac", "resources/compiler.properties");</pre>
+ *
+ * <p>If the call was executed on Windows, with SOURCE_PATH set to
+ * <code>"C:\Documents and Settings\UncleBob\src\share\classes"</code>,
+ * a valid result would be a file object representing the file
+ * <code>"C:\Documents and Settings\UncleBob\src\share\classes\com\sun\tools\javac\resources\compiler.properties"</code>.
+ *
+ * @param location a package-oriented location
+ * @param packageName a package name
+ * @param relativeName a relative name
+ * @return a file object, might return {@code null} if the file
+ * does not exist
+ * @throws IllegalArgumentException if the location is not known
+ * to this file manager and the file manager does not support
+ * unknown locations, or if {@code relativeName} is not valid,
+ * or if the location is a module-oriented location
+ * @throws IOException if an I/O error occurred, or if {@link
+ * #close} has been called and this file manager cannot be
+ * reopened
+ * @throws IllegalStateException if {@link #close} has been called
+ * and this file manager cannot be reopened
+ */
+ FileObject getFileForInput(Location location,
+ String packageName,
+ String relativeName)
+ throws IOException;
+
+ /**
+ * Returns a {@linkplain FileObject file object} for output
+ * representing the specified <a href="JavaFileManager.html#relative_name">relative
+ * name</a> in the specified package in the given location.
+ *
+ * <p>Optionally, this file manager might consider the sibling as
+ * a hint for where to place the output. The exact semantics of
+ * this hint is unspecified. The JDK compiler, javac, for
+ * example, will place class files in the same directories as
+ * originating source files unless a class file output directory
+ * is provided. To facilitate this behavior, javac might provide
+ * the originating source file as sibling when calling this
+ * method.
+ *
+ * <p>If the returned object represents a {@linkplain
+ * JavaFileObject.Kind#SOURCE source} or {@linkplain
+ * JavaFileObject.Kind#CLASS class} file, it must be an instance
+ * of {@link JavaFileObject}.
+ *
+ * <p>Informally, the file object returned by this method is
+ * located in the concatenation of the location, package name, and
+ * relative name or next to the sibling argument. See {@link
+ * #getFileForInput getFileForInput} for an example.
+ *
+ * @param location an output location
+ * @param packageName a package name
+ * @param relativeName a relative name
+ * @param sibling a file object to be used as hint for placement;
+ * might be {@code null}
+ * @return a file object
+ * @throws IllegalArgumentException if sibling is not known to
+ * this file manager, or if the location is not known to this file
+ * manager and the file manager does not support unknown
+ * locations, or if {@code relativeName} is not valid,
+ * or if the location is not an output location
+ * @throws IOException if an I/O error occurred, or if {@link
+ * #close} has been called and this file manager cannot be
+ * reopened
+ * @throws IllegalStateException if {@link #close} has been called
+ * and this file manager cannot be reopened
+ */
+ FileObject getFileForOutput(Location location,
+ String packageName,
+ String relativeName,
+ FileObject sibling)
+ throws IOException;
+
+ /**
+ * Flushes any resources opened for output by this file manager
+ * directly or indirectly. Flushing a closed file manager has no
+ * effect.
+ *
+ * @throws IOException if an I/O error occurred
+ * @see #close
+ */
+ @Override
+ void flush() throws IOException;
+
+ /**
+ * Releases any resources opened by this file manager directly or
+ * indirectly. This might render this file manager useless and
+ * the effect of subsequent calls to methods on this object or any
+ * objects obtained through this object is undefined unless
+ * explicitly allowed. However, closing a file manager which has
+ * already been closed has no effect.
+ *
+ * @throws IOException if an I/O error occurred
+ * @see #flush
+ */
+ @Override
+ void close() throws IOException;
+
+ /**
+ * Gets a location for a named module within a location, which may be either
+ * a module-oriented location or an output location.
+ * The result will be an output location if the given location is
+ * an output location, or it will be a package-oriented location.
+ *
+ * @implSpec This implementation throws {@code UnsupportedOperationException}.
+ *
+ * @param location the module-oriented location
+ * @param moduleName the name of the module to be found
+ * @return the location for the named module
+ *
+ * @throws IOException if an I/O error occurred
+ * @throws UnsupportedOperationException if this operation if not supported by this file manager
+ * @throws IllegalArgumentException if the location is neither an output location nor a
+ * module-oriented location
+ * @since 9
+ * @spec JPMS
+ */ // TODO: describe failure modes
+ default Location getLocationForModule(Location location, String moduleName) throws IOException {
+ throw new UnsupportedOperationException();
+ }
+
+ /**
+ * Gets a location for the module containing a specific file
+ * to be found within a location, which may be either
+ * a module-oriented location or an output location.
+ * The result will be an output location if the given location is
+ * an output location, or it will be a package-oriented location.
+ *
+ * @implSpec This implementation throws {@code UnsupportedOperationException}.
+ *
+ * @param location the module-oriented location
+ * @param fo the file
+ * @return the module containing the file
+ *
+ * @throws IOException if an I/O error occurred
+ * @throws UnsupportedOperationException if this operation if not supported by this file manager
+ * @throws IllegalArgumentException if the location is neither an output location nor a
+ * module-oriented location
+ * @since 9
+ * @spec JPMS
+ */
+ default Location getLocationForModule(Location location, JavaFileObject fo) throws IOException {
+ throw new UnsupportedOperationException();
+ }
+
+ /**
+ * Get a service loader for a specific service class from a given location.
+ *
+ * If the location is a module-oriented location, the service loader will use the
+ * service declarations in the modules found in that location. Otherwise, a service loader
+ * is created using the package-oriented location, in which case, the services are
+ * determined using the provider-configuration files in {@code META-INF/services}.
+ *
+ * @implSpec This implementation throws {@code UnsupportedOperationException}.
+ *
+ * @param location the module-oriented location
+ * @param service the {@code Class} object of the service class
+ * @param <S> the service class
+ * @return a service loader for the given service class
+ *
+ * @throws IOException if an I/O error occurred
+ * @throws UnsupportedOperationException if this operation if not supported by this file manager
+ * @since 9
+ * @spec JPMS
+ */ // TODO: describe failure modes
+ default <S> ServiceLoader<S> getServiceLoader(Location location, Class<S> service) throws IOException {
+ throw new UnsupportedOperationException();
+ }
+
+ /**
+ * Infer the name of the module from its location, as returned by
+ * {@code getLocationForModule} or {@code listModuleLocations}.
+ *
+ * @implSpec This implementation throws {@code UnsupportedOperationException}.
+ *
+ * @param location a package-oriented location representing a module
+ * @return the name of the module
+ *
+ * @throws IOException if an I/O error occurred
+ * @throws UnsupportedOperationException if this operation if not supported by this file manager
+ * @throws IllegalArgumentException if the location is not one known to this file manager
+ * @since 9
+ * @spec JPMS
+ */ // TODO: describe failure modes
+ default String inferModuleName(Location location) throws IOException {
+ throw new UnsupportedOperationException();
+ }
+
+ /**
+ * Lists the locations for all the modules in a module-oriented location or an output location.
+ * The locations that are returned will be output locations if the given location is an output,
+ * or it will be a package-oriented locations.
+ *
+ * @implSpec This implementation throws {@code UnsupportedOperationException}.
+ *
+ * @param location the module-oriented location for which to list the modules
+ * @return a series of sets of locations containing modules
+ *
+ * @throws IOException if an I/O error occurred
+ * @throws UnsupportedOperationException if this operation if not supported by this file manager
+ * @throws IllegalArgumentException if the location is not a module-oriented location
+ * @since 9
+ * @spec JPMS
+ */ // TODO: describe failure modes
+ default Iterable<Set<Location>> listLocationsForModules(Location location) throws IOException {
+ throw new UnsupportedOperationException();
+ }
+
+ /**
+ * Determines whether or not a given file object is "contained in" a specified location.
+ *
+ * <p>For a package-oriented location, a file object is contained in the location if there exist
+ * values for <i>packageName</i> and <i>relativeName</i> such that either of the following
+ * calls would return the {@link #isSameFile same} file object:
+ * <pre>
+ * getFileForInput(location, <i>packageName</i>, <i>relativeName</i>)
+ * getFileForOutput(location, <i>packageName</i>, <i>relativeName</i>, null)
+ * </pre>
+ *
+ * <p>For a module-oriented location, a file object is contained in the location if there exists
+ * a module that may be obtained by the call:
+ * <pre>
+ * getLocationForModule(location, <i>moduleName</i>)
+ * </pre>
+ * such that the file object is contained in the (package-oriented) location for that module.
+ *
+ * @implSpec This implementation throws {@code UnsupportedOperationException}.
+ *
+ * @param location the location
+ * @param fo the file object
+ * @return whether or not the file is contained in the location
+ *
+ * @throws IOException if there is a problem determining the result
+ * @throws UnsupportedOperationException if the method is not supported
+ *
+ * @since 9
+ */
+
+ default boolean contains(Location location, FileObject fo) throws IOException {
+ throw new UnsupportedOperationException();
+ }
+
+}