Package org.exolab.castor.jdo.transactionmanager

Implementation of the Castor JDO transaction manager factory.

See:
          Description

Interface Summary
TransactionManagerFactory A factory for properly acquiring javax.transaction.TransactionManager from J2EE containers.
 

Class Summary
TransactionManagerFactoryRegistry Registry for TransactionManagerFactory implementations obtained from the Castor properties file and used by the JDO mapping configuration file.
TransactionManagerRegistry Registry for TransactionManager implementations obtained by the configuartion they are specified in.
 

Exception Summary
TransactionManagerAcquireException An exception encapsulating an exception that occurs during the operation to acquire a javax.transaction.TransactionManager.
 

Package org.exolab.castor.jdo.transactionmanager Description

Implementation of the Castor JDO transaction manager factory.

With the release 0.9.6 of Castor, a new way of configuring transaction demarcation has been added. This configuration is now part of the main JDO configuration file and mandates the specification of the transaction demarcation used within your application.

As part of this configuration file, the user has to specify which transaction demarcation to use. This can either be 'local' or 'global', and is supplied by the use of a <transaction-demarcation> element.

Local mode

When using Castor JDO stand-alone and you want Castor to control transaction demarcation ('local' mode), please use this element as follows:

       <transaction-demarcation mode="local" />
     

Global mode

When running inside a J2EE application server, and you want to use container managed transactions ('global' transactions), please make sure you use this element as follows:

       <transaction-demarcation mode="global">
          <transaction-manager name="jndi" />
       </transaction-demarcation>
    

In this mode, the XML element <transaction-manager> specifies the transaction manager that is used by your application server/web container to control these transactions. The following transaction manager (names) are supported in Castor at the time of the release of Castor 0.9.6:

jndi:TM looked up in the JNDI ENC
websphere:WebSphere 4 and previous releases.
websphere5:WebSphere 5
websphere51:WebSphere 5.1

In addition to specifying the transaction manager name, it is possible to pass arbitrary name/value pairs to the transaction manager instance.

Note:It should also be noted that "database pooling" must be enabled for the JDO instance when using the WAS v4 and v5 transaction managers, or the JDO "database" instance will fall outside the current transaction/thread, resulting in the error message "No transaction in progress for the current thread". For example:

       JDO myJdo = new JDO();
       myJdo.setDatabasePooling( true );
        

Note:At the moment, only the JNDI transaction manager factory supports such an attribute. In this context, the jndiEnc attribute can be used to specify what JNDI ENC to use to lookup the transaction manager as shown below:

       <transaction-demarcation mode="global">
          <transaction-manager name="jndi">
            <param name="jndiEnc" value="java:comp/env/TransactionManager" />
          </transaction-manager>
       </transaction-demarcation>
    

Sample configurations

Local transaction demarcation (minimal)

        <!DOCTYPE jdo-config PUBLIC "-//EXOLAB/Castor JDO Configuration DTD Version 1.0//EN"
                           "http://castor.exolab.org/jdo-conf.dtd">

        <jdo-config>
        <database name="test" engine="mysql" >
                <driver url="jdbc:mysql://localhost/castor_foreign" class-name="com.mysql.jdbc.Driver" >
                        <param name="user" value="..." />
                        <param name="password" value="..." />
                </driver>
        </database>
        <transaction-demarcation mode="local" />
        <mapping href="mapping.xml" />
        </jdo-config>
    

Local transaction demarcation (eloborated)

    <!DOCTYPE jdo-config PUBLIC "-//EXOLAB/Castor JDO Configuration DTD Version 1.0//EN"
                           "http://castor.exolab.org/jdo-conf.dtd">

    <jdo-config>
        <database name="test" engine="mysql" >
            <driver url="jdbc:mysql://localhost/castor_foreign" class-name="com.mysql.jdbc.Driver" >
                <param name="user" value="..." />
                <param name="password" value="..." />
            </driver>
        </database>
        <transaction-demarcation mode="local">
            <transaction-manager name="local">
        </transaction-demarcation>
        <mapping href="mapping.xml" />
    </jdo-config>
    

Global transaction demarcation (JNDI)

    <!DOCTYPE jdo-config PUBLIC "-//EXOLAB/Castor JDO Configuration DTD Version 1.0//EN"
                           "http://castor.exolab.org/jdo-conf.dtd">

    <jdo-config>
        <database name="test" engine="mysql" >
            <driver url="jdbc:mysql://localhost/castor_foreign" class-name="com.mysql.jdbc.Driver" >
                <param name="user" value="..." />
                <param name="password" value="..." />
            </driver>
        </database>
        <transaction-demarcation mode="global">
            <transaction-manager name="jndi"/>
        </transaction-demarcation>
        <mapping href="mapping.xml" />
    </jdo-config>
    

Please note that in this sample, Castor will try to load the transaction manager from the default location "java:comp/transaction/TransactionManager";

Global transaction demarcation (JNDI, with parameters)

In this sample, we want to indicate that the javax.jta.TransactionManager instance is bound to the JNDI ENC 'java:comp/env/transaction/TransactionManager' rather than the default value as shown in the previous sample.

    <!DOCTYPE jdo-config PUBLIC "-//EXOLAB/Castor JDO Configuration DTD Version 1.0//EN"
                           "http://castor.exolab.org/jdo-conf.dtd">

    <jdo-config>
        <database name="test" engine="mysql" >
            <driver url="jdbc:mysql://localhost/castor_foreign" class-name="com.mysql.jdbc.Driver" >
                <param name="user" value="..." />
                <param name="password" value="..." />
            </driver>
        </database>
        <transaction-demarcation mode="global">
            <transaction-manager name="jndi">
                <param name="jndiEnc" value="java:comp/env/transaction/TransactionManager" />
            </transaction-manager>
        </transaction-demarcation>
        <mapping href="mapping.xml" />
    </jdo-config>
    
Version:
$Revision: 1.3 $ $Date: 2005/03/30 16:46:42 $
Author:
Werner Guttmann



Intalio Inc. (C) 1999-2004. All rights reserved http://www.intalio.com