Overview

OpenJMS requires a JDBC 2.0 compliant database.

As of release 0.7.7, OpenJMS is distributed pre-configured with Derby, a pure Java database. This is provided to demonstrate OpenJMS' features "out-of-the-box", and may change in future.

Supported databases

The following databases are known to work with OpenJMS:

JDBC
DatabaseVersionWeb Site
Oracle9i 9 http://www.oracle.com
Sybase ASE12.0 http://www.sybase.com
MySQL 4.0.12 http://www.mysql.com
Derby 10.0.2.1 http://incubator.apache.org/derby

Configuration

To configure OpenJMS to use a JDBC database:

  1. Add the JDBC jars to the CLASSPATH
  2. Configure openjms.xml
  3. Create the OpenJMS tables in the database

Add the JDBC jars to the CLASSPATH

Windows

Edit the %OPENJMS_HOME%\bin\setenv.bat batch file: 

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

Unix

Edit the $OPENJMS_HOME/bin/setenv.sh script: 

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

Configure openjms.xml

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>

Create the OpenJMS tables

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

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

Windows 

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

Unix 

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

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/db/sql 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="com.mysql.jdbc.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: