de.schlichtherle.io
Interface ArchiveDetector

All Superinterfaces:

FileFactory

All Known Implementing Classes:

AbstractArchiveDetector, DefaultArchiveDetector

public interface ArchiveDetector
extends FileFactory

Detects archive files solely by scanning file paths - usually by testing for file name suffixes like .zip or the like. Whenever an archive file is recognized, the getArchiveDriver(String) method returns an instance of the ArchiveDriver interface which allows to access it.

ArchiveDetector instances are assigned to File instances in the following way:

1. If an archive detector is explicitly provided as a parameter to the constructor of the File class or any other method which creates File instances (e.g. listFiles(*)), then this archive detector is used.
2. Otherwise, the archive detector returned by File.getDefaultArchiveDetector() is used. This is initially set to the predefined instance DEFAULT. Both the class property and the predefined instance can be customized.

An archive file which has been recognized by an archive detector is said to be a prospective archive file. On the first read or write access to a prospective archive file, TrueZIP checks its true state in cooperation with the ArchiveDriver. If the true state of the file turns out to be actually a directory or not to be compatible to the archive file format, it's said to be a false positive archive file. TrueZIP implements the appropriate behavior for all read or write operations according to the true state. Thanks to this design, TrueZIP detects and handles all kinds of false positives correctly.

Implementations must be (virtually) immutable and hence thread safe.

Rather than implementing ArchiveDetector directly, it's easier to instantiate or subclass the DefaultArchiveDetector class. This class provides a registry for archive file suffixes and archive drivers which can be easily customized via configuration files or Java code.

Since TrueZIP 6.4, although it's not required, it's recommended for implementations to implement the Serializable interface, too, so that File instances which use it can be serialized.

Since:

TrueZIP 6.0

Version:

TrueZIP 6.7

Author:

Christian Schlichtherle

See Also:

DefaultArchiveDetector, File, ArchiveDriver

Field Summary

static DefaultArchiveDetector	ALL Recognizes all archive file suffixes registerd in the global registry by the configuration file(s).
static DefaultArchiveDetector	DEFAULT Recognizes the archive file suffixes defined by the key DEFAULT in the configuration file(s).
static DefaultArchiveDetector	NULL Never recognizes archive files in a path.

Method Summary

File	createFile(File blueprint) Constructs a new File instance from the given blueprint.
File	createFile(File delegate, File innerArchive) This factory method is not for public use - do not use it!
File	createFile(File blueprint, File delegate, File enclArchive) This factory method is not for public use - do not use it!
File	createFile(File parent, String child) Constructs a new File instance which uses this ArchiveDetector to detect any archive files in its pathname.
File	createFile(String path) Constructs a new File instance which uses this ArchiveDetector to detect any archive files in its pathname.
File	createFile(String parent, String child) Constructs a new File instance which uses this ArchiveDetector to detect any archive files in its pathname.
File	createFile(URI uri) Constructs a new File instance from the given uri.
FileInputStream	createFileInputStream(File file) Creates a new FileInputStream to read the content of the given file.
FileOutputStream	createFileOutputStream(File file, boolean append) Creates a new FileOutputStream to write the new content of the given file.
ArchiveDriver	getArchiveDriver(String path) Detects whether the given path identifies a prospective archive file or not by applying heuristics to it and returns an appropriate ArchiveDriver to use or null if the path does not denote a prospective archive file or an appropriate ArchiveDriver is not available for some reason.

Field Detail

NULL

static final DefaultArchiveDetector NULL

Never recognizes archive files in a path. This can be used as the end of a chain of DefaultArchiveDetector instances or if archive files shall be treated like ordinary files rather than (virtual) directories.

See Also:

DefaultArchiveDetector

DEFAULT

static final DefaultArchiveDetector DEFAULT

Recognizes the archive file suffixes defined by the key DEFAULT in the configuration file(s). If only TrueZIP's default configuration file is used, then this is set so that no additional JARs are required on the runtime class path.

This archive detector is initially returned by File.getDefaultArchiveDetector().

Note that the actual set of archive file suffixes detected by this instance may be extended without prior notice in future releases.

See Also:

How Configuration Files are located and processed by the DefaultArchiveDetector class

ALL

static final DefaultArchiveDetector ALL

Recognizes all archive file suffixes registerd in the global registry by the configuration file(s). This requires additional JARs on the runtime class path.

Note that the actual set of archive file suffixes detected by this instance may be extended without prior notice in future releases.

See Also:

How Configuration Files are located and processed by the DefaultArchiveDetector class

Method Detail

getArchiveDriver

ArchiveDriver getArchiveDriver(String path)

Detects whether the given path identifies a prospective archive file or not by applying heuristics to it and returns an appropriate ArchiveDriver to use or null if the path does not denote a prospective archive file or an appropriate ArchiveDriver is not available for some reason.

Please note that implementations must not check the actual contents of the file identified by path! This is because this method may be used to detect archive files by their names before they are actually created or to detect archive files which are enclosed in other archive files, in which case there is no way to check the file contents in the real file system.

Parameters:

path - The (not necessarily absolute) path of the prospective archive file. This does not actually need to be accessible in the real file system!

Returns:

An ArchiveDriver instance for this archive file or null if the path does not denote an archive file (i.e. the path does not have a known suffix) or an appropriate ArchiveDriver is not available for some reason.

Throws:

NullPointerException - If path is null.

RuntimeException - A subclass is thrown if loading or instantiating an archive driver class fails.

createFile

File createFile(File blueprint)

Constructs a new File instance from the given blueprint.

Specified by:

createFile in interface FileFactory

Parameters:

blueprint - The file to use as a blueprint. If this is an instance of the File class, its fields are simply copied.

Returns:

A newly created instance of the class File.

createFile

File createFile(File delegate,
                File innerArchive)

This factory method is not for public use - do not use it!

Specified by:

createFile in interface FileFactory

createFile

File createFile(File blueprint,
                File delegate,
                File enclArchive)

This factory method is not for public use - do not use it!

Specified by:

createFile in interface FileFactory

createFile

File createFile(String path)

Constructs a new File instance which uses this ArchiveDetector to detect any archive files in its pathname.

Specified by:

createFile in interface FileFactory

Parameters:

path - The pathname of the file.

Returns:

A newly created instance of the class File.

createFile

File createFile(String parent,
                String child)

Constructs a new File instance which uses this ArchiveDetector to detect any archive files in its pathname.

Specified by:

createFile in interface FileFactory

Parameters:

parent - The parent pathname as a String.

child - The child pathname as a String.

Returns:

A newly created instance of the class File.

createFile

File createFile(File parent,
                String child)

Constructs a new File instance which uses this ArchiveDetector to detect any archive files in its pathname.

Specified by:

createFile in interface FileFactory

Parameters:

parent - The parent pathname as a File.

child - The child pathname as a String.

Returns:

A newly created instance of the class File.

createFile

File createFile(URI uri)

Constructs a new File instance from the given uri. This method behaves similar to new java.io.File(uri) with the following amendment: If the URI matches the pattern (jar:)*file:(path!/)*entry, then the constructed file object treats the URI like a (possibly ZIPped) file.

The newly created File instance uses this ArchiveDetector to detect any archive files in its pathname.

Specified by:

createFile in interface FileFactory

Parameters:

uri - an absolute, hierarchical URI with a scheme equal to file or jar, a non-empty path component, and undefined authority, query, and fragment components.

Returns:

A newly created instance of the class File.

Throws:

NullPointerException - if uri is null.

IllegalArgumentException - if the preconditions on the parameter uri do not hold.

createFileInputStream

FileInputStream createFileInputStream(File file)
                                      throws FileNotFoundException

Creates a new FileInputStream to read the content of the given file.

Specified by:

createFileInputStream in interface FileFactory

Parameters:

file - The file to read.

Returns:

A newly created instance of the class FileInputStream.

Throws:

FileNotFoundException - On any I/O related issue when opening the file.

createFileOutputStream

FileOutputStream createFileOutputStream(File file,
                                        boolean append)
                                        throws FileNotFoundException

Creates a new FileOutputStream to write the new content of the given file.

Specified by:

createFileOutputStream in interface FileFactory

Parameters:

file - The file to write.

append - If true the new content should be appended to the old content rather than overwriting it.

Returns:

A newly created instance of the class FileOutputStream.

Throws:

FileNotFoundException - On any I/O related issue when opening the file.