Module io.github.ascopes.jct

Package io.github.ascopes.jct.filemanagers

Interface JctFileManager

All Superinterfaces:

AutoCloseable, Closeable, Flushable, JavaFileManager, OptionChecker

@API(since="0.0.1",
     status=STABLE)
public interface JctFileManager
extends JavaFileManager

Extension around a JavaFileManager that allows adding of PathRoot objects to the manager.

This component is responsible for bridging the gap between a Workspace and a JavaCompiler when performing a compilation, and thus includes a number of required operations that the compiler will query the file system with. In addition, this interface also defines a number of additional functionalities that are useful for querying and verifying the outcome of compilations within tests.

Since:

0.0.1

Author:

Ashley Scopes

Nested Class Summary

Nested classes/interfaces inherited from interface javax.tools.JavaFileManager

JavaFileManager.Location

Method Summary

Modifier and Type	Method	Description
void	addPath(JavaFileManager.Location location, PathRoot path)	Add a package-oriented path to a given location.
void	addPaths(JavaFileManager.Location location, Collection<? extends PathRoot> paths)	Add a collection of package-oriented paths to a given location.
void	close()	Close this file manager.
boolean	contains(JavaFileManager.Location location, FileObject fileObject)	Determine if the given file object resides in the given location.
void	copyContainers(JavaFileManager.Location from, JavaFileManager.Location to)	Copy all containers from the first location to the second location.
void	createEmptyLocation(JavaFileManager.Location location)	Register an empty container for the given location to indicate to the compiler that the feature exists, but has no configured paths.
void	flush()	Flush this file manager.
default @Nullable ModuleContainerGroup	getAnnotationProcessorModulePathGroup()	Get the location holding the annotation processor module path.
default @Nullable PackageContainerGroup	getAnnotationProcessorPathGroup()	Get the location holding the annotation processor path.
@Nullable ClassLoader	getClassLoader(JavaFileManager.Location location)	Get the class loader for loading classes for the given location.
default @Nullable OutputContainerGroup	getClassOutputGroup()	Get the location holding the class outputs.
default @Nullable PackageContainerGroup	getClassPathGroup()	Get the location holding the class path.
String	getEffectiveRelease()	Get the associated effective release.
@Nullable FileObject	getFileForInput(JavaFileManager.Location location, String packageName, String relativeName)	Get a file for input operations.
@Nullable FileObject	getFileForOutput(JavaFileManager.Location location, String packageName, String relativeName, @Nullable FileObject sibling)	Get a file for output operations.
@Nullable JavaFileObject	getJavaFileForInput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind)	Get a Java file for input operations.
@Nullable JavaFileObject	getJavaFileForOutput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, @Nullable FileObject sibling)	Get a Java file for output operations.
@Nullable JavaFileManager.Location	getLocationForModule(JavaFileManager.Location location, String moduleName)	Get the location for a named module within the given location.
@Nullable JavaFileManager.Location	getLocationForModule(JavaFileManager.Location location, JavaFileObject fileObject)	Get the location for the module holding a given file object within the given location.
@Nullable ModuleContainerGroup	getModuleContainerGroup(JavaFileManager.Location location)	Get the container group for the given module-oriented location.
Collection<ModuleContainerGroup>	getModuleContainerGroups()	Get a collection of all module container groups in this file manager.
default @Nullable ModuleContainerGroup	getModulePathGroup()	Get the location holding the module path.
default @Nullable ModuleContainerGroup	getModuleSourcePathGroup()	Get the location holding the module source path.
@Nullable OutputContainerGroup	getOutputContainerGroup(JavaFileManager.Location location)	Get the container group for the given output-oriented location.
Collection<OutputContainerGroup>	getOutputContainerGroups()	Get a collection of all output container groups in this file manager.
@Nullable PackageContainerGroup	getPackageContainerGroup(JavaFileManager.Location location)	Get the container group for the given package-oriented location.
Collection<PackageContainerGroup>	getPackageContainerGroups()	Get a collection of all package container groups in this file manager.
default @Nullable OutputContainerGroup	getSourceOutputGroup()	Get the location holding the source outputs.
default @Nullable PackageContainerGroup	getSourcePathGroup()	Get the location holding the source path.
boolean	handleOption(String current, Iterator<String> remaining)	Handles one option.
boolean	hasLocation(JavaFileManager.Location location)	Determines if a location is known to this file manager.
@Nullable String	inferBinaryName(JavaFileManager.Location location, JavaFileObject file)	Infers a binary name of a file object based on a package-oriented location.
@Nullable String	inferModuleName(JavaFileManager.Location location)	Infer the name of the module from its location, as returned by getLocationForModule or listModuleLocations.
boolean	isSameFile(@Nullable FileObject a, @Nullable FileObject b)	Determine if the two file objects are the same file.
Set<JavaFileObject>	list(JavaFileManager.Location location, String packageName, Set<JavaFileObject.Kind> kinds, boolean recurse)	List all file objects in the given location matching the given criteria.
Iterable<Set<JavaFileManager.Location>>	listLocationsForModules(JavaFileManager.Location location)	List all module-based locations for the given module-oriented or output location.

Methods inherited from interface javax.tools.JavaFileManager

getServiceLoader

Methods inherited from interface javax.tools.OptionChecker

isSupportedOption

Method Details

addPath

void addPath(JavaFileManager.Location location,
 PathRoot path)

Add a package-oriented path to a given location.

To add a module, first obtain the module location using getLocationForModule(Location, String), and pass that result to this call.

Parameters:

location - the location to use.

path - the path to add.

See Also:

• getLocationForModule(Location, String)

addPaths

void addPaths(JavaFileManager.Location location,
 Collection<? extends PathRoot> paths)

Add a collection of package-oriented paths to a given location.

To add a module, first obtain the module location using getLocationForModule(Location, String), and pass that result to this call.

Parameters:

location - the location to use.

paths - the paths to add.

See Also:

• getLocationForModule(Location, String)

close

void close()
    throws IOException

Close this file manager.

If the file manager is already closed, this will have no effect.

JCT File managers may choose to not implement this operation if not applicable.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Specified by:

close in interface JavaFileManager

Throws:

IOException - if an IO error occurs during closure.

contains

boolean contains(JavaFileManager.Location location,
 FileObject fileObject)
          throws IOException

Determine if the given file object resides in the given location.

If package-oriented, then the file must exist in the given location directly.

If module-oriented, then the file must exist in one of the modules within the location. This implies that getLocationForModule(Location, JavaFileObject) would also return a valid non-null value.

Specified by:

contains in interface JavaFileManager

Parameters:

location - the location.

fileObject - the file object.

Returns:

true if the file exists in the given location, or false otherwise.

Throws:

IOException - if an IO error occurs during the lookup.

copyContainers

void copyContainers(JavaFileManager.Location from,
 JavaFileManager.Location to)

Copy all containers from the first location to the second location.

Parameters:

from - the first location.

to - the second location.

createEmptyLocation

void createEmptyLocation(JavaFileManager.Location location)

Register an empty container for the given location to indicate to the compiler that the feature exists, but has no configured paths.

This is needed to coerce the behaviour for annotation processing in some cases.

If the location already exists, then do not do anything.

If the location is an output location, then this operation does not make any sense, since an empty location cannot have files output to it. In this case, you will likely get an exception.

Likewise, this operation does not make sense for module locations within a module-oriented location group, so this operation will fail with an error for those inputs as well.

Parameters:

location - the location to apply an empty container for.

Throws:

IllegalArgumentException - if the location is an output location or a module location.

flush

void flush()
    throws IOException

Flush this file manager.

If the file manager is already closed, this will have no effect.

JCT File managers may choose to not implement this operation if not applicable.

Specified by:

flush in interface Flushable

Specified by:

flush in interface JavaFileManager

Throws:

IOException - if an IO error occurs during flushing.

getClassLoader

@Nullable ClassLoader getClassLoader(JavaFileManager.Location location)

Get the class loader for loading classes for the given location.

Specified by:

getClassLoader in interface JavaFileManager

Parameters:

location - the location to fetch a class loader for.

Returns:

a class loader, or null if loading classes for the given location is not supported.

Throws:

SecurityException - if a class loader can not be created in the current security context

IllegalStateException - if close() has been called and this file manager cannot be reopened

IllegalArgumentException - if the location is a module-oriented location

getEffectiveRelease

String getEffectiveRelease()

Get the associated effective release.

Returns:

the effective release.

Since:

0.0.1

getFileForInput

@Nullable FileObject getFileForInput(JavaFileManager.Location location,
 String packageName,
 String relativeName)
                              throws IOException

Get a file for input operations.

Specified by:

getFileForInput in interface JavaFileManager

Parameters:

location - a package-oriented location.

packageName - a package name.

relativeName - a relative name.

Returns:

the file object, or null if not found or not available.

Throws:

IOException - if an IO error occurs reading the file details.

IllegalArgumentException - if the location is not a package-oriented location.

getFileForOutput

@Nullable FileObject getFileForOutput(JavaFileManager.Location location,
 String packageName,
 String relativeName,
 @Nullable FileObject sibling)
                               throws IOException

Get a file for output operations.

Specified by:

getFileForOutput in interface JavaFileManager

Parameters:

location - an output location.

packageName - a package name.

relativeName - a relative name.

sibling - a file object to be used as hint for placement, might be null.

Returns:

the file object, or null if not found or not available.

Throws:

IOException - if an IO error occurs reading the file details.

IllegalArgumentException - if the location is not an output location.

getJavaFileForInput

@Nullable JavaFileObject getJavaFileForInput(JavaFileManager.Location location,
 String className,
 JavaFileObject.Kind kind)
                                      throws IOException

Get a Java file for input operations.

Specified by:

getJavaFileForInput in interface JavaFileManager

Parameters:

location - a package-oriented location.

className - the name of a class.

kind - the kind of file.

Returns:

the file object, or null if not found or not available.

Throws:

IOException - if an IO error occurs reading the file details.

IllegalArgumentException - if the location is not a package-oriented location.

getJavaFileForOutput

@Nullable JavaFileObject getJavaFileForOutput(JavaFileManager.Location location,
 String className,
 JavaFileObject.Kind kind,
 @Nullable FileObject sibling)
                                       throws IOException

Get a Java file for output operations.

Specified by:

getJavaFileForOutput in interface JavaFileManager

Parameters:

location - an output location.

className - the name of a class.

kind - the kind of file.

sibling - a file object to be used as hint for placement, might be null.

Returns:

the file object, or null if not found or not available.

Throws:

IOException - if an IO error occurs reading the file details.

IllegalArgumentException - if the location is not an output location.

getLocationForModule

@Nullable JavaFileManager.Location getLocationForModule(JavaFileManager.Location location,
 String moduleName)
                                                 throws IOException

Get the location for a named module within the given location.

Specified by:

getLocationForModule in interface JavaFileManager

Parameters:

location - the module-oriented location.

moduleName - the name of the module to be found.

Returns:

the location of the named module, or null if not found.

Throws:

IOException - if an IO error occurs during resolution.

IllegalArgumentException - if the location is neither an output location nor a module-oriented location.

getLocationForModule

@Nullable JavaFileManager.Location getLocationForModule(JavaFileManager.Location location,
 JavaFileObject fileObject)
                                                 throws IOException

Get the location for the module holding a given file object within the given location.

Specified by:

getLocationForModule in interface JavaFileManager

Parameters:

location - the module-oriented location.

fileObject - the file object to resolve the module for.

Returns:

the location, or null if not found.

Throws:

IOException - if an IO error occurs during resolution.

IllegalArgumentException - if the location is neither an output location nor a module-oriented location.

getPackageContainerGroup

@Nullable PackageContainerGroup getPackageContainerGroup(JavaFileManager.Location location)

Get the container group for the given package-oriented location.

Parameters:

location - the package oriented location.

Returns:

the container group, or null if one does not exist.

getPackageContainerGroups

Collection<PackageContainerGroup> getPackageContainerGroups()

Get a collection of all package container groups in this file manager.

Returns:

the package container groups.

getModuleContainerGroup

@Nullable ModuleContainerGroup getModuleContainerGroup(JavaFileManager.Location location)

Get the container group for the given module-oriented location.

Parameters:

location - the module oriented location.

Returns:

the container group, or null if one does not exist.

getModuleContainerGroups

Collection<ModuleContainerGroup> getModuleContainerGroups()

Get a collection of all module container groups in this file manager.

Returns:

the module container groups.

getOutputContainerGroup

@Nullable OutputContainerGroup getOutputContainerGroup(JavaFileManager.Location location)

Get the container group for the given output-oriented location.

Parameters:

location - the output oriented location.

Returns:

the container group, or null if one does not exist.

getOutputContainerGroups

Collection<OutputContainerGroup> getOutputContainerGroups()

Get a collection of all output container groups in this file manager.

Returns:

the output container groups.

handleOption

boolean handleOption(String current,
 Iterator<String> remaining)

Handles one option. If current is an option to this file manager it will consume any arguments to that option from remaining and return true, otherwise return false.

Specified by:

handleOption in interface JavaFileManager

Parameters:

current - current option.

remaining - remaining options.

Returns:

true if this option was handled by this file manager, false otherwise.

Throws:

IllegalArgumentException - if this option to this file manager is used incorrectly.

IllegalStateException - if close() has been called and this file manager cannot be reopened.

hasLocation

boolean hasLocation(JavaFileManager.Location location)

Determines if a location is known to this file manager.

Specified by:

hasLocation in interface JavaFileManager

Parameters:

location - a location.

Returns:

true if the location is known to this file manager.

inferBinaryName

@Nullable String inferBinaryName(JavaFileManager.Location location,
 JavaFileObject file)

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 the Java Language Specification.

Specified by:

inferBinaryName in interface JavaFileManager

Parameters:

location - a location.

file - a file object.

Returns:

a binary name or null the file object is not found in the given location

Throws:

IllegalArgumentException - if the location is a module-oriented location.

IllegalStateException - if close() has been called and this file manager cannot be reopened.

inferModuleName

@Nullable String inferModuleName(JavaFileManager.Location location)
                          throws IOException

Infer the name of the module from its location, as returned by getLocationForModule or listModuleLocations.

Specified by:

inferModuleName in interface JavaFileManager

Parameters:

location - a package-oriented location representing a module.

Returns:

the name of the module, or null if the name cannot be resolved or does not exist.

Throws:

IOException - if an I/O error occurred during resolution.

IllegalArgumentException - if the location is not one known to this file manager.

isSameFile

boolean isSameFile(@Nullable FileObject a,
 @Nullable FileObject b)

Determine if the two file objects are the same file.

Specified by:

isSameFile in interface JavaFileManager

Parameters:

a - a file object, can be null.

b - a file object, can be null.

Returns:

true if both arguments are non-null and refer to the same logical file, or false otherwise.

list

Set<JavaFileObject> list(JavaFileManager.Location location,
 String packageName,
 Set<JavaFileObject.Kind> kinds,
 boolean recurse)
                  throws IOException

List all file objects in the given location matching the given criteria.

Specified by:

list in interface JavaFileManager

Parameters:

location - the location to search in.

packageName - the package name to search in, or "" to search in the root location.

kinds - the kinds of file to return, or Set.of() ( JavaFileObject.Kind.OTHER ) to find all files.

recurse - true to recurse into subpackages, false to only check the current package.

Returns:

a collection of unique file objects that were found.

Throws:

IOException - if an IO error occurs reading the file system.

IllegalArgumentException - if the location is a module-oriented location

IllegalStateException - if close() has been called and this file manager cannot be reopened

listLocationsForModules

Iterable<Set<JavaFileManager.Location>> listLocationsForModules(JavaFileManager.Location location)
                                                         throws IOException

List all module-based locations for the given module-oriented or output location.

Specified by:

listLocationsForModules in interface JavaFileManager

Parameters:

location - the module-oriented/output location for which to list the modules.

Returns:

the iterable of sets of modules.

Throws:

IOException - if an IO error occurs during resolution.

IllegalArgumentException - if the location is not a module-oriented or output location.

getClassOutputGroup

default @Nullable OutputContainerGroup getClassOutputGroup()

Get the location holding the class outputs.

Returns:

the location, or null if the location is not present in the file manager.

Since:

0.1.0

getSourceOutputGroup

default @Nullable OutputContainerGroup getSourceOutputGroup()

Get the location holding the source outputs.

Returns:

the location, or null if the location is not present in the file manager.

Since:

0.1.0

getClassPathGroup

default @Nullable PackageContainerGroup getClassPathGroup()

Get the location holding the class path.

Returns:

the location, or null if the location is not present in the file manager.

Since:

0.1.0

getSourcePathGroup

default @Nullable PackageContainerGroup getSourcePathGroup()

Get the location holding the source path.

Returns:

the location, or null if the location is not present in the file manager.

Since:

0.1.0

getAnnotationProcessorPathGroup

default @Nullable PackageContainerGroup getAnnotationProcessorPathGroup()

Get the location holding the annotation processor path.

Returns:

the location, or null if the location is not present in the file manager.

Since:

0.1.0

getAnnotationProcessorModulePathGroup

default @Nullable ModuleContainerGroup getAnnotationProcessorModulePathGroup()

Get the location holding the annotation processor module path.

Returns:

the location, or null if the location is not present in the file manager.

Since:

0.1.0

getModuleSourcePathGroup

default @Nullable ModuleContainerGroup getModuleSourcePathGroup()

Get the location holding the module source path.

Returns:

the location, or null if the location is not present in the file manager.

Since:

0.1.0

getModulePathGroup

default @Nullable ModuleContainerGroup getModulePathGroup()

Get the location holding the module path.

Returns:

the location, or null if the location is not present in the file manager.

Since:

0.1.0