Interface JarContents

All Superinterfaces:
AutoCloseable, Closeable
All Known Implementing Classes:
CompositeJarContents, EmptyJarContents, FolderJarContents, JarFileContents
@NonExtendable public interface JarContents extends Closeable
Access to the contents of a list of Paths, interpreted as a jar file.

Relative Paths

To address files within jars, paths that are interpreted to be relative to the root of the jar file are used. The relative path for a class-file for class your.package.YourClass would be your/package/YourClass, for example.

  • Method Details

    • ofFilteredPaths

      static JarContents ofFilteredPaths(Collection<JarContents.FilteredPath> paths) throws IOException
      Creates jar contents from paths with optional per-path filters.

      Non-existent paths are ignored. If all paths are missing, throws NoSuchFileException.

      If only one valid unfiltered path is provided, behaves as ofPath(Path).

      Throws:
      IOException

    • ofPaths

      static JarContents ofPaths(Collection<Path> paths) throws IOException
      Creates jar contents from multiple paths, treating them as overlay layers.

      Later paths override earlier ones for conflicting files.

      Non-existent paths are ignored. If all paths are missing, throws NoSuchFileException.

      If only one valid path is provided, behaves as ofPath(Path).

      Throws:
      IOException

    • ofPath

      static JarContents ofPath(Path path) throws IOException
      Creates jar contents from a single path.

      The path must exist and be either a regular file (treated as a jar/zip) or a directory.

      Throws:
      IOException

    • empty

      static JarContents empty(Path path)
      Creates an empty jar contents instance.

      The path is used only as an identifier and need not exist.

      All content queries will return empty/null results.

    • getChecksum

      Optional<String> getChecksum()
      Returns SHA-256 hash of the contents, if available.

      This value is intended to be used as a cache-key, and will be empty if the jar contents are not stable enough to be cached (i.e. they're sourced from memory or a folder).

      Returns:
      SHA-256 hash of the contents, if available

    • getPrimaryPath

      Path getPrimaryPath()

    • getContentRoots

      Collection<Path> getContentRoots()
      Returns the locations that this Jar content was opened from.

      Usually this will only contain a single path, for example to the Jar file that was opened, but especially during development, it can contain multiple build output folders that were joined into a single virtual Jar file.

      The resulting paths do not need to be on the local file-system, they can be from custom NIO filesystem implementations.

      The returned list may also not contain all content roots if the underlying jar content is held in-memory.

    • get

      @Nullable @Nullable JarResource get(String relativePath)
      Tries to find a resource with the given path in this jar content.
      Parameters:
      relativePath - See JarContents for a definition of relative paths.
      Returns:
      Null if the resource could not be found within the jar, or if relativePath refers to a directory.

    • findFile

      Optional<URI> findFile(String relativePath)
      Looks for a file in the jar.
      Returns:
      A URI for the file, or empty if the file cannot be found or if relativePath refers to a directory.

    • openFile

      @Nullable @Nullable InputStream openFile(String relativePath) throws IOException
      Tries to open a file inside the jar content using a path relative to the root.

      The stream will not be buffered.

      The behavior when relativePath refers to a directory rather than a file is unspecified. The method may throw a IOException immediately, but may also defer this until the first byte is read from the stream. This behavior is filesystem provider specific.

      Returns:
      null if the file cannot be found
      Throws:
      IOException

    • readFile

      default byte @Nullable [] readFile(String relativePath) throws IOException
      A convenience method that opens a file and if the file was found, returns its content.

      Trying to read the contents of a directory using this method will throw an IOException.

      Returns:
      Null if the file does not exist.
      Throws:
      IOException

    • containsFile

      boolean containsFile(String relativePath)
      Checks, if a given file exists in this jar.
      Parameters:
      relativePath - The path to the file, relative to the root of this Jar file.
      Returns:
      True if the file exists, false if it doesn't or relativePath refers to a directory.

    • getManifest

      Manifest getManifest()
      Returns the manifest of the jar. Empty if no manifest is present in the jar.

      NOTE: Do not modify the returned manifest.

      Returns:
      the manifest of the jar

    • visitContent

      default void visitContent(JarResourceVisitor visitor)
      Visits all content found in this jar.

    • visitContent

      void visitContent(String startingFolder, JarResourceVisitor visitor)
      Visits all content found in this jar, starting in the given folder.

      If the folder does not exist, the visitor is not invoked and no error is raised.