Castor 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 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 1.0:

jndi:	TM looked up in the JNDI ENC
jotm:	JOTM
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: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-conf PUBLIC "-//EXOLAB/Castor JDO Configuration DTD Version 1.0//EN"
                                     "http://castor.org/jdo-conf.dtd">

      <jdo-conf name="default-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>
          <mapping href="mapping.xml"/>
        </database>
        <transaction-demarcation mode="local"/>
      </jdo-conf>
    

Local transaction demarcation (eloborated)

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

      <jdo-conf name="default-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>
          <mapping href="mapping.xml"/>
        </database>
        <transaction-demarcation mode="local">
          <transaction-manager name="local"/>
        </transaction-demarcation>
      </jdo-conf>
    

Global transaction demarcation (JNDI)

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

      <jdo-conf name="default-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>
          <mapping href="mapping.xml"/>
        </database>
        <transaction-demarcation mode="global">
          <transaction-manager name="jndi"/>
        </transaction-demarcation>
      </jdo-conf>
    

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 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-conf PUBLIC "-//EXOLAB/Castor JDO Configuration DTD Version 1.0//EN"
                                   "http://castor.org/jdo-conf.dtd">

      <jdo-conf name="default-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>
          <mapping href="mapping.xml"/>
        </database>
        <transaction-demarcation mode="global">
          <transaction-manager name="jndi">
            <param name="jndiEnc" value="java:comp/env/transaction/TransactionManager"/>
          </transaction-manager>
        </transaction-demarcation>
      </jdo-conf>
    

Configuring supported transaction manager

For every transaction manager that can be used with Castor, its factory needs to be listed in castor.properties file. If you want to use a transaction manager not supported by Castor yet, you will have to provide an implementation of org.castor.transaction.TransactionManagerFactory and add it to the list of supported transaction manager factories in the castor.properties file.

      #
      # List of supported TransactionManagerFactory implementations; please expand
      # this list to add any custom transaction manager fatories.
      #
      org.castor.transactionmanager.Factories=\
      org.castor.transactionmanager.LocalTransactionManagerFactory,\
      org.castor.transactionmanager.JNDIENCTransactionManagerFactory,\
      org.castor.transactionmanager.JOTMTransactionManagerFactory,\
      org.castor.transactionmanager.WebSphereTransactionManagerFactory,\
      org.castor.transactionmanager.WebSphere5TransactionManagerFactory,\
      org.castor.transactionmanager.WebSphere51TransactionManagerFactory
    

In addition it is possible to specify if a transaction manager should be initialized when it is registered at TransactionManagerRegistry or when it is first accessed.

      #
      # Shell the TransactionManager be initialized at registration or lazily when
      # requested for the first time? Defaults to false.
      #
      org.castor.transactionmanager.InitializeAtRegistration=false
    

Version:

$Revision: 6907 $ $Date: 2006-01-05 15:45:58 -0700 (Thu, 05 Jan 2006) $

Author:

Werner Guttmann

Author:

Ralf Joachim