Introduction

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.

Back to top

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.

Back to top

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 http://xadisk.java.net/)
3. JCA 1.5 Jar (download from http://download.java.net/maven/1/javax.resource/jars/connector-api-1.5.jar)

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.

String XADiskSystemDirectory =“/home/systems/XADiskSystem1";
StandaloneFileSystemConfiguration configuration = 
    new StandaloneFileSystemConfiguration(XADiskSystemDirectory, “instance-1”);
XAFileSystem xaf = XAFileSystemProxy.bootNativeXAFileSystem(configuration);
xaf.waitForBootup(10000L);

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.

XAFileSystem xaf = XAFileSystemProxy.getNativeXAFileSystemReference(“instance-1”);
            

3. By remote applications, as shown in Listing 3.

XAFileSystem xaf = XAFileSystemProxy.getRemoteXAFileSystemReference("10.30.9.200", 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.

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.

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) xis.read();
        if( a== -1) {
            break;
        }
        System.out.print(a);
     }
    xis.close();
    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;
     }
     xafos.write(buffer);
     xafos.close();
}
/* 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.

//commit the transaction
session.commit();
//or rollback the transaction
session.rollback();

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.

XAFileSystem xaf = XAFileSystemProxy.getNativeXAFileSystemReference(“instance-1”);
xaf.shutdown();

Back to top

Conclusion

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.

Resources

Learn

• Transaction processing and ACID: Check out these Wikipedia pages if you are new to transactions.
  
  
• developerWorks Open source zone: Find extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM products.
  
  
• Events of interest: Check out upcoming conferences, trade shows, and webcasts that are of interest to IBM open source developers.
  
  
• developerWorks podcasts: Tune into interesting interviews and discussions for software developers
  
  
• developerWorks demos: Watch our no-cost demos and learn about IBM and open source technologies and product functions.
  
  
• developerWorks on Twitter: Follow us for the latest news.
  
  

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.
  
  

Discuss

• XADisk Discussion Group: Discuss anything related to XADisk
  
  
• developerWorks community: Connect with other developerWorks users while exploring the developer-driven blogs, forums, groups, and wikis. Help build the Real world open source group in the developerWorks community.
  
  

About the author

Nitin 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.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Basics of XADisk
• Using XADisk
• Conclusion
• Resources
• About the author
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

Dig deeper into Open source on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers