TFile (TrueZIP File* 7.0 API)

Overview

Package

Class

Use

Tree

Deprecated

Index

TrueZIP File* 7.0

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

de.schlichtherle.truezip.file
Class TFile

java.lang.Object
  java.io.File
      de.schlichtherle.truezip.file.TFile

All Implemented Interfaces:: Serializable, Comparable<File>

@DefaultAnnotation(value=edu.umd.cs.findbugs.annotations.NonNull.class) @Immutable public final class TFile
extends File
extends File

A replacement for the class File which provides transparent read/write access to archive files and their entries as if they were (virtual) directories and files. Because this class actually extends the class File it can be used with the class FileSystemView or any other classes which depend on the class File.

Bulk I/O Methods

This class provides some convenient methods which use pooled buffers and pooled threads in order to achieve superior performance as compared to the naive read-then-write-in-a-loop approach. These bulk I/O methods fall into the following categories:

The cp(_p|_r|_rp)? methods copy files or directory trees. The method names have been modelled after the Unix command line utility cp with its options.

The mv methods move files or directory trees. The method names have been modelled after the Unix command line utility mv.

The rm(_r)? methods remove files or directory trees. The method names have been modelled after the Unix command line utility rm with its options.

The input|output methods copy the given streams to this file or vice versa. In contrast to the previous methods they never close their argument streams, so applications can call them multiple times on the same streams to concatenate data.

Finally, the cat(InputStream, OutputStream) method is the core copy engine for all these methods. It performs the data transfer from an input stream to an output stream. When used with unbuffered input and output stream implementations, it delivers the same performance as the transfer method in the package java.nio. Its name is modelled after the Unix command line utility cat.

Important: You must provide the full path name for both source and destination parameters to any of these methods! In particular, both the source and destination parameters must either represent a file or a directory - mixing file and directory parameters will not work. This limitation is designed to prevent ambiguous method semantics.

Direct Data Copying (DDC)

If data is copied from an archive file to another archive file of the same type, some of the copy methods support a feature called Direct Data Copying (DDC) to achieve best performance: DDC copies the raw data from the source archive entry to the destination archive entry without the need to temporarily reproduce, copy and process the original data again.

The benefits of this feature are archive driver specific: In case of ZIP compatible files with compressed entries, this avoids the need to inflate the data from the source entry just to deflate it again for the destination entry. In case of TAR compatible files, it avoids the need to create an additional temporary file, but shows no impact otherwise - the TAR file format doesn't support compression.

Traversing Directory Trees

When traversing directory trees using different instances of this class, it's important that they use TArchiveDetectors which recognize the same set of archive files, i.e. their TArchiveDetector.toString() method compares equal. This is required in order to make sure that the cached data structures in the TrueZIP Kernel do not get bypassed. Otherwise, archive files may loose data or even get corrupted!

When copying or moving a directory tree, if you need a verbatim copy of any archive files within this directory tree, then make sure that any cached data structures in the TrueZIP Kernel are purged by calling umount() before calling one of the methods which accept the additional parameter TArchiveDetector.NULL for the traversal of this directory tree. For example, to make a recursive archive copy, call


 TFile src = ...
 TFile dst = ...
 TFile.umount();
 TFile.cp_rp(src, dst, TArchiveDetector.NULL, TArchiveDetector.NULL);

Recognizing Archive Files and False Positives

Whenever an archive file suffix is recognized in a path, this class treats the corresponding file or directory as a prospective archive file. The word "prospective" suggests that just because a file is named archive.zip it isn't necessarily a valid ZIP file. In fact, it could be anything, even a plain directory in the OS file system!

Such an invalid archive file is called a false positive archive file. TrueZIP correctly identifies all types of false positive archive files by performing a recursive look up operation for the first parent file system where the given archive file actually exists and treats it according to the true state of this entity.

The following table shows how certain methods in this class behave, depending upon an archive file's path and its true state in the first parent file system where it actually exists.

Path	True State	`isArchive()`¹	`isDirectory()`	`isFile()`	`exists()`	`length()`²
archive.zip³	Valid ZIP file	`true`	`true`	`false`	`true`	`0`
archive.zip	False positive: Plain directory	`true`	`true`	`false`	`true`	`?`
archive.zip	False positive: Plain file	`true`	`false`	`true`	`true`	`?`
archive.zip	False positive: Regular special file	`true`	`false`	`false`	`true`	`?`
archive.zip	TFile or directory does not exist	`true`	`false`	`false`	`false`	`0`

archive.tzp⁴	Valid RAES encrypted ZIP file with valid key (e.g. password)	`true`	`true`	`false`	`true`	`0`
archive.tzp	Valid RAES encrypted ZIP file with unknown key⁵	`true`	`false`	`false`	`true`	`?`
archive.tzp	False positive: Plain directory	`true`	`true`	`false`	`true`	`?`
archive.tzp	False positive: Plain file	`true`	`false`	`true`	`true`	`?`
archive.tzp	False positive: Regular special file	`true`	`false`	`false`	`true`	`?`
archive.tzp	TFile or directory does not exist	`true`	`false`	`false`	`false`	`0`

other	Plain directory	`false`	`true`	`false`	`true`	`?`
other	Plain file	`false`	`false`	`true`	`true`	`?`
other	Regular special file	`false`	`false`	`false`	`true`	`?`
other	TFile or directory does not exist	`false`	`false`	`false`	`false`	`0`

isArchive() doesn't check the true state of the file - it just looks at its path: If the path ends with a configured archive file suffix, isArchive() always returns true.
length() always returns 0 if the path denotes a valid archive file. Otherwise, the return value of length() depends on the platform and file system, which is indicated by ?. For regular directories on Windows/NTFS for example, the return value would be 0.
This example assumes that the TrueZIP Driver ZIP module is present on the run-time class path.
This example assumes that the TrueZIP Driver TZP (ZIP.RAES) module is present on the run-time class path.
The methods behave exactly the same for both archive.zip and archive.tzp with one exception: If the key for a RAES encrypted ZIP file remains unknown (e.g. because the user cancelled password prompting), then these methods behave as if the true state of the path were a special file, i.e. both isDirectory() and isFile() return false, while exists() returns true.

Author:: Christian Schlichtherle
See Also:: Serialized Form

Field Summary
`private FsController<?>`	`controller` This refers to the file system controller if and only if this file is located within a federated file system, otherwise it's `null`.
`private static TArchiveDetector`	`defaultDetector`
`private File`	`delegate` The delegate is used to implement the behaviour of the file system operations in case this instance represents neither an archive file nor an entry in an archive file.
`private TArchiveDetector`	`detector`
`private TFile`	`enclArchive`
`private FsEntryName`	`enclEntryName`
`private TFile`	`innerArchive`
`private static boolean`	`lenient`
`(package private) static FsManager`	`manager` The file system manager to use within this package.
`private static Set<File>`	`ROOTS` The file system roots.
`private static long`	`serialVersionUID`
`private static String`	`UNC_PREFIX` The prefix of a UNC (a Windows concept).

Fields inherited from class java.io.File
`pathSeparator, pathSeparatorChar, separator, separatorChar`

Constructor Summary
	`TFile(File file)` Copy constructor.
	`TFile(File parent, String member)` Equivalent to `new TFile(parent, child, null)`.
	`TFile(File parent, String member, TArchiveDetector detector)` Constructs a new `TFile` instance which uses the given `TArchiveDetector` to detect any archive files in its path and configure their parameters.
	`TFile(File file, TArchiveDetector detector)` Constructs a new `TFile` instance which may use the given `TArchiveDetector` to detect any archive files in its path.
`private`	`TFile(File delegate, TFile innerArchive, TArchiveDetector detector)`
`private`	`TFile(FsMountPoint mountPoint, TArchiveDetector detector)`
	`TFile(FsPath path)` Constructs a new `TFile` instance from the given `path`.
`private`	`TFile(FsPath path, TArchiveDetector detector)`
	`TFile(String path)` Equivalent to `new TFile(path, getDefaultArchiveDetector())`.
	`TFile(String parent, String member)` Equivalent to `new TFile(parent, child, getDefaultArchiveDetector())`.
	`TFile(String parent, String member, TArchiveDetector detector)` Constructs a new `TFile` instance which uses the given `TArchiveDetector` to detect any archive files in its path.
	`TFile(String path, TArchiveDetector detector)` Constructs a new `TFile` instance which uses the given `TArchiveDetector` to detect any archive files in its path.
	`TFile(URI uri)` Constructs a new `TFile` instance from the given `uri`.

Method Summary
`boolean`	`canRead()`
`boolean`	`canWrite()`
`static void`	`cat(InputStream in, OutputStream out)` Copies the data from the given input stream to the given output stream without closing them.
`int`	`compareTo(File other)` The implementation in the class `TFile` delegates the call to its `decorated file`.
`boolean`	`contains(File file)` Returns `true` if and only if the path represented by this instance contains the path represented by the specified `file`, where a path is said to contain another path if and only if it's equal or an ancestor of the other path.
`static boolean`	`contains(File a, File b)` Returns `true` if and only if the path represented by `a` contains the path represented by `b`, where a path is said to contain another path if and only if it's equal or an ancestor of the other path.
`private static TFile[]`	`convert(File[] files, TArchiveDetector detector)`
`TFile`	`cp_p(File dst)` Equivalent to `cp_p(this, dst)`.
`static void`	`cp_p(File src, File dst)` Copies the file `src` to the file `dst` and tries to preserve all attributes of the source file to the destination file, too.
`TFile`	`cp_r(File dst)` Equivalent to `cp_r(this, dst, getArchiveDetector(), getArchiveDetector())`.
`static void`	`cp_r(File src, File dst, TArchiveDetector srcDetector, TArchiveDetector dstDetector)` Recursively copies the file or directory `src` to the file or directory `dst`.
`TFile`	`cp_rp(File dst)` Equivalent to `cp_rp(this, dst, getArchiveDetector(), getArchiveDetector())`.
`static void`	`cp_rp(File src, File dst, TArchiveDetector srcDetector, TArchiveDetector dstDetector)` Recursively copies the file or directory `src` to the file or directory `dst` and tries to preserve all attributes of each source file to the destination file, too.
`TFile`	`cp(File dst)` Equivalent to `cp(this, dst)`.
`static void`	`cp(File src, File dst)` Copies the file `src` to the file `dst`.
`static void`	`cp(File src, OutputStream out)` Copies the file `src` to the output stream `out` and closes the stream - even if an exception occurs.
`static void`	`cp(InputStream in, File dst)` Copies the input stream `in` to the file `dst` and closes the stream - even if an exception occurs.
`static void`	`cp(InputStream in, OutputStream out)` Copies the data from the input stream `in` to the output stream `out` and closes both streams - even if an exception occurs.
`boolean`	`createNewFile()` Creates a new, empty file similar to its superclass implementation.
`private TFile[]`	`delegateListFiles(FileFilter filter, TArchiveDetector detector)`
`boolean`	`delete()` Deprecated. This method just returns a boolean value to indicate failure, which is hard to analyze.
`void`	`deleteOnExit()`
`boolean`	`equals(Object that)` The implementation in the class `TFile` delegates the call to its `decorated file`.
`boolean`	`exists()` This file system operation is virtually atomic.
`TFile`	`getAbsoluteFile()`
`String`	`getAbsolutePath()`
`TArchiveDetector`	`getArchiveDetector()` Returns the `TArchiveDetector` that was used to construct this object - never `null`.
`TFile`	`getCanonicalFile()`
`String`	`getCanonicalPath()`
`TFile`	`getCanOrAbsFile()` This convenience method simply returns the canonical form of this abstract path or the normalized absolute form if resolving the prior fails.
`String`	`getCanOrAbsPath()` This convenience method simply returns the canonical form of this abstract path or the normalized absolute form if resolving the prior fails.
`Icon`	`getClosedIcon()` If this file is a true archive file, its archive driver is asked to return an icon to be displayed for this file.
`(package private) FsController<?>`	`getController()` Returns a file system controller if and only if the path denotes an archive file, or `null` otherwise.
`static TArchiveDetector`	`getDefaultArchiveDetector()` Returns the `TArchiveDetector` to use if no archive detector is explicitly passed to the constructor of a `TFile` instance.
`TFile`	`getEnclArchive()` Returns the enclosing archive file in this path.
`String`	`getEnclEntryName()` Returns the entry path in the enclosing archive file.
`(package private) FsEntryName`	`getEnclEntryName0()`
`File`	`getFile()` Returns the decorated file object.
`TFile`	`getInnerArchive()` Returns the innermost archive file in this path.
`String`	`getInnerEntryName()` Returns the entry name in the innermost archive file.
`(package private) FsEntryName`	`getInnerEntryName0()`
`String`	`getName()`
`TFile`	`getNonArchivedParentFile()` Returns the first parent directory (starting from this file) which is not an archive file or a file located in an archive file.
`TFile`	`getNormalizedAbsoluteFile()` Similar to `getAbsoluteFile()`, but removes any `"."` and `".."` directories from the path name wherever possible.
`String`	`getNormalizedAbsolutePath()` Similar to `getAbsolutePath()`, but removes any redundant `"."` and `".."` directories from the path name.
`TFile`	`getNormalizedFile()` Removes any `"."` and `".."` directories from the path name wherever possible.
`String`	`getNormalizedPath()` Removes any redundant `"."`, `".."` directories from the path name.
`Icon`	`getOpenIcon()` If this file is a true archive file, its archive driver is asked to return an icon to be displayed for this file.
`String`	`getParent()`
`TFile`	`getParentFile()`
`String`	`getPath()`
`TFile`	`getTopLevelArchive()` Returns The top level archive file in the path or `null` if this path does not denote an archive.
`int`	`hashCode()` The implementation in the class `TFile` delegates the call to its `decorated file`.
`void`	`input(InputStream in)` Copies the input stream `in` to this file or entry in an archive file without closing it.
`private boolean`	`invariants()` Checks the invariants of this class and throws an AssertionError if any is violated even if assertion checking is disabled.
`boolean`	`isAbsolute()`
`boolean`	`isArchive()` Returns `true` if and only if the path represented by this instance denotes an archive file.
`boolean`	`isDirectory()` Similar to its super class implementation, but returns `true` for a valid archive file.
`boolean`	`isEntry()` Returns `true` if and only if the path represented by this instance names an archive file as its ancestor.
`boolean`	`isFile()` Similar to its super class implementation, but returns `false` for a valid archive file.
`boolean`	`isFileSystemRoot()` Returns `true` if and only if this file denotes a file system root or a UNC (if running on the Windows platform).
`boolean`	`isHidden()`
`static boolean`	`isLenient()` Returns the value of the class property `lenient`.
`boolean`	`isParentOf(File file)` Returns `true` if and only if the path represented by this instance is a direct or indirect parent of the path represented by the specified `file`.
`boolean`	`isUNC()` Returns `true` if and only if this file denotes a UNC.
`private static boolean`	`isUNC(String path)` Returns `true` iff the given path is a UNC.
`long`	`lastModified()` Returns a `long` value representing the time this file was last modified, measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970), or `0L` if the file does not exist or if an I/O error occurs or if this is a ghost directory in an archive file.
`long`	`length()` Returns the (uncompressed) getLength of the file.
`String[]`	`list()` Returns the names of the members in this directory in a newly created array.
`String[]`	`list(FilenameFilter filter)` Returns the names of the members in this directory which are accepted by `filenameFilter` in a newly created array.
`TFile[]`	`listFiles()` Equivalent to `listFiles((FilenameFilter) null, getArchiveDetector())`.
`TFile[]`	`listFiles(FileFilter fileFilter)` Equivalent to `listFiles(fileFilter, getArchiveDetector())`.
`TFile[]`	`listFiles(FileFilter filter, TArchiveDetector detector)` Returns `TFile` objects for the members in this directory which are accepted by `fileFilter` in a newly created array.
`TFile[]`	`listFiles(FilenameFilter filenameFilter)` Equivalent to `listFiles(filenameFilter, getArchiveDetector())`.
`TFile[]`	`listFiles(FilenameFilter filter, TArchiveDetector detector)` Returns `TFile` objects for the members in this directory which are accepted by `filenameFilter` in a newly created array.
`TFile[]`	`listFiles(TArchiveDetector detector)` Returns `TFile` objects for the members in this directory in a newly created array.
`boolean`	`mkdir()` Creates a new, empty (virtual) directory similar to its superclass implementation.
`TFile`	`mkdir(boolean recursive)` Ensures that a (virtual) directory with `this path name` exists in the (federated) file system.
`boolean`	`mkdirs()`
`TFile`	`mv(File dst)` Equivalent to `mv(this, dst, getArchiveDetector())`.
`static void`	`mv(File src, File dst, TArchiveDetector detector)` Moves the given source file or directory to the given destination file or directory.
`void`	`output(OutputStream out)` Copies this file or entry in an archive file to the output stream `out` without closing it.
`private void`	`parse(FsPath path, TArchiveDetector detector)`
`private void`	`readObject(ObjectInputStream in)`
`boolean`	`renameTo(File dst)` Deprecated. This method just returns a boolean value to indicate failure, which is hard to analyze.
`TFile`	`rm_r()` Equivalent to `rm_r(this)`.
`static void`	`rm_r(File node)` Recursively deletes the given file or directory tree.
`TFile`	`rm()` Equivalent to `rm(this)`.
`static void`	`rm(File node)` Deletes the given file or directory.
`private void`	`scan(TFile ancestor)` Initialize this file object by scanning its path for archive files, using the given `ancestor` file (i.e. a direct or indirect parent file) if any.
`private void`	`scan(TFile ancestor, TArchiveDetector detector, int skip, String path, StringBuilder enclEntryNameBuf, Paths.Splitter splitter)`
`static void`	`setDefaultArchiveDetector(TArchiveDetector detector)` Sets the `TArchiveDetector` to use if no archive detector is explicitly passed to the constructor of a `TFile` instance.
`boolean`	`setLastModified(long time)` Sets the last modification of this file or (virtual) directory.
`static void`	`setLenient(boolean lenient)` Sets the value of the class property `lenient`.
`boolean`	`setReadOnly()` Like the super class implementation, but is aware of archive files in its path.
`static void`	`sync(BitField<FsSyncOption> options)` Commits all unsynchronized changes to the contents of all federated file systems (i.e. archive files) to their respective parent file system, releases the associated resources (i.e. the target archive files) for access by third parties (e.g. other processes) and cleans up any temporary resources (i.e. temporary files).
`static void`	`sync(TFile archive, BitField<FsSyncOption> options)` Commits all unsynchronized changes to the contents of all federated file systems (i.e. archive files) identified by `archive` and all its member federated file systems to their respective parent file system, releases the associated resources (i.e. the target archive files) for access by third parties (e.g. other processes) and cleans up any temporary resources (i.e. temporary files).
`FsPath`	`toFsPath()`
`String`	`toString()`
`URI`	`toURI()`
`URL`	`toURL()` Deprecated.
`static void`	`umount()` Commits all unsynchronized changes to the contents of all federated file systems (i.e. archive files) to their respective parent file system, releases the associated resources (i.e. the target archive files) for access by third parties (e.g. other processes) and cleans up any temporary resources (i.e. temporary files).
`static void`	`umount(boolean closeStreams)` Commits all unsynchronized changes to the contents of all federated file systems (i.e. archive files) to their respective parent file system, releases the associated resources (i.e. the target archive files) for access by third parties (e.g. other processes) and cleans up any temporary resources (i.e. temporary files).
`static void`	`umount(boolean waitForInputStreams, boolean closeInputStreams, boolean waitForOutputStreams, boolean closeOutputStreams)` Commits all unsynchronized changes to the contents of all federated file systems (i.e. archive files) to their respective parent file system, releases the associated resources (i.e. the target archive files) for access by third parties (e.g. other processes) and cleans up any temporary resources (i.e. temporary files).
`static void`	`umount(TFile archive)` Commits all unsynchronized changes to the contents of all federated file systems (i.e. archive files) to their respective parent file system, releases the associated resources (i.e. the target archive files) for access by third parties (e.g. other processes) and cleans up any temporary resources (i.e. temporary files).
`static void`	`umount(TFile archive, boolean closeStreams)` Commits all unsynchronized changes to the contents of all federated file systems (i.e. archive files) to their respective parent file system, releases the associated resources (i.e. the target archive files) for access by third parties (e.g. other processes) and cleans up any temporary resources (i.e. temporary files).
`static void`	`umount(TFile archive, boolean waitForInputStreams, boolean closeInputStreams, boolean waitForOutputStreams, boolean closeOutputStreams)` Commits all unsynchronized changes to the contents of all federated file systems (i.e. archive files) to their respective parent file system, releases the associated resources (i.e. the target archive files) for access by third parties (e.g. other processes) and cleans up any temporary resources (i.e. temporary files).
`private void`	`writeObject(ObjectOutputStream out)`
`private Object`	`writeReplace()`

Methods inherited from class java.io.File
`canExecute, createTempFile, createTempFile, getFreeSpace, getTotalSpace, getUsableSpace, listRoots, setExecutable, setExecutable, setReadable, setReadable, setWritable, setWritable`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

serialVersionUID

private static final long serialVersionUID

See Also:: Constant Field Values

UNC_PREFIX

private static final String UNC_PREFIX

The prefix of a UNC (a Windows concept).

ROOTS

private static final Set<File> ROOTS

The file system roots.

manager

static final FsManager manager

The file system manager to use within this package.

defaultDetector

private static TArchiveDetector defaultDetector

lenient

private static boolean lenient

delegate

private transient File delegate

The delegate is used to implement the behaviour of the file system operations in case this instance represents neither an archive file nor an entry in an archive file. If this instance is constructed from another File instance, then this field is initialized with that instance.

This enables federation of file system implementations and is essential to enable the broken implementation in JFileChooser to browse archive files.

detector

private transient TArchiveDetector detector

innerArchive

@Nullable
private transient TFile innerArchive

enclArchive

@Nullable
private transient TFile enclArchive

enclEntryName

@Nullable
private transient FsEntryName enclEntryName

controller

@Nullable
private transient volatile FsController<?> controller

This refers to the file system controller if and only if this file is located within a federated file system, otherwise it's null. This field should be considered to be final!

See Also:: readObject(java.io.ObjectInputStream)

Constructor Detail

TFile

public TFile(File file)

Copy constructor. Equivalent to new TFile(template, getDefaultArchiveDetector()).

TFile

public TFile(File file,
             @CheckForNull
             TArchiveDetector detector)

Constructs a new TFile instance which may use the given TArchiveDetector to detect any archive files in its path.

Parameters:: file - The file to decorate. If this is an instance of this class, its fields are copied and the detector parameter is not used to scan the path.; detector - The object to use for the detection of any archive files in the path if necessary. This parameter is ignored if and only if file is an instance of this class. Otherwise, if it's null, the default archive detector is used.

TFile

public TFile(String path)

Equivalent to new TFile(path, getDefaultArchiveDetector()).

TFile

public TFile(String path,
             @CheckForNull
             TArchiveDetector detector)

Constructs a new TFile instance which uses the given TArchiveDetector to detect any archive files in its path.

Parameters:: path - The path of the file.; detector - The object to use for the detection of any archive files in the path. If this is null, the default archive detector is used.

TFile

public TFile(String parent,
             String member)

Equivalent to new TFile(parent, child, getDefaultArchiveDetector()).

TFile

public TFile(String parent,
             String member,
             @CheckForNull
             TArchiveDetector detector)

Constructs a new TFile instance which uses the given TArchiveDetector to detect any archive files in its path.

Parameters:: parent - The parent path as a String.; member - The child path as a String.; detector - The object to use for the detection of any archive files in the path. If this is null, the default archive detector is used.

TFile

public TFile(File parent,
             String member)

Equivalent to new TFile(parent, child, null).

Parameters:: parent - The parent directory as a TFile instance. If this parameter is an instance of this class, its TArchiveDetector is used to detect any archive files in the path of this TFile instance. Otherwise, the getDefaultArchiveDetector() is used. This is used in order to make this TFile instance behave as if it had been created by one of the listFiles() methods called on parent instead.; member - The child path as a String.

TFile

public TFile(File parent,
             String member,
             @CheckForNull
             TArchiveDetector detector)

Constructs a new TFile instance which uses the given TArchiveDetector to detect any archive files in its path and configure their parameters.

Parameters:: parent - The parent directory as a TFile instance.; member - The child path as a String.; detector - The object to use for the detection of any archive files in the path. If this is null and parent is an instance of this class, the archive detector is copied from parent. If this is null and parent is not an instance of this class, the default archive detector is used.

TFile

public TFile(URI uri)

Constructs a new TFile instance from the given uri. This method behaves similar to the super class constructor File.File(URI) with the following amendment: If the URI matches the pattern scheme:file:path!/entry, then the constructed file object treats the URI like an entry in the federated file system of the type named scheme. This can be applied recursively to access the entries of archive files within other archive files.

Note that the newly created TFile instance uses the default archive detector to look up archive drivers for the named scheme(s).

Parameters:: uri - an absolute URI with a scheme supported by the default archive detector.
Throws:: IllegalArgumentException - if the given URI does not conform to the syntax constraints for FsPaths or File.File(URI).

TFile

public TFile(FsPath path)

Constructs a new TFile instance from the given path. This method behaves similar to the super class constructor File.File(URI) with the following amendment: If the path matches the pattern scheme:file:path!/entry, then the constructed file object treats the URI like an entry in the federated file system of the type named scheme. This may be applied unlimitedly recursively to access archive entries within other archive files.

Note that the newly created TFile instance uses the default archive detector to look up archive drivers for the named scheme(s).

Parameters:: path - an absolute path with a scheme supported by the default archive detector.
Throws:: IllegalArgumentException - if the given URI does not conform to the syntax constraints for FsPaths or File.File(URI).

TFile

private TFile(FsPath path,
              TArchiveDetector detector)

TFile

private TFile(FsMountPoint mountPoint,
              TArchiveDetector detector)

TFile

private TFile(File delegate,
              @CheckForNull
              TFile innerArchive,
              TArchiveDetector detector)

Method Detail

parse

private void parse(FsPath path,
                   TArchiveDetector detector)

scan

private void scan(@CheckForNull
                  TFile ancestor)

Initialize this file object by scanning its path for archive files, using the given ancestor file (i.e. a direct or indirect parent file) if any. delegate and detector must already be initialized! Must not be called to re-initialize this object!

scan

private void scan(@CheckForNull
                  TFile ancestor,
                  TArchiveDetector detector,
                  int skip,
                  String path,
                  StringBuilder enclEntryNameBuf,
                  Paths.Splitter splitter)

writeReplace

private Object writeReplace()
                     throws ObjectStreamException

Throws:: ObjectStreamException

writeObject

private void writeObject(ObjectOutputStream out)
                  throws IOException

Throws:: IOException

readObject

private void readObject(ObjectInputStream in)
                 throws IOException,
                        ClassNotFoundException

Throws:: IOException; ClassNotFoundException

invariants

private boolean invariants()

Checks the invariants of this class and throws an AssertionError if any is violated even if assertion checking is disabled.

The constructors call this method like this:

assert invariants();

This calls the method if and only if assertions are enabled in order to assert that the instance invariants are properly obeyed. If assertions are disabled, the call to this method is thrown away by the HotSpot compiler, so there is no performance penalty.

When deserializing however, this method is called regardless of the assertion status. On error, the AssertionError is wrapped in an InvalidObjectException and thrown instead.

Returns:: true
Throws:: AssertionError - If any invariant is violated even if assertions are disabled.

sync

public static void sync(BitField<FsSyncOption> options)
                 throws FsSyncException

Commits all unsynchronized changes to the contents of all federated file systems (i.e. archive files) to their respective parent file system, releases the associated resources (i.e. the target archive files) for access by third parties (e.g. other processes) and cleans up any temporary resources (i.e. temporary files). Note that temporary files may get used even if the archive files where accessed read-only.

Throws:: IllegalArgumentException - if the combination of synchronization options is illegal, e.g. if FsSyncOption.FORCE_CLOSE_INPUT is cleared and FsSyncOption.FORCE_CLOSE_OUTPUT is set or if the synchronization option FsSyncOption.ABORT_CHANGES is set.; FsSyncWarningException - if only warning conditions occur. This implies that the respective parent file system has been updated with constraints, such as a failure to set the last modification time of the entry for the federated file system (i.e. archive file) in its parent file system.; FsSyncException - if any error conditions occur. This implies loss of data!

sync

public static void sync(TFile archive,
                        BitField<FsSyncOption> options)
                 throws FsSyncException

Commits all unsynchronized changes to the contents of all federated file systems (i.e. archive files) identified by archive and all its member federated file systems to their respective parent file system, releases the associated resources (i.e. the target archive files) for access by third parties (e.g. other processes) and cleans up any temporary resources (i.e. temporary files). Note that temporary files may get used even if the archive files where accessed read-only.

If a client application needs to sync an individual archive file, the following idiom could be used:

if (file.isArchive() && file.getEnclArchive() == null) // filter top level federated file system
   if (file.isDirectory()) // ignore false positives
     TFile.sync(file); // sync federated file system and all its members

Again, this will also sync all federated file systems which are located within the file system referred to by file.

Parameters:: archive - a top level federated file system, i.e. archive file.
Throws:: IllegalArgumentException - if archive is not a top level federated file system or the combination of synchronization options is illegal, e.g. if FsSyncOption.FORCE_CLOSE_INPUT is cleared and FsSyncOption.FORCE_CLOSE_OUTPUT is set or if the synchronization option FsSyncOption.ABORT_CHANGES is set.; FsSyncWarningException - if only warning conditions occur. This implies that the respective parent file system has been updated with constraints, such as a failure to set the last modification time of the entry for the federated file system (i.e. archive file) in its parent file system.; FsSyncException - if any error conditions occur. This implies loss of data!
See Also:: sync(BitField)

umount

public static void umount()
                   throws FsSyncException

This method is equivalent to calling sync(FsManager.UMOUNT).

Throws:: FsSyncWarningException - if only warning conditions occur. This implies that the respective parent file system has been updated with constraints, such as a failure to set the last modification time of the entry for the federated file system (i.e. archive file) in its parent file system.; FsSyncException - if any error conditions occur. This implies loss of data!
See Also:: sync(BitField)

umount

public static void umount(boolean closeStreams)
                   throws FsSyncException

This method is equivalent to calling sync( BitField.of(FsSyncOption.CLEAR_CACHE) .set(FsSyncOption.FORCE_CLOSE_INPUT, closeStreams) .set(FsSyncOption.FORCE_CLOSE_OUTPUT, closeStreams)).

Throws:: FsSyncWarningException - if only warning conditions occur. This implies that the respective parent file system has been updated with constraints, such as a failure to set the last modification time of the entry for the federated file system (i.e. archive file) in its parent file system.; FsSyncException - if any error conditions occur. This implies loss of data!
See Also:: sync(BitField)

umount

public static void umount(boolean waitForInputStreams,
                          boolean closeInputStreams,
                          boolean waitForOutputStreams,
                          boolean closeOutputStreams)
                   throws FsSyncException

This method is equivalent to calling sync( BitField.of(FsSyncOption.CLEAR_CACHE) .set(FsSyncOption.WAIT_CLOSE_INPUT, waitForInputStreams) .set(FsSyncOption.FORCE_CLOSE_INPUT, closeInputStreams) .set(FsSyncOption.WAIT_CLOSE_OUTPUT, waitForOutputStreams) .set(FsSyncOption.FORCE_CLOSE_OUTPUT, closeOutputStreams)).

Throws:: FsSyncWarningException - if only warning conditions occur. This implies that the respective parent file system has been updated with constraints, such as a failure to set the last modification time of the entry for the federated file system (i.e. archive file) in its parent file system.; FsSyncException - if any error conditions occur. This implies loss of data!
See Also:: sync(BitField)

umount

public static void umount(TFile archive)
                   throws FsSyncException

This method is equivalent to calling sync(archive, FsManager.UMOUNT).

Throws:: FsSyncWarningException - if only warning conditions occur. This implies that the respective parent file system has been updated with constraints, such as a failure to set the last modification time of the entry for the federated file system (i.e. archive file) in its parent file system.; FsSyncException - if any error conditions occur. This implies loss of data!
See Also:: sync(TFile, BitField)

umount

public static void umount(TFile archive,
                          boolean closeStreams)
                   throws FsSyncException

This method is equivalent to calling sync( archive, BitField.of(FsSyncOption.CLEAR_CACHE) .set(FsSyncOption.FORCE_CLOSE_INPUT, closeStreams) .set(FsSyncOption.FORCE_CLOSE_OUTPUT, closeStreams)).

Throws:: FsSyncWarningException - if only warning conditions occur. This implies that the respective parent file system has been updated with constraints, such as a failure to set the last modification time of the entry for the federated file system (i.e. archive file) in its parent file system.; FsSyncException - if any error conditions occur. This implies loss of data!
See Also:: sync(TFile, BitField)

umount

public static void umount(TFile archive,
                          boolean waitForInputStreams,
                          boolean closeInputStreams,
                          boolean waitForOutputStreams,
                          boolean closeOutputStreams)
                   throws FsSyncException

This method is equivalent to calling sync( archive, BitField.of(FsSyncOption.CLEAR_CACHE) .set(FsSyncOption.WAIT_CLOSE_INPUT, waitForInputStreams) .set(FsSyncOption.FORCE_CLOSE_INPUT, closeInputStreams) .set(FsSyncOption.WAIT_CLOSE_OUTPUT, waitForOutputStreams) .set(FsSyncOption.FORCE_CLOSE_OUTPUT, closeOutputStreams)).

Throws:: FsSyncWarningException - if only warning conditions occur. This implies that the respective parent file system has been updated with constraints, such as a failure to set the last modification time of the entry for the federated file system (i.e. archive file) in its parent file system.; FsSyncException - if any error conditions occur. This implies loss of data!
See Also:: sync(TFile, BitField)

isLenient

public static boolean isLenient()

Returns the value of the class property lenient. By default, the value of this class property is true.

See Also:: setLenient(boolean)

setLenient

public static void setLenient(boolean lenient)

Sets the value of the class property lenient. This class property controls whether archive files and their member directories get automatically created whenever required. By default, the value of this class property is true!

Consider the following path: a/outer.zip/b/inner.zip/c. Now let's assume that a exists as a plain directory in the OS file system, while all other parts of this path don't, and that the module TrueZIP Driver ZIP is present on the run-time class path in order to recognize outer.zip and inner.zip as ZIP files by default.

Now, if this class property is set to false, then an application would have to call new TFile("a/outer.zip/b/inner.zip").mkdirs() before it could actually create the innermost c entry as a file or directory.

More formally, before an application could access an entry in a federated file system, all its parent directories would need to exist, including archive files. This emulates the behaviour of any OS file system type.

If this class property is set to true however, then any missing parent directories (including archive files) up to the outermost archive file outer.zip would get automatically created when using operations to create the innermost element of the path c.

This allows applications to succeed with doing this: new TFile("a/outer.zip/b/inner.zip/c").createNewFile(), or that: new TFileOutputStream("a/outer.zip/b/inner.zip/c").

Note that in either case the parent directory of the outermost archive file a must exist - TrueZIP does not automatically create directories in the OS file system!

See Also:: isLenient()

getDefaultArchiveDetector

public static TArchiveDetector getDefaultArchiveDetector()

Returns the TArchiveDetector to use if no archive detector is explicitly passed to the constructor of a TFile instance.

This class property is initially set to TArchiveDetector.ALL

See Also:: setDefaultArchiveDetector(de.schlichtherle.truezip.file.TArchiveDetector)

setDefaultArchiveDetector

public static void setDefaultArchiveDetector(TArchiveDetector detector)

Sets the TArchiveDetector to use if no archive detector is explicitly passed to the constructor of a TFile instance. When a new TFile instance is constructed, but no archive detector parameter is provided, then the value of this class property is used. So changing the value of this class property affects only subsequently constructed TFile instances - not any existing ones.

Parameters:: detector - the TArchiveDetector to use for subsequently constructed TFile instances if no archive detector is explicitly passed to the constructor
See Also:: getDefaultArchiveDetector()

getNonArchivedParentFile

@Nullable
public TFile getNonArchivedParentFile()

Returns the first parent directory (starting from this file) which is not an archive file or a file located in an archive file.

getParent

@Nullable
public String getParent()

Overrides:: getParent in class File

getParentFile

@Nullable
public TFile getParentFile()

Overrides:: getParentFile in class File

getAbsoluteFile

public TFile getAbsoluteFile()

Overrides:: getAbsoluteFile in class File

getAbsolutePath

public String getAbsolutePath()

Overrides:: getAbsolutePath in class File

getNormalizedAbsoluteFile

public TFile getNormalizedAbsoluteFile()

Similar to getAbsoluteFile(), but removes any "." and ".." directories from the path name wherever possible. The result is similar to getCanonicalFile(), but symbolic links are not resolved. This may be useful if getCanonicalFile() throws an IOException.

See Also:: getCanonicalFile(), getNormalizedFile()

getNormalizedAbsolutePath

public String getNormalizedAbsolutePath()

Similar to getAbsolutePath(), but removes any redundant "." and ".." directories from the path name. The result is similar to getCanonicalPath(), but symbolic links are not resolved. This may be useful if getCanonicalPath() throws an IOException.

See Also:: getCanonicalPath(), getNormalizedPath()

getNormalizedFile

public TFile getNormalizedFile()

Removes any "." and ".." directories from the path name wherever possible.

Returns:: If this file is already normalized, it is returned. Otherwise a new instance of this class is returned.

getNormalizedPath

public String getNormalizedPath()

Removes any redundant ".", ".." directories from the path name.

Returns:: The normalized path of this file as a String.

getCanonicalFile

public TFile getCanonicalFile()
                       throws IOException

Overrides:: getCanonicalFile in class File

Throws:: IOException

getCanonicalPath

public String getCanonicalPath()
                        throws IOException

Overrides:: getCanonicalPath in class File

Throws:: IOException

getCanOrAbsFile

public final TFile getCanOrAbsFile()

This convenience method simply returns the canonical form of this abstract path or the normalized absolute form if resolving the prior fails.

Returns:: The canonical or absolute path of this file as an instance of this class.

getCanOrAbsPath

public String getCanOrAbsPath()

This convenience method simply returns the canonical form of this abstract path or the normalized absolute form if resolving the prior fails.

Returns:: The canonical or absolute path of this file as a String instance.

isArchive

public boolean isArchive()

Returns true if and only if the path represented by this instance denotes an archive file. Whether or not this is true solely depends on the TArchiveDetector which was used to construct this TFile instance.

Please note that no file system tests are performed! If you need to know whether this file really exists as an archive file in the file system (and the correct password has been entered in case it's a RAES encrypted ZIP file), you should call isDirectory(), too. This will automount the (virtual) file system from the archive file and return true if and only if it's a valid archive file.

See Also:: Recognizing Archive Paths and False Positives, isDirectory(), isEntry()

isEntry

public boolean isEntry()

Returns true if and only if the path represented by this instance names an archive file as its ancestor. Whether or not this is true solely depends on the TArchiveDetector which was used to construct this TFile instance.

Please note that no file system tests are performed! If you need to know whether this file is really an entry in an archive file (and the correct password has been entered in case it's a RAES encrypted ZIP file), you should call getParentFile().isDirectory(), too. This will automount the (virtual) file system from the archive file and return true if and only if it's a valid archive file.

See Also:: Recognizing Archive Paths and False Positives, isArchive(), isDirectory()

getInnerArchive

@CheckForNull
public TFile getInnerArchive()

Returns the innermost archive file in this path. I.e. if this object is an archive file, then this method returns this object. If this object is a file or directory located within a archive file, then this methods returns the file representing the enclosing archive file, or null otherwise.

This method always returns a normalized path, i.e. all occurences of "." and ".." in the path name are removed according to their meaning wherever possible.

In order to support unlimited nesting levels, this method returns a TFile instance which again could be an entry within another archive file.

getInnerEntryName

@Nullable
public String getInnerEntryName()

Returns the entry name in the innermost archive file. I.e. if this object is a archive file, then this method returns the empty string "". If this object is a file or directory located within an archive file, then this method returns the relative path of the entry in the enclosing archive file separated by the entry separator character '/', or null otherwise.

This method always returns an undotified path, i.e. all occurences of "." and ".." in the path name are removed according to their meaning wherever possible.

getInnerEntryName0

@Nullable
FsEntryName getInnerEntryName0()

getEnclArchive

@CheckForNull
public TFile getEnclArchive()

Returns the enclosing archive file in this path. I.e. if this object is an entry located within an archive file, then this method returns the file representing the enclosing archive file, or null otherwise.

This method always returns a normalized path, i.e. all occurences of "." and ".." in the path name are removed according to their meaning wherever possible.

In order to support unlimited nesting levels, this method returns a TFile instance which again could be an entry within another archive file.

getEnclEntryName

@Nullable
public String getEnclEntryName()

Returns the entry path in the enclosing archive file. I.e. if this object is an entry located within a archive file, then this method returns the relative path of the entry in the enclosing archive file separated by the entry separator character '/', or null otherwise.

This method always returns an undotified path, i.e. all occurences of "." and ".." in the path are removed according to their meaning wherever possible.

getEnclEntryName0

@Nullable
final FsEntryName getEnclEntryName0()

getArchiveDetector

public final TArchiveDetector getArchiveDetector()

Returns the TArchiveDetector that was used to construct this object - never null.

getFile

public File getFile()

Returns the decorated file object.

If this file instance has been created from a FileSystemView, the decorated file object may be an instance of a sibling class, i.e. another sub-class of File.

Returns:: An instance of the File class or any of its sub-classes, but never an instance of this class and never null.

getController

@Nullable
FsController<?> getController()

Returns a file system controller if and only if the path denotes an archive file, or null otherwise.

isParentOf

public boolean isParentOf(File file)

Returns true if and only if the path represented by this instance is a direct or indirect parent of the path represented by the specified file.

Note:

This method uses the absolute path name of the given files.
This method does not access the file system. It just tests the paths.

Parameters:: file - The path to test for being a direct or indirect child of this path.

contains

public boolean contains(File file)

Returns true if and only if the path represented by this instance contains the path represented by the specified file, where a path is said to contain another path if and only if it's equal or an ancestor of the other path.

Note:

This method uses the absolute path name of the given files.
This method does not access the file system. It just tests the paths.

Parameters:: file - The path to test for being contained by this path.
Throws:: NullPointerException - If the parameter is null.

contains

public static boolean contains(File a,
                               File b)

Returns true if and only if the path represented by a contains the path represented by b, where a path is said to contain another path if and only if it's equal or an ancestor of the other path.

Note:

This method uses the absolute path name of the given files.
This method does not access the file system. It just tests the paths.

Parameters:: a - The file to test for containing b.; b - The file to test for being contained by a.
Throws:: NullPointerException - If any parameter is null.

isFileSystemRoot

public boolean isFileSystemRoot()

Returns true if and only if this file denotes a file system root or a UNC (if running on the Windows platform).

isUNC

public boolean isUNC()

Returns true if and only if this file denotes a UNC. Note that this should be relevant on the Windows platform only.

isUNC

private static boolean isUNC(String path)

Returns true iff the given path is a UNC. Note that this may be only relevant on the Windows platform.

hashCode

public int hashCode()

The implementation in the class TFile delegates the call to its decorated file.

Overrides:: hashCode in class File

See Also:: equals(Object)

equals

public boolean equals(Object that)

The implementation in the class TFile delegates the call to its decorated file. This implies that only the hierarchicalized file system path of this file instance is considered in the comparison. E.g. new TFile(FsPath.create("zip:file:/archive!/entry")) and new TFile(FsPath.create("tar:file:/archive!/entry")) would compare equal because their hierarchicalized file system path is "file:/archive/entry".

More formally, let a and b be two TFile objects. Then if the expression a.toFsPath().hierarchicalize().equals(b.toFsPath().hierarchicalize()) is true, the expression a.equals(b) is also true.

Note that this does not work vice versa: E.g. on Windows, the expression new TFile("file").equals(new TFile("FILE")) is true, but new TFile("file").toFsPath().hierarchicalize().equals(new TFile("FILE").toFsPath().hierarchicalize()) is false because FsPath.equals(Object) is case sensitive.

Overrides:: equals in class File

See Also:: hashCode(), compareTo(File)

compareTo

public int compareTo(File other)

The implementation in the class TFile delegates the call to its decorated file. This implies that only the hierarchicalized file system path Note that this implies that only the hierarchicalized file system path of this file instance is considered in the comparison. E.g. new TFile(FsPath.create("zip:file:/archive!/entry")) and new TFile(FsPath.create("tar:file:/archive!/entry")) would compare equal because their hierarchicalized file system path is "file:/archive/entry".

More formally, let a and b be two TFile objects. Then if the expression a.toFsPath().hierarchicalize().compareTo(b.toFsPath().hierarchicalize()) == 0 is true, the expression a.compareTo(b) == 0 is also true.

Note that this does not work vice versa: E.g. on Windows, the expression new TFile("file").compareTo(new TFile("FILE")) == 0 is true, but new TFile("file").toFsPath().hierarchicalize().compareTo(new TFile("FILE").toFsPath().hierarchicalize()) == 0 is false because FsPath.equals(Object) is case sensitive.

Specified by:: compareTo in interface Comparable<File>
Overrides:: compareTo in class File

See Also:: equals(Object)

getTopLevelArchive

public TFile getTopLevelArchive()

Returns The top level archive file in the path or null if this path does not denote an archive. A top level archive is not enclosed in another archive. If this does not return null, this denotes the longest part of the path which actually may (but does not need to) exist as a plain file in the real file system.

getPath

public String getPath()

Overrides:: getPath in class File

getName

public String getName()

Overrides:: getName in class File

isAbsolute

public boolean isAbsolute()

Overrides:: isAbsolute in class File

isHidden

public boolean isHidden()

Overrides:: isHidden in class File

toString

public String toString()

Overrides:: toString in class File

toFsPath

public FsPath toFsPath()

toURI

public URI toURI()

Overrides:: toURI in class File

toURL

@Deprecated
public URL toURL()
          throws MalformedURLException

Deprecated.

Overrides:: toURL in class File

Throws:: MalformedURLException

exists

public boolean exists()

This file system operation is virtually atomic.

Overrides:: exists in class File

See Also:: Recognizing Archive Paths and False Positives

isFile

public boolean isFile()

Similar to its super class implementation, but returns false for a valid archive file.

This file system operation is virtually atomic.

Overrides:: isFile in class File

See Also:: Recognizing Archive Paths and False Positives

isDirectory

public boolean isDirectory()

Similar to its super class implementation, but returns true for a valid archive file.

In case a RAES encrypted ZIP file is tested which is accessed for the first time, the user is prompted for the password (if password based encryption is used). Note that this is not the only method which would prompt the user for a password: For example, length() would prompt the user and return 0 unless the user cancels the prompting or the file is a false positive archive file.

This file system operation is virtually atomic.

Overrides:: isDirectory in class File

See Also:: Recognizing Archive Paths and False Positives, isArchive(), isEntry()

getOpenIcon

@CheckForNull
public Icon getOpenIcon()

If this file is a true archive file, its archive driver is asked to return an icon to be displayed for this file. Otherwise, null is returned.

getClosedIcon

@CheckForNull
public Icon getClosedIcon()

If this file is a true archive file, its archive driver is asked to return an icon to be displayed for this file. Otherwise, null is returned.

canRead

public boolean canRead()

Overrides:: canRead in class File

canWrite

public boolean canWrite()

Overrides:: canWrite in class File

setReadOnly

public boolean setReadOnly()

Like the super class implementation, but is aware of archive files in its path. For entries in a archive file, this is effectively a no-op: The method will only return true if the entry isExisting and the archive file was mounted read only.

This file system operation is virtually atomic.

Overrides:: setReadOnly in class File

length

public long length()

Returns the (uncompressed) getLength of the file. The getLength returned of a valid archive file is 0 in order to correctly emulate virtual directories across all platforms.

In case a RAES encrypted ZIP file is tested which is accessed for the first time, the user is prompted for the password (if password based encryption is used). Note that this is not the only method which would prompt the user for a password: For example, isDirectory() would prompt the user and return true unless the user cancels the prompting or the file is a false positive archive file.

This file system operation is virtually atomic.

Overrides:: length in class File

See Also:: Recognizing Archive Paths and False Positives

lastModified

public long lastModified()

Returns a long value representing the time this file was last modified, measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970), or 0L if the file does not exist or if an I/O error occurs or if this is a ghost directory in an archive file.

This file system operation is virtually atomic.

Overrides:: lastModified in class File

See Also:: Package description for more information about ghost directories

setLastModified

public boolean setLastModified(long time)

Sets the last modification of this file or (virtual) directory. If this is a ghost directory within an archive file, it's reincarnated as a plain directory within the archive file.

Note that calling this method may incur a severe performance penalty if the file is an entry in an archive file which has just been written (such as after a normal copy operation). If you want to copy a file's contents as well as its last modification time, use cp_p(File, File) instead.

This file system operation is virtually atomic.

Overrides:: setLastModified in class File

See Also:: cp_p(File, File), Package description for more information about ghost directories

list

@Nullable
public String[] list()

Returns the names of the members in this directory in a newly created array. The returned array is not sorted. This is the most efficient list method.

Note: Archive entries with absolute paths are ignored by this method and are never returned.

This file system operation is virtually atomic.

Overrides:: list in class File

list

@Nullable
public String[] list(@CheckForNull
                              FilenameFilter filter)

Returns the names of the members in this directory which are accepted by filenameFilter in a newly created array. The returned array is not sorted.

Note: Archive entries with absolute paths are ignored by this method and are never returned.

This file system operation is virtually atomic.

Overrides:: list in class File

Returns:: null if this is not a directory or an archive file, a valid (but maybe empty) array otherwise.

listFiles

@Nullable
public TFile[] listFiles()

Equivalent to listFiles((FilenameFilter) null, getArchiveDetector()).

Overrides:: listFiles in class File

listFiles

@Nullable
public TFile[] listFiles(TArchiveDetector detector)

Returns TFile objects for the members in this directory in a newly created array. The returned array is not sorted.

Note that archive entries with absolute paths are ignored by this method and are never returned.

This file system operation is virtually atomic.

Parameters:: detector - The archive detector to detect any archives files in the member file names.
Returns:: null if this is not a directory or an archive file, a valid (but maybe empty) array otherwise.

listFiles

@Nullable
public TFile[] listFiles(@CheckForNull
                                  FilenameFilter filenameFilter)

Equivalent to listFiles(filenameFilter, getArchiveDetector()).

Overrides:: listFiles in class File

listFiles

@Nullable
public TFile[] listFiles(@CheckForNull
                                  FilenameFilter filter,
                                  TArchiveDetector detector)

Returns TFile objects for the members in this directory which are accepted by filenameFilter in a newly created array. The returned array is not sorted.

Note that archive entries with absolute paths are ignored by this method and are never returned.

This file system operation is virtually atomic.

Parameters:: detector - The archive detector to detect any archives files in the member file names.
Returns:: null if this is not a directory or an archive file, a valid (but maybe empty) array otherwise.

convert

@Nullable
private static TFile[] convert(File[] files,
                                        TArchiveDetector detector)

listFiles

@Nullable
public TFile[] listFiles(@CheckForNull
                                  FileFilter fileFilter)

Equivalent to listFiles(fileFilter, getArchiveDetector()).

Overrides:: listFiles in class File

listFiles

@Nullable
public TFile[] listFiles(@CheckForNull
                                  FileFilter filter,
                                  TArchiveDetector detector)

Returns TFile objects for the members in this directory which are accepted by fileFilter in a newly created array. The returned array is not sorted.

Note that archive entries with absolute paths are ignored by this method and are never returned.

This file system operation is virtually atomic.

Parameters:: detector - The archive detector to detect any archives files in the member file names.
Returns:: null if this is not a directory or an archive file, a valid (but maybe empty) array otherwise.

delegateListFiles

@Nullable
private TFile[] delegateListFiles(@CheckForNull
                                           FileFilter filter,
                                           TArchiveDetector detector)

createNewFile

public boolean createNewFile()
                      throws IOException

Creates a new, empty file similar to its superclass implementation. Note that this method doesn't create archive files because archive files are virtual directories, not files!

This file system operation is virtually atomic.

Overrides:: createNewFile in class File

Throws:: IOException
See Also:: mkdir()

mkdirs

public boolean mkdirs()

Overrides:: mkdirs in class File

mkdir

public boolean mkdir()

Creates a new, empty (virtual) directory similar to its superclass implementation. This method creates an archive file if isArchive() returns true. Example: new TFile("archive.zip").mkdir();

Alternatively, archive files get created automatically by simply creating their entries. Example: new TFileOutputStream("archive.zip/README"); This assumes the default configuration where isLenient() returns true.

This file system operation is virtually atomic.

Overrides:: mkdir in class File

mkdir

public TFile mkdir(boolean recursive)
            throws IOException

Ensures that a (virtual) directory with this path name exists in the (federated) file system.

Parameters:: recursive - whether or not any missing ancestor directories shall get created if required.
Returns:: this
Throws:: IOException - if any I/O error occurs.

delete

@Deprecated
public final boolean delete()

Deprecated. This method just returns a boolean value to indicate failure, which is hard to analyze.

Overrides:: delete in class File

See Also:: rm()

rm

public TFile rm()
         throws IOException

Equivalent to rm(this).

Returns:: this
Throws:: IOException - if any I/O error occurs.

rm

public static void rm(File node)
               throws IOException

Deletes the given file or directory. If the file is a directory, it must be empty. This file system operation is virtually atomic.

Throws:: IOException - if any I/O error occurs.

rm_r

public TFile rm_r()
           throws IOException

Equivalent to rm_r(this).

Returns:: this
Throws:: IOException - if any I/O error occurs.

rm_r

public static void rm_r(File node)
                 throws IOException

Recursively deletes the given file or directory tree. This file system operation is not atomic.

If node is an instance of this class, its archive detector is used to detect prospective archive files in the directory tree. Otherwise, TArchiveDetector.NULL is used to detect prospective archive files in the directory tree.

Throws:: IOException - if any I/O error occurs.

deleteOnExit

public void deleteOnExit()

Overrides:: deleteOnExit in class File

renameTo

@Deprecated
public final boolean renameTo(File dst)

Deprecated. This method just returns a boolean value to indicate failure, which is hard to analyze.

Overrides:: renameTo in class File

See Also:: mv(File)

mv

public TFile mv(File dst)
         throws IOException

Equivalent to mv(this, dst, getArchiveDetector()).

Parameters:: dst - the destination file or directory tree.
Returns:: this
Throws:: IOException - if any I/O error occurs.

mv

public static void mv(File src,
                      File dst,
                      TArchiveDetector detector)
               throws IOException

Moves the given source file or directory to the given destination file or directory.

In certain cases, this method might perform a recursive copy-then-delete operation rather than an atomic move operation. This method uses the given archive detector to detect any archive files when traversing a directory tree.

Parameters:: src - the source file or directory tree.; dst - the destination file or directory tree.; detector - the archive detector to use for detecting any archive files in the source directory tree.
Throws:: IOException - if any I/O error occurs.
See Also:: Copy Methods, Traversing Directory Trees

cp

public static void cp(InputStream in,
                      OutputStream out)
               throws IOException

Copies the data from the input stream in to the output stream out and closes both streams - even if an exception occurs.

This is a high performance implementation which uses a pooled background thread to fill a FIFO of pooled buffers which is concurrently flushed by the current thread. It performs best when used with unbuffered streams.

Feature	Supported
Preserves file attributes	n/a
Copies directories recursively	n/a
Reads and overwrites special files	n/a
Closes parameter streams	Always
Direct Data Copying (DDC)	n/a
Deletes partial written files on failure	n/a
Deletes partial written directories on failure	n/a
Atomic	No

Parameters:: in - the input stream.; out - the output stream.
Throws:: IOException - if any I/O error occurs.
See Also:: cat(InputStream, OutputStream), Copy Methods

cp

public static void cp(InputStream in,
                      File dst)
               throws IOException

Copies the input stream in to the file dst and closes the stream - even if an exception occurs.

Feature	Supported
Preserves file attributes	None
Copies directories recursively	No
Reads and overwrites special files	Yes
Closes parameter streams	Always
Direct Data Copying (DDC)	No
Deletes partial written files on failure	Yes
Deletes partial written directories on failure	n/a
Atomic	No

Parameters:: dst - the destination file. Note that although this just needs to be a plain File, archive entries are only supported for instances of this class.
Throws:: IOException - if any I/O error occurs.
See Also:: Copy Methods

cp

public static void cp(File src,
                      OutputStream out)
               throws IOException

Copies the file src to the output stream out and closes the stream - even if an exception occurs.

Feature	Supported
Preserves file attributes	None
Copies directories recursively	No
Reads and overwrites special files	Yes
Closes parameter streams	Always
Direct Data Copying (DDC)	No
Deletes partial written files on failure	n/a
Deletes partial written directories on failure	n/a
Atomic	No

Parameters:: src - the source file. Note that although this just needs to be a plain File, archive entries are only supported for instances of this class.
Throws:: IOException - if any I/O error occurs.
See Also:: Copy Methods

cp

public TFile cp(File dst)
         throws IOException

Equivalent to cp(this, dst).

Parameters:: dst - the destination file.
Returns:: this
Throws:: IOException - if any I/O error occurs.

cp

public static void cp(File src,
                      File dst)
               throws IOException

Copies the file src to the file dst.

Feature	Supported
Preserves file attributes	None
Copies directories recursively	No
Reads and overwrites special files	Yes
Closes parameter streams	n/a
Direct Data Copying (DDC)	Yes
Deletes partial written files on failure	Yes
Deletes partial written directories on failure	n/a
Atomic	No

Parameters:: src - the source file. Note that although this just needs to be a plain File, archive entries are only supported for instances of this class.; dst - the destination file. Note that although this just needs to be a plain File, archive entries are only supported for instances of this class.
Throws:: IOException - if any I/O error occurs.
See Also:: Copy Methods

cp_p

public TFile cp_p(File dst)
           throws IOException

Equivalent to cp_p(this, dst).

Parameters:: dst - the destination file.
Returns:: this
Throws:: IOException - if any I/O error occurs.

cp_p

public static void cp_p(File src,
                        File dst)
                 throws IOException

Copies the file src to the file dst and tries to preserve all attributes of the source file to the destination file, too. Currently, only the last modification time is preserved.

Feature	Supported
Preserves file attributes	Best effort
Copies directories recursively	No
Reads and overwrites special files	Yes
Closes parameter streams	n/a
Direct Data Copying (DDC)	Yes
Deletes partial written files on failure	Yes
Deletes partial written directories on failure	n/a
Atomic	No

Parameters:: src - the source file. Note that although this just needs to be a plain File, archive entries are only supported for instances of this class.; dst - the destination file. Note that although this just needs to be a plain File, archive entries are only supported for instances of this class.
Throws:: IOException - if any I/O error occurs.
See Also:: Copy Methods

cp_r

public TFile cp_r(File dst)
           throws IOException

Equivalent to cp_r(this, dst, getArchiveDetector(), getArchiveDetector()).

Parameters:: dst - the destination file or directory tree.
Returns:: this
Throws:: IOException - if any I/O error occurs.

cp_r

public static void cp_r(File src,
                        File dst,
                        TArchiveDetector srcDetector,
                        TArchiveDetector dstDetector)
                 throws IOException

Recursively copies the file or directory src to the file or directory dst.

This method uses the given archive detectors to detect any archive files in the source and destination directory trees.

Feature	Supported
Preserves file attributes	None
Copies directories recursively	Yes
Reads and overwrites special files	No
Closes parameter streams	n/a
Direct Data Copying (DDC)	Yes
Deletes partial written files on failure	Yes
Deletes partial written directories on failure	No
Atomic	No

Parameters:: src - the source file. Note that although this just needs to be a plain File, archive files and entries are only supported for instances of this class.; dst - the destination file. Note that although this just needs to be a plain File, archive files and entries are only supported for instances of this class.; srcDetector - the archive detector to use for detecting any archive files in the source directory tree.; dstDetector - the archive detector to use for detecting any archive files in the destination directory tree.
Throws:: IOException - if any I/O error occurs.
See Also:: Copy Methods, Traversing Directory Trees

cp_rp

public TFile cp_rp(File dst)
            throws IOException

Equivalent to cp_rp(this, dst, getArchiveDetector(), getArchiveDetector()).

Parameters:: dst - the destination file or directory tree.
Returns:: this
Throws:: IOException - if any I/O error occurs.

cp_rp

public static void cp_rp(File src,
                         File dst,
                         TArchiveDetector srcDetector,
                         TArchiveDetector dstDetector)
                  throws IOException

Recursively copies the file or directory src to the file or directory dst and tries to preserve all attributes of each source file to the destination file, too. Note that the current implementation only preserves the last modification time.

This method uses the given archive detectors to detect any archive files when traversing a directory tree.

Feature	Supported
Preserves file attributes	Best effort
Copies directories recursively	Yes
Reads and overwrites special files	No
Closes parameter streams	n/a
Direct Data Copying (DDC)	Yes
Deletes partial written files on failure	Yes
Deletes partial written directories on failure	No
Atomic	No

Parameters:: src - the source file. Note that although this just needs to be a plain File, archive files and entries are only supported for instances of this class.; dst - the destination file. Note that although this just needs to be a plain File, archive files and entries are only supported for instances of this class.
Throws:: IOException - if any I/O error occurs.
See Also:: Copy Methods, Traversing Directory Trees

input

public void input(InputStream in)
           throws IOException

Copies the input stream in to this file or entry in an archive file without closing it.

Feature	Supported
Preserves file attributes	n/a
Copies directories recursively	n/a
Reads and overwrites special files	Yes
Closes parameter streams	Never
Direct Data Copying (DDC)	n/a
Deletes partial written files on failure	Yes
Deletes partial written directories on failure	n/a
Atomic	No

Parameters:: in - the input stream.
Throws:: IOException - if any I/O error occurs.
See Also:: Copy Methods

output

public void output(OutputStream out)
            throws IOException

Copies this file or entry in an archive file to the output stream out without closing it.

Feature	Supported
Preserves file attributes	n/a
Copies directories recursively	n/a
Reads and overwrites special files	Yes
Closes parameter streams	Never
Direct Data Copying (DDC)	n/a
Deletes partial written files on failure	n/a
Deletes partial written directories on failure	n/a
Atomic	No

Parameters:: out - the output stream.
Throws:: IOException - if any I/O error occurs.
See Also:: Copy Methods

cat

public static void cat(InputStream in,
                       OutputStream out)
                throws IOException

Copies the data from the given input stream to the given output stream without closing them. The name of this method is inspired by the Unix command line utility cat because you could use it to concatenate the contents of multiple streams.

This is a high performance implementation which uses a pooled background thread to fill a FIFO of data buffers which is concurrently flushed by the current thread.

Feature	Supported
Preserves file attributes	n/a
Copies directories recursively	n/a
Reads and overwrites special files	n/a
Closes parameter streams	Never
Direct Data Copying (DDC)	n/a
Deletes partial written files on failure	n/a
Deletes partial written directories on failure	n/a
Atomic	No

Parameters:: in - the input stream.; out - the output stream.
Throws:: IOException - if any I/O error occurs.
See Also:: cp(InputStream, OutputStream), Copy Methods

Overview

Package

Class

Use

Tree

Deprecated

Index

TrueZIP File* 7.0

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

de.schlichtherle.truezip.file Class TFile

Bulk I/O Methods

Direct Data Copying (DDC)

Traversing Directory Trees

Recognizing Archive Files and False Positives

serialVersionUID

UNC_PREFIX

ROOTS

manager

defaultDetector

lenient

delegate

detector

innerArchive

enclArchive

enclEntryName

controller

TFile

TFile

TFile

TFile

TFile

TFile

TFile

TFile

TFile

TFile

TFile

TFile

TFile

parse

scan

scan

writeReplace

writeObject

readObject

invariants

sync

sync

umount

umount

umount

umount

umount

umount

isLenient

setLenient

getDefaultArchiveDetector

setDefaultArchiveDetector

getNonArchivedParentFile

getParent

getParentFile

getAbsoluteFile

getAbsolutePath

getNormalizedAbsoluteFile

getNormalizedAbsolutePath

getNormalizedFile

getNormalizedPath

getCanonicalFile

getCanonicalPath

getCanOrAbsFile

getCanOrAbsPath

isArchive

isEntry

getInnerArchive

getInnerEntryName

getInnerEntryName0

getEnclArchive

getEnclEntryName

getEnclEntryName0

getArchiveDetector

getFile

getController

isParentOf

contains

contains

isFileSystemRoot

isUNC

isUNC

hashCode

de.schlichtherle.truezip.file
Class TFile