KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > de > schlichtherle > io > ArchiveDetector


1 /*
2  * ArchiveDetector.java
3  *
4  * Created on 31. Juli 2005, 00:00
5  */

6 /*
7  * Copyright 2005-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;
23
24 import de.schlichtherle.io.archive.spi.ArchiveDriver;
25
26 import java.io.FileNotFoundException JavaDoc;
27 import java.net.URI JavaDoc;
28
29 /**
30  * Detects an archive file solely by looking at the file's pathname -
31  * usually by scanning for file name suffixes like <code>".zip"</code> or the
32  * like - and provides resources required to access their contents.
33  * If a pathname actually denotes an archive file, the file is said to be
34  * a <i>prospective archive file</i>. Later on, TrueZIP will try to access the
35  * file via an appropriate archive driver, which is an instance of the
36  * {@link ArchiveDriver} interface.
37  * The archive driver then checks the file contents for compatibility to the
38  * respective archive file format.
39  * If the file is actually a directory or not compatible to the archive file
40  * format, it is said to be a <i>false positive archive file</i>.
41  * With the support of the archive driver, TrueZIP always detects and handles
42  * all kinds of false positives correctly.
43  * <p>
44  * Implementations must be virtually immutable and thread safe.
45  * Otherwise, an application of the <code>File*</code> classes in this package
46  * may get lots of bad surprises!
47  * <p>
48  * Rather than implementing your own <code>ArchiveDetector</code>, you could
49  * instantiate or subclass the {@link DefaultArchiveDetector} class and
50  * provide an instance as the parameter for
51  * {@link File#setDefaultArchiveDetector(ArchiveDetector)} or any of the
52  * {@link File} constructors whenever you need to configure the way archive
53  * files are detected and configured.
54  * <p>
55  * Since TrueZIP 6.4, although it's not required, it's recommended for
56  * implementations to implement the {@link java.io.Serializable} interface,
57  * too, so that {@link de.schlichtherle.io.File} instances which use it can
58  * be serialized.
59  *
60  * @see DefaultArchiveDetector
61  * @see File
62  * @see ArchiveDriver
63  * @author Christian Schlichtherle
64  * @version @version@
65  * @since TrueZIP 6.0 (refactored from the former <code>ZipDetector</code>)
66  */

67 public interface ArchiveDetector extends FileFactory {
68
69     //
70
// Predefined default implementations:
71
//
72

73     /**
74      * The nullary archive detector as implemented by the
75      * {@link DefaultArchiveDetector} class.
76      * As the name implies, this <code>ArchiveDetector</code> never detects
77      * an archive file in a pathname.
78      *
79      * @see DefaultArchiveDetector
80      */

81     DefaultArchiveDetector NULL = new DefaultArchiveDetector(null);
82     
83     /**
84      * The archive types recognized by default.
85      * <p>
86      * This value is determined by processing all configuration files on the
87      * class path which are provided by the TrueZIP JAR and (optionally)
88      * the client application.
89      * The class path is searched by the current thread's context class
90      * loader when the {@link DefaultArchiveDetector} class is loaded.
91      *
92      * @see DefaultArchiveDetector
93      */

94     DefaultArchiveDetector DEFAULT = new DefaultArchiveDetector(
95             DefaultArchiveDetector.DEFAULT_SUFFIXES);
96
97     /**
98      * All archive types registered with the {@link DefaultArchiveDetector}
99      * implementation.
100      * <p>
101      * This value is determined by processing all configuration files on the
102      * class path which are provided by the TrueZIP JAR and (optionally)
103      * the client application.
104      * The class path is searched by the current thread's context class
105      * loader when the {@link DefaultArchiveDetector} class is loaded.
106      *
107      * @see DefaultArchiveDetector
108      */

109     DefaultArchiveDetector ALL = new DefaultArchiveDetector(
110             DefaultArchiveDetector.ALL_SUFFIXES);
111
112     //
113
// The one and only method this interface really adds:
114
//
115

116     /**
117      * Detects whether the given <code>pathname</code> identifies an archive
118      * file or not by applying heuristics to the path name only and returns
119      * an appropriate <code>ArchiveDriver</code> to use or <code>null</code>
120      * if the pathname does not denote an archive file or an appropriate
121      * <code>ArchiveDriver</code> is not available for some reason.
122      * <p>
123      * Please note that implementations <em>must not</em> check the actual
124      * contents of the file identified by <code>pathname</code>!
125      * This is because this method may be used to detect archive files
126      * by their names before they are actually created or to detect archive
127      * files which are enclosed in other archive files, in which case there
128      * is no way to check the file contents in the native file system.
129      *
130      * @param pathname The (not necessarily absolute) pathname of the
131      * prospective archive file.
132      * This does not actually need to be accessible in the native file
133      * system!
134      *
135      * @return An <code>ArchiveDriver</code> instance for this archive file
136      * or <code>null</code> if the pathname does not denote an
137      * archive file (i.e. the pathname does not have a known suffix)
138      * or an appropriate <code>ArchiveDriver</code> is not available
139      * for some reason.
140      *
141      * @throws NullPointerException If pathname is <code>null</code>.
142      */

143     ArchiveDriver getArchiveDriver(String JavaDoc pathname);
144
145     //
146
// Specification of the (undocumented) contract inherited from FileFactory:
147
//
148

149     /**
150      * Constructs a new {@link File} instance from the given
151      * <code>blueprint</code>.
152      *
153      * @param blueprint The file to use as a blueprint. If this is an instance
154      * of the {@link File} class, its fields are simply copied.
155      *
156      * @return A newly created instance of the class {@link File}.
157      */

158     File createFile(java.io.File JavaDoc blueprint);
159
160     /**
161      * This factory method is <em>not</em> for public use - do not use it!
162      */

163     // It is used by {@link File#getParentFile()} for fast file construction
164
// without rescanning the pathname for archive files,
165
// which could even lead to wrong results.
166
//
167
// Calling this constructor with illegal arguments may result in
168
// <code>IllegalArgumentException</code>, <code>AssertionError</code> or
169
// may even silently fail!
170
File createFile(java.io.File JavaDoc delegate, File innerArchive);
171
172     /**
173      * This factory method is <em>not</em> for public use - do not use it!
174      */

175     // It is used by some methods for fast file
176
// construction without rescanning the pathname for archive files
177
// when rewriting the pathname of an existing <code>File</code> instance.
178
// <p>
179
// Calling this method with illegal arguments may result in
180
// <code>IllegalArgumentException</code>, <code>AssertionError</code> or
181
// may even silently fail!
182
File createFile(File blueprint, java.io.File JavaDoc delegate, File enclArchive);
183
184     /**
185      * Constructs a new {@link File} instance which uses this
186      * {@link ArchiveDetector} to detect any archive files in its pathname.
187      *
188      * @param pathName The pathname of the file.
189      *
190      * @return A newly created instance of the class {@link File}.
191      */

192     File createFile(String JavaDoc pathName);
193
194     /**
195      * Constructs a new {@link File} instance which uses this
196      * {@link ArchiveDetector} to detect any archive files in its pathname.
197      *
198      * @param parent The parent pathname as a {@link String}.
199      * @param child The child pathname as a {@link String}.
200      *
201      * @return A newly created instance of the class {@link File}.
202      */

203     File createFile(String JavaDoc parent, String JavaDoc child);
204
205     /**
206      * Constructs a new {@link File} instance which uses this
207      * {@link ArchiveDetector} to detect any archive files in its pathname.
208      *
209      * @param parent The parent pathname as a <code>File</code>.
210      * @param child The child pathname as a {@link String}.
211      *
212      * @return A newly created instance of the class {@link File}.
213      */

214     File createFile(java.io.File JavaDoc parent, String JavaDoc child);
215
216     /**
217      * Constructs a new {@link File} instance from the given
218      * <code>uri</code>. This method behaves similar to
219      * {@link java.io.File#File(URI) new java.io.File(uri)} with the following
220      * amendment:
221      * If the URI matches the pattern
222      * <code>(jar:)*file:(<i>path</i>!/)*<i>entry</i></code>, then the
223      * constructed file object treats the URI like a (possibly ZIPped) file.
224      * <p>
225      * The newly created {@link File} instance uses this
226      * {@link ArchiveDetector} to detect any archive files in its pathname.
227      *
228      * @param uri an absolute, hierarchical URI with a scheme equal to
229      * <code>file</code> or <code>jar</code>, a non-empty path component,
230      * and undefined authority, query, and fragment components.
231      *
232      * @return A newly created instance of the class {@link File}.
233      *
234      * @throws NullPointerException if <code>uri</code> is <code>null</code>.
235      * @throws IllegalArgumentException if the preconditions on the
236      * parameter <code>uri</code> do not hold.
237      */

238     File createFile(URI JavaDoc uri);
239
240     /**
241      * Creates a new {@link FileInputStream} to read the content of the
242      * given file.
243      *
244      * @param file The file to read.
245      *
246      * @return A newly created instance of the class {@link FileInputStream}.
247      *
248      * @throws FileNotFoundException On any I/O related issue when opening the file.
249      */

250     FileInputStream createFileInputStream(java.io.File JavaDoc file)
251     throws FileNotFoundException JavaDoc;
252
253     /**
254      * Creates a new {@link FileOutputStream} to write the new content of the
255      * given file.
256      *
257      * @param file The file to write.
258      * @param append If <code>true</code> the new content should be appended
259      * to the old content rather than overwriting it.
260      *
261      * @return A newly created instance of the class {@link FileOutputStream}.
262      *
263      * @throws FileNotFoundException On any I/O related issue when opening the file.
264      */

265     FileOutputStream createFileOutputStream(java.io.File JavaDoc file, boolean append)
266     throws FileNotFoundException JavaDoc;
267 }
268
Popular Tags