Package de.schlichtherle.truezip.nio.file

Provides uniform, transparent, thread-safe, read/write access to archive files as if they were just plain directories in a file system path by means of the TPath class and its dependent classes.

This is the primary API for JSE 7 compliant TrueZIP applications: Like the API of the module TrueZIP Path, this API is a facade for the module TrueZIP Kernel. In contrast to the TrueZIP 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 TrueZIP 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 TrueZIP Kernel module, this module can concurrently access the same file systems than the TrueZIP 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 TrueZIP Driver HTTP(S) and TrueZIP 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 restrictions 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 TrueZIP file system provider instance limits the access to the platform file system, which is identified by the custom URI scheme "tpath".
• The TrueZIP 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 TrueZIP 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 restrictions, an application should directly create TPath instances by calling one of the public class constructors. Once created, it's safe to use TPath instances polymorphically as Path instances.

Mind that the NIO.2 API provides some features which are not supported by the current implementation of this package. Consequently, if an unsupported method is called, an UnsupportedOperationException is thrown.