$Author: bastafidli $
$Date: 2006/08/27 07:51:38 $
$Revision: 1.5 $
$RCSfile: implementation_newcpool.html,v $
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.
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
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.
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
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
interface. Create new class
directory derived from
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
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
connection pool. 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 connection pool becomes the default OpenSubsystems connection pool.
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.
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 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.
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
directory. This class must be derived from the
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
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.
and in the method addGenericTests include line