KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2  * ArchiveDriver.java
3  *
4  * Created on 25. Februar 2006, 16:59
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.File;
25 import de.schlichtherle.io.FileInputStream;
26 import de.schlichtherle.io.FileOutputStream;
27 import de.schlichtherle.io.archive.Archive;
28 import de.schlichtherle.io.rof.ReadOnlyFile;
29
30 import java.io.CharConversionException JavaDoc;
31 import java.io.FileNotFoundException JavaDoc;
32 import java.io.IOException JavaDoc;
33 import java.io.OutputStream JavaDoc;
34
35 import javax.swing.Icon JavaDoc;
36
37 /**
38  * This "driver" interface is an Abstract Factory used to build archives of
39  * a specific type, such as ZIP32, ZIP32.RAES, JAR, TAR, TAR.GZ, TAR.BZ2
40  * or the like.
41  * Archive drivers are used by the non-public class
42  * <code>de.schlichtherle.io.ArchiveController</code> as the Factory side of
43  * a Builder pattern and may be shared by multiple archive controllers and
44  * instances of the {@link de.schlichtherle.io.ArchiveDetector} interface.
45  * <p>
46  * The following requirements must be met by any implementation:
47  * <ul>
48  * <li>
49  * Implementations must not assume that they are used as singletons:
50  * Multiple instances of an implementation may be used for the same archive
51  * type.
52  * <li>
53  * Implementations must be immutable to avoid all kinds of surprising
54  * effects in the behaviour of the {@link de.schlichtherle.io.File} class,
55  * including strange exceptions.
56  * <li>
57  * If the driver should be supported by the driver registration process of
58  * the class {@link de.schlichtherle.io.DefaultArchiveDetector},
59  * a no-arguments constructor must be provided.
60  * This constructor should be fast to process.
61  * <li>
62  * Implementations should be lightweight in terms of memory.
63  * <li>
64  * Implementations do <em>not</em> need to be thread safe.
65  * <li>
66  * Since TrueZIP 6.4, although it's not required, it's recommended for
67  * implementations to implement the {@link java.io.Serializable} interface,
68  * too, so that {@link de.schlichtherle.io.File} instances which are
69  * indirectly referring to it can be serialized.
70  * </ul>
71  *
72  * @author Christian Schlichtherle
73  * @version @version@
74  * @since TrueZIP 6.0
75  */

76 public interface ArchiveDriver {
77     
78     /**
79      * Returns the icon that {@link de.schlichtherle.io.swing.tree.FileTreeCellRenderer}
80      * should display for the given archive.
81      *
82      * @param archive The abstract archive representation which TrueZIP's
83      * internal <code>ArchiveController</code> is processing
84      * - never <code>null</code>.
85      * @return The icon that should be displayed for the given archive if is
86      * is open/expanded in the view.
87      * If <code>null</code> is returned, a default icon should be used.
88      */

89     Icon JavaDoc getOpenIcon(Archive archive);
90
91     /**
92      * Returns the icon that {@link de.schlichtherle.io.swing.FileSystemView}
93      * and {@link de.schlichtherle.io.swing.tree.FileTreeCellRenderer} should
94      * display for the given archive.
95      *
96      * @param archive The abstract archive representation which TrueZIP's
97      * internal <code>ArchiveController</code> is processing
98      * - never <code>null</code>.
99      * @return The icon that should be displayed for the given archive if is
100      * is closed/collapsed in the view.
101      * If <code>null</code> is returned, a default icon should be used.
102      */

103     Icon JavaDoc getClosedIcon(Archive archive);
104
105     /**
106      * Creates an {@link InputArchive} object for <code>archive</code>
107      * from the given {@link ReadOnlyFile} instance.
108      * <p>
109      * Note that if an exception is thrown, the method must be reentrant!
110      * In addition, the exception type determines the behaviour of the classes
111      * {@link File}, {@link FileInputStream} and {@link FileOutputStream}
112      * as follows:
113      * <ul>
114      * <li>If a {@link FileNotFoundException} is thrown, then
115      * {@link File#isFile} returns <b><code>false</code></b>,
116      * {@link File#isArchive} returns <code>true</code>,
117      * {@link File#isDirectory} returns <code>false</code>,
118      * {@link File#exists} returns <code>true</code> and
119      * {@link File#delete} returns <code>true</code> unless prohibited
120      * by the native file system.
121      * <li>If an {@link IOException} is thrown, then
122      * {@link File#isFile} returns <b><code>true</code></b>,
123      * {@link File#isArchive} returns <code>true</code>,
124      * {@link File#isDirectory} returns <code>false</code>,
125      * {@link File#exists} returns <code>true</code> and
126      * {@link File#delete} returns <code>true</code> unless prohibited
127      * by the native file system.
128      * </ul>
129      *
130      * @param archive The abstract archive representation which TrueZIP's
131      * internal <code>ArchiveController</code> is processing
132      * - never <code>null</code>.
133      * @param rof The {@link ReadOnlyFile} to read the actual archive
134      * contents from - never <code>null</code>.
135      * Hint: If you'ld prefer to have an <code>InputStream</code>,
136      * you could decorate this parameter with a
137      * {@link de.schlichtherle.io.rof.ReadOnlyFileInputStream}.
138      * @return A newly created {@link InputArchive}.
139      * @throws TransientIOException If calling this method for the same
140      * archive file again may finally succeed.
141      * This exception is associated with another <code>IOException</code>
142      * as its cause which is unwrapped and interpreted as below.
143      * @throws FileNotFoundException If the input archive is inaccessible
144      * for any reason and you would like the package
145      * {@link de.schlichtherle.io} to mask the archive as a special
146      * file which cannot get read, written or deleted.
147      * @throws IOException On any other I/O or data format related issue
148      * and you would like the package {@link de.schlichtherle.io}
149      * to treat the archive like a regular file which may be read,
150      * written or deleted.
151      * @see InputArchive
152      */

153     InputArchive createInputArchive(
154             Archive archive,
155             ReadOnlyFile rof)
156     throws IOException JavaDoc;
157
158     /**
159      * Creates a new {@link ArchiveEntry} instance for <code>name</code> which
160      * may be used within an {@link OutputArchive}.
161      *
162      * @param archive The abstract archive representation which TrueZIP's
163      * internal <code>ArchiveController</code> is processing
164      * - never <code>null</code>.
165      * @param name The path name of the entry to create
166      * - never <code>null</code>.
167      * @param blueprint If not <code>null</code>, then the newly created entry
168      * shall inherit as much attributes from this object as possible
169      * (with the exception of the name).
170      * This is typically used for archive copy operations.
171      * Note that there is no guarantee on the runtime type of this
172      * object; it may have been created by other drivers.
173      * It is safe to ignore the <code>metaData</code> property when
174      * copying entries.
175      * @return A newly created <code>ArchiveEntry</code> instance.
176      * @throws CharConversionException If <code>name</code> contains
177      * illegal characters.
178      * @see ArchiveEntry
179      */

180     ArchiveEntry createArchiveEntry(
181             Archive archive,
182             String JavaDoc name,
183             ArchiveEntry blueprint)
184     throws CharConversionException JavaDoc;
185
186     /**
187      * Creates an {@link OutputArchive} object for <code>archive</code>
188      * from the given {@link OutputStream} instance.
189      *
190      * @param archive The abstract archive representation which TrueZIP's
191      * internal <code>ArchiveController</code> is processing
192      * - never <code>null</code>.
193      * @param out The {@link OutputStream} to write the archive entries to
194      * - never <code>null</code>.
195      * @param source The source {@link InputArchive} if
196      * <code>archive</code> is going to get updated.
197      * If not <code>null</code>, this is guaranteed to be a product
198      * of this driver's {@link #createInputArchive} method.
199      * This may be used to copy some meta data which is specific to
200      * the type of archive this driver supports.
201      * For example, this could be used to copy the comment of a ZIP32
202      * archive file.
203      * @return A newly created {@link OutputArchive}.
204      * @throws TransientIOException If calling this method for the same
205      * archive file again may finally succeed.
206      * This exception is associated with another <code>IOException</code>
207      * as its cause which is unwrapped and interpreted as below.
208      * @throws IOException On any issue when writing to the output stream.
209      * @see OutputArchive
210      */

211     OutputArchive createOutputArchive(
212             Archive archive,
213             OutputStream out,
214             InputArchive source)
215     throws IOException JavaDoc;
216
217     /**
218      * Archive drivers will be put into hash maps as keys,
219      * so be sure to implement this properly.
220      * Note that this is just a reinforcement of the general contract for
221      * {@link Object#hashCode} and the best possible implementation is the
222      * default implementation in Object which is most discriminating.
223      * Normally this
224      *
225      * @since TrueZIP 6.4
226      */

227     int hashCode();
228
229     /**
230      * Archive drivers will be put into hash maps as keys,
231      * so be sure to implement this properly.
232      * Note that this is just a reinforcement of the general contract for
233      * {@link Object#equals} and the best possible implementation is the
234      * default implementation in Object which is most discriminating.
235      *
236      * @since TrueZIP 6.4
237      */

238     boolean equals(Object JavaDoc o);
239 }
240
Popular Tags