|  |  |  | License Codehaus OpenEJB OpenJMS OpenORB Tyrex

Old releases
General
Release 1.3
Release 1.3rc1
Release 1.2

Main
Home
About
Features
Download
Dependencies
Reference guide
Publications
JavaDoc
Maven 2 support
Maven 2 archetypes
DTD & Schemas
Recent HTML changes
News Archive
RSS news feed
Project Wiki

Development/Support
Mailing Lists
SVN/JIRA
Contributing
Support
Continuous builds
Prof. services

Related projects
Spring ORM support
Spring XML factories
WS frameworks

XML
XML

XML Code Generator
XML Code Generator

JDO
Introduction
First steps
Using JDO
JDO Config
Types
JDO Mapping
JDO FAQ
JDO Examples
JDO HOW-TOs
Tips & Tricks
Other Features
JDO sample JAR

Tools
Schema generator

Advanced JDO
Caching
OQL
Trans. & Locks
Design
KeyGen
Long Trans.
Nested Attrs.
Pooling Examples
LOBs
Best practice

DDL Generator
Using DDL Generator
Properties
Ant task
Type Mapping

More
The Examples
3rd Party Tools
JDO Tests
XML Tests
Configuration

About
License
User stories
Contributors
Marketplace
Status, Todo
Changelog
Library
Contact
Project Name

## Castor JDO Long Transactions Support

Introduction
Bounded dirty checking
Long transactions that do not depend on cache

## Introduction

The usual Castor transactions are called here short transactions: an object is read, modified and written within the bounds of one transaction. Long transactions consist of two Castor transactions: an object is read in the first and written in the second. Between them the object is sent "outwards" and modified there. For example, the object may be send to a client application and dispayed to a user, or it may be sent to a servlet engine and is displayed on a web page. After that the modified object returns back and is written to the database in the second transaction. At this point the object is usually not the same physical instance as one that was read in the first transaction. The example code for writing the object in the second Castor transaction follows:

        // a customer go to a webpage to review her personal information.
        // The servlet then call this server side function: getCustomerInfo
        public CustomerInfo getCustomerInfo( Integer customNum ) {

                 // in most case, users simply review information and
                 // make no change. Even if they make changes, it often
                 // takes time for them to decide. We don't want to
                 // lock the database row, so commit right after we load.
             db.begin();
             CustomerInfo info = (CustomerInfo)
                db.load( CustomerInfo.class, customNum );

                     // we also want to keep track of customers patterns
                     // well...it helps us provide better service.
             info.setLastVisit( today );
             db.commit();
             return info;
        }

            // Three days passed, the indecisive customer finally agrees to
            // marry Joe. She changes her last name in the webpage and
            // clicked the "Submit" button on the webpage.

            // The servlet then calls updateCustomerInfo to update the
            // last name for the indecisive customer.
        public void updateCustomerInfo( CustomerInfo info ) {
            db.begin();
            db.update(info);
            db.commit();
        }

Note, that it is natural to read the object in the first transaction in the read-only mode.

Since the time interval between the first and the second transaction is relatively big, it is desirable to perform dirty checking, i.e. to check that the object has not been modified in the database during the long transaction. For that the object must hold a timestamp: it is set by Castor during the first Castor transaction and is checked during the second one. In order to enable the dirty checking for long transactions, the object should implement the interface org.exolab.castor.jdo.TimeStampable having two methods:

    long jdoGetTimeStamp()

and

    void jdoSetTimeStamp(long timeStamp)

## Bounded dirty checking

The advantage of the bounded dirty checking is that it doesn't require any changes to the database schema. It uses the Castor cache to store object timestamps. The disadvantage of this algorithm is that it is bounded by a lifetime of the cached copy of the object. After the cached copy has been purged, db.update() causes ObjectModifiedException.

Thus, parameters of the cache define dirty checking capabilities. The cache-type attribute is part of the <class> element in the XML mapping. Consider the existing cache types:

- | none - the bounded dirty checking is impossible
- | count-limited - the count limit for the cache is a count limit for the objects of this class that can participate in long and short transactions simultaneously.
- | time-limited - the time limit for the cache is a time limit for the long transaction.
- | unlimited - the bounded dirty checking gives correct results while the cache exists, i.e. until the crash of the server.

## Long transactions that do not depend on cache

For long transactions (detached objects) it was required that the entity has been kept in cache from being loaded until its update. If the entity was expired from cache before the update an ObjectModifiedException had been thrown. While this is no problem if all entities of an application can be kept in cache all the time, it is one for large scale applications with millions of entities.

With release 1.3 we have changed the handling of timestamps. While it is still possible to rely on cache only it is now also possible to persist the timestamp together with the other properties of the entity. Doing so will ensure that the timestamp do not change even if the entity got expired from cache from being loaded until it gets updated. If this happens the entity gets reloaded during update which also loads the previous timestamp. Having said that it still is possible that an ObjectModifiedException is thrown when another user has changed the same entity in the meantime.

See an example entity and its mapping below:

    public class Entity implements TimeStampable {
        private Integer _id;
        private String _name;
        private long _timeStamp;

        public Integer getId() { return _id; }
        public void setId(final Integer id) { _id = id; }

        public String getName() { return _name; }
        public void setName(final String name) { _name = name; }

        public long getTimeStamp() { return _timeStamp; }
        public void setTimeStamp(final long timeStamp) {
            _timeStamp = timeStamp;
        }

        public long jdoGetTimeStamp() { return _timeStamp; }
        public void jdoSetTimeStamp(final long timestamp) {
            _timeStamp = timestamp;
        }
    }

    <class name="Entity">
        <cache-type type="time-limited" capacity="300"/>
        <map-to table="entity"/>
        <field name="id" type="integer" identity="true">
            <sql name="id" type="integer"/>
        </field>
        <field name="name" type="string">
            <sql name="name" type="char"/>
        </field>
        <field name="timeStamp" type="long">
            <sql name="timestamp" type="numeric" />
        </field>
    </class>

<notice> Copyright © 1999-2005 ExoLab Group, Intalio Inc., and Contributors. All rights reserved. </notice>
<notice> Java, EJB, JDBC, JNDI, JTA, Sun, Sun Microsystems are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and in other countries. XML, XML Schema, XSLT and related standards are trademarks or registered trademarks of MIT, INRIA, Keio or others, and a product of the World Wide Web Consortium. All other product names mentioned herein are trademarks of their respective owners. </notice>