About

Instruments the TrueVFS Kernel for statistics monitoring via JMX.

Usage

Add the JAR artifact of this module to the run time class path to make its services available for service location in the client API modules.

When using Maven, add the following to your pom.xml file:

<project    xmlns="http://maven.apache.org/POM/4.0.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    ...
    <dependencies>
        ...
        <dependency>
            <groupId>net.java.truevfs</groupId>
            <artifactId>truevfs-ext-insight</artifactId>
            <version>0.12.0</version>
            <scope>runtime</scope>
        </dependency>
    </dependencies>
</project>

Sample

TODO: This section still reflects TrueZIP Extension JMX/JUL and needs an update.

To demonstrate this module, let's use the Tree class generated by the TrueVFS Archetype File*. This class simply prints an ASCII directory tree of a directory and then terminates. When run unchanged with no arguments in the project directory of the generated archetype, it's output may look like this:

.
|-- nbactions.xml
|-- pom.xml
|-- src
|   `-- main
|       `-- java
|           `-- de
|               `-- schlichtherle
|                   `-- mavenproject1
|                       |-- Application.java
|                       |-- Cat.java
|                       |-- Copy.java
|                       |-- Pickr.java
|                       `-- Tree.java
|-- target
|   |-- classes
|   |   `-- de
|   |       `-- schlichtherle
|   |           `-- mavenproject1
|   |               |-- Application.class
|   |               |-- Cat.class
|   |               |-- Copy.class
|   |               |-- Pickr$1.class
|   |               |-- Pickr.class
|   |               `-- Tree.class
|   |-- generated-sources
|   |   `-- annotations
|   |-- maven-archiver
|   |   `-- pom.properties
|   `-- mavenproject1-1.0-SNAPSHOT.jar
|       |-- de
|       |   `-- schlichtherle
|       |       `-- mavenproject1
|       |           |-- Application.class
|       |           |-- Cat.class
|       |           |-- Copy.class
|       |           |-- Pickr$1.class
|       |           |-- Pickr.class
|       |           `-- Tree.class
|       `-- META-INF
|           |-- MANIFEST.MF
|           `-- maven
|               `-- de.schlichtherle
|                   `-- mavenproject1
|                       |-- pom.properties
|                       `-- pom.xml
`-- test.jar
    |-- archive.tar
    |   `-- pom.xml
    |-- archive.tar.gz
    |   `-- pom.xml
    |-- archive.zip
    |   `-- pom.xml
    |-- pom.xml
    `-- the-password-is-test1234.tzp
        `-- pom.xml

As you see, the Tree class recursively prints the (virtual) directory structure of the archive files mavenproject1-1.0-SNAPSHOT.jar and test.jar with its enclosed archive files.

It was said initially that you could use this module without changing the client application code. However, the Tree class terminates immediately before you would even have a chance to connect to the JVM with JConsole or JVisualVM. So let's add the following method to the base class Application:

@Override
protected void sync() throws FsSyncException {
    try {
        Thread.sleep(Long.MAX_VALUE);
    } catch (InterruptedException ok) {
    }
    super.sync();
}

This will not only make the Tree class run forever, it will also prevent it from unmounting the archive files, so that you have something to monitor and manage in the JConsole.

The MXBeans

Now, when running the tweaked utility, you see the output above and then the utility halts. Next, let's start JConsole and connect it to the JVM running the Tree class. When changing to the MBeans tab, you can now see some nice MXBeans for TrueVFS. Each of the MXBean classes provide attributes and operations with descriptions so you can figure what's going on.

The FsManager MXBean represents the singleton file system manager:

FsManager MXBean

It has two operations, one for unmounting all archive files and one for clearing all but the last I/O statistics.

The FsModel MXBeans represent federated file systems alias archive file systems:

FsModel MXBeans

Because the Tree class has found six archive files in the directory tree, we see six MXBeans, one for each mounted archive file. Each MXBean provides one operation for unmounting the respecting archive file.

Last but not least, the IOPool$Entry MXBeans represent temporary files:

IOPool$Entry MXBeans

It may be hard to follow, but one temporary file is required for each enclosed ZIP file - so in this case two temporary files for the file archive.zip and the-password-is-test1234.tzp within test.jar. Furthermore, because the TAR file format does not have a central directory, the TAR drivers unroll each TAR file when mounting them - so in this case two more temporary files for the file pom.xml in archive.tar and archive.tar.gz within test.jar.

Now you can inspect the attribute descriptions and values and/or you can use the umount/clearStatistics operations:

umount() operation

I need to add a few points, though:

  • If umount gets called on an FsModel MXBean, then the virtual file system for the respective archive file and all enclosed archive files get unmounted. So if called on test.jar, then archive.tar, archive.tar.gz, archive.zip and the-password-is-test1234.tzp get unmounted, too. With earlier TrueVFS versions, the filtering doesn't work correctly and accidentally all archive files may get unmounted.
  • If umount gets called on the FsManager MXBean, then all federated file systems get unmounted.
  • In any case, this will only work if the federated file systems are idle! If any file system is busy doing I/O, then you will get a FsSyncException. So calling this operation is safe.

Once you unmount a federated file system, its respective FsModel and IOPool$Entry MXBeans vanish automagically. So you only see the stuff which keeps TrueVFS busy.