Module io.github.ascopes.jct
Package io.github.ascopes.jct.containers

Interface PackageContainerGroup

All Superinterfaces:
AutoCloseable, Closeable, ContainerGroup
All Known Subinterfaces:
OutputContainerGroup
@API(since="0.0.1", status=EXPERIMENTAL) public interface PackageContainerGroup extends ContainerGroup
Base interface representing a group of package-oriented paths.
Since:
0.0.1
Author:
Ashley Scopes

  • Method Details

    • addPackage

      void addPackage(@WillCloseWhenClosed Container container)
      Add a container to this group.

      The provided container will be closed when this group is closed.

      Parameters:
      container - the container to add.

    • addPackage

      void addPackage(@WillNotClose PathRoot path)
      Add a path to this group.

      Note that this will destroy the classloader if one is already allocated.

      If the path points to some form of archive (such as a JAR), then this may open that archive in a new resource internally. If this occurs, then the resource will always be freed by this class by calling Closeable.close().

      Any other closable resources passed to this function will not be closed by this implementation. You must handle the lifecycle of those objects yourself.

      Parameters:
      path - the path to add.

    • getClassLoader

      ClassLoader getClassLoader()
      Get a class loader for this group of containers.

      Note that adding additional containers to this group after accessing this class loader may result in the class loader being destroyed or re-created.

      Returns:
      the class loader.

    • getFile

      @Nullable Path getFile(String fragment, String... fragments)
      Find the first occurrence of a given path to a file in packages or modules.

      Modules are treated as subdirectories.

      Parameters:
      fragment - the first part of the path.
      fragments - any additional parts of the path.
      Returns:
      the first occurrence of the path in this group, or null if not found.
      Throws:
      IllegalArgumentException - if the provided path is absolute.

    • getFileForInput

      @Nullable PathFileObject getFileForInput(String packageName, String relativeName)
      Get a FileObject that can have content read from it.

      This will return null if no file is found matching the criteria.

      Parameters:
      packageName - the package name of the file to read.
      relativeName - the relative name of the file to read.
      Returns:
      the file object, or null if the file is not found.

    • getFileForOutput

      @Nullable PathFileObject getFileForOutput(String packageName, String relativeName)
      Get a FileObject that can have content written to it for the given file.

      This will attempt to write to the first writeable path in this group. null will be returned if no writeable paths exist in this group.

      Parameters:
      packageName - the name of the package the file is in.
      relativeName - the relative name of the file within the package.
      Returns:
      the FileObject to write to, or null if this group has no paths that can be written to.

    • getJavaFileForInput

      @Nullable PathFileObject getJavaFileForInput(String className, JavaFileObject.Kind kind)
      Get a JavaFileObject that can have content read from it for the given file.

      This will return null if no file is found matching the criteria.

      Parameters:
      className - the binary name of the class to read.
      kind - the kind of file to read.
      Returns:
      the JavaFileObject to write to, or null if this group has no paths that can be written to.

    • getJavaFileForOutput

      @Nullable PathFileObject getJavaFileForOutput(String className, JavaFileObject.Kind kind)
      Get a JavaFileObject that can have content written to it for the given class.

      This will attempt to write to the first writeable path in this group. null will be returned if no writeable paths exist in this group.

      Parameters:
      className - the name of the class.
      kind - the kind of the class file.
      Returns:
      the JavaFileObject to write to, or null if this group has no paths that can be written to.

    • getLocation

      JavaFileManager.Location getLocation()
      Get the package-oriented location that this group of paths is for.
      Specified by:
      getLocation in interface ContainerGroup
      Returns:
      the package-oriented location.

    • getPackages

      Collection<Container> getPackages()
      Get the package containers in this group.
      Returns:
      the containers.

    • inferBinaryName

      @Nullable String inferBinaryName(PathFileObject fileObject)
      Try to infer the binary name of a given file object.
      Parameters:
      fileObject - the file object to infer the binary name for.
      Returns:
      the binary name if known, or null otherwise.

    • isEmpty

      boolean isEmpty()
      Determine if this group has no paths registered.
      Returns:
      true if no paths are registered. false if paths are registered.

    • 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.
      Parameters:
      packageName - the package name to look in.
      kinds - the kinds of file to look for.
      recurse - true to recurse subpackages, false to only consider the given package.
      collection - the collection to fill.
      Throws:
      IOException - if the file lookup fails due to an IO exception.