OpenSubsystems

Open Core supports out of the box many connection pools: Commons-DBCP, C3P0, Proxool, XAPool and J2EE datasources for supported J2EE application servers. If the connection pool 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 connection pool 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 connection pool name]

directory. For example

OpenSubsystems/external/commons-dbcp

contains Commons-DBCP connection pool 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 connection pool 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 connection pool when Open Core is built and distributed. Use as an example one of already supported connection pools 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 connection pool 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 connection pool into Open Core you will have to write custom code, which will most likely have to use and import classes specific to you connection pool. You have to include the connection pool 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.connectionpool.[ConnectionPoolIdentifier]DatabaseConnectionFactoryImpl

Each supported connection pool has some behavior that is different from other pools. This behavior may include for example how and when it creates connections or how are the connections tracked and closed. This connection pool specific behavior is encapsulated in a class that implements

org.opensubsystems.core.persist.db.DatabaseConnectionFactory

interface. Create new class

org.opensubsystems.core.persist.db.connectionpool.[ConnectionPoolIdentifier]DatabaseConnectionFactoryImpl

in the

\OpenSubsystems\sources\code\java

directory derived from

org.opensubsystems.core.persist.db.connectionpool.PooledDatabaseConnectionFactoryImpl

class. The base class PooledDatabaseConnectionFactoryImpl provides functionality that is common to most connection pools and that should make your implementation easier. Implement all methods required by the interface and the base class. Override any methods from the base class that require different behavior for your connection pool. For example behavior specific to Commons-DBCP connection pool is implemented in class

org.opensubsystems.core.persist.db.connectionpool.DBCPDatabaseConnectionFactoryImpl

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 connection pool. In general only a single property

org.opensubsystems.core.persist.db.DatabaseConnectionFactory=org.opensubsystems.core.persist.db.connectionpool.[ConnectionPoolIdentifier]DatabaseConnectionFactoryImpl

is required. Before committing this file into CVS make sure that all the newly added properties are commented out unless your connection pool becomes the default OpenSubsystems connection pool.

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 connection pool 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 connection pool 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

org.opensubsystems.core.persist.db.connectionpool.[ConnectionPoolIdentifier]DatabaseConnectionFactoryTest

Open Core comes with about 150 JUnit tests that can be immediately used to test functionality of your new connection pool since most of them write to a database using connection obtained from a connection pool. Open Core JUnit test suite includes also number of JUnit test cases, which specifically test each and every one of the connection pools. To take advantage of these tests you need to create class

org.opensubsystems.core.persist.db.connectionpool.[ConnectionPoolIdentifier]DatabaseConnectionFactoryTest

in the

\OpenSubsystems\sources\tests\java

directory. This class must be derived from the

org.opensubsystems.core.persist.db.connectionpool.PooledDatabaseConnectionFactoryImplBaseTest

class and implement all the unimplemented methods. It may also need to override some already defined methods to provide connection pool specific implementation. Use as an example one of the existing classes for other supported connection pools. For example JUnit test support for Commons-DBCP connection pool is implemented in class

org.opensubsystems.core.persist.db.connectionpool.DBCPDatabaseConnectionFactoryTest

org.opensubsystems.core.persist.db.connectionpool.ConnectionPoolTests

The last step is to ensure that the tests for your connection pool are also executed when one of the test suites that is supposed to test connection pool functionality is run. Modify file

org.opensubsystems.core.persist.db.connectionpool.ConnectionPoolTests

and in the method addGenericTests include line

suite.addTestSuite([ConnectionPoolIdentifier]DatabaseConnectionFactoryTestInternal.class);