OpenSubsystems

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.

Adding New Libraries

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

OpenSubsystems/external/jotm

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.

Setting up Classpath

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

Implementation

org.opensubsystems.core.persist.db.transaction.[TransactionManagerIdentifier]TransactionFactoryImpl

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

org.opensubsystems.core.util.TransactionFactory

interface. Since Open Core is utilizing transaction managers to manage mainly database transactions, it also requires them to implement also interface

org.opensubsystems.core.persist.db.DatabaseTransactionFactory

Create new class

org.opensubsystems.core.persist.db.transaction.[TransactionManagerIdentifier]TransactionFactoryImpl

in the

\OpenSubsystems\sources\code\java

directory derived from

org.opensubsystems.core.persist.db.DatabaseTransactionFactoryImpl

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

org.opensubsystems.core.persist.db.transaction.JOTMTransactionFactoryImpl

Configuration

oss.properties

OpenSubsystems is by default using oss.properties as it's main configuration file when running production applications. Edit this file and add here all properties required by OpenSubsystems to access your transaction manager. In general only a single property

org.opensubsystems.core.util.TransactionFactory=org.opensubsystems.core.persist.db.transaction.[TransactionManagerIdentifier]TransactionFactoryImpl

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.

osstest.properties

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.

osstest[dbidentifier].properties

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

\OpenSubsystems\sources\config\osstesthsqldb.properties

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.

JUnit Tests

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.