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  ;
27  import java.net.URI  ;
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   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   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   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   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   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   parent, String   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   parent, String   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   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   file)
251     throws FileNotFoundException  ;
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   file, boolean append)
266     throws FileNotFoundException  ;
267 }
268
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Free Books Free Magazines
Popular Tags