KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > de > schlichtherle > io > archive > spi > InputArchive


1 /*
2  * InputArchive.java
3  *
4  * Created on 27. Februar 2006, 03:19
5  */
6 /*
7  * Copyright 2006 Schlichtherle IT Services
8  *
9  * Licensed under the Apache License, Version 2.0 (the "License");
10  * you may not use this file except in compliance with the License.
11  * You may obtain a copy of the License at
12  *
13  * http://www.apache.org/licenses/LICENSE-2.0
14  *
15  * Unless required by applicable law or agreed to in writing, software
16  * distributed under the License is distributed on an "AS IS" BASIS,
17  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18  * See the License for the specific language governing permissions and
19  * limitations under the License.
20  */
21
22 package de.schlichtherle.io.archive.spi;
23
24 import de.schlichtherle.io.InputArchiveMetaData;
25 import de.schlichtherle.io.archive.spi.InputArchiveBusyException;
26
27 import java.io.FileNotFoundException JavaDoc;
28 import java.io.IOException JavaDoc;
29 import java.io.InputStream JavaDoc;
30 import java.util.Enumeration JavaDoc;
31
32 /**
33  * Defines the interface used to read entries from an archive file.
34  * <p>
35  * Implementations do <em>not</em> need to be thread safe.
36  *
37  * @author Christian Schlichtherle
38  * @version @version@
39  * @since TrueZIP 6.0
40  */
41 public interface InputArchive {
42
43     /**
44      * Returns the number of {@link ArchiveEntry} instances in this archive.
45      */
46     int getNumArchiveEntries();
47
48     /**
49      * Returns an enumeration of the {@link ArchiveEntry} instances in this
50      * archive.
51      */
52     Enumeration JavaDoc getArchiveEntries();
53
54     /**
55      * Returns the {@link ArchiveEntry} for the given pathname or
56      * <code>null</code> if no entry with this pathname exists.
57      *
58      * @param name The name of the <code>ArchiveEntry</code>.
59      */
60     ArchiveEntry getArchiveEntry(String JavaDoc name);
61
62     /**
63      * Returns an <code>InputStream</code> for reading the contents of the
64      * given archive entry.
65      * <p>
66      * The returned stream should preferrably be unbuffered, as buffering is
67      * usually done on higher layers (all copy routines in TrueZIP do this
68      * and most client applications do it, too).
69      * Buffering twice does not increase, but decrease performance.
70      * <p>
71      * Note that the stream is guaranteed to be closed before the
72      * {@link #close()} method of this archive is called!
73      *
74      * @param entry The archive entry to read. This is <em>never</em>
75      * <code>null</code> and safe to be casted to the archive entry
76      * type actually returned by the {@link #getArchiveEntry} method.
77      * @param dstEntry If not <code>null</code>, this identifies the entry
78      * to which TrueZIP is actually copying data to and should be
79      * used to implement the Direct Data Copying (DDC) feature.
80      * Note that there is no guarantee on the runtime type of this
81      * object; it may have been created by other drivers.
82      * <p>
83      * For example, the {@link de.schlichtherle.io.archive.zip.Zip32Driver}
84      * uses this to determine if data should be provided in its deflated
85      * form if the destination entry is another
86      * {@link de.schlichtherle.io.archive.zip.Zip32Entry}.
87      * @return A (preferrably unbuffered) {@link InputStream} to read the
88      * archive entry data from.
89      * May be <code>null</code> to indicate that the entry does not
90      * exist.
91      * @throws InputArchiveBusyException If the archive is currently busy
92      * on input for another entry.
93      * This exception is guaranteed to be recoverable, meaning it
94      * should be possible to read the same entry again as soon as
95      * the archive is not busy on input anymore.
96      * @throws FileNotFoundException If the archive entry does not exist or
97      * is not accessible for some reason.
98      * @throws IOException On any other exceptional condition.
99      */
100     InputStream JavaDoc getInputStream(ArchiveEntry entry, ArchiveEntry dstEntry)
101     throws InputArchiveBusyException, FileNotFoundException JavaDoc, IOException JavaDoc;
102
103     /**
104      * Closes this input archive and releases any system resources
105      * associated with it.
106      *
107      * @throws IOException On any I/O related issue.
108      */
109     void close() throws IOException JavaDoc;
110
111     /**
112      * Returns the meta data for this input archive.
113      * This property is used by TrueZIP's virtual file system class and is
114      * transparent to the driver implementation.
115      */
116     InputArchiveMetaData getMetaData();
117
118     /**
119      * Sets the meta data for this input archive.
120      * This property is used by TrueZIP's virtual file system class and is
121      * transparent to the driver implementation.
122      */
123     void setMetaData(InputArchiveMetaData metaData);
124 }
125
Popular Tags