Interface Workspace

All Superinterfaces:

AutoCloseable

public interface Workspace
extends AutoCloseable

Interface for a Workspace to hold files and directories within.

This acts as a nexus for managing the lifetime of test sources and directories, and should be used within a try-with-resources block to ensure temporary files get released after the test completes.

While this interface may seem somewhat intimidating due to the number of methods it provides, you will usually only ever need to use a small subset of them. The main ones you probably will want to use are:

• addSourcePathPackage(Path) - for copying a source path tree from your file system.
• createSourcePathPackage() - for creating a new source path tree.
• addClassPathPackage(Path) - for adding a class path resource (usually a JAR or a directory of packages of classes).
• addModulePathModule(String, Path) - for adding a module path resource (usually a JAR or a directory of packages of classes).
• getClassPathPackages() - for fetching all class path resources.
• getModulePathModules() - for fetching all module path resources.
• getSourceOutputPackages() - for fetching all generated source packages.
• getSourceOutputModules() - for fetching all generated source modules.
• close() - to close any resources in the temporary file system.

A simple example of usage of this interface would be the following:

 try (Workspace workspace = Workspaces.newWorkspace()) {
   workspace
      .createSourcePathPackage()
      .copyContentsFrom("src", "test", "resources", "test-data");

   var compilation = someCompiler.compile(workspace);

   assertThat(compilation).isSuccessful();
 }
 

As of 3.2.0, you can use a functional version of the above instead if this is more suitable for your use-case:

 Workspaces.newWorkspace().use(workspace -> {
   ...
 });
 

Remember that files that are created as the result of a compilation can be queried via JctFileManager, which is accessible on the compilation result object. This may more accurately represent the logical project structure that is the result of various processing operations during compilation.

Since:

0.0.1

Author:

Ashley Scopes

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	Workspace.ThrowingWorkspaceConsumer<T extends Throwable>	A consumer functional interface that consumes a workspace and can throw a checked exception.

Method Summary

Modifier and Type	Method	Description
default void	addAnnotationProcessorPathModule(String moduleName, Path path)	Add a module to the annotation processor module path.
default void	addAnnotationProcessorPathPackage(Path path)	Add a package to the annotation processor path.
default void	addClassOutputModule(String moduleName, Path path)	Add a module to the class outputs.
default void	addClassOutputPackage(Path path)	Add a package to the class outputs.
default void	addClassPathPackage(Path path)	Add a package to the class path.
void	addModule(JavaFileManager.Location location, String moduleName, Path path)	Add an existing package root to this workspace and associate it with the given module name in the given location.
default void	addModulePathModule(String moduleName, Path path)	Add a module to the module path.
void	addPackage(JavaFileManager.Location location, Path path)	Add an existing package root to this workspace and associate it with the given location.
default void	addSourceOutputModule(String moduleName, Path path)	Add a module to the generated source outputs.
default void	addSourceOutputPackage(Path path)	Add a package to the generated source outputs.
default void	addSourcePathModule(String moduleName, Path path)	Add a module to the module source path.
default void	addSourcePathPackage(Path path)	Add a package to the legacy source path.
void	close()	Attempt to close all resources in this workspace.
default ManagedDirectory	createAnnotationProcessorPathModule(String moduleName)	Create a module in the annotation processor module path.
default ManagedDirectory	createAnnotationProcessorPathPackage()	Create a package in the annotation processor path.
default ManagedDirectory	createClassOutputModule(String moduleName)	Create a module in the class outputs.
default ManagedDirectory	createClassOutputPackage()	Create a package in the class outputs.
default ManagedDirectory	createClassPathPackage()	Create a package in the class path.
ManagedDirectory	createModule(JavaFileManager.Location location, String moduleName)	Create a new test directory for a package root and associate it with the given module name in the given location.
default ManagedDirectory	createModulePathModule(String moduleName)	Create a module in the module path.
ManagedDirectory	createPackage(JavaFileManager.Location location)	Create a new test directory for a package root and associate it with the given location.
default ManagedDirectory	createSourceOutputModule(String moduleName)	Create a module in the generated source outputs.
default ManagedDirectory	createSourceOutputPackage()	Create a package in the generated source outputs.
default ManagedDirectory	createSourcePathModule(String moduleName)	Create a module in the module source path.
default ManagedDirectory	createSourcePathPackage()	Create a package in the source path.
Map<JavaFileManager.Location,List<? extends PathRoot>>	getAllPaths()	Get an immutable copy of the current paths to operate on.
default List<? extends PathRoot>	getAnnotationProcessorPathModule(String moduleName)	Get the path roots for the annotation processor module path.
default Map<String,List<? extends PathRoot>>	getAnnotationProcessorPathModules()	Get the module path roots for the annotation processor module path.
default List<? extends PathRoot>	getAnnotationProcessorPathPackages()	Get the path roots for the annotation processor path.
default List<? extends PathRoot>	getClassOutputModule(String moduleName)	Get the module path roots for class outputs for the given module name.
default Map<String,List<? extends PathRoot>>	getClassOutputModules()	Get the module path roots for class outputs.
default List<? extends PathRoot>	getClassOutputPackages()	Get the non-module path roots for class outputs.
default List<? extends PathRoot>	getClassPathPackages()	Get the path roots for the class path.
List<? extends PathRoot>	getModule(JavaFileManager.Location location, String moduleName)	Get the collection of path roots associated with the given module.
default List<? extends PathRoot>	getModulePathModule(String moduleName)	Get the path roots for the module path.
default Map<String,List<? extends PathRoot>>	getModulePathModules()	Get the module path roots for the module paths.
Map<String,List<? extends PathRoot>>	getModules(JavaFileManager.Location location)	Get the collection of modules associated with the given location.
List<? extends PathRoot>	getPackages(JavaFileManager.Location location)	Get the collection of path roots associated with the given location.
PathStrategy	getPathStrategy()	Get the path strategy in use.
default List<? extends PathRoot>	getSourceOutputModule(String moduleName)	Get the module path roots for source outputs for the given module name.
default Map<String,List<? extends PathRoot>>	getSourceOutputModules()	Get the module path roots for source outputs.
default List<? extends PathRoot>	getSourceOutputPackages()	Get the non-module path roots for source outputs.
default List<? extends PathRoot>	getSourcePathModule(String moduleName)	Get the path roots for the module source path.
default Map<String,List<? extends PathRoot>>	getSourcePathModules()	Get the module path roots for the module source paths.
default List<? extends PathRoot>	getSourcePathPackages()	Get the path roots for the source path.
boolean	isClosed()	Determine if the workspace is closed or not.
default <T extends Throwable> void	use(Workspace.ThrowingWorkspaceConsumer<T> consumer)	Functional equivalent of consuming this object with a try-with-resources.

Method Details

close

void close()

Attempt to close all resources in this workspace.

Specified by:

close in interface AutoCloseable

Throws:

UncheckedIOException - if an error occurs.

isClosed

boolean isClosed()

Determine if the workspace is closed or not.

Returns:

true if closed, false if open.

Since:

0.4.0

getAllPaths

Map<JavaFileManager.Location,List<? extends PathRoot>> getAllPaths()

Get an immutable copy of the current paths to operate on.

Returns:

the paths.

getModule

List<? extends PathRoot> getModule(JavaFileManager.Location location,
 String moduleName)

Get the collection of path roots associated with the given module.

Usually this should only ever contain one path root at a maximum, although Workspace does not explicitly enforce this constraint.

If no results were found, then an empty collection is returned.

Parameters:

location - the module-oriented or output location.

moduleName - the module name within the location.

Returns:

the collection of paths.

Throws:

IllegalArgumentException - if the location is neither module-oriented or an output location. This will also be raised if this method is called with an instance of ModuleLocation (you should use getPackages(Location) instead for this).

Since:

0.1.0

See Also:

• getPackages(Location)
• getModules(Location)

getModules

Map<String,List<? extends PathRoot>> getModules(JavaFileManager.Location location)

Get the collection of modules associated with the given location.

If no results were found, then an empty map is returned.

Parameters:

location - the location to get the modules for.

Returns:

the map of module names to lists of associated paths.

Throws:

IllegalArgumentException - if the location is neither module-oriented or an output location. This will also be raised if this method is called with an instance of ModuleLocation.

Since:

0.1.0

See Also:

• getModule(Location, String)

getPathStrategy

PathStrategy getPathStrategy()

Get the path strategy in use.

Returns:

the path strategy.

getPackages

List<? extends PathRoot> getPackages(JavaFileManager.Location location)

Get the collection of path roots associated with the given location.

If no results were found, then an empty collection is returned.

Parameters:

location - the location to get.

Returns:

the collection of paths.

Throws:

IllegalArgumentException - if the location is module-oriented.

Since:

0.1.0

See Also:

• getModule(Location, String)

addPackage

void addPackage(JavaFileManager.Location location,
 Path path)

Add an existing package root to this workspace and associate it with the given location.

The following constraints must be met, otherwise an IllegalArgumentException will be thrown:

• The location must not be module-oriented.
• The path must exist.

For example, this would add the package tree in src/test/resources/packages into the source code path that is used to compile files:

   var path = Path.of("src", "test", "resources", "packages");
   workspace.addPackage(StandardLocation.SOURCE_PATH, path);
 

Parameters:

location - the location to associate with.

path - the path to add.

Throws:

IllegalArgumentException - if the inputs are invalid.

See Also:

• addModule(Location, String, Path)
• createPackage(Location)
• createModule(Location, String)

addModule

void addModule(JavaFileManager.Location location,
 String moduleName,
 Path path)

Add an existing package root to this workspace and associate it with the given module name in the given location.

The following constraints must be met, otherwise an IllegalArgumentException will be thrown:

• The location must be module-oriented or an output location.
• The location must not be a module-location handle already.
• The path must exist.

For example, this would add the package tree in src/test/resources/packages into the module source code path under the module name foo.bar:

   var path = Path.of("src", "test", "resources", "packages");
   workspace.addModule(StandardLocation.MODULE_SOURCE_PATH, "foo.bar", path);
 

Parameters:

location - the location to associate with.

moduleName - the name of the module.

path - the path to add.

Throws:

IllegalArgumentException - if the inputs are invalid.

See Also:

• addPackage(Location, Path)
• createPackage(Location)
• createModule(Location, String)

createPackage

ManagedDirectory createPackage(JavaFileManager.Location location)

Create a new test directory for a package root and associate it with the given location.

This path will be destroyed when the workspace is closed.

The following constraints must be met, otherwise an IllegalArgumentException will be thrown:

• The location must not be module-oriented.

For example, this would create a new source root that you could add files to:

   workspace.createPackage(StandardLocation.SOURCE_PATH);
 

Parameters:

location - the location to associate with.

Returns:

the test directory that was created.

Throws:

IllegalArgumentException - if the inputs are invalid.

See Also:

• createModule(Location, String)
• addPackage(Location, Path)
• addModule(Location, String, Path)

createModule

ManagedDirectory createModule(JavaFileManager.Location location,
 String moduleName)

Create a new test directory for a package root and associate it with the given module name in the given location.

This path will be destroyed when the workspace is closed.

The following constraints must be met, otherwise an IllegalArgumentException will be thrown:

• The location must be module-oriented or an output location.
• The location must not be a module-location handle already.

For example, this would create a new multi-module source root that you could add files to, for a module named foo.bar:

   workspace.createModule(StandardLocation.MODULE_SOURCE_PATH, "foo.bar");
 

Parameters:

location - the location to associate with.

moduleName - the module name to use.

Returns:

the test directory that was created.

Throws:

IllegalArgumentException - if the inputs are invalid.

See Also:

• createPackage(Location)
• addPackage(Location, Path)
• addModule(Location, String, Path)

addClassOutputPackage

default void addClassOutputPackage(Path path)

Add a package to the class outputs.

Parameters:

path - the path to add.

Throws:

IllegalArgumentException - if the path does not exist.

See Also:

• addPackage(Location, Path)
• addClassOutputModule(String, Path)
• createClassOutputPackage()
• createClassOutputModule(String)

addClassOutputModule

default void addClassOutputModule(String moduleName,
 Path path)

Add a module to the class outputs.

Parameters:

moduleName - the module name.

path - the path to add.

Throws:

IllegalArgumentException - if the path does not exist.

See Also:

• addModule(Location, String, Path)
• addClassOutputPackage(Path)
• createClassOutputPackage()
• createClassOutputModule(String)

addSourceOutputPackage

default void addSourceOutputPackage(Path path)

Add a package to the generated source outputs.

Parameters:

path - the path to add.

Throws:

IllegalArgumentException - if the path does not exist.

See Also:

• addPackage(Location, Path)
• addSourceOutputModule(String, Path)
• createSourceOutputPackage()
• createSourceOutputModule(String)

addSourceOutputModule

default void addSourceOutputModule(String moduleName,
 Path path)

Add a module to the generated source outputs.

Parameters:

moduleName - the module name.

path - the path to add.

Throws:

IllegalArgumentException - if the path does not exist.

See Also:

• addModule(Location, String, Path)
• addSourceOutputPackage(Path)
• createSourceOutputPackage()
• createSourceOutputModule(String)

addClassPathPackage

default void addClassPathPackage(Path path)

Add a package to the class path.

If you are adding JPMS modules, you may want to use addModulePathModule(String, Path) instead.

Parameters:

path - the path to add.

Throws:

IllegalArgumentException - if the path does not exist.

See Also:

• addPackage(Location, Path)
• addModulePathModule(String, Path)
• createClassPathPackage()
• createModulePathModule(String)

addModulePathModule

default void addModulePathModule(String moduleName,
 Path path)

Add a module to the module path.

If you are adding non-JPMS modules, you may want to use addClassPathPackage(Path) instead.

Parameters:

moduleName - the module name.

path - the path to add.

Throws:

IllegalArgumentException - if the path does not exist.

See Also:

• addModule(Location, String, Path)
• addClassPathPackage(Path)
• createClassPathPackage()
• createModulePathModule(String)

addSourcePathPackage

default void addSourcePathPackage(Path path)

Add a package to the legacy source path.

This is the location you will usually tend to use for your source code.

If you wish to define multiple JPMS modules in your source code tree to compile together, you will want to consider using addSourcePathModule(String, Path) instead. For most purposes, however, this method is the one you will want to be using if your code is not in a named module directory (so not something like src/my.module/org/example/...).

Parameters:

path - the path to add.

Throws:

IllegalArgumentException - if the path does not exist.

See Also:

• addPackage(Location, Path)
• addSourcePathModule(String, Path)
• createSourcePathPackage()
• createSourcePathModule(String)

addSourcePathModule

default void addSourcePathModule(String moduleName,
 Path path)

Add a module to the module source path.

Note that this will signal to the compiler to run in multi-module compilation mode. Any source packages that were added or created will be ignored.

If you are using a single-module, you can add a source package and include a module-info.java in the base directory instead.

Parameters:

moduleName - the module name.

path - the path to add.

Throws:

IllegalArgumentException - if the path does not exist.

See Also:

• addModule(Location, String, Path)
• addSourcePathPackage(Path)
• createSourcePathPackage()
• createSourcePathModule(String)

addAnnotationProcessorPathPackage

default void addAnnotationProcessorPathPackage(Path path)

Add a package to the annotation processor path.

Note that this will be ignored if the compiler is provided with explicit annotation processor instances to run.

Parameters:

path - the path to add.

Throws:

IllegalArgumentException - if the path does not exist.

See Also:

• addPackage(Location, Path)
• addAnnotationProcessorPathModule(String, Path)
• createAnnotationProcessorPathPackage()
• createAnnotationProcessorPathModule(String)

addAnnotationProcessorPathModule

default void addAnnotationProcessorPathModule(String moduleName,
 Path path)

Add a module to the annotation processor module path.

Note that this will be ignored if the compiler is provided with explicit annotation processor instances to run.

Parameters:

moduleName - the module name.

path - the path to add.

Throws:

IllegalArgumentException - if the path does not exist.

See Also:

• addModule(Location, String, Path)
• addAnnotationProcessorPathPackage(Path)
• createAnnotationProcessorPathPackage()
• createAnnotationProcessorPathModule(java.lang.String)

createClassOutputPackage

default ManagedDirectory createClassOutputPackage()

Create a package in the class outputs.

Returns:

the created test directory.

See Also:

• createPackage(Location)
• createClassOutputModule(String)
• addClassOutputPackage(Path)
• addClassOutputModule(String, Path)

createClassOutputModule

default ManagedDirectory createClassOutputModule(String moduleName)

Create a module in the class outputs.

Parameters:

moduleName - the module name.

Returns:

the created test directory.

See Also:

• createModule(Location, String)
• createClassOutputPackage()
• addClassOutputPackage(Path)
• addClassOutputModule(String, Path)

createSourceOutputPackage

default ManagedDirectory createSourceOutputPackage()

Create a package in the generated source outputs.

Returns:

the created test directory.

See Also:

• createPackage(Location)
• createSourceOutputModule(String)
• addSourceOutputPackage(Path)
• addSourceOutputModule(String, Path)

createSourceOutputModule

default ManagedDirectory createSourceOutputModule(String moduleName)

Create a module in the generated source outputs.

Parameters:

moduleName - the module name.

Returns:

the created test directory.

See Also:

• createModule(Location, String)
• createSourceOutputPackage()
• addSourceOutputPackage(Path)
• addSourceOutputModule(String, Path)

createClassPathPackage

default ManagedDirectory createClassPathPackage()

Create a package in the class path.

If you are adding JPMS modules, you may want to use createModulePathModule(String) instead.

Returns:

the created test directory.

See Also:

• createPackage(Location)
• createModulePathModule(String)
• addClassPathPackage(Path)
• addModulePathModule(String, Path)

createModulePathModule

default ManagedDirectory createModulePathModule(String moduleName)

Create a module in the module path.

If you are adding non-JPMS modules, you may want to use createClassPathPackage() instead.

Parameters:

moduleName - the module name.

Returns:

the created test directory.

See Also:

• createModule(Location, String)
• createClassPathPackage()
• addModulePathModule(String, Path)
• addClassPathPackage(Path)

createSourcePathPackage

default ManagedDirectory createSourcePathPackage()

Create a package in the source path.

If you wish to define multiple JPMS modules in your source code tree to compile together, you will want to consider using createSourcePathModule(String) instead. For most purposes, however, this method is the one you will want to be using if your code is not in a named module directory (so not something like src/my.module/org/example/...).

Returns:

the created test directory.

See Also:

• createPackage(Location)
• createSourcePathModule(String)
• addSourcePathPackage(Path)
• addSourcePathModule(String, Path)

createSourcePathModule

default ManagedDirectory createSourcePathModule(String moduleName)

Create a module in the module source path.

Note that this will signal to the compiler to run in multi-module compilation mode. Any source packages that were created or added will be ignored.

If you are using a single-module, you can create a source package and include a module-info.java in the base directory instead.

Parameters:

moduleName - the module name.

Returns:

the created test directory.

See Also:

• createModule(Location, String)
• createSourcePathPackage()
• addSourcePathPackage(Path)
• addSourcePathModule(String, Path)

createAnnotationProcessorPathPackage

default ManagedDirectory createAnnotationProcessorPathPackage()

Create a package in the annotation processor path.

Note that this will be ignored if the compiler is provided with explicit annotation processor instances to run.

Returns:

the created test directory.

See Also:

• createPackage(Location)
• createAnnotationProcessorPathModule(String)
• addAnnotationProcessorPathPackage(Path)
• addAnnotationProcessorPathModule(String, Path)

createAnnotationProcessorPathModule

default ManagedDirectory createAnnotationProcessorPathModule(String moduleName)

Create a module in the annotation processor module path.

Note that this will be ignored if the compiler is provided with explicit annotation processor instances to run.

Parameters:

moduleName - the module name.

Returns:

the created test directory.

See Also:

• createModule(Location, String)
• createAnnotationProcessorPathPackage()
• addAnnotationProcessorPathPackage(Path)
• addAnnotationProcessorPathModule(String, Path)

getClassOutputPackages

default List<? extends PathRoot> getClassOutputPackages()

Get the non-module path roots for class outputs.

Returns:

the roots in a collection, or an empty collection if none were found.

Since:

0.1.0

getClassOutputModule

default List<? extends PathRoot> getClassOutputModule(String moduleName)

Get the module path roots for class outputs for the given module name.

Parameters:

moduleName - the module name.

Returns:

the roots in a collection, or an empty collection if none were found.

Since:

0.1.0

getClassOutputModules

default Map<String,List<? extends PathRoot>> getClassOutputModules()

Get the module path roots for class outputs.

Returns:

the roots in a map of module names to lists of roots, or an empty map if none were found.

Since:

0.1.0

getSourceOutputPackages

default List<? extends PathRoot> getSourceOutputPackages()

Get the non-module path roots for source outputs.

Returns:

the roots in a collection, or an empty collection if none were found.

Since:

0.1.0

getSourceOutputModule

default List<? extends PathRoot> getSourceOutputModule(String moduleName)

Get the module path roots for source outputs for the given module name.

Parameters:

moduleName - the module name.

Returns:

the roots in a collection, or an empty collection if none were found.

Since:

0.1.0

getSourceOutputModules

default Map<String,List<? extends PathRoot>> getSourceOutputModules()

Get the module path roots for source outputs.

Returns:

the roots in a map of module names to lists of roots, or an empty map if none were found.

Since:

0.1.0

getClassPathPackages

default List<? extends PathRoot> getClassPathPackages()

Get the path roots for the class path.

Returns:

the roots in a collection, or an empty collection if none were found.

Since:

0.1.0

getSourcePathPackages

default List<? extends PathRoot> getSourcePathPackages()

Get the path roots for the source path.

Returns:

the roots in a collection, or an empty collection if none were found.

Since:

0.1.0

getAnnotationProcessorPathPackages

default List<? extends PathRoot> getAnnotationProcessorPathPackages()

Get the path roots for the annotation processor path.

Returns:

the roots in a collection, or an empty collection if none were found.

Since:

0.1.0

getAnnotationProcessorPathModule

default List<? extends PathRoot> getAnnotationProcessorPathModule(String moduleName)

Get the path roots for the annotation processor module path.

Parameters:

moduleName - the module name to get.

Returns:

the roots in a collection, or an empty collection if none were found.

Since:

0.1.0

getAnnotationProcessorPathModules

default Map<String,List<? extends PathRoot>> getAnnotationProcessorPathModules()

Get the module path roots for the annotation processor module path.

Returns:

the roots in a map of module names to lists of roots, or an empty map if none were found.

Since:

0.1.0

getSourcePathModule

default List<? extends PathRoot> getSourcePathModule(String moduleName)

Get the path roots for the module source path.

Parameters:

moduleName - the module name to get.

Returns:

the roots in a collection, or an empty collection if none were found.

Since:

0.1.0

getSourcePathModules

default Map<String,List<? extends PathRoot>> getSourcePathModules()

Get the module path roots for the module source paths.

Returns:

the roots in a map of module names to lists of roots, or an empty map if none were found.

Since:

0.1.0

getModulePathModule

default List<? extends PathRoot> getModulePathModule(String moduleName)

Get the path roots for the module path.

Parameters:

moduleName - the module name to get.

Returns:

the roots in a collection, or an empty collection if none were found.

Since:

0.1.0

getModulePathModules

default Map<String,List<? extends PathRoot>> getModulePathModules()

Get the module path roots for the module paths.

Returns:

the roots in a map of module names to lists of roots, or an empty map if none were found.

Since:

0.1.0

use

default <T extends Throwable> void use(Workspace.ThrowingWorkspaceConsumer<T> consumer)
                                throws T

Functional equivalent of consuming this object with a try-with-resources.

This workspace will be closed upon completion of this method or upon an exception being raised.

Type Parameters:

T - the exception that the consumer can throw, or RuntimeException if no checked exception is thrown.

Parameters:

consumer - the consumer to pass this object to.

Throws:

UncheckedIOException - if the closure fails after the consumer is called.

T - the checked exception that the consumer can throw.

Since:

3.2.0