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:
Like the TrueZIP Path API, this API is a facade for the TrueZIP
Kernel API.
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 {@code TPath} like this:
Path path = new TPath(new URI("http://acme.com/download/everything.tar.gz/README.TXT"));
try (Files.newInputStream(path)) {
// Read the file contents here.
...
}
This example requires 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.
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.