Module io.github.ascopes.jct

Package io.github.ascopes.jct.containers

Interface Container

All Superinterfaces:

AutoCloseable, Closeable

@API(since="0.0.1",
     status=STABLE)
public interface Container
extends Closeable

Container that wraps a file path source of some description.

Closing this resource will close any internally held resources that were opened internally. Already-opened resources passed to the implementation will not be closed.

Since:

0.0.1

Author:

Ashley Scopes

Method Summary

Modifier and Type	Method	Description
boolean	contains(PathFileObject fileObject)	Determine if this container contains the path file object.
@Nullable Path	getFile(String... fragments)	Find the physical path to a given string file path.
@Nullable PathFileObject	getFileForInput(String packageName, String relativeName)	Get a FileObject for reading, if it exists.
@Nullable PathFileObject	getFileForOutput(String packageName, String relativeName)	Get a FileObject for writing.
PathRoot	getInnerPathRoot()	Get the inner path root of the container.
@Nullable PathFileObject	getJavaFileForInput(String className, JavaFileObject.Kind kind)	Get a JavaFileObject for reading, if it exists.
@Nullable PathFileObject	getJavaFileForOutput(String className, JavaFileObject.Kind kind)	Get a JavaFileObject for writing.
JavaFileManager.Location	getLocation()	Get the location of this container.
@Nullable ModuleFinder	getModuleFinder()	Get a module finder for this container.
String	getName()	Get the name of this container for human consumption.
PathRoot	getPathRoot()	Get the path root of the container.
@Nullable String	inferBinaryName(PathFileObject javaFileObject)	Infer the binary name of a given Java file object.
Collection<Path>	listAllFiles()	List all files within this container.
void	listFileObjects(String packageName, Set<? extends JavaFileObject.Kind> kinds, boolean recurse, Collection<JavaFileObject> collection)	List all the file objects that match the given criteria in this group.

Methods inherited from interface java.io.Closeable

close

Method Details

contains

boolean contains(PathFileObject fileObject)

Determine if this container contains the path file object.

Parameters:

fileObject - the file object to look up.

Returns:

true if the object exists in this container, or false otherwise.

getFile

@Nullable Path getFile(String... fragments)

Find the physical path to a given string file path.

Examples:

   // Using platform-specific separators ('/' for in-memory file systems).
   container.getFile("foo/bar/baz.txt");

   // Letting JCT infer the correct path separators to use.
   container.getFile("foo", "bar", "baz.txt");
 

Parameters:

fragments - parts of the file name to find.

Returns:

the path if the file exists, or null if it does not exist.

Throws:

NullPointerException - if any of the path fragments are null.

IllegalArgumentException - if there are no path fragments provided.

getFileForInput

@Nullable PathFileObject getFileForInput(String packageName,
 String relativeName)

Get a FileObject for reading, if it exists.

If the file does not exist, null is returned.

Parameters:

packageName - the package name of the file.

relativeName - the relative name of the file in the package.

Returns:

the file object, or null if it does not exist.

getFileForOutput

@Nullable PathFileObject getFileForOutput(String packageName,
 String relativeName)

Get a FileObject for writing.

If the container is read-only, null is returned.

Parameters:

packageName - the package name of the file.

relativeName - the relative name of the file in the package.

Returns:

the file object, or null if this container is read-only.

getInnerPathRoot

@API(since="0.0.6",
     status=STABLE)
PathRoot getInnerPathRoot()

Get the inner path root of the container.

This will usually be the same as the path root, but for archives, this will point to the root directory of the archive for the virtual file system it is loaded in, rather than the location of the archive on the original file system.

It is worth noting that this operation may result in the archive being loaded into memory eagerly if it uses lazy loading, due to the need to load the archive to be able to determine an accurate handle to the inner root directory.

Returns:

the path root.

Since:

0.0.6

getJavaFileForInput

@Nullable PathFileObject getJavaFileForInput(String className,
 JavaFileObject.Kind kind)

Get a JavaFileObject for reading, if it exists.

If the file does not exist, null is returned.

Parameters:

className - the binary name of the class to open.

kind - the kind of file to open.

Returns:

the file object, or null if it does not exist.

getJavaFileForOutput

@Nullable PathFileObject getJavaFileForOutput(String className,
 JavaFileObject.Kind kind)

Get a JavaFileObject for writing.

If the container is read-only, null is returned.

Parameters:

className - the binary name of the class to open.

kind - the kind of file to open.

Returns:

the file object, or null if this container is read-only.

getLocation

JavaFileManager.Location getLocation()

Get the location of this container.

Returns:

the location.

getModuleFinder

@Nullable ModuleFinder getModuleFinder()

Get a module finder for this container.

Note that this will not detect modules that are not yet compiled.

Returns:

the module finder for this container, or null if not relevant to the implementation.

getName

String getName()

Get the name of this container for human consumption.

Returns:

the container name.

getPathRoot

PathRoot getPathRoot()

Get the path root of the container.

Returns:

the path root.

inferBinaryName

@Nullable String inferBinaryName(PathFileObject javaFileObject)

Infer the binary name of a given Java file object.

Parameters:

javaFileObject - the Java file object to infer the binary name of.

Returns:

the name, or null if the file does not exist in this container.

listAllFiles

Collection<Path> listAllFiles()
                       throws IOException

List all files within this container.

Returns:

all files within the container, relative to the container base path.

Throws:

IOException - if the file system failed to be read.

listFileObjects

void listFileObjects(String packageName,
 Set<? extends JavaFileObject.Kind> kinds,
 boolean recurse,
 Collection<JavaFileObject> collection)
              throws IOException

List all the file objects that match the given criteria in this group.

The results are filled into a given collection, since this call may be made many times per compilation, and this reduces the memory overhead needed in such cases.

Parameters:

packageName - the package name to look in.

kinds - the kinds of file to look for. Set to Set.of(Kind.OTHER) to find all types of file.

recurse - true to recurse subpackages, false to only consider the given package.

collection - the collection to fill.

Throws:

IOException - if the file system failed to be read.