Package org.apache.tomcat

# Interface Jar

All Superinterfaces:
  `AutoCloseable`

All Known Implementing Classes:
  `AbstractInputStreamJar`, `JarFileUrlJar`, `JarFileUrlNestedJar`, `ReferenceCountedJar`, `UrlJar`

public interface Jar extends AutoCloseable
Provides an abstraction for use by the various classes that need to scan JARs. The classes provided by the JRE for accessing JARs (`JarFile` and `JarInputStream`) have significantly different performance characteristics depending on the form of the URL used to access the JAR. For file based JAR `URL`s, `JarFile` is faster but for non-file based `URL`s, `JarFile` creates a copy of the JAR in the temporary directory so `JarInputStream` is faster.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  Close any resources associated with this JAR.
  `boolean`
  `exists(String name)`
  Determine if the given resource in present in the JAR.
  `InputStream`
  `getEntryInputStream()`
  Obtains the input stream for the current entry.
  `String`
  `getEntryName()`
  Obtains the name of the current entry.
  `InputStream`
  `getInputStream(String name)`
  Obtain an `InputStream` for a given entry in a JAR.
  `URL`
  `getJarFileURL()`
  `long`
  `getLastModified(String name)`
  Obtain the last modified time for the given resource in the JAR.
  `Manifest`
  `getManifest()`
  Obtain the manifest for the JAR file.
  `String`
  `getURL(String entry)`
  Obtain, in String form, the URL for an entry in this JAR.
  `void`
  `nextEntry()`
  Moves the internal pointer to the next entry in the JAR.
  `void`
  `reset()`
  Resets the internal pointer used to track JAR entries to the beginning of the JAR.

- ## Method Details

  - ### getJarFileURL

    URL getJarFileURL()
    Returns:
      The URL for accessing the JAR file.

  - ### getInputStream

    InputStream getInputStream(String name) throws IOException
    Obtain an `InputStream` for a given entry in a JAR. The caller is responsible for closing the stream.
    Parameters:
      `name` - Entry to obtain an `InputStream` for
    Returns:
      An `InputStream` for the specified entry or null if the entry does not exist
    Throws:
      `IOException` - if an I/O error occurs while processing the JAR file

  - ### getLastModified

    long getLastModified(String name) throws IOException
    Obtain the last modified time for the given resource in the JAR.
    Parameters:
      `name` - Entry to obtain the modification time for
    Returns:
      The time (in the same format as `System.currentTimeMillis()` that the resource was last modified. Returns -1 if the entry does not exist
    Throws:
      `IOException` - if an I/O error occurs while processing the JAR file

  - ### exists

    boolean exists(String name) throws IOException
    Determine if the given resource in present in the JAR.
    Parameters:
      `name` - Entry to look for
    Returns:
      `true` if the entry is present in the JAR, otherwise `false`
    Throws:
      `IOException` - if an I/O error occurs while processing the JAR file

  - ### close

    void close()
    Close any resources associated with this JAR.
    Specified by:
      `close` in interface `AutoCloseable`

  - ### nextEntry

    void nextEntry()
    Moves the internal pointer to the next entry in the JAR.

  - ### getEntryName

    String getEntryName()
    Obtains the name of the current entry.
    Returns:
      The entry name

  - ### getEntryInputStream

    InputStream getEntryInputStream() throws IOException
    Obtains the input stream for the current entry.
    Returns:
      The input stream
    Throws:
      `IOException` - If the stream cannot be obtained

  - ### getURL

    String getURL(String entry)
    Obtain, in String form, the URL for an entry in this JAR. Note that for JARs nested in WAR files, the Tomcat specific war:file:... form will not be used, rather the jar:jar:file:... form (that the JRE does not understand will be used). Note that this means that any code using these URLs will need to understand the jar:jar:file:... form and use the `JarFactory` to ensure resources are accessed correctly.
    Parameters:
      `entry` - The entry to generate the URL for
    Returns:
      a URL for the specified entry in the JAR

  - ### getManifest

    Manifest getManifest() throws IOException
    Obtain the manifest for the JAR file.
    Returns:
      The manifest for this JAR file.
    Throws:
      `IOException` - If an I/O error occurs trying to obtain the manifest

  - ### reset

    void reset() throws IOException
    Resets the internal pointer used to track JAR entries to the beginning of the JAR.
    Throws:
      `IOException` - If the pointer cannot be reset