$Author: bastafidli $
$Date: 2006/08/27 07:51:40 $
$Revision: 1.4 $
$RCSfile: implementation_newtxman.html,v $
Open Core supports out of the box several transaction managers: JOTM, J2EE transaction managers for supported J2EE application servers and custom in JVM transaction manager. If the transaction manager you are interested in is not yet supported by Open Core it is a straigh forward process to implement such support. This document describes in detail steps required to add support for a new transaction manager into Open Core.
Open Core is Java based framework and as such it easily
integrates with any project developed in Java assuming it
provides its deliverable in the form of jar files. If the
libraries you have decided to use for your implementation
are freely redistributable, we recommend to make them part of
OpenSubsystems Externals and
place them into
OpenSubsystems/external/[new transaction manager name]
directory. For example
contains JOTM transaction manager libraries, which were tested to work with OpenSubsystems. It is also recommended that you rename all required files so that the filename doesn't contain version number of the particular release. This will make future upgrades easier since only the files will need to be updated and no other references will have to be modified.
Once the directory is created and all files are located inside,
compress this directory into a single package
[new transaction manager name].zip
and commit this package into OpenSubsystems CVS. Do not commit the uncompressed directory into CVS to prevent issues related to maintaining many individual externaly supplied files. Add this directory into .cvsignore file located in OpenSubsystems/external directory and commit this file into CVS.
For more information about adding new libraries read the following article.
The last step when adding new libraries is to modify the build-external.xml build file and create section that will include all the files required by the new transaction manager when Open Core is built and distributed. Use as an example one of already supported transaction managers that have an appropriate section in this build file.
Once the libraries are located, it is important to include them on a classpath so that OpenSubsystems can access them. Since the transaction manager will be required while running your application, you need to include it on your Eclipse runtime classpath. You can follow article describing how to run your application for a step by step instructions.
To integrate the transaction manager into Open Core you will have to write custom code, which will most likely have to use and import classes specific to you transaction manager. You have to include the transaction manager libraries on your project classpath. In Eclipse you can do so by going to Project menu and selecting Properties menu item. In the Project properties dialog select Java Build Path section from the list on the left and then on the Libraries tab you can add your custom libraries using Add JARs or Add External JARs buttons.
Open Core provides support for desktop applications and provide set of shell scripts to make launching such applications easier. It is recommended that you include the required libraries on the classpath set in these scripts to make them available for the application. Modify all files starting with coreclasspath to include the required libraries. For example for Windows you need to modify script coreclasspath.bat
Each supported transaction managers has some behavior that is
different from other transaction managers. This behavior may
include for example how are the transactional resources
associated with the transaction or what is the support for
recovery of failed transactions. This transaction manager
specific behavior is encapsulated in a class that implements
interface. Since Open Core is utilizing transaction managers to manage mainly database transactions, it also requires them to implement also interface
Create new class
directory derived from
class. The base class DatabaseTransactionFactoryImpl provides functionality that is common to most transactions managers integrating with Open Core and it should make your implementation easier. Implement all methods required by the interfaces and the base class. Override any methods from the base class that require different behavior for your transaction manager. For example behavior specific to JOTM transaction manager is implemented in class
OpenSubsystems is by default using oss.properties
as it's main configuration file when running production
applications. Edit this file and add here
properties required by OpenSubsystems to access your
transaction manager. In general only a single property
is required. Before committing this file into CVS make sure that all the newly added properties are commented out unless your transaction manager becomes the default OpenSubsystems transaction manager.
OpenSubsystems is by default using osstest.properties as it's main configuration file when running JUnit tests. Edit this file and add here all properties required by OpenSubsystems to access your transaction manager during tests. In general you just need to copy the changes you made in oss.properties into this file, no other modifications should be necessary.
OpenSubsystems is using each of the osstest[dbidentifier].properties
files for its configuration information when the tests are
run against the specified database. For example configuration
file for HSQLDB is in the
Edit each of these files and add here all properties required by OpenSubsystems to access your transaction manager during tests. In general you just need to copy the changes you made in oss.properties into each file, no other modifications should be necessary.
Open Core comes with about 150 JUnit tests that can be immediately used to test functionality of your new transaction manager since most of them write to a database within transactions managed by a specified transaction manager. Open Core JUnit test suite includes also number of JUnit test cases, which specifically test transactional behaviour of the system such as commits, rollbacks and autocommit behaviour of the database connections. To take advantage of these tests you need to uncomment the changes you made into osstest.properties and then execute the JUnit test suite provided by OpenSubsystems.