Overview

OpenJMS may be configured to use a JDBC 2.0 compliant database to support persistent messages.

The following databases have been tested:

Database Version Web Site
Oracle8i 8.1.7 http://www.oracle.com
Sybase ASE 12.0 http://www.sybase.com
MySQL 3.23.39 http://www.mysql.com
HSQLDB 1.6.1 http://hsqldb.sourceforge.net

To following must be done to configure OpenJMS and the database:

  1. Add the JDBC driver to the classpath
  2. Edit the OpenJMS configuration file
  3. Create the OpenJMS tables in the database

Adding the JDBC driver to the CLASSPATH

To add the JDBC driver to the class path on Windows, edit the %OPENJMS_HOME%\bin\setenv.bat batch file, and add the JDBC driver to the CLASSPATH:

rem Configures the JDBC driver
set CLASSPATH=<insert path to JDBC driver here>
        

To add the JDBC dri ver to the class path on Unix, edit the $OPENJMS_HOME/bin/setenv.sh script, and add the JDBC driver to the CLASSPATH:

# Configures the JDBC driver
CLASSPATH=<insert path to JDBC driver here>
        

Editing the OpenJMS configuration file

The JDBC driver connection properties need to be added to the OpenJMS configuration file, $OPENJMS_HOME/config/openjms.xml , e.g:


  <DatabaseConfiguration>
    <RdbmsDatabaseConfiguration
      driver="oracle.jdbc.driver.OracleDriver"
      url="jdbc:oracle:oci8:@myhost" 
      user="openjms" 
      password="openjms" />
  </DatabaseConfiguration>

        

Creating the OpenJMS tables

The dbtool application may be used to create, drop, and recreate the OpenJMS database tables.

To create the tables on Windows, open up a command prompt and type:

cd %OPENJMS_HOME%\bin
dbtool.bat -create -config %OPENJMS_HOME%\config\openjms.xml
        

On Unix:

cd $OPENJMS_HOME/bin
dbtool.sh -create -config $OPENJMS_HOME/config/openjms.xml
        

What if dbtool doesn't work?

The dbtool application may not support all available JDBC drivers, due to buggy JDBC implementations. In this case, the tables must be manually created. The OpenJMS distribution ships with SQL scripts for most popular databases. These scripts are located in the $OPENJMS_HOME/config/db directory and are named in the form of create_ db .sql (e.g create_oracle.sql, create_mysql.sql)

For example, to manually create the tables in an Oracle database:

sqlplus user/password @create_oracle.sql
          

Connection pooling

OpenJMS uses a pool of JDBC connections, for performance reasons. This can be configured via the < RdbmsDatabaseConfiguration > element. E.g.:

    <RdbmsDatabaseConfiguration
      driver="org.gjt.mm.mysql.Driver" 
      url="jdbc:mysql://localhost/openjms"
      user="openjms" 
      password="openjms"
      maxActive="10"
      maxIdle="5"
      evictionInterval="3600"
      testQuery="select current_date"/>
         

The above specifies to use MySQL as the JDBC provider, with the connection pool configured as follows:

  • maxActive specifies to use up to 10 connections
  • maxIdle specifies to allow up to 5 connections to sit idle in the pool.
  • evictionInterval specifies to run testQuery every 3600 seconds to check if idle connections are valid.
  • testQuery is an SQL query used to validate connections before OpenJMS tries to use them. This is useful in the case of MySQL, which forces closure of connections that have been idle for too long.

See Also

The following references provide detailed descriptions of the configuration elements related to database configuration: