de.schlichtherle.truezip.nio.file.package.html Maven / Gradle / Ivy
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.