@Nonnull @ParametersAreNonnullByDefault

Package net.java.truevfs.access

Provides uniform, transparent, thread-safe, read/write access to archive files as if they were virtual directories.

See: Description

Interface Summary

Interface	Description
TFileSystemProvider.Parameter	Keys for environment maps.
TRex	Defines common properties and operations of TFile and TPath.

Class Summary

Class	Description
TApplication<E extends Exception>	A template class which aids in establishing the typical setup-work-sync life cycle of a TrueVFS application.
TArchiveDetector	Detects a prospective archive file and declares its file system scheme by mapping its file name extension to an archive driver.
TConfig	A mutable container for configuration options with global or inheritable thread local scope.
TFile	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.
TFileComparator	Compares two files by their status and path name so that directories are always ordered before other files.
TFileInputStream	A replacement for the class FileInputStream for reading plain old files or entries in an archive file.
TFileOutputStream	A replacement for the class FileOutputStream for writing plain old files or entries in an archive file.
TFileReader	A replacement for the class FileReader for reading plain old files or entries in an archive file.
TFileSystem	A FileSystem implementation for use with NIO.2.
TFileSystemProvider	A FileSystemProvider implementation for use with NIO.2.
TFileWriter	A replacement for the class FileWriter for writing plain old files or entries in an archive file.
TPath	A Path implementation for use with NIO.2.
TVFS	Static utility methods for virtual file system operations with global scope.

Enum Summary

Enum	Description
ExpertFeature.Level	The experience level required to safely use an expert feature.
ExpertFeature.Reason	The reason why a feature should only be used by an expert.

Annotation Types Summary

Annotation Type	Description
ExpertFeature	Indicates a feature which requires a certain experience level for safe use.

Package net.java.truevfs.access Description

Provides uniform, transparent, thread-safe, read/write access to archive files as if they were virtual directories.

The TFile* Classes

This is the primary API for JSE 6 compliant TrueVFS applications: Like the API of the module TrueVFS Access Path, this API is just a facade for the module TrueVFS Kernel. In contrast to the TrueVFS Access Path API however, this API is limited to access the platform file system and any archive files within the platform file system. In contrast to the TrueVFS Kernel API, both APIs are designed to be easy to learn and convenient to use while providing a great level of flexibility. Because all virtual file system state is managed by the TrueVFS Kernel module, this module can concurrently access the same file systems than the TrueVFS Access Path module.

For example, an application could access an entry within an archive file using a TFile like this:

 File entry = new TFile("archive.zip/dir/HälloWörld.txt");
 Writer writer = new TFileWriter(entry);
 try {
     writer.write("Hello world!\n");
 } finally {
     writer.close();
 }
 

This example presumes that the JARs of the file system driver modules TrueVFS Driver File and TrueVFS Driver TAR are present on the run time class path.

Mind that a TFile is a File, so you can use it polymorphically. However, you cannot use it with a plain File(In|Out)putStream or a plain File(Reader|Writer) to access prospective archive entries because these classes were not designed for this task. You have to use a TFile(In|Out)putStream or a TFile(Reader|Writer) instead.

The TPath Class and its Companions

This is the primary API for JSE 7 compliant TrueVFS applications: Like the API of the module TrueVFS Access File*, this API is just a facade for the module TrueVFS Kernel. In contrast to the TrueVFS Access File* API however, this API can access any (virtual) file system, not just the platform file system and any archive files within the platform file system. In contrast to the TrueVFS Kernel API, both APIs are designed to be easy to learn and convenient to use while providing a great level of flexibility. Because all virtual file system state is managed by the TrueVFS Kernel module, this module can concurrently access the same file systems than the TrueVFS Access File* module.

For example, an application could access an entry within an archive file which is located at a web site using a TPath like this:

 Path path = new TPath(new URI("http://acme.com/download/everything.tar.gz/README.TXT"));
 try (InputStream in = Files.newInputStream(path)) {
     // Read archive entry contents here.
     ...
 }
 

This example presumes that the JARs of the file system driver modules TrueVFS Driver HTTP(S) and TrueVFS Driver TAR are present on the run time class path.

Mind that a TPath is a Path, so you can use it polymorphically with the NIO.2 API.

File System Provider Service Location

This package provides a JSE 7 compliant file system provider implementation in its class TFileSystemProvider. If the JAR of this package is present on the run time class path, an application can transparently access archive files without a compile time dependency on this API. However, some constraints apply in this case because the NIO.2 API does not support file system federation:

• A FileSystemProvider instance is limited to support exactly only one file system provider scheme. So the installed TrueVFS file system provider instance limits the access to the platform file system, which is identified by the custom URI scheme "tpath".
• The TrueVFS file system provider instance competes with the ZipFileSystemProvider instance provided by JSE 7. So when probing ZIP or JAR files, it's undefined which provider will be used - see below.
• When using Paths.get(String, String[]), the returned Path instance is always associated with the default file system provider, which depends on the JVM platform.
• When using a Path object to resolve another Path object, e.g. by calling Path.resolve(Path), then the new Path object is typically associated with the same FileSystemProvider object. So unless the original Path object was an instance of TPath, when traversing a directory tree which contains a prospective archive file, the new Path object will not be a TPath instance, too, and so the application will most likely not be able to access the archive file transparently as if it were just a plain directory.

So the only way how an application can use the TrueVFS file system provider instance without a compile time dependency is to use FileSystems.newFileSystem(java.nio.file.Path, java.lang.ClassLoader). However, this is unlikely to get used in most applications.

Recommended Usage

To overcome these constraints, an application should not rely on File System Provider Service Location and directly create TPath instances instead by calling one of the public class constructors. Once created, it's safe to use TPath instances polymorphically as Path instances.

General Constraints

Currently, the NIO.2 API provides some features which are not supported by the implementation of this package, e.g. a file system permissions or watch services. Consequently, if an unsupported method is called, an UnsupportedOperationException gets thrown.

Author:

Christian Schlichtherle