Package Summary

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 {@link de.schlichtherle.truezip.nio.file.TPath} class and its dependent classes.

This is the primary API for JSE 7 compliant TrueZIP applications. In contrast to the TrueZIP Kernel API, this API is designed to be easy to learn and convenient to use while providing a great level of flexibility.

File System Provider Service Location

This package provides a JSE 7 compliant {@link java.nio.file.spi.FileSystemProvider file system provider} implementation in its class {@link de.schlichtherle.truezip.nio.file.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 {@link java.nio.file.spi.FileSystemProvider#getScheme() file system provider scheme}. So the installed TrueZIP file system provider {@link de.schlichtherle.truezip.nio.file.TFileSystemProvider#TFileSystemProvider() instance} limits the access to the platform file system, which is identified by the custom URI {@link java.net.URI#getScheme() scheme} "{@code tpath}".
The TrueZIP file system provider instance competes with the ZipFileSystemProvider instance provided by JSE 7. So when {@link java.nio.file.FileSystems#newFileSystem(java.nio.file.Path, java.lang.ClassLoader) probing} ZIP or JAR files, it's undefined which provider will be used - see below.
When using {@link java.nio.file.Paths#get(String, String[])}, the returned {@link java.nio.file.Path} instance is always associated with the default file system provider, which depends on the JVM platform.
When using a {@code Path} object to resolve another {@code Path} object, e.g. by calling {@link java.nio.file.Path#resolve(Path)}, then the new {@code Path} object is typically associated with the same {@code FileSystemProvider} object. So unless the original {@code Path} object was an instance of {@code TPath}, when traversing a directory tree which contains a prospective archive file, the new {@code Path} object will not be a {@code 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 {@link java.nio.file.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 {@link de.schlichtherle.truezip.nio.file.TPath} instances by calling one of the public class constructors. Once created, it's safe to use {@code TPath} instances polymorphically as {@link java.nio.file.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 {@link java.lang.UnsupportedOperationException} is thrown.