Motivation

Suppose you're writing a plug-in for the next generation IDE which shall show the users the contents of any assembly and allow them to arbitrarily modify it. Then you may need to support at least the following archive types:

• TAR.GZ
• TAR.BZ2
• TAR.XZ
• ZIP
• JAR
• WAR
• EAR
• ...

You can easily figure that writing the code to read and write archive files of all these types will be a cumbersome and tedious task because each archive type typically comes with its own API to read and write its archive files. Furthermore, the algorithms required to manage the state transitions required to support arbitrary modifications to an archive file in a thread-safe manner are very complex.

Reading and Writing Archive Files

Thanks to the client API of the module TrueVFS Access, here's your relief: The TFile class extends the java.io.File class in order to add the required functionality.

See how easy listing the contents of the top level directory of an archive file can be:

TFile[] entries = new TFile("archive.jar").listFiles();

To create or overwrite an entry in an archive file, you could simply use this:

try (Writer writer = new TFileWriter("archive.jar/META-INF/MANIFEST.MF")) {
    ...;
}

You may be glad to see that this works recursively, too. Here's how to read the manifest of a library JAR within a web application:

try (Reader reader = new TFileReader("app.war/WEB-INF/lib/lib.jar/META-INF/MANIFEST.MF")) {
    ...;
}

And finally, to delete an entry in an archive file, you could use this:

new TFile("archive.jar/META-INF/MANIFEST.MF").rm();

Customizing the Initial Configuration

You may be wondering how TrueVFS gets configured to treat a file name with a jar or war extension as a JAR or WAR file instead of a plain old file. For now, let it suffice to say that TrueVFS follows the convention-over-configuration principle as much as possible, so there are reasonable defaults for everything in order to relieve you from typical configuration tasks.

For the previous examples to work, the JARs of the driver module TrueVFS Driver ZIP needs to be present on the run time class path. You can do this by adding the Maven artifactId truevfs-driver-zip as a dependency to the POM of your Maven build.

For more information about configuring the client API, please refer to the article Configuring TrueVFS Access.

Committing Changes / Cleaning Up

If your application has created or changed one or more archive files, then these changes need to get committed sometime. Even if your application has done read-only acess to the virtual file system, some temporary files may have been created to speed up random access - this dependends on the driver implementation.

If your application is only short-running, then there is actually nothing to do because the TrueVFS Kernel automatically registers and de-registers a JVM shutdown hook which will commit all changes when its run. Note that shutdown hooks are run even if the application terminates due to a Throwable.

However, if your application is long running or wants to handle any exceptions, then you may want to manually call this operation - here's how to do this:

TVFS.umount();

As a side effect, once this operation succeeded, third parties (e.g. other processes) can safely access the processed archive files until the next time your application starts to operate on them again.