Java IoT Authors: Hollis Tibbetts, Elizabeth White, Liz McMillan, Pat Romanski, Sematext Blog

Related Topics: Java IoT

Java IoT: Article

Enabling A File System As A Transactional Resource

Building An Adapter

Transactional support is fundamental to application development. While most data sources are transactional in nature, some data sources like the file system are not.

In typical J2EE deployments, applications often need to interface with other applications through file-based messages. Such deployments would benefit from an adapter that would buffer all file operations and provide a transactional view to the file system.

This article, targeted at developers, demonstrates how J2EE Connector Architecture and JTA specifications can be implemented to build such an adapter, XAFileConnector. We'll also suggest enhancements to extend the adapter functionality in light of the new proposed draft connector specifications.

Most applications are bound to the local file system. They use the file system to store and share data. Often the success of interactions with the file system needs to be tied to the successful completion of other actions involving other Enterprise Information Systems (EIS). For instance, we often encounter situations where a record is to be deleted from the database only after it has been successfully written to a file. While the same can be easily built into the application logic, it would be infinitely more neater if we could develop an extension on the file system that would help us include the file operations such as "create", "read", "update", and "delete" as part of a transactional unit of work that could be committed or rolled back as a group. This extension is called a Resource Adapter. The ubiquitous presence of the file system and the role it plays in Enterprise Application Integration strategy justify the need to build such a resource adapter.

For a J2EE-managed environment, i.e., an environment characterized by the presence of a container for runtime support, J2EE recommends Connector Architecture as a standard way of integrating heterogeneous EISs with the application server. The Connector Architecture specifies application- and system-level contracts to be implemented by the EIS. The resource adapter implements the EIS side of the contracts. The adapter uses a native interface specific to the underlying EIS, runs in the containers address space, and manages access to the EIS resources. Adherence to the Connector contracts on one hand ensures that the same adapter can be deployed on different vendors' containers, while ensuring that application and tool developers have a standard interface to program to for accessing different EIS systems. Among the set of contracts that need to be implemented by the resource adapter to seamlessly plug-in to any J2EE platform is the XAResource transaction contract. This contract defines the communication interfaces between the parties involved in a distributed transaction. Implementation of this interface by the adapter enables seamless propagation of transaction context and allows the associated resource manager (RM) to participate in a two-phase commit protocol along with other resources.

With this introduction we proceed to discuss what these contracts are and what it takes to implement these contracts to build an adapter.

Understanding and Implementing the Contracts
The application contract manifests itself as a Common Client Interface (CCI). CCI is the client side of the adapter and performs the following roles:

  • Specifies how application components connect to the EIS through a resource adapter
  • Provides an API for coding EIS function calls and retrieving results

    Connecting to the EIS
    ConnectionFactory is the application's gateway to the EIS. It's instantiated at the time of deployment by the container and a reference to it, or its serialized representation, is bound to the JNDI namespace. Later the application components do a JNDI lookup to get hold of the factory to create connection objects to the EIS. The ConnectionFactory does not represent the actual connection repository, nor is the connection the actual physical connection to the EIS. Both are client-side proxies that nevertheless maintain handles to the actual factory and connection objects, respectively. The container plays the role of an intermediary between the real objects and their proxies, and the mechanism allows the container to inject value-added services by intercepting calls made on the proxies before they're actually delegated to the real objects.

    When a ConnectionFactory encounters a getConnection request, it delegates it to the ConnectionManager instance.

    public Connection getConnection()
    throws ResourceException {

    return (Connection)connMgr.allocateConnection
    (mngdConnFactory, new ConnectionRequestInfoImpl());

    In a managed environment the ConnectionManager implementation is provided by the container. The ConnectionManager maintains a pool of connections corresponding to each factory. The ConnectionManager checks whether it can service the request from the pool. If not, it requests the real factory (ManagedConnectionFactory) to create a new connection.

    How does the container know about the availability status of a connection?

    The Connector Architecture prescribes an elaborate mechanism of listeners to implement callbacks. Whenever a new connection is created, the container registers a listener with it. The connection raises event notifications to intimate the container about the happenings on the connection. When a close is called on the connection proxy it terminates its association with the physical connection. The physical connection in turn generates an event. All the listeners registered on the connection can react to the event. The container on its part uses the event to change the availability status of the connection from in-use to available, i.e., if the connection is not participating in a transaction. If the connection is participating in a transaction, the container waits for the transaction to commit before it can make the connection available (see Listing 1).

    Invoking EIS Functions
    An InteractionSpec implementation holds properties for driving an interaction with an EIS instance. In our case each property maps to a File Operation that may be performed.

    public static final int CREATE = 10;
    public static final int UPDATE = 20;
    public static final int DELETE = 30;
    public static final int MOVE = 40;
    public static final int SKIP = 50;
    public static final int READ = 60;

    Since CCI is EIS independent it cannot use any of the EIS data structures. To get over this, CCI introduces the concept of a record. A record is a generic representation of data that's exchanged with the EIS. More specific implementations to represent hierarchical, tabular data collections can also be implemented. XAFileConnector extends the MappedRecord, which is a key value representation of record elements for both input and output records (see Listing 2).

    CCI defines an interaction interface that allows a client to interact with EIS. An interaction represents a single communication with the EIS, an EIS function call. An interaction instance is obtained from a connection. The interaction instance is required to maintain its association with the connection instance. The interaction delegates its execution to the connection, which in turn delegates its execution to the associated ManagedConnection (see Listing 3).

    Transaction Contract
    A transaction as we know it is a set of operations performed in such a way that the state of the system after the transaction is either the cumulative effect of state changes due to successful individual operations or is the initial state before the commencement of the transaction in case one or more operations happens to fail. Transactions can be classified into two types based on the number of resources participating.
    1.  A local transaction performs operations on a single RM. The local transactions can be further classified based on the manner of demarcating transaction boundaries.

  • javax.resource.cci.LocalTransaction: These run under the control of the RM. The transaction object can be obtained from the connection object and used to demarcate transaction boundaries somewhat analogous to the way JDBC setAutoCommit(false) and commit APIs are used to demarcate transaction boundaries.
  • javax.resource.spi.LocalTransaction: Work in this type of transaction can accrue over multiple client components. A client component may do some work on a resource and pass control to another component, which may again do some work while still being part of the same transaction. The transaction context is passed along with the control, and it contains the following information:
    - A reference to the transaction manager (TM), the external entity that is used to demarcate transaction boundaries
    - A globally unique transaction identifier, XID, generated by the TM
    - A transaction timeout time

    2.  Global/distributed transactions - work in this type of transaction can span multiple RMs. The transaction manager demarcates the transaction boundaries. A TM coordinates the activities on the participating RMs using the XAResource interface. An RM knows only about the work it does for its transaction branch. The XAResource interface implements the two-phase commit protocol between the RMs and the TM. The XAResource interface allows for a one-phase optimization in case only one resource is participating.

    With this brief introduction to transactions we'll start with how we can incorporate transactional ability into our file system adapter.

    For a file system adapter to be able to roll back a transaction, i.e., revert to state prior to the start of a transaction, an adapter must either memorize the original state or it must be able to get back to the original state by performing certain anti-operations that reverse the effect of the operations. To ensure feasibility and consistency at all times, the anti-operations have to be performed in the order that is exactly the reverse order in which the operations were performed. Similarly, committing a transaction should flush all transactional logs to free all memory.

    For each file operation on the connection that modifies the state of the file system (nonread only call), XAFileConnector adds a WorkItem to the associated transaction's work list. If there's no active transaction associated with the connection, it autocommits the work and no WorkItem is created. The WorkItem stores enough information about the associated operation to be able to reverse its effect in case of a rollback or to do a cleanup of the backup in case of a commit. A work area is designated to store the information needed for restoration in the event of a rollback (see Listing 4).

    Note how MOVE and CREATE file operation do not have any associated cleanup during operation commit while UPDATE and DELETE operations delete the backups.

    Depending on the kind of transaction running, javax.resource.cci.LocalTransaction, javax.resource.spi. LocalTransaction, or XAResource keeps track of the work being done in the transaction impending completion.

    CCI Local Transaction implementations are obtained directly from the connection, without the container having any role to play. Since the container is not directly involved, it is not intimated of the state of the transaction, so CCI implementations of local transactions differ from SPI implementations in the sense that they need to raise event notifications to apprise the container of transaction life-cycle events. The events help the container in connection pool management. Since there's only a marginal difference in functionality, the same class is used to implement both forms of local transactions with a flag identifying the type of transaction the current instance represents.

    Our implementation model exhibits the following relationships shown in Figure 1.

    Figure 1

    Each ManagedConnection can provide an XAResource implementation for distributed transaction management. The beginTransaction call associates the application component's thread of control with a global transaction. The TM generates a globally unique XID and calls start on all open RMs that are linked with the thread. The RMs are enlisted with the transaction. To guarantee scalability of the Connector Architecture, it recommends that a physical connection and hence the associated XAResource can participate in multiple transactions, but at any point only one of these transactions can be active. To ensure this, the start call first checks that the associated connection isn't running a local transaction nor is the XAResource instance associated with an active transaction. Once assured, it associates the passed XID with the XAResource instance and activates the transaction. All work done henceforth on this physical connection, until the transaction is suspended or completed, accumulates against the active transaction.

    The start call is accompanied by the following flags:

  • TMNOFLAGS: Indicates that it is a new transaction. A call to getTransactionState with flag true creates new entries for the new transaction and initializes the instance.
  • TMRESUME: Indicates a suspended transaction is being resumed. A call to getTransactionState with flag false means no new entries need to be made. The state of the transaction is retrieved and the current instance is initialized with that state. The state of the transaction is also changed from SUSPENDED to NOT SUSPENDED.
  • TMJOIN: A two-phase optimization, the TM, when it detects that a particular RM instance is already participating in a transaction, instead of creating a new branch decides to merge all work done on a single RM against a single XID. By doing this it saves on running the two-phase protocol on all branches separately. No new entries have to be made and the state of the transaction remains throughout NOT SUSPENDED (see Listing 5).

    The application component calls commit to make the effects of the transaction permanent. The TM first calls end for each involved RM, from the AP's thread of control, to dissociate the thread from the global transaction. The TM then executes the two-phase commit protocol.

    STAGE 1 is the prepare stage or the voting stage. TM calls prepare for each RM that was associated with the global transaction. RMs express their readiness to commit the transaction. A single negative vote ensures rollback. A prepare attempt on a suspended transaction would throw back a protocol exception. Similarly it throws back an exception, albeit a different one, when the transaction has been marked earlier for rollback due to internal errors. Prepare stage also offers a two-phase optimization. A transaction that has not changed the state of the RM doesn't need to go through the second phase if prepare returns XA_RDONLY (see Listing 6).

    Stage 2 is the commit stage. If all RMs return success from prepare, the TM records a decision to commit the transaction and calls commit for each RM. The XA specification allows for an optimization in this procedure. If the TM has dealt with only one subordinate RM in the global transaction, it can omit Phase 1 by directly calling commit with the onePhase flag set to true (see Listing 7).

    Deployment Process
    Before we can start using the adapter, we need to deploy it. All adapter interfaces, classes, native libraries, etc., along with the Deployment Descriptor (DD), are packaged in a .rar archive. In situations where multiple J2EE applications need to share the XAFileConnector, it can be deployed directly into an application server as a standalone unit. However, the resource adapter module may also be bundled with a J2EE application, if it is needed only by a single application.

    The Deployment Descriptor provides a lot of information to the container, including:

  • General information such as name and version of adapter, vendor name, licensing requirements, etc.
  • Names of concrete classes for certain core interfaces; for example, we have to provide the name of the class that implements the ManagedConnectionFactory Interface.
  • Information about the kind of support built into the adapter. This allows the container to perform certain optimizations. XAFileConnector offers full support for XATransaction. No authentication support is needed as all native calls to connect to the resource, i.e., the local file system, are made in the current user's context.
  • Configurable properties that are dependent on the deployment environment. The property naming conventions follow the JavaBean standard. XAFileConnector uses a property by the name of workingFolder to store the name of the folder where transaction logs of the running transactions are kept. The deployer sets this property at the time of deployment by invoking the corresponding setter method. The method checks for the existence of the folder and sufficient access permissions before returning (see Listings 8 and 9).

    To be able to successfully deploy an adapter, a better understanding of the deployment process is essential. We will briefly walk through the responsibilities of the deployment code and how it interacts with the adapter code.

  • The deployment code looks at the DD to find out which class implements the ManagedConnectionFactory Interface. It dynamically creates an instance of the same and configures properties on the instance.XAFile The Connector uses only one property workingFolder as discussed earlier.
  • In a managed environment the deployment code instantiates a ConnectionManager specific to the container and obtains a ConnectionFactory instance from ManagedConnectionFactory, as shown in the following implementation:

    public Object createConnectionFactory(ConnectionManager cxManager)
    throws ResourceException
    return new ConnectionFactoryImpl(this, cxManager);

    Note how the ConnectionManager instance is passed around while creating the ConnectionFactory. The mechanism helps associate the two factories and the ConnectionManager. The ConnectionManager is the ConnectionFactory's interface to the container.

  • The deployment code then binds the ConnectionFactory instance in the JNDI namespace from where it's later looked up by the application component.

    Writing a Client
    Clients needing to interact with the file system will have to use the CCI interface. They cannot use the java.io package to access the file system if they want the transactional support. While the approach may look nonintuitive and tiresome, which in fact it is, it is not as big a pain as you would imagine it to be.

    By this time we would have understood how to acquire a connection to the file system.

  • Once connected we can obtain an interaction from the connection.

    Interaction interaction = conn.createInteraction();

    Interaction maintains an association with the connection from which it was created and executes on the same connection.

  • A connection object also serves as the source for RecordFactory. RecordFactory hands out all types of records. Records are the means of exchanging data, both incoming and outgoing, with the files system.

    RecordFactory rf = cf.getRecordFactory();
    MappedRecord in = rf.createMappedRecord("IN");
    MappedRecord out = rf.createMappedRecord("OUT");

  • Assuming that we wish to create a file, the only parameters we would need to pass are the folder name in which to create the file and the file name. Initialize the records with the input parameters.

    in.put("SOURCE_DIR", "E:\\bea\\weblogic700\\FILES1");
    in.put("SOURCE_FILENAME", "create.txt");

  • Now the only information that needs to be passed is our intention of actually creating a file. This is specified when we instantiate an object of the class InteractionSpecImpl.

    InteractionSpecImpl(InteractionSpecImpl.CREATE), in, out);

  • Handle the exceptions and examine the OUT record for returned values.
  • Close all open resources.

    What Further?
    The proposed draft connector specification makes provisions for inbound communication through a Message Inflow Contract and also includes a Work Management Contract. The inclusion of the two would make it feasible for the adapter to work as a poller.

    The Work Management Contract would allow the adapter to monitor folders for incoming files. The activity can be performed by submitting work to the container. The contract would save the adapter the task of creating its own threads thus allowing the container to exercise better control over its runtime environment.

    The Message Inflow Contract would allow the adapter to trigger action in the event of receiving a file. The situation can be thought of as analogous to a JMS situation, with the adapter instead of an MDB delivering messages by polling on a folder instead of a queue.

    Better concurrency control can also be built into the adapter using the new improved I/O support found in newer Java runtimes, 1.4 onwards.

  • More Stories By Ashish Garg

    Ashish Garg is a Senior Technical Specialist with Infosys Technologies Ltd. He has more than 4 years of experience in J2EE Technologies.

    More Stories By Sandip Mane

    Sandip Mane is a senior technical specialist with Infosys Technologies Ltd. and specializes in WebLogic

    Comments (6) View Comments

    Share your thoughts on this story.

    Add your comment
    You must be signed in to add a comment. Sign-in | Register

    In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.

    Most Recent Comments
    Michael Wolff 06/21/06 09:24:22 AM EDT

    Very interesting article, but it would be great to get the complete source code instead of the snippets. The links mentioned in the other comments does not work, they produce an HTTP 404 error.

    lperon 11/29/05 05:35:09 AM EST

    The source code is not available following indicated link:

    404 Not Found

    JDJ Editorial Staffer 06/02/04 11:04:52 AM EDT

    The source code is here:

    Ernest Muljadi 06/02/04 12:40:15 AM EDT

    Please make the SOURCE code available or post it to my e-mail address

    skr 04/07/04 05:47:58 PM EDT

    Please post the source code.

    Peter Reinhardt 01/08/04 02:25:40 AM EST

    great article. it would have been nice if you provided a fully functional rar and not only the code snippets.


    @ThingsExpo Stories
    Everyone knows that truly innovative companies learn as they go along, pushing boundaries in response to market changes and demands. What's more of a mystery is how to balance innovation on a fresh platform built from scratch with the legacy tech stack, product suite and customers that continue to serve as the business' foundation. In his General Session at 19th Cloud Expo, Michael Chambliss, Head of Engineering at ReadyTalk, will discuss why and how ReadyTalk diverted from healthy revenue an...
    In past @ThingsExpo presentations, Joseph di Paolantonio has explored how various Internet of Things (IoT) and data management and analytics (DMA) solution spaces will come together as sensor analytics ecosystems. This year, in his session at @ThingsExpo, Joseph di Paolantonio from DataArchon, will be adding the numerous Transportation areas, from autonomous vehicles to “Uber for containers.” While IoT data in any one area of Transportation will have a huge impact in that area, combining sensor...
    The Internet of Things (IoT), in all its myriad manifestations, has great potential. Much of that potential comes from the evolving data management and analytic (DMA) technologies and processes that allow us to gain insight from all of the IoT data that can be generated and gathered. This potential may never be met as those data sets are tied to specific industry verticals and single markets, with no clear way to use IoT data and sensor analytics to fulfill the hype being given the IoT today.
    For basic one-to-one voice or video calling solutions, WebRTC has proven to be a very powerful technology. Although WebRTC’s core functionality is to provide secure, real-time p2p media streaming, leveraging native platform features and server-side components brings up new communication capabilities for web and native mobile applications, allowing for advanced multi-user use cases such as video broadcasting, conferencing, and media recording.
    Established in 1998, Calsoft is a leading software product engineering Services Company specializing in Storage, Networking, Virtualization and Cloud business verticals. Calsoft provides End-to-End Product Development, Quality Assurance Sustenance, Solution Engineering and Professional Services expertise to assist customers in achieving their product development and business goals. The company's deep domain knowledge of Storage, Virtualization, Networking and Cloud verticals helps in delivering ...
    SYS-CON Events announced today that Enzu will exhibit at the 19th International Cloud Expo, which will take place on November 1–3, 2016, at the Santa Clara Convention Center in Santa Clara, CA. Enzu’s mission is to be the leading provider of enterprise cloud solutions worldwide. Enzu enables online businesses to use its IT infrastructure to their competitive advantage. By offering a suite of proven hosting and management services, Enzu wants companies to focus on the core of their online busine...
    In the next five to ten years, millions, if not billions of things will become smarter. This smartness goes beyond connected things in our homes like the fridge, thermostat and fancy lighting, and into heavily regulated industries including aerospace, pharmaceutical/medical devices and energy. “Smartness” will embed itself within individual products that are part of our daily lives. We will engage with smart products - learning from them, informing them, and communicating with them. Smart produc...
    November 1–3, 2016, at the Santa Clara Convention Center in Santa Clara, CA. Penta Security is a leading vendor for data security solutions, including its encryption solution, D’Amo. By using FPE technology, D’Amo allows for the implementation of encryption technology to sensitive data fields without modification to schema in the database environment. With businesses having their data become increasingly more complicated in their mission-critical applications (such as ERP, CRM, HRM), continued ...
    OnProcess Technology has announced it will be a featured speaker at @ThingsExpo, taking place November 1 - 3, 2016, in Santa Clara, California. Dan Gettens, OnProcess’ Chief Analytics Officer, will discuss how Internet of Things (IoT) data can be leveraged to predict product failures, improve uptime and slash costly inventory stock. @ThingsExpo is an annual gathering of IoT and cloud developers, practitioners and thought-leaders who exchange ideas and insights on topics ranging from Big Data in...
    SYS-CON Events announced today that SoftNet Solutions will exhibit at the 19th International Cloud Expo, which will take place on November 1–3, 2016, at the Santa Clara Convention Center in Santa Clara, CA. SoftNet Solutions specializes in Enterprise Solutions for Hadoop and Big Data. It offers customers the most open, robust, and value-conscious portfolio of solutions, services, and tools for the shortest route to success with Big Data. The unique differentiator is the ability to architect and ...
    SYS-CON Events announced today that Transparent Cloud Computing (T-Cloud) Consortium will exhibit at the 19th International Cloud Expo®, which will take place on November 1–3, 2016, at the Santa Clara Convention Center in Santa Clara, CA. The Transparent Cloud Computing Consortium (T-Cloud Consortium) will conduct research activities into changes in the computing model as a result of collaboration between "device" and "cloud" and the creation of new value and markets through organic data proces...
    SYS-CON Events announced today that Cloudbric, a leading website security provider, will exhibit at the 19th International Cloud Expo, which will take place on November 1–3, 2016, at the Santa Clara Convention Center in Santa Clara, CA. Cloudbric is an elite full service website protection solution specifically designed for IT novices, entrepreneurs, and small and medium businesses. First launched in 2015, Cloudbric is based on the enterprise level Web Application Firewall by Penta Security Sys...
    SYS-CON Events announced today that Roundee / LinearHub will exhibit at the WebRTC Summit at @ThingsExpo, which will take place on November 1–3, 2016, at the Santa Clara Convention Center in Santa Clara, CA. LinearHub provides Roundee Service, a smart platform for enterprise video conferencing with enhanced features such as automatic recording and transcription service. Slack users can integrate Roundee to their team via Slack’s App Directory, and '/roundee' command lets your video conference ...
    Successful digital transformation requires new organizational competencies and capabilities. Research tells us that the biggest impediment to successful transformation is human; consequently, the biggest enabler is a properly skilled and empowered workforce. In the digital age, new individual and collective competencies are required. In his session at 19th Cloud Expo, Bob Newhouse, CEO and founder of Agilitiv, will draw together recent research and lessons learned from emerging and established ...
    SYS-CON Events announced today that Coalfire will exhibit at the 19th International Cloud Expo, which will take place on November 1–3, 2016, at the Santa Clara Convention Center in Santa Clara, CA. Coalfire is the trusted leader in cybersecurity risk management and compliance services. Coalfire integrates advisory and technical assessments and recommendations to the corporate directors, executives, boards, and IT organizations for global brands and organizations in the technology, cloud, health...
    As ridesharing competitors and enhanced services increase, notable changes are occurring in the transportation model. Despite the cost-effective means and flexibility of ridesharing, both drivers and users will need to be aware of the connected environment and how it will impact the ridesharing experience. In his session at @ThingsExpo, Timothy Evavold, Executive Director Automotive at Covisint, will discuss key challenges and solutions to powering a ride sharing and/or multimodal model in the a...
    In his general session at 19th Cloud Expo, Manish Dixit, VP of Product and Engineering at Dice, will discuss how Dice leverages data insights and tools to help both tech professionals and recruiters better understand how skills relate to each other and which skills are in high demand using interactive visualizations and salary indicator tools to maximize earning potential. Manish Dixit is VP of Product and Engineering at Dice. As the leader of the Product, Engineering and Data Sciences team a...
    DevOps is being widely accepted (if not fully adopted) as essential in enterprise IT. But as Enterprise DevOps gains maturity, expands scope, and increases velocity, the need for data-driven decisions across teams becomes more acute. DevOps teams in any modern business must wrangle the ‘digital exhaust’ from the delivery toolchain, "pervasive" and "cognitive" computing, APIs and services, mobile devices and applications, the Internet of Things, and now even blockchain. In this power panel at @...
    A completely new computing platform is on the horizon. They’re called Microservers by some, ARM Servers by others, and sometimes even ARM-based Servers. No matter what you call them, Microservers will have a huge impact on the data center and on server computing in general. Although few people are familiar with Microservers today, their impact will be felt very soon. This is a new category of computing platform that is available today and is predicted to have triple-digit growth rates for some ...
    SYS-CON Events announced today that Numerex Corp, a leading provider of managed enterprise solutions enabling the Internet of Things (IoT), will exhibit at the 19th International Cloud Expo | @ThingsExpo, which will take place on November 1–3, 2016, at the Santa Clara Convention Center in Santa Clara, CA. Numerex Corp. (NASDAQ:NMRX) is a leading provider of managed enterprise solutions enabling the Internet of Things (IoT). The Company's solutions produce new revenue streams or create operating...