de.schlichtherle.truezip.file
Class TDefaultArchiveDetector

java.lang.Object
  de.schlichtherle.truezip.file.TDefaultArchiveDetector

All Implemented Interfaces:

TArchiveDetector, FsCompositeDriver, FsDriverService

@Immutable
@DefaultAnnotation(value=edu.umd.cs.findbugs.annotations.NonNull.class)
public final class TDefaultArchiveDetector
extends Object
implements TArchiveDetector, FsDriverService

An archive detector which matches file paths against a pattern of file suffixes in order to detect prospective archive files (i.e. prospective federated file systems) and look up their corresponding file system driver using a file system driver service.

There are basically two types of constructors available in this class:

1. Constructors which filter the drivers of a given file system driver service by a given list of file suffixes. For example, the drivers known by the service FsDriverLocator.SINGLETON could be filtered by the suffix list "tar|zip" in order to recognize only TAR and ZIP files.
2. Constructors which decorate a given file system driver service with a given map of file system schemes to file system drivers - whereby a number of options are available to conveniently specify the map. This could be used to specify custom archive file suffixes or file system schemes, i.e. file system drivers. For example, the suffix list "foo|bar" could be used to recognize a custom variant of the JAR file format (you would need to provide a custom file system driver then, too).

Where a constructor expects a suffix list as a parameter, it must obeye the syntax constraints for SuffixSets. As an example, the parameter "zip|jar" would cause the archive detector to recognize ZIP and JAR files in a path. The same would be true for "||.ZIP||.JAR||ZIP||JAR||", but this notation is discouraged because it's obviously not in canonical form.

Author:

Christian Schlichtherle

NULL

public static final TDefaultArchiveDetector NULL

This instance never recognizes any archive files in a path. This could be used as the end of a chain of TDefaultArchiveDetector instances or if archive files shall be treated like ordinary files rather than (virtual) directories.

ALL

public static final TDefaultArchiveDetector ALL

This instance recognizes all archive files which are known by the file system driver service FsDriverLocator.SINGLETON. The file system schemes are used as the archive file suffixes to recognize.

drivers

private final Map<FsScheme,FsDriver> drivers

suffixes

private final String suffixes

The canonical string respresentation of the set of suffixes recognized by this archive detector. This set is used to filter the registered archive file suffixes in drivers.

matcher

private final ThreadLocalMatcher matcher

The thread local matcher used to match archive file suffixes. This field should be considered final.

TDefaultArchiveDetector

public TDefaultArchiveDetector(@CheckForNull
                               String suffixes)

Equivalent to new TDefaultArchiveDetector(FsDriverLocator.SINGLETON, suffixes).

TDefaultArchiveDetector

public TDefaultArchiveDetector(FsDriverService service,
                               @CheckForNull
                               String suffixes)

Constructs a new TDefaultArchiveDetector by filtering the given driver service for all canonicalized suffixes in the suffixes list.

Parameters:

service - the file system driver service to filter.

suffixes - A list of suffixes which shall identify prospective archive files. If this is null, no filtering is applied and all drivers known by the given service are available for use with this archive detector.

Throws:

IllegalArgumentException - If any of the suffixes in the list names a suffix for which no file system driver is known by the service.

See Also:

Syntax constraints for suffix lists.

TDefaultArchiveDetector

public TDefaultArchiveDetector(String suffixes,
                               @CheckForNull
                               FsDriver driver)

Equivalent to TDefaultArchiveDetector(TDefaultArchiveDetector.NULL, suffixes, driver).

TDefaultArchiveDetector

public TDefaultArchiveDetector(FsDriverService delegate,
                               String suffixes,
                               @CheckForNull
                               FsDriver driver)

Constructs a new TDefaultArchiveDetector by decorating the configuration of delegate with mappings for all canonicalized suffixes in suffixes to driver.

Parameters:

delegate - the file system driver service to decorate.

suffixes - a list of suffixes which shall identify prospective archive files. This must not be null and must not be empty.

driver - the file system driver to map for the suffix list. null may be used to shadow a mapping for an equal file system scheme in delegate by removing it from the resulting map for this detector.

Throws:

NullPointerException - if a required configuration element is null.

IllegalArgumentException - if any other parameter precondition does not hold.

See Also:

Syntax contraints for suffix lists.

TDefaultArchiveDetector

public TDefaultArchiveDetector(FsDriverService delegate,
                               Object[][] config)

Creates a new TDefaultArchiveDetector by decorating the configuration of delegate with mappings for all entries in config.

Parameters:

delegate - the file system driver service to decorate.

config - an array of key-value pair arrays. The first element of each inner array must either be a file system scheme, an object o which can get converted to a set of file system suffixes by calling new SuffixSet(o.toString()) or a collection of these. The second element of each inner array must either be a file system driver object, a file system driver class, a fully qualified name of a file system driver class, or null. null may be used to shadow a mapping for an equal file system scheme in delegate by removing it from the resulting map for this detector.

Throws:

NullPointerException - if a required configuration element is null.

IllegalArgumentException - if any other parameter precondition does not hold.

See Also:

Syntax contraints for suffix lists.

TDefaultArchiveDetector

public TDefaultArchiveDetector(FsDriverService delegate,
                               Map<FsScheme,FsDriver> config)

Constructs a new TDefaultArchiveDetector by decorating the configuration of delegate with mappings for all entries in config.

Parameters:

delegate - the file system driver service to decorate.

config - a map of file system schemes to file system drivers. null may be used to shadow a mapping for an equal file system scheme in delegate by removing it from the resulting map for this detector.

Throws:

NullPointerException - if a required configuration element is null.

ClassCastException - if a configuration element is of the wrong type.

IllegalArgumentException - if any other parameter precondition does not hold.

See Also:

Syntax contraints for suffix lists.

getSuffixes

private static SuffixSet getSuffixes(FsDriverService service)

getDrivers

public Map<FsScheme,FsDriver> getDrivers()

Specified by:

getDrivers in interface FsDriverService

getScheme

@CheckForNull
public FsScheme getScheme(String path)

Description copied from interface: TArchiveDetector

Detects whether the given path name identifies a prospective archive file or not by applying heuristics to it and returns a scheme for accessing archive files of this type or null if the path does not denote a prospective archive file or an appropriate scheme is unknown.

Please note that implementations must not check the actual contents of the file identified by path! This is because path may refer to a file which is not yet existing or even an entry in a federated file system, in which case there is no way to check the file contents in the parent file systems.

Specified by:

getScheme in interface TArchiveDetector

Parameters:

path - the path name of the file in the federated file system. This does not need to be absolute and it does not need to be accessible in its containing virtual file system!

Returns:

A scheme for accessing the 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 scheme is unknown.

getDriver

@CheckForNull
FsDriver getDriver(FsScheme scheme)

Reserved for unit testing only.

newController

public FsController<?> newController(FsMountPoint mountPoint,
                                     @CheckForNull
                                     FsController<?> parent)

Specified by:

newController in interface FsCompositeDriver

toString

public String toString()

Returns the canonical suffix list for all federated file system types recognized by this TDefaultArchiveDetector.

Overrides:

toString in class Object

Returns:

Either "" to indicate an empty set or a string of the form "suffix[|suffix]*", where suffix is a combination of lower case letters which does not start with a dot. The string never contains empty or duplicated suffixes and the suffixes are sorted in natural sort order.

See Also:

TDefaultArchiveDetector(String), Syntax constraints for suffix lists.