The VirtualFileSystem lets you deal with data in terms of files, input, and output streams. VirtualFileSystem works over an Environment instance:

final Environment env = Environments.newInstance("/home/me/.myAppData");
final VirtualFileSystem vfs = new VirtualFileSystem(env);

Any VirtualFileSystem operation requires a Transaction instance. An application working with VirtualFileSystem should shutdown() it before closing the underlying Environment:

vfs.shutdown();
env.close();

Files

In the following examples, we assume that all operations are performed inside a Transaction named txn. To create a file:

final File file = vfs.createFile(txn, "myFile");

"myFile" is the path of the file. This method throws FileExistsException on an attempt to create a file with the path of any other existing file. The path is an abstract string and can be used to codify a hierarchy, though VirtualFileSystem doesn't contain methods to enumerate files by a path prefix.

The file does not appear in the file system until the transaction is flushed or committed. You can also create a file with the openFile() method:

final File file = vfs.openFile(txn, "myFile", true);

The Boolean parameter true lets you create the file if it does not exist in the file system.

You can create a file with a unique auto-generated path and specified path prefix with createUniqueFile().

In addition to the path, any File gets a unique auto-generated file descriptor. This can be used further on a par with the path to identify the file.

Streams

To access file contents, VirtualFileSystem lets you create an InputStream and OutputStream that are associated with the file.

// read the file from the beginning
final InputStream input = vfs.readFile(txn, file);
// read the file from specified position
final long position = 31415926;
final InputStream input = vfs.readFile(txn, file, position);
// write the file from the beginning
final OutputStream output = vfs.writeFile(txn, file);
// write the file from specified position
final OutputStream output = vfs.writeFile(txn, file, position);
// write the file from the end of the file (append file)
final OutputStream output = vfs.appendFile(txn, file);

Lucene Directory

ExodusDirectory is a good sample of using VirtualFileSystem. It implements org.apache.lucene.store.Directory and stores the contents of a full-text index that was created by Apache Lucene in Xodus. See the tests to find out how ExodusDirectory can be used.

To use ExodusDirectory in your application, define a dependency on the xodus-lucene-directory artifacts:

<!-- in Maven project -->
<dependency>
    <groupId>org.jetbrains.xodus</groupId>
    <artifactId>xodus-lucene-directory</artifactId>
    <version>1.0.0</version>
</dependency>

// in Gradle project
dependencies {
    compile 'org.jetbrains.xodus:xodus-lucene-directory:1.0.0'
}