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. * *
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 * The Java™ Virtual Machine Specification. *
* ** Discussion: 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 * The Java™ Language Specification, * section 13.1 "The Form of a Binary". *
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. * *
Relative names: 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 RFC 3986, * section 3.3. Informally, this should be true: * * *
URI.{@linkplain java.net.URI#create create}(relativeName).{@linkplain java.net.URI#normalize normalize}().{@linkplain java.net.URI#getPath getPath}().equals(relativeName)
*
* All methods in this interface might throw a SecurityException. * *
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. * *
Implementation note: 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. * *
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. * *
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. * *
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 * package/class hierarchy: such locations are described as * package-oriented. * Alternatively, the files may be organized in a module/package/class * hierarchy: such locations are described as module-oriented. * 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. * *
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#listLocationsForModule}. */ 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 module/package/class * hierarchy, as compared to a package-oriented location, which * is expected to contain classes in a package/class 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. * *
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 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 relative
* name in the specified package in the given package-oriented location.
*
* 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}.
*
* 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:
*
* If the call was executed on Windows, with SOURCE_PATH set to
* 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.
*
* 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}.
*
* 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 representing a Java
* source or class, 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.
*
* @apiNote the package name is used to identify the position of the file object
* within the module/package/class hierarchy identified by by the location.
*
* @implSpec This implementation throws {@code UnsupportedOperationException}.
*
* @param location the module-oriented location
* @param fo the file
* @param pkgName the package name for the class(es) defined in this 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, String pkgName) 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 getFileForInput(SOURCE_PATH, "com.sun.tools.javac", "resources/compiler.properties");
*
* "C:\Documents and Settings\UncleBob\src\share\classes",
* a valid result would be a file object representing the file
* "C:\Documents and Settings\UncleBob\src\share\classes\com\sun\tools\javac\resources\compiler.properties".
*
* @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 relative
* name in the specified package in the given location.
*
* 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 ServiceLoader getServiceLoader(Location location, Class 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