Interface Container

All Superinterfaces:
AutoCloseable, Closeable
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.

Author:
Ashley Scopes

  • 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

      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.