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.
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"/>
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>
<!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>
<!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>
<!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";
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>
For every transaction manager that can be used with Castor its factory need 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 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