Transactions with file systems using XADisk

Introduction to XADisk

Java™ applications, which store their data in files, can benefit in many ways by accessing file-systems using transactions. Learn how to work with open source XADisk for transactional file access.


Nitin Verma, Computer Scientist, Adobe Systems

Nitin Verma photoNitin Verma is a JavaEE developer at Adobe Systems. He previously worked at Oracle and contributed to JCA Adapters of the Oracle SOA Suite. XADisk started out of his love for JCA and XA. Nitin graduated from IIT in Computer Science and Engineering.

19 December 2011

Also available in Chinese Russian Japanese


Many Java applications, including server-side and desktop, maintain their critical data in file-systems, databases, and other information systems. For safe and robust interaction with such crucial data, application developers often look for transactional access to these information systems. A typical transaction provides the well-known ACID properties, atomicity, consistency, isolation and durability.

Most current databases have support for transactions. For file systems, this functionality is either unavailable or is difficult to integrate with Java applications. It becomes impossible or very difficult to associate a transaction with a sequence of file/directory operations. Without transactions, there are risks like unexpected outcomes during application crash, concurrent access to the same set of data, and partial changes being visible, etc.

This article introduces XADisk, an open source comprehensive transaction system that enables transactional access to file-systems from Java and JavaEE applications. With a few simple APIs, you can deploy XADisk over any JVM without requiring any installation on the OS. Once deployed, applications invoke the XADisk APIs for performing various file IO operations inside transactions.

XADisk provides many other features such as XA transactions, full JCA compliance, inbound messaging and others. These features are outside the introductory level of this article.

Basics of XADisk

Consider XADisk a layer between applications and the file-systems. XADisk is not a file-system implementation in itself; it can work with a variety of file-systems (e.g., NTFS, FAT, ext3) and enable applications to access those file-systems transactionally. Applications invoke XADisk APIs for performing various I/O operations, and are able to commit or rollback all of them as a single transaction.

XADisk has been written in Java and runs on Java 5 or above. It can be used by all kinds of Java applications, web-applications running in Java servers like Apache Tomcat and JavaEE applications running in JavaEE servers, etc.

For a simple example of XADisk use, consider a Java application. This application wants to create a new file called F1, write some data to it from another file called F2, and then delete F2. These three operations can be performed inside a single transaction using XADisk with typical guarantees of the ACID properties mentioned previously. XADisk would maintain these guarantees even if the application crashed in the middle.

XADisk supports a variety of operations over files/directories:

  • Files — create, delete, move, copy, truncate, read, write, exists, getLength
  • Directories — create, delete, move, list children, exists

When using XADisk, an application and the target file-system need not be on the same machine. It is possible for an application to invoke XADisk APIs remotely in the same way as XADisk deployed on the same JVM.

The remainder of this article covers some simple steps to start using XADisk in any Java application.

Using XADisk

Boot up process

Before invoking XADisk IO operations, boot an XADisk instance inside a JVM. Within the same JVM, there can be multiple instances of XADisk; each XADisk instance will have its own isolated state. This article demonstrates how to boot and invoke one such XADisk instance.

As you can boot XADisk on any JVM, you can use it in a variety of Java environments, ranging from simple Java programs to JavaEE servers like JBoss and web servers like Tomcat.

To boot an XADisk instance, you need the following in your system environment:

  1. Java5 or above
  2. XADisk.jar (download from
  3. JCA 1.5 Jar (download from

During bootup, XADisk accepts a configuration object for its various configuration properties. Most of the configuration properties have their default values set. Only SystemDirectory and InstanceId are mandatory. As shown in Listing 1, the configuration constructor accepts these two configuration properties. SystemDirectory is a directory where XADisk keeps all of its artifacts (for example, transaction logs) required for its functioning. InstanceId uniquely identifies an XADisk instance within a JVM.

Listing 1. Configure and initialize an XADisk instance
String XADiskSystemDirectory =“/home/systems/XADiskSystem1";
StandaloneFileSystemConfiguration configuration = 
    new StandaloneFileSystemConfiguration(XADiskSystemDirectory, “instance-1”);
XAFileSystem xaf = XAFileSystemProxy.bootNativeXAFileSystem(configuration);

The above sequence completes the configuration of an XADisk instance and goes into a wait for it to complete the boot up process. After the booting is complete, this XADisk instance is available for use by applications on the same JVM or remote JVMs.

Note that a reference of type XAFileSystem is the entry point to start invoking operations on an XADisk instance. This XAFileSystem reference can be obtained:

  1. During boot up, as shown in Listing 1.
  2. Using the instanceId from anywhere in the JVM, as shown in Listing 2.
Listing 2. Obtaining XAFileSystem reference for XADisk instance in the same JVM.
XAFileSystem xaf = XAFileSystemProxy.getNativeXAFileSystemReference(“instance-1”);
  1. By remote applications, as shown in Listing 3.
Listing 3. Obtaining XAFileSystem reference for XADisk instance on a remote JVM.
XAFileSystem xaf = XAFileSystemProxy.getRemoteXAFileSystemReference("", 5151);
/*the parameters are the serverAddress and serverPort configuration properties 
used during booting of the remote XADisk instance. Note that remoting to 
an XADisk instance is disabled by default and can be enabled 
using configuration.setEnableRemoteInvocations(true) during bootup*/

Calling IO operations

Now that the XADisk instance is ready, transactional operations can begin over files/directories.

After obtaining the XAFileSystem reference, the method of invoking XADisk APIs remains the same whether the target XADisk instance is running on the same JVM or a remote one.

As file/directory operations would be happening inside a transaction, first start a transaction by creating a Session, as shown in Listing 4.

Listing 4. Create a session and start a transaction
Session session = xaf.createSessionForLocalTransaction();

After we have the session, IO operations can be performed as needed. The XADisk APIs for file/directory operations are straightforward. Listing 5 shows some examples.

Listing 5. Invoke XADisk APIs for file/directory operations
File f = new File("/testAPIs/test.txt");
if(session.fileExists(f)) {
    XAFileInputStream xis = session.createXAFileInputStream(f);
    for (int i = 0; i < 100; i++) {
        byte a = (byte);
        if( a== -1) {
    session.moveFile(f, new File("/testAPIs/test.txt___” + System.currentTimeMillis()));
else {
    //use false below to create file, true for directory
    session.createFile(f, false);
     //use false below for tiny write operations, true otherwise
     XAFileOutputStream xafos = session.createXAFileOutputStream(f, false);
     byte[] buffer = new byte[100];
     for (int i = 0; i < 100; i++) {
        buffer[i] = i*i;
/* You can do more operations here, by calling Session APIs 
for reading/writing/creating/deleting/updating/copying/moving files 
and directories. For details, please see the XADisk JavaDoc for 
interface named XADiskBasicIOOperations.*/

After completing all IO operations, we can commit (or rollback) the transaction with a simple call to the session object, as shown in Listing 6.

Listing 6. Commit or rollback the transaction associated with the session
//commit the transaction
//or rollback the transaction

To start a new transaction, create a new Session object and follow the same steps shown in Listing 5

Shutting down

You can shut down an XADisk instance from anywhere in the JVM, as shown in Listing 7.

Listing 7. Shut down the XADisk instance from the same JVM
XAFileSystem xaf = XAFileSystemProxy.getNativeXAFileSystemReference(“instance-1”);


Applications that keep their critical data over file-systems can realize a significant benefit by using transactions with the file-systems. XADisk is an open source and freely available solution enabling applications to interact with file-systems using transactions. It provides simple APIs for initializing, performing various file/directory operations, and managing the transactions.

XADisk can do much more. Visit the links in Resources to get more information, sample code, and join in technology discussions.



Get products and technologies

  • XADisk home page: Find more about XADisk, access user guides, and obtain JavaDoc and sample codes.
  • Evaluate IBM software products: From trial downloads to cloud-hosted products, you can innovate your next open source development project using software especially for developers.



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Open source on developerWorks

Zone=Open source, Java technology
ArticleTitle=Transactions with file systems using XADisk