de.schlichtherle.truezip.file
Class TArchiveDetector

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

All Implemented Interfaces:

FsCompositeDriver, FsDriverProvider

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

Detects a prospective archive file by matching its path name against a pattern of file name suffixes like .zip et al and looks up its corresponding file system driver by using a file system driver provider.

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

1. Constructors which filter the drivers of a given file system driver provider by a given list of file suffixes. For example, the drivers known by the provider 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 provider 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 TArchiveDetector NULL

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

ALL

public static final TArchiveDetector ALL

This instance recognizes all archive files which are known by the file system driver provider 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.

TArchiveDetector

public TArchiveDetector(@CheckForNull
                        String suffixes)

Equivalent to TArchiveDetector(FsDriverLocator.SINGLETON, suffixes).

TArchiveDetector

public TArchiveDetector(FsDriverProvider provider,
                        @CheckForNull
                        String suffixes)

Constructs a new TArchiveDetector by filtering the given driver provider for all canonicalized suffixes in the suffixes list.

Parameters:

provider - the file system driver provider 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 provider 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 provider.

See Also:

Syntax constraints for suffix lists.

TArchiveDetector

public TArchiveDetector(String suffixes,
                        @CheckForNull
                        FsDriver driver)

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

TArchiveDetector

public TArchiveDetector(FsDriverProvider delegate,
                        String suffixes,
                        @CheckForNull
                        FsDriver driver)

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

Parameters:

delegate - the file system driver provider 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.

TArchiveDetector

public TArchiveDetector(FsDriverProvider delegate,
                        Object[][] config)

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

Parameters:

delegate - the file system driver provider 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.

TArchiveDetector

public TArchiveDetector(FsDriverProvider delegate,
                        Map<FsScheme,FsDriver> config)

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

Parameters:

delegate - the file system driver provider 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(FsDriverProvider provider)

get

public Map<FsScheme,FsDriver> get()

Specified by:

get in interface FsDriverProvider

getScheme

@CheckForNull
public FsScheme getScheme(String path)

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.

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(FsModel model,
                                     @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 TArchiveDetector.

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 order.

See Also:

TArchiveDetector(String), Syntax constraints for suffix lists.