de.schlichtherle.io.archive.spi.InputArchive Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of truezip Show documentation
TrueZIP is a Java based Virtual File System (VFS) to enable transparent, multi-threaded read/write access to archive files (ZIP, TAR etc.) as if they were directories. Archive files may be arbitrarily nested and the nesting level is only limited by heap and file system size.
The newest version!
/*
 * Copyright (C) 2006-2010 Schlichtherle IT Services
 *
 * Licensed 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 de.schlichtherle.io.archive.spi;

import de.schlichtherle.io.InputArchiveMetaData;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.InputStream;
import java.util.Enumeration;

/**
 * Defines the interface used to read entries from an archive file.
 * 
 * Implementations do not need to be thread safe:
 * Multithreading is addressed in the package {@code de.schlichtherle.io}.
 *
 * @author Christian Schlichtherle
 * @version $Id: InputArchive.java,v 1.4 2010/08/20 13:09:48 christian_schlichtherle Exp $
 * @since TrueZIP 6.0
 */
public interface InputArchive {

    /**
     * Returns the number of {@link ArchiveEntry} instances in this archive.
     */
    int getNumArchiveEntries();

    /**
     * Returns an enumeration of the {@link ArchiveEntry} instances in this
     * archive.
     */
    Enumeration getArchiveEntries();

    /**
     * Returns the {@link ArchiveEntry} for the given entry name or
     * {@code null} if no entry with this name exists.
     * 
     * @param entryName A valid archive entry name - never {@code null}.
     * @see Requirements for Archive Entry Names
     */
    ArchiveEntry getArchiveEntry(String entryName);

    /**
     * Returns a new {@code InputStream} for reading the contents of the
     * given archive entry.
     * 

     * The returned stream should preferrably be unbuffered, as buffering is
     * usually done in higher layers (all copy routines in TrueZIP do this
     * and most client applications do it, too).
     * Buffering twice does not increase, but decrease performance.
     * 

     * Note that the stream is guaranteed to be closed before the
     * {@link #close()} method of this archive is called!
     * 
     * @param entry A valid reference to an archive entry.
     *        The runtime class of this entry is the same as the runtime class
     *        of the entries returned by {@link #getArchiveEntries}.
     * @param dstEntry If not {@code null}, this identifies the entry
     *        to which TrueZIP is actually copying data to and should be
     *        used to implement the Direct Data Copying (DDC) feature.
     *        Note that there is no guarantee on the runtime type of this
     *        object; it may have been created by other drivers.
     *        
     *        For example, the ZIP driver family uses this to determine
     *        if data should be provided in its deflated form if the
     *        destination entry is another ZIP file entry.
     * @return A (preferrably unbuffered) {@link InputStream} to read the
     *         archive entry data from.
     *         {@code null} is not allowed!
     * @throws InputArchiveBusyException If the archive is currently busy
     *         on input for another entry.
     *         This exception is guaranteed to be recoverable, meaning it
     *         should be possible to read the same entry again as soon as
     *         the archive is not busy on input anymore.
     * @throws FileNotFoundException If the archive entry does not exist or
     *         is not accessible for some reason.
     * @throws IOException On any other exceptional condition.
     */
    InputStream getInputStream(ArchiveEntry entry, ArchiveEntry dstEntry)
    throws InputArchiveBusyException, FileNotFoundException, IOException;

    /**
     * Closes this input archive and releases any system resources
     * associated with it.
     * 
     * @throws IOException On any I/O related issue.
     */
    void close()
    throws IOException;

    /**
     * Returns the meta data for this input archive.
     * The default value is {@code null}.
     */
    InputArchiveMetaData getMetaData();

    /**
     * Sets the meta data for this input archive.
     *
     * @param metaData The meta data - may not be {@code null}.
     */
    void setMetaData(InputArchiveMetaData metaData);
}