TFile (TrueVFS 0.12.0 API)

java.lang.Object
- java.io.File
- - net.java.truevfs.access.TFile

All Implemented Interfaces:: Serializable, Comparable<File>, TRex

@Immutable
public final class TFile
extends File
implements TRex

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 get used polymorphic with the class FileSystemView or any other class which depends 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 modeled after the Unix command line utility cp with its options.
The mv methods move files or directory trees. The method names have been modeled after the Unix command line utility mv.
The rm(_r)? methods remove files or directory trees. The method names have been modeled 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 modeled 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 constraint is meant to prevent ambiguous method semantics.

Raw Data Copying (RDC)

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 Raw Data Copying (RDC) to achieve best performance: With RDC, the raw entry data is copied from the input entry to the output entry without the need to temporarily reproduce, copy and process the file entry data again.

The benefits of this feature are archive driver specific: In case of ZIP files with compressed entries, RDC avoids inflating the entry data when reading the input entry and immediately deflating it again when writing the output entry. In case of TAR files, RDC avoids the need to create an additional temporary file, but shows no impact otherwise because the TAR file format doesn't support compression.

Traversing Directory Trees

When traversing directory trees, e.g. when searching, copying or moving them, it's important that all file objects use consistent TArchiveDetector objects for archive file detection in these directory trees. This is required in order to make sure that the virtual file system state which is managed by the TrueVFS Kernel does not get bypassed. Otherwise, file system operations on archive files would yield inconsistent results and may even cause loss of data!

By default, all file objects use TArchiveDetector.ALL in order to detect all supported archive types (see TConfig for other options). This is fine because it's fail-safe and performs reasonably well when copying archive files (e.g. ZIP entries won't get recompressed thanks to RDC).

Making Verbatim Copies of Directory Trees

Using the default TArchiveDetector.ALL results in structural copies rather than verbatim copies (byte-by-byte copies) of any archive files within the source directory tree. This saves you from accidentally bypassing the virtual file system state which is managed by the TrueVFS Kernel.

However, sometimes you may need verbatim copies, e.g. when comparing hash sums for archive files. In this case, you need to unmount any archive file in the source and destination directory trees first, e.g. by calling TVFS.umount() or TVFS.umount(TFile) before you can copy the directory trees. For the subsequent traversal of the directory trees, you need use TFile objects which do not recognize prospective archive files. For example, to make a recursive verbatim copy, you could use this:


 TFile src = ...; // any
 TFile dst = ...; // dito
 ... // any I/O operations
 TVFS.umount(src); // unmount selectively
 TVFS.umount(dst); // dito
 src.toNonArchiveFile().cp_rp(dst.toNonArchiveFile());

The calls to TVFS.umount(TFile) selectively unmount any archive files within the source and destination directory trees and the calls to toNonArchiveFile() ensure that prospective archive file detection is inhibited when recursively copying the source and destination directory trees.

Detecting Archive Files and False Positives

Whenever an archive file extension is detected 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 platform file system!

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

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.

Test Methods
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	File 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	File 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	File 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 extension, 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 file system, which is indicated by ?. For regular directories on Windows/NTFS for example, the return value would be 0.
This example presumes that the JAR of the module TrueVFS Driver ZIP is present on the run time class path.
This example presumes that the JAR of the module TrueVFS Driver ZIP.RAES (TZP) 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
- Fields inherited from class java.io.File
  pathSeparator, pathSeparatorChar, separator, separatorChar

Constructor Summary

Constructors
Constructor and Description
`TFile(File file)` Constructs a new `TFile` instance which wraps the given `file`.
`TFile(File parent, String child)` Constructs a new `TFile` instance which scans its path name for prospective archive files using the current archive detector by calling `TConfig.current().getArchiveDetector()`.
`TFile(File parent, String child, TArchiveDetector detector)` Constructs a new `TFile` instance which uses the given archive detector to scan its path name for prospective archive files.
`TFile(File file, TArchiveDetector detector)` Constructs a new `TFile` instance which uses the given archive detector to scan its path name for prospective archive files.
`TFile(FsNodePath path)` Constructs a new `TFile` instance for the given `path`.
`TFile(FsNodePath path, TArchiveDetector detector)` Constructs a new `TFile` instance for the given `path` and `detector`.
`TFile(String path)` Constructs a new `TFile` instance which scans its path name for prospective archive files using the current archive detector by calling `TConfig.current().getArchiveDetector()`.
`TFile(String parent, String child)` Constructs a new `TFile` instance which scans its path name for prospective archive files using the current archive detector by calling `TConfig.current().getArchiveDetector()`.
`TFile(String parent, String child, TArchiveDetector detector)` Constructs a new `TFile` instance which uses the given archive detector to scan its path name for prospective archive files.
`TFile(String path, TArchiveDetector detector)` Constructs a new `TFile` instance which uses the given archive detector to scan its path name for prospective archive files.
`TFile(URI uri)` Constructs a new `TFile` instance for the given `uri`.
`TFile(URI uri, TArchiveDetector detector)` Constructs a new `TFile` instance for the given `uri` and `detector`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`boolean`	`canExecute()`
`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.
`TFile`	`compact()` Compacts this archive file by removing any redundant archive entry contents and meta data, including central directories.
`int`	`compareTo(File that)`
`boolean`	`contains(File file)` Returns `true` if and only if the path represented by this instance contains the path represented by the given `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.
`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 attempts to copy all attributes of the source file to the destination file, too.
`TFile`	`cp_r(File dst)` Equivalent to `cp_r(this, dst, detector, detector)`, where `detector` is `TConfig.current().getArchiveDetector()`.
`static void`	`cp_r(File src, File dst, TArchiveDetector detector)` Equivalent to `cp_r(this, dst, detector, detector)`.
`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, detector, detector)`, where `detector` is `TConfig.current().getArchiveDetector()`.
`static void`	`cp_rp(File src, File dst, TArchiveDetector detector)` Equivalent to `cp_rp(this, dst, detector, detector)`.
`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 attempts to copy 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.
`void`	`deleteOnExit()`
`boolean`	`equals(Object that)`
`boolean`	`exists()`
`TFile`	`getAbsoluteFile()`
`String`	`getAbsolutePath()`
`TArchiveDetector`	`getArchiveDetector()` Returns the `TArchiveDetector` which was used to detect any archive files in the path name of this object at construction time.
`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.
`TFile`	`getEnclArchive()` Returns the parent file system object for this file object.
`String`	`getEnclEntryName()` Returns the node name relative to the parent file system.
`TFile`	`getInnerArchive()` Returns the innermost archive file object for this file object.
`String`	`getInnerEntryName()` Returns the entry name relative to the innermost archive file.
`FsMountPoint`	`getMountPoint()` Returns the file system mount point for this path.
`String`	`getName()`
`FsNodeName`	`getNodeName()` Returns the file system entry name.
`FsNodePath`	`getNodePath()` Returns a file system node path which is consistent with `toURI()`.
`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 redundant `"."` and `".."` directories from the path name.
`String`	`getNormalizedPath()` Removes any redundant `"."`, `".."` directories from the path name.
`String`	`getParent()`
`TFile`	`getParentFile()`
`String`	`getPath()`
`TFile`	`getTopLevelArchive()` Returns the top level archive file in the path or `null` if this file object does not name an archive file.
`URI`	`getUri()` In case no prospective archive file has been detected in the path name at construction time, this method behaves like the super class method `File.toURI()`.
`int`	`hashCode()`
`void`	`input(InputStream in)` Copies the input stream `in` to this file or entry in an archive file without closing the stream.
`boolean`	`isAbsolute()`
`boolean`	`isArchive()` Returns `true` if and only if this `TFile` addresses an archive file.
`boolean`	`isDirectory()` Similar to its super class implementation, but returns `true` for a valid archive file, too.
`boolean`	`isEntry()` Returns `true` if and only if this `TPath` addresses an entry located within an archive file.
`boolean`	`isFile()` Similar to its super class implementation, but returns `false` for a valid archive file, too.
`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()`
`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 given `file`.
`boolean`	`isTopLevelArchive()` Returns `true` if and only if this file is a top level archive file.
`boolean`	`isUNC()` Returns `true` if and only if this file denotes 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) length of the file.
`String[]`	`list()` Returns the names of the members in this (virtual) 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()`
`TFile[]`	`listFiles(FileFilter filter)`
`TFile[]`	`listFiles(FilenameFilter filter)`
`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, detector)`, where `detector` is `TConfig.current().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 the stream.
`TFile`	`rm_r()` Equivalent to `rm_r(this)`.
`static void`	`rm_r(File file)` Recursively deletes the given file or directory tree.
`TFile`	`rm()` Equivalent to `rm(this)`.
`static void`	`rm(File file)` Deletes the given file or directory.
`boolean`	`setLastModified(long time)` Sets the last modification of this file or (virtual) directory.
`boolean`	`setReadOnly()` Like the super class implementation, but is aware of archive files in its path.
`TFile`	`toFile()` Returns a file representation of this object.
`TFile`	`toNonArchiveFile()` Returns a file object for the same path name, but does not detect any archive file name patterns in the last path name segment.
`TPath`	`toPath()` Returns a path representation of this object.
`String`	`toString()`
`URI`	`toURI()`
`URL`	`toURL()` Deprecated.

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

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

Constructor Detail
- TFile
```
public TFile(File file)
```
  Constructs a new TFile instance which wraps the given file. If file is an instance of this class, then this method behaves like a copy constructor, otherwise the current archive detector gets resolved by calling TConfig.current().getArchiveDetector() in order to scan the entire path name for prospective archive files.
  
  Parameters:
  
  file - the file object to decorate. If this is an instance of this class, most of its fields current copied.
- TFile
```
public TFile(@CheckForNull
             File parent,
             String child)
```
  Constructs a new TFile instance which scans its path name for prospective archive files using the current archive detector by calling TConfig.current().getArchiveDetector().
  
  Parameters:
  
  parent - the parent directory. If this is an instance of this class, then only the child path name gets scanned for prospective archive files, otherwise the entire path name.
  
  child - the child path name.
- TFile
```
@ExpertFeature(value=INJECTING_A_DIFFERENT_DETECTOR_FOR_THE_SAME_PATH_MAY_CORRUPT_DATA)
public TFile(@CheckForNull
                                                                                                     File parent,
                                                                                                     String child,
                                                                                                     @CheckForNull
                                                                                                     TArchiveDetector detector)
```
  Constructs a new TFile instance which uses the given archive detector to scan its path name for prospective archive files.
  
  Parameters:
  
  parent - the parent directory. If this is an instance of this class, then only the child path name gets scanned for prospective archive files, otherwise the entire path name.
  
  child - the child path name.
  
  detector - the archive detector to use for scanning the path name for prospective archive files. If this parameter is null, then the default archive detector gets resolved by calling TConfig.current().getArchiveDetector().
- TFile
```
@ExpertFeature(value=INJECTING_A_DIFFERENT_DETECTOR_FOR_THE_SAME_PATH_MAY_CORRUPT_DATA)
public TFile(File file,
                                                                                                     @CheckForNull
                                                                                                     TArchiveDetector detector)
```
  Constructs a new TFile instance which uses the given archive detector to scan its path name for prospective archive files.
  
  Parameters:
  
  file - the file object to decorate. If this is an instance of this class, most of its fields get copied.
  
  detector - the archive detector to use for scanning the path name for prospective archive files. If this parameter is null and file is an instance of this class, then its archive detector gets used. If this parameter is null and file is not an instance of this class, then the current archive detector gets resolved by calling TConfig.current().getArchiveDetector().
- TFile
```
public TFile(FsNodePath path)
```
  Constructs a new TFile instance for the given path. This constructor is equivalent to new TFile(path, null)
  
  Parameters:
  
  path - a node path with an absolute hierarchical URI which has a scheme component which is known by the current archive detector TConfig.current().getArchiveDetector().
  
  Throws:
  
  IllegalArgumentException - if the hierarchical URI of the given node path does not conform to the syntax constraints for File.File(URI).
  
  See Also:
  
  getNodePath()
- TFile
```
@ExpertFeature(value=INJECTING_A_DIFFERENT_DETECTOR_FOR_THE_SAME_PATH_MAY_CORRUPT_DATA)
public TFile(FsNodePath path,
                                                                                                     @CheckForNull
                                                                                                     TArchiveDetector detector)
```
  Constructs a new TFile instance for the given path and detector. This constructor is a super set of the super class constructor File.File(URI) with the following additional features: If the URI of the given node path is opaque, it must match the pattern <scheme>:<uri>!/<entry>. The constructed file object then parses the URI to address an entry in a federated file system (i.e. prospective archive file) with the name <entry> in the prospective archive file addressed by <uri> which is of the type identified by <scheme> . This is recursively applied to access entries within other prospective archive files until <uri> is a hierarchical URI. Note that the scheme component of this hierarchical URI must be file in order to maintain interoperability with the super class!
  
  Parameters:
  
  path - a path with an absolute hierarchical URI which has a scheme component which is known by the given detector.
  
  detector - the archive detector to look up archive file system drivers for the named URI scheme components. If this parameter is null, then the default archive detector gets resolved by calling TConfig.current().getArchiveDetector().
  
  Throws:
  
  IllegalArgumentException - if the hierarchical URI of the given node path does not conform to the syntax constraints for File.File(URI).
  
  See Also:
  
  getNodePath()
- TFile
```
public TFile(String path)
```
  Constructs a new TFile instance which scans its path name for prospective archive files using the current archive detector by calling TConfig.current().getArchiveDetector().
  
  Parameters:
  
  path - the path name.
- TFile
```
public TFile(@CheckForNull
             String parent,
             String child)
```
  Constructs a new TFile instance which scans its path name for prospective archive files using the current archive detector by calling TConfig.current().getArchiveDetector().
  
  Parameters:
  
  parent - the parent directory. If this is an instance of this class, then only the child path name gets scanned for prospective archive files, otherwise the entire path name.
  
  child - the child path name.
- TFile
```
@ExpertFeature(value=INJECTING_A_DIFFERENT_DETECTOR_FOR_THE_SAME_PATH_MAY_CORRUPT_DATA)
public TFile(@CheckForNull
                                                                                                     String parent,
                                                                                                     String child,
                                                                                                     @CheckForNull
                                                                                                     TArchiveDetector detector)
```
  Constructs a new TFile instance which uses the given archive detector to scan its path name for prospective archive files.
  
  Parameters:
  
  parent - the parent directory.
  
  child - the child path name.
  
  detector - the archive detector to use for scanning the path name for prospective archive files. If this parameter is null, then the default archive detector gets resolved by calling TConfig.current().getArchiveDetector().
- TFile
```
@ExpertFeature(value=INJECTING_A_DIFFERENT_DETECTOR_FOR_THE_SAME_PATH_MAY_CORRUPT_DATA)
public TFile(String path,
                                                                                                     @CheckForNull
                                                                                                     TArchiveDetector detector)
```
  Constructs a new TFile instance which uses the given archive detector to scan its path name for prospective archive files.
  
  Parameters:
  
  path - the path name.
  
  detector - the archive detector to use for scanning the path name for prospective archive files. If this parameter is null, then the default archive detector gets resolved by calling TConfig.current().getArchiveDetector().
- TFile
```
public TFile(URI uri)
```
  Constructs a new TFile instance for the given uri. This constructor is equivalent to new TFile(FsNodePath.create(uri, CANONICALIZE), null)),
  
  Parameters:
  
  uri - an absolute URI which has a scheme component which is known by the current archive detector TConfig.current().getArchiveDetector().
  
  Throws:
  
  IllegalArgumentException - if the given URI does not conform to the syntax constraints for FsNodePaths or File.File(URI).
  
  See Also:
  
  getUri()
- TFile
```
@ExpertFeature(value=INJECTING_A_DIFFERENT_DETECTOR_FOR_THE_SAME_PATH_MAY_CORRUPT_DATA)
public TFile(URI uri,
                                                                                                     @CheckForNull
                                                                                                     TArchiveDetector detector)
```
  Constructs a new TFile instance for the given uri and detector. This constructor is a super set of the super class constructor File.File(URI) with the following additional features: If the given URI is opaque, it must match the pattern <scheme>:<uri>!/<entry>. The constructed file object then parses the URI to address an entry in a federated file system (i.e. prospective archive file) with the name <entry> in the prospective archive file addressed by <uri> which is of the type identified by <scheme> . This is recursively applied to access entries within other prospective archive files until <uri> is a hierarchical URI. Note that the scheme component of this hierarchical URI must be file in order to maintain interoperability with the super class!
  
  Parameters:
  
  uri - an absolute URI which has a scheme component which is known by the given detector.
  
  detector - the archive detector to look up archive file system drivers for the named URI scheme components. If this parameter is null, then the default archive detector gets resolved by calling TConfig.current().getArchiveDetector().
  
  Throws:
  
  IllegalArgumentException - if the given URI does not conform to the syntax constraints for File.File(URI).
  
  See Also:
  
  getNodePath()

Method Detail

canExecute

@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES,
             durable=NOT_APPLICABLE)
public boolean canExecute()

Overrides:: canExecute in class File

canRead

@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES,
             durable=NOT_APPLICABLE)
public boolean canRead()

Overrides:: canRead in class File

canWrite

@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES,
             durable=NOT_APPLICABLE)
public boolean canWrite()

Overrides:: canWrite in class File

cat

@FsAssertion(atomic=NO,
             consistent=YES,
             isolated=NO)
public static void cat(@WillNotClose
                                                                                                      InputStream in,
                                                                                                      @WillNotClose
                                                                                                      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. It performs best when used with unbuffered streams.

Feature Matrix
Feature	Supported
Preserves file attributes	n/a
Copies directories recursively	n/a
Reads and overwrites special files	n/a
Closes parameter stream(s)	Never
Raw Data Copying (RDC)	n/a
Deletes partial written files on failure	n/a
Deletes partial written directories on failure	n/a

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

compact
```
@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=NO,
             durable=YES)
public TFile compact()
                                                                                                                        throws IOException
```
Compacts this archive file by removing any redundant archive entry contents and meta data, including central directories. If this file isn't a top level archive file, then this operation does nothing and returns immediately.
This operation is intended to compact archive files which have been frequently updated with FsAccessOption.GROW or similar means. If this access option is set and an archive file is updated frequently, then over time a lot of redundant artifacts such as archive entry contents and meta data, including central directories may be physically present in the archive file, even if all its entries have been deleted. This operation should then get used to remove any redundant artifacts and reclaim the storage space.
Mind that this operation has no means to detect if there is actually any redundant data present in this archive file. Any invocation will perform exactly the same steps, so if this archive file is already compact, then this will just waste time and temporary space in the platform file system.
Note that this operation is not thread-safe and hence not isolated, so you should not concurrently access this archive file or any of its entries!
This operation performs in the order of O(s), where s is the total size of the archive file either before (worst case) or after (best case) compacting it. If this archive file has already been mounted, then s is the total size of the archive file after compacting it (best case). Otherwise, the definition of s is specific to the archive file system driver. Usually, if the archive file contains a central directory, you could expect the best case, otherwise the worst case, but this information is given without warranty.
If this archive file has been successfully compacted, then it's left unmounted, so any subsequent operation will mount it again, which requires additional time.

Returns:

this

Throws:

IOException - On any I/O error.

See Also:

FsAccessOption.GROW

compareTo
```
public int compareTo(File that)
```
The implementation in the class TFile delegates the call to its decorated file object. This implies that only the hierarchicalized file system path of this file instance is considered in the comparison. E.g. new TFile(FsNodePath.create("zip:file:/archive!/entry")) and new TFile(FsNodePath.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. Now if the expression a.getNodePath().toHierarchicalUri().compareTo(b.getNodePath().toHierarchicalUri()) == 0 is true, then 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").getNodePath().toHierarchicalUri().compareTo(new TFile("FILE").getNodePath().toHierarchicalUri()) == 0 is false because FsNodePath.equals(Object) is case sensitive.

Specified by:

compareTo in interface Comparable<File>

Overrides:

compareTo in class File

Parameters:

that - the file object to get compared with this object

See Also:

equals(Object)

contains
```
public boolean contains(File file)
```
Returns true if and only if the path represented by this instance contains the path represented by the given 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 file object for the path to test for being contained by the path of this instance.

Returns:

true if and only if the path represented by this instance contains the path represented by the given file

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.

Returns:

true if and only if the path represented by a contains the path represented by b.

Throws:

NullPointerException - If any parameter is null.

cp_p
```
@FsAssertion(atomic=NO,
             consistent=YES,
             isolated=NO)
public TFile cp_p(File dst)
                                                                                          throws IOException
```
Equivalent to cp_p(this, dst).

Parameters:

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.

Returns:

this

Throws:

IOException - if any I/O error occurs.

cp_p

@FsAssertion(atomic=NO,
             consistent=YES,
             isolated=NO)
public static void cp_p(File src,
                                                                                                       File dst)
                                                                                                throws IOException

Copies the file src to the file dst and attempts to copy all attributes of the source file to the destination file, too. Which attributes are actually copied is specific to the source and destination file system driver implementations, but the minimum guarantee is to copy the last modification time.

Feature Matrix
Feature	Supported
Preserves file attributes	Best effort
Copies directories recursively	No
Reads and overwrites special files	Yes
Closes parameter stream(s)	n/a
Raw Data Copying (RDC)	Yes
Deletes partial written files on failure	Yes
Deletes partial written directories on failure	n/a

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:: Bulk I/O Methods

cp_r
```
@FsAssertion(atomic=NO,
             consistent=YES,
             isolated=NO)
public TFile cp_r(File dst)
                                                                                          throws IOException
```
Equivalent to cp_r(this, dst, detector, detector), where detector is TConfig.current().getArchiveDetector().

Parameters:

dst - the destination file or directory tree. Note that although this just needs to be a plain File, archive files and entries are only supported for instances of this class.

Returns:

this

Throws:

IOException - if any I/O error occurs.

See Also:

Bulk I/O Methods, Traversing Directory Trees

cp_r

@ExpertFeature(level=INTERMEDIATE,
               value=INJECTING_A_DIFFERENT_DETECTOR_FOR_THE_SAME_PATH_MAY_CORRUPT_DATA)
 @FsAssertion(atomic=NO,
             consistent=YES,
             isolated=NO)
public static void cp_r(File src,
                                                                                                                                                                                                                                   File dst,
                                                                                                                                                                                                                                   TArchiveDetector detector)
                                                                                                                                                                                                                            throws IOException

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

Parameters:: src - the source file or directory tree. 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 or directory tree. Note that although this just needs to be a plain File, archive files and entries are only supported for instances of this class.; detector - the archive detector to use for detecting any archive files within the source and destination directory trees.
Throws:: IOException - if any I/O error occurs.
Since:: TrueZIP 7.2
See Also:: Bulk I/O Methods, Traversing Directory Trees

cp_r

@ExpertFeature(level=INTERMEDIATE,
               value=INJECTING_A_DIFFERENT_DETECTOR_FOR_THE_SAME_PATH_MAY_CORRUPT_DATA)
 @FsAssertion(atomic=NO,
             consistent=YES,
             isolated=NO)
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.

Feature Matrix
Feature	Supported
Preserves file attributes	None
Copies directories recursively	Yes
Reads and overwrites special files	No
Closes parameter stream(s)	n/a
Raw Data Copying (RDC)	Yes
Deletes partial written files on failure	Yes
Deletes partial written directories on failure	No

Parameters:: src - the source file or directory tree. 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 or directory tree. 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 within the source directory tree.; dstDetector - the archive detector to use for detecting any archive files within the destination directory tree.
Throws:: IOException - if any I/O error occurs.
See Also:: Bulk I/O Methods, Traversing Directory Trees

cp_rp
```
@FsAssertion(atomic=NO,
             consistent=YES,
             isolated=NO)
public TFile cp_rp(File dst)
                                                                                           throws IOException
```
Equivalent to cp_rp(this, dst, detector, detector), where detector is TConfig.current().getArchiveDetector().

Parameters:

dst - the destination file or directory tree. Note that although this just needs to be a plain File, archive files and entries are only supported for instances of this class.

Returns:

this

Throws:

IOException - if any I/O error occurs.

See Also:

Bulk I/O Methods, Traversing Directory Trees

cp_rp

@ExpertFeature(level=INTERMEDIATE,
               value=INJECTING_A_DIFFERENT_DETECTOR_FOR_THE_SAME_PATH_MAY_CORRUPT_DATA)
 @FsAssertion(atomic=NO,
             consistent=YES,
             isolated=NO)
public static void cp_rp(File src,
                                                                                                                                                                                                                                    File dst,
                                                                                                                                                                                                                                    TArchiveDetector detector)
                                                                                                                                                                                                                             throws IOException

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

Parameters:: src - the source file or directory tree. 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 or directory tree. Note that although this just needs to be a plain File, archive files and entries are only supported for instances of this class.; detector - the archive detector to use for detecting any archive files within the source and destination directory trees.
Throws:: IOException - if any I/O error occurs.
Since:: TrueZIP 7.2
See Also:: Bulk I/O Methods, Traversing Directory Trees

cp_rp

@ExpertFeature(level=INTERMEDIATE,
               value=INJECTING_A_DIFFERENT_DETECTOR_FOR_THE_SAME_PATH_MAY_CORRUPT_DATA)
 @FsAssertion(atomic=NO,
             consistent=YES,
             isolated=NO)
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 attempts to copy all attributes of each source file to the destination file, too. Which attributes are actually copied is specific to the source and destination file system driver implementations, but the minimum guarantee is to copy the last modification time - except for archive files.

Feature Matrix
Feature	Supported
Preserves file attributes	Best effort
Copies directories recursively	Yes
Reads and overwrites special files	No
Closes parameter stream(s)	n/a
Raw Data Copying (RDC)	Yes
Deletes partial written files on failure	Yes
Deletes partial written directories on failure	No

Parameters:: src - the source file or directory tree. 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 or directory tree. 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 within the source directory tree.; dstDetector - the archive detector to use for detecting any archive files within the destination directory tree.
Throws:: IOException - if any I/O error occurs.
See Also:: Bulk I/O Methods, Traversing Directory Trees

cp
```
@FsAssertion(atomic=NO,
             consistent=YES,
             isolated=NO)
public TFile cp(File dst)
                                                                                        throws IOException
```
Equivalent to cp(this, dst).

Parameters:

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.

Returns:

this

Throws:

IOException - if any I/O error occurs.

cp

@FsAssertion(atomic=NO,
             consistent=YES,
             isolated=NO)
public static void cp(File src,
                                                                                                     File dst)
                                                                                              throws IOException

Copies the file src to the file dst.

Feature Matrix
Feature	Supported
Preserves file attributes	None
Copies directories recursively	No
Reads and overwrites special files	Yes
Closes parameter stream(s)	n/a
Raw Data Copying (RDC)	Yes
Deletes partial written files on failure	Yes
Deletes partial written directories on failure	n/a

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:: Bulk I/O Methods

cp

@FsAssertion(atomic=NO,
             consistent=YES,
             isolated=NO)
public static void cp(File src,
                                                                                                     @WillClose
                                                                                                     OutputStream out)
                                                                                              throws IOException

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

Feature Matrix
Feature	Supported
Preserves file attributes	None
Copies directories recursively	No
Reads and overwrites special files	Yes
Closes parameter stream(s)	Always
Raw Data Copying (RDC)	No
Deletes partial written files on failure	n/a
Deletes partial written directories on failure	n/a

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.; out - the output stream.
Throws:: IOException - if any I/O error occurs.
See Also:: Bulk I/O Methods

cp

@FsAssertion(atomic=NO,
             consistent=YES,
             isolated=NO)
public static void cp(@WillClose
                                                                                                     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 Matrix
Feature	Supported
Preserves file attributes	None
Copies directories recursively	No
Reads and overwrites special files	Yes
Closes parameter stream(s)	Always
Raw Data Copying (RDC)	No
Deletes partial written files on failure	Yes
Deletes partial written directories on failure	n/a

Parameters:: in - the input stream.; 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:: Bulk I/O Methods

cp

@FsAssertion(atomic=NO,
             consistent=YES,
             isolated=NO)
public static void cp(@WillClose
                                                                                                     InputStream in,
                                                                                                     @WillClose
                                                                                                     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 Matrix
Feature	Supported
Preserves file attributes	n/a
Copies directories recursively	n/a
Reads and overwrites special files	n/a
Closes parameter stream(s)	Always
Raw Data Copying (RDC)	n/a
Deletes partial written files on failure	n/a
Deletes partial written directories on failure	n/a

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

createNewFile
```
@FsAssertion(consistent=YES,
             isolated=NO)
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!

Overrides:

createNewFile in class File

Throws:

IOException

See Also:

mkdir()

deleteOnExit

@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES,
             durable=YES)
public void deleteOnExit()

Overrides:: deleteOnExit in class File

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(FsNodePath.create("zip:file:/archive!/entry")) and new TFile(FsNodePath.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.getNodePath().toHierarchicalUri().equals(b.getNodePath().toHierarchicalUri()) 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").getNodePath().toHierarchicalUri().equals(new TFile("FILE").getNodePath().toHierarchicalUri()) is false because FsNodePath.equals(Object) is case sensitive.

Overrides:

equals in class File

Parameters:

that - the object to get compared with this object

See Also:

hashCode(), compareTo(File)

exists

@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES,
             durable=NOT_APPLICABLE)
public boolean exists()

Overrides:: exists in class File
See Also:: Detecting Archive Paths and False Positives

getAbsoluteFile
```
public TFile getAbsoluteFile()
```
Overrides:

getAbsoluteFile in class File

getAbsolutePath
```
public String getAbsolutePath()
```
Overrides:

getAbsolutePath in class File

getArchiveDetector
```
public TArchiveDetector getArchiveDetector()
```
Description copied from interface: TRex

Returns the TArchiveDetector which was used to detect any archive files in the path name of this object at construction time.

Specified by:

getArchiveDetector in interface TRex

Returns:

The TArchiveDetector which was used to detect any archive files in the path name of this object at construction time.

getCanonicalFile

@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES,
             durable=NOT_APPLICABLE)
public TFile getCanonicalFile()
                                                                                                                                             throws IOException

Overrides:: getCanonicalFile in class File
Throws:: IOException

getCanonicalPath

@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES,
             durable=NOT_APPLICABLE)
public String getCanonicalPath()
                                                                                                                                              throws IOException

Overrides:: getCanonicalPath in class File
Throws:: IOException

getCanOrAbsFile
```
public 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.

getEnclArchive
```
@CheckForNull
public TFile getEnclArchive()
```
Returns the parent file system object for this file object. That is, if this object addresses an entry located within an archive file, then this method returns the file object 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 may recursively address an entry within another archive file.

Returns:

The enclosing archive file in this path.

getEnclEntryName
```
@Nullable
public String getEnclEntryName()
```
Returns the node name relative to the parent file system. That is, if this object addresses an entry 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 redundant occurences of "." and ".." in the path are removed wherever possible.

Returns:

The entry name relative to the enclosing archive file.

getInnerArchive
```
@CheckForNull
public TFile getInnerArchive()
```
Returns the innermost archive file object for this file object. That is, if this object addresses an archive file, then this method returns this. If this object addresses an entry located within an archive file, then this methods returns the file object 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 may recursively address an entry within another archive file.

Returns:

The innermost archive path object for this path object.

getInnerEntryName
```
@Nullable
public String getInnerEntryName()
```
Returns the entry name relative to the innermost archive file. That is, if this object addresses an archive file, then this method returns the empty string "". If this object addresses an entry 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 redundant occurences of "." and ".." in the path are removed wherever possible.

Returns:

The entry name relative to the innermost archive file.

getMountPoint
```
public FsMountPoint getMountPoint()
```
Description copied from interface: TRex

Returns the file system mount point for this path. Note that multiple calls to this method result in objects which are required to compare equal, but are not necessarily identical.

Specified by:

getMountPoint in interface TRex

Returns:

the file system mount point for this path.

getName
```
public String getName()
```
Overrides:

getName in class File

getNodeName
```
public FsNodeName getNodeName()
```
Description copied from interface: TRex

Returns the file system entry name. Note that multiple calls to this method result in objects which are required to compare equal, but are not necessarily identical.

Specified by:

getNodeName in interface TRex

Returns:

the file system entry name.

getNodePath
```
public FsNodePath getNodePath()
```
Returns a file system node path which is consistent with toURI().

Specified by:

getNodePath in interface TRex

Returns:

A file system node path which is consistent with toURI().

See Also:

TFile(FsNodePath), toURI()

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.

Returns:

The first parent directory (starting from this file) which is not an archive file or a file located in an archive 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.

Returns:

The normalized absolute file object denoting the same file or directory as this instance.

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.

Returns:

The normalized absolute path string denoting the same file or directory as this instance.

See Also:

getCanonicalPath(), getNormalizedPath()

getNormalizedFile
```
public TFile getNormalizedFile()
```
Removes any redundant "." and ".." directories from the path name.

Returns:

The normalized file object denoting the same file or directory as this instance.

getNormalizedPath
```
public String getNormalizedPath()
```
Removes any redundant ".", ".." directories from the path name.

Returns:

The normalized path string denoting the same file or directory as this instance.

getParent
```
@Nullable
public String getParent()
```
Overrides:

getParent in class File

getParentFile
```
@Nullable
public TFile getParentFile()
```
Overrides:

getParentFile in class File

getPath
```
public String getPath()
```
Overrides:

getPath in class File

getTopLevelArchive
```
@Nullable
public TFile getTopLevelArchive()
```
Returns the top level archive file in the path or null if this file object does not name an archive file. A top level archive is not enclosed in another archive. If this method returns non-null, the value denotes the longest part of the path which may (but does not need to) exist as a plain file in the platform file system.

Returns:

The top level archive file in the path or null if this file object does not name an archive file.

getUri
```
public URI getUri()
```
In case no prospective archive file has been detected in the path name at construction time, this method behaves like the super class method File.toURI().
Otherwise, an opaque URI of the form <scheme>:<uri>!/<entry> is returned, where <scheme> is the URI scheme component identifying a file system driver, <uri> is the URI returned by this method for the innermost archive file and <entry> is the relative path name of the the entry addressed by this file object in the innermost archive file. If this file object addresses an archive file, then <uri> is the URI which would have been returned by this method if the file name of the archive file had not been detected as a prospective archive file and entry is an empty string.
Example URIs
- file:/foo addresses a regular file
- war:file:/foo.war!/ addresses the root entry of the WAR file addressed by file:/foo.war.
- war:file:/foo.war!/META-INF/MANIFEST.MF addresses the entry META-INF/MANIFEST.MF in the WAR file addressed by file:/foo.war.
- jar:war:file:/foo.war!/WEB-INF/lib/bar.jar!/META-INF/MANIFEST.MF addresses the entry META-INF/MANIFEST.MF in the JAR file addressed by war:file:/foo.war!/WEB-INF/lib/bar.jar, which recursively addresses the entry WEB-INF/lib/bar.jar in the WAR file addressed by file:/foo.war.
Specified by:

getUri in interface TRex

Returns:

A URI for this file object.

See Also:

getNodePath()

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)

input

@FsAssertion(atomic=NO,
             consistent=YES,
             isolated=NO)
public void input(@WillNotClose
                                                                                                 InputStream in)
                                                                                          throws IOException

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

Feature Matrix
Feature	Supported
Preserves file attributes	n/a
Copies directories recursively	n/a
Reads and overwrites special files	Yes
Closes parameter stream(s)	Never
Raw Data Copying (RDC)	n/a
Deletes partial written files on failure	Yes
Deletes partial written directories on failure	n/a

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

isAbsolute
```
public boolean isAbsolute()
```
Overrides:

isAbsolute in class File

isArchive
```
public boolean isArchive()
```
Returns true if and only if this TFile addresses an archive file. Whether or not this is true solely depends on the TArchiveDetector which was used to construct this TFile - no file system tests are performed by this method!

Returns:

true if and only if this TFile addresses an archive file.

See Also:

isEntry(), isDirectory(), Detecting Archive Paths and False Positives

isDirectory
```
@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES,
             durable=NOT_APPLICABLE)
public boolean isDirectory()
```
Similar to its super class implementation, but returns true for a valid archive file, too.
For archive file validation its virtual file system gets mounted. In case a RAES encrypted ZIP file gets mounted, the user gets prompted for its password unless the default configuration for key management hasn't been overridden.

Overrides:

isDirectory in class File

See Also:

Detecting Archive Paths and False Positives, isArchive(), isEntry()

isEntry
```
public boolean isEntry()
```
Returns true if and only if this TPath addresses an entry located within an archive file. Whether or not this is true solely depends on the TArchiveDetector which was used to construct this TPath - no file system tests are performed by this method!

Returns:

true if and only if this TPath addresses an entry located within an archive file.

See Also:

isArchive(), isDirectory(), Detecting Archive Paths and False Positives

isFile
```
@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES,
             durable=NOT_APPLICABLE)
public boolean isFile()
```
Similar to its super class implementation, but returns false for a valid archive file, too.
For archive file validation its virtual file system gets mounted. In case a RAES encrypted ZIP file gets mounted, the user gets prompted for its password unless the default configuration for key management hasn't been overridden.

Overrides:

isFile in class File

See Also:

Detecting Archive Paths and False Positives

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

Returns:

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

isHidden
```
public boolean isHidden()
```
Overrides:

isHidden in class File

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 given 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 file object for the path to test for being a direct or indirect child of the path of this instance.

Returns:

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

isTopLevelArchive
```
public boolean isTopLevelArchive()
```
Returns true if and only if this file is a top level archive file.

Returns:

true if and only if this file is a top level archive file.

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.

Returns:

true if and only if this file denotes a UNC.

lastModified
```
@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES,
             durable=NOT_APPLICABLE)
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.

Overrides:

lastModified in class File

See Also:

Package description for more information about ghost directories

length
```
@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES,
             durable=NOT_APPLICABLE)
public long length()
```
Returns the (uncompressed) length of the file. The length returned of a valid archive file is 0 in order to properly emulate virtual directories across all platforms.
For archive file validation its virtual file system gets mounted. In case a RAES encrypted ZIP file gets mounted, the user gets prompted for its password unless the default configuration for key management hasn't been overridden.

Overrides:

length in class File

See Also:

Detecting Archive Paths and False Positives

list
```
@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES,
             durable=NOT_APPLICABLE)
 @Nullable
public String[] list()
```
Returns the names of the members in this (virtual) 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.

Overrides:

list in class File

Returns:

A possibly empty array with the members of this (virtual) directory or null if this instance does not refer to a (virtual) directory or if the virtual directory is inaccessible due to an I/O error.

list

@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES,
             durable=NOT_APPLICABLE)
 @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.

Overrides:: list in class File
Returns:: A possibly empty array with the members of this (virtual) directory or null if this instance does not refer to a (virtual) directory or if the virtual directory is inaccessible due to an I/O error.

listFiles

@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES,
             durable=NOT_APPLICABLE)
 @Nullable
public TFile[] listFiles()

Overrides:: listFiles in class File

listFiles

@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES,
             durable=NOT_APPLICABLE)
 @Nullable
public TFile[] listFiles(@CheckForNull
                                                                                                                                                          FileFilter filter)

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

Overrides:: listFiles in class File

listFiles

@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES,
             durable=NOT_APPLICABLE)
 @Nullable
public TFile[] listFiles(@CheckForNull
                                                                                                                                                          FilenameFilter filter)

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

Overrides:: listFiles in class File

mkdir
```
@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES)
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 TConfig.current().isLenient() is true.

Overrides:

mkdir in class File

mkdir
```
@FsAssertion(consistent=YES,
             isolated=NO)
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.

mkdirs

@FsAssertion(consistent=YES,
             isolated=NO)
public boolean mkdirs()

Overrides:: mkdirs in class File

mv
```
@FsAssertion(consistent=YES)
public TFile mv(File dst)
                                      throws IOException
```
Equivalent to mv(this, dst, detector), where detector is TConfig.current().getArchiveDetector().

Parameters:

dst - the destination file or directory tree. Note that although this just needs to be a plain File, archive files and entries are only supported for instances of this class.

Returns:

this

Throws:

IOException - if any I/O error occurs.

See Also:

Bulk I/O Methods, Traversing Directory Trees

mv

@ExpertFeature(level=INTERMEDIATE,
               value=INJECTING_A_DIFFERENT_DETECTOR_FOR_THE_SAME_PATH_MAY_CORRUPT_DATA)
 @FsAssertion(consistent=YES)
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. In these cases, an attempt is made to copy all attributes of each source file to the destination file, too. Which attributes are actually copied is specific to the destination file system driver implementation, but the minimum guarantee is to copy the last modification time.

Parameters:: src - the source file or directory tree. 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 or directory tree. Note that although this just needs to be a plain File, archive files and entries are only supported for instances of this class.; detector - the archive detector to use for detecting any archive files within the source and destination directory trees.
Throws:: IOException - if any I/O error occurs.
See Also:: Bulk I/O Methods, Traversing Directory Trees

output

@FsAssertion(atomic=NO,
             consistent=YES,
             isolated=NO,
             durable=NOT_APPLICABLE)
public void output(@WillNotClose
                                                                                                                                       OutputStream out)
                                                                                                                                throws IOException

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

Feature Matrix
Feature	Supported
Preserves file attributes	n/a
Copies directories recursively	n/a
Reads and overwrites special files	Yes
Closes parameter stream(s)	Never
Raw Data Copying (RDC)	n/a
Deletes partial written files on failure	n/a
Deletes partial written directories on failure	n/a

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

rm_r
```
@FsAssertion(consistent=YES)
public TFile rm_r()
                                        throws IOException
```
Equivalent to rm_r(this).

Returns:

this

Throws:

IOException - if any I/O error occurs.

See Also:

Bulk I/O Methods, Traversing Directory Trees

rm_r
```
@FsAssertion(consistent=YES)
public static void rm_r(File file)
                                              throws IOException
```
Recursively deletes the given file or directory tree.
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.
This file system operation is not atomic.

Parameters:

file - the file or directory tree. 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:

Bulk I/O Methods, Traversing Directory Trees

rm

@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES)
public TFile rm()
                                                                                          throws IOException

Equivalent to rm(this).

Returns:: this
Throws:: IOException - if any I/O error occurs.
See Also:: Bulk I/O Methods

rm
```
@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES)
public static void rm(File file)
                                                                                                throws IOException
```
Deletes the given file or directory. If the file is a directory, it must be empty.

Parameters:

file - the file or directory. Note that although this just needs to be a plain File object, archive files and entries are only supported for instances of TFile.

Throws:

IOException - if any I/O error occurs.

See Also:

Bulk I/O Methods

setLastModified
```
@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES)
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.

Overrides:

setLastModified in class File

See Also:

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

setReadOnly
```
@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES)
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.

Overrides:

setReadOnly in class File

toFile
```
public TFile toFile()
```
Description copied from interface: TRex

Returns a file representation of this object.

Specified by:

toFile in interface TRex

Returns:

A file representation of this object.

toNonArchiveFile
```
@ExpertFeature(level=INTERMEDIATE,
               value=INJECTING_A_DIFFERENT_DETECTOR_FOR_THE_SAME_PATH_MAY_CORRUPT_DATA)
public TFile toNonArchiveFile()
```
Returns a file object for the same path name, but does not detect any archive file name patterns in the last path name segment. The parent file object is unaffected by this transformation, so the path name of this file object may address an entry in an archive file.

Returns:

A file object for the same path name, but does not detect any archive file name patterns in the last path name segment.

See Also:

TVFS.umount(TFile)

toPath
```
public TPath toPath()
```
Description copied from interface: TRex

Returns a path representation of this object.

Specified by:

toPath in interface TRex

Overrides:

toPath in class File

Returns:

A path representation of this object.

toString
```
public String toString()
```
Overrides:

toString in class File

toURI
```
public URI toURI()
```
Overrides:

toURI in class File

toURL

@Deprecated
public URL toURL()
                      throws MalformedURLException

Deprecated.

Overrides:: toURL in class File
Throws:: MalformedURLException

Class TFile

Bulk I/O Methods

Raw Data Copying (RDC)

Traversing Directory Trees

Making Verbatim Copies of Directory Trees

Detecting Archive Files and False Positives

Field Summary

Fields inherited from class java.io.File

Constructor Summary

Method Summary

Methods inherited from class java.io.File

Methods inherited from class java.lang.Object

Constructor Detail

TFile

TFile

TFile

TFile

TFile

TFile

TFile

TFile

TFile

TFile

TFile

TFile

Method Detail

canExecute

canRead

canWrite

cat

compact

compareTo

contains

contains

cp_p

cp_p

cp_r

cp_r

cp_r

cp_rp

cp_rp

cp_rp

cp

cp

cp

cp

cp

createNewFile

deleteOnExit

equals

exists

getAbsoluteFile

getAbsolutePath

getArchiveDetector

getCanonicalFile

getCanonicalPath

getCanOrAbsFile

getCanOrAbsPath

getEnclArchive

getEnclEntryName

getInnerArchive

getInnerEntryName

getMountPoint

getName

getNodeName

getNodePath

getNonArchivedParentFile

getNormalizedAbsoluteFile

getNormalizedAbsolutePath

getNormalizedFile

getNormalizedPath

getParent

getParentFile

getPath

getTopLevelArchive

getUri

Example URIs

hashCode

input

isAbsolute