/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.tomcat;

import java.io.IOException;
import java.io.InputStream;
import java.net.URL;
import java.util.jar.Manifest;

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 URLs, JarFile is faster but for non-file based URLs, JarFile creates a copy of the JAR in the temporary directory so JarInputStream is faster. /**
 * Provides an abstraction for use by the various classes that need to scan
 * JARs. The classes provided by the JRE for accessing JARs
 * ({@link java.util.jar.JarFile} and {@link java.util.jar.JarInputStream}) have
 * significantly different performance characteristics depending on the form of
 * the URL used to access the JAR. For file based JAR {@link java.net.URL}s,
 * {@link java.util.jar.JarFile} is faster but for non-file based
 * {@link java.net.URL}s, {@link java.util.jar.JarFile} creates a copy of the
 * JAR in the temporary directory so {@link java.util.jar.JarInputStream} is
 * faster.
 */
public interface Jar extends AutoCloseable {

    
Returns:
The URL for accessing the JAR file./**
     * @return The URL for accessing the JAR file.
     */
    URL getJarFileURL();

    
Obtain an InputStream for a given entry in a JAR. The caller is responsible for closing the stream. 
Params:
name –  Entry to obtain an InputStream for
Throws:
IOException – if an I/O error occurs while processing the JAR file
Returns:
 An InputStream for the specified entry or null if the entry does not exist/**
     * Obtain an {@link InputStream} for a given entry in a JAR. The caller is
     * responsible for closing the stream.
     *
     * @param name  Entry to obtain an {@link InputStream} for
     * @return      An {@link 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
     */
    InputStream getInputStream(String name) throws IOException;

    
Obtain the last modified time for the given resource in the JAR.
Params:
name –  Entry to obtain the modification time for
Throws:
IOException – if an I/O error occurs while processing the JAR file
Returns:
The time (in the same format as System.currentTimeMillis() that the resource was last modified. Returns -1 if the entry does not exist/**
     * Obtain the last modified time for the given resource in the JAR.
     *
     * @param name  Entry to obtain the modification time for
     *
     * @return The time (in the same format as
     *         {@link 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
     */
    long getLastModified(String name) throws IOException;

    
Determine if the given resource in present in the JAR.
Params:
name –  Entry to look for
Throws:
IOException – if an I/O error occurs while processing the JAR file
Returns:
true if the entry is present in the JAR, otherwise false/**
     * Determine if the given resource in present in the JAR.
     *
     * @param name  Entry to look for
     *
     * @return {@code true} if the entry is present in the JAR, otherwise
     *         {@code false}
     *
     * @throws IOException if an I/O error occurs while processing the JAR file
     */
    boolean exists(String name) throws IOException;

    
Close any resources associated with this JAR.
/**
     * Close any resources associated with this JAR.
     */
    @Override
    void close();

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

    
Obtains the name of the current entry.
Returns:
 The entry name/**
     * Obtains the name of the current entry.
     *
     * @return  The entry name
     */
    String getEntryName();

    
Obtains the input stream for the current entry.
Throws:
IOException –  If the stream cannot be obtained
Returns:
 The input stream/**
     * Obtains the input stream for the current entry.
     *
     * @return  The input stream
     * @throws IOException  If the stream cannot be obtained
     */
    InputStream getEntryInputStream() throws IOException;

    
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. 
Params:
entry – The entry to generate the URL for
Returns:
a URL for the specified entry in the JAR/**
     * 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
     * {@link org.apache.tomcat.util.scan.JarFactory} to ensure resources are
     * accessed correctly.
     *
     * @param entry The entry to generate the URL for
     *
     * @return a URL for the specified entry in the JAR
     */
    String getURL(String entry);

    
Obtain the manifest for the JAR file.
Throws:
IOException – If an I/O error occurs trying to obtain the manifest
Returns:
The manifest for this JAR file./**
     * Obtain the manifest for the JAR file.
     *
     * @return The manifest for this JAR file.
     *
     * @throws IOException If an I/O error occurs trying to obtain the manifest
     */
    Manifest getManifest() 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/**
     * Resets the internal pointer used to track JAR entries to the beginning of
     * the JAR.
     *
     * @throws IOException  If the pointer cannot be reset
     */
    void reset() throws IOException;
}