Configuring JDBC Resource Adapters

The content of this guide is the following:

  1. Target Audience
  2. Configuring Resource Adapters
  3. Using CMP2.0/JORM
  4. Tracing SQL Requests through P6Spy
  5. Migration from dbm service to the JDBC RA

Target Audience

The target audience for this guide is the bean or application deployer. It describes how the JDBC Resource Adapters should be configured to connect the application to databases.

Configuring Resource Adapters

For both container-managed or bean-managed persistence, the JDBC Resource Adapter(RA) makes use of relational storage systems through the JDBC interface. JDBC connections are obtained from a JDBC RA. The JDBC RA implements the J2EE Connector Specification using the DataSource interface as defined in the JDBC 2.0 standard extensions. An RA is configured to identify a database and a means to access it via a JDBC driver. Multiple JDBC RAs can be deployed either via the jonas.properties file or included in the autoload directory of the resource service. For complete information about RAs in JOnAS, refer to Configuring Resource Adapters. The following section explains how JDBC RARs can be defined and configured in the JOnAS server.

To support distributed transactions, the JDBC RA requires the use of at least a JDBC2-XA-compliant driver. Such drivers implementing the XADataSource interface are not yet available for all relational databases. The JDBC RA provides a generic driver-wrapper that emulates the XADataSource interface on a regular JDBC driver. It is important to note that this driver-wrapper does not ensure a real two-phase commit for distributed database transactions.

The generic JDBC RAs of JOnAS provide implementations of the DriverManager, DataSource, PooledConnection, and XAConnection interfaces. These can be configured using a JDBC-compliant driver for some relational database management server products, such as Oracle, PostGres, or MySQL.

The remainder of this section, which describes how to define and configure JDBC RAs, is specific to JOnAS. However, the way to use these JDBC RAs in the Application Component methods is standard, i.e. via the resource manager connection factory references (refer to the example in the section "Writing Database Access Operations" of the Developing Entity Bean Guide).

An RAR file must be configured and deployed (e.g., Oracle1.rar for an Oracle RAR and MySQL1.rar for a MySQL RAR, as delivered with the platform).

To define a Resource "Oracle1" in the jonas.properties file, add its name "Oracle1" (name of the RAR file) to the line jonas.service.resource.services or just include it in the autoload directory. For more information about deploying an RAR, refer to Configuring Resource Adapters.

jonas.service.resource.services Oracle1,MySQL1,PostgreSQL1

The jonas-ra.xml file that defines a DataSource should contain the following information:

jndiname JNDI name of the RAR 
URL  The JDBC database URL: jdbc:<database_vendor_subprotocol>:...
dsClass Name of the class implementing the JDBC driver
user  Database user name 
password  Database user password 

An RAR for Oracle configured as jdbc_1 in JNDI and using the Oracle thin DriverManger JDBC driver, should be described in a file called Oracle1_DM.rar, with the following properties configured in the jonas-ra.xml file:

          <jndiname>jdbc_1</jndiname>
          <rarlink>JOnASJDBC_DM</rarlink>
          .
          .
          <jonas-config-property>
            <jonas-config-property-name>user</jonas-config-property-name>
            <jonas-config-property-value>scott</jonas-config-property-value>
          </jonas-config-property>
          <jonas-config-property>
            <jonas-config-property-name>password</jonas-config-property-name>
            <jonas-config-property-value>tiger</jonas-config-property-value>
          </jonas-config-property>
          <jonas-config-property>
            <jonas-config-property-name>loginTimeout</jonas-config-property-name>
            <jonas-config-property-value></jonas-config-property-value>
          </jonas-config-property>
          <jonas-config-property>
            <jonas-config-property-name>URL</jonas-config-property-name>
            <jonas-config-property-value>jdbc:oracle:thin:@malte:1521:ORA1</jonas-config-property-value>
          </jonas-config-property>
          <jonas-config-property>
            <jonas-config-property-name>dsClass</jonas-config-property-name>
            <jonas-config-property-value>oracle.jdbc.driver.OracleDriver</jonas-config-property-value>
          </jonas-config-property>
          <jonas-config-property>
            <jonas-config-property-name>mapperName</jonas-config-property-name>
            <jonas-config-property-value>rdb.oracle</jonas-config-property-value>
          </jonas-config-property>
    

In this example, "malte" is the hostname of the server running the Oracle DBMS, 1521 is the SQL*Net V2 port number on this server, and ORA1 is the ORACLE_SID.

This example makes use of the Oracle "Thin" JDBC driver. For an application server running on the same host as the Oracle DBMS, use the Oracle OCI JDBC driver; in this case, the URL to use is jdbc:oracle:oci7: or jdbc:oracle:oci8:, depending on the Oracle release. Oracle JDBC drivers can be downloaded from the Oracle Web site.

To create a MySQL RAR configured as jdbc_2 in JNDI, it should be described in a file called MySQL2_DM.rar, with the following properties configured in the jonas-ra.xml file:

          <jndiname>jdbc_2</jndiname>
          <rarlink>JOnASJDBC_DM</rarlink>
          .
          .
          <jonas-config-property>
            <jonas-config-property-name>user</jonas-config-property-name>
            <jonas-config-property-value></jonas-config-property-value>
          </jonas-config-property>
          <jonas-config-property>
            <jonas-config-property-name>password</jonas-config-property-name>
            <jonas-config-property-value></jonas-config-property-value>
          </jonas-config-property>
          <jonas-config-property>
            <jonas-config-property-name>loginTimeout</jonas-config-property-name>
            <jonas-config-property-value></jonas-config-property-value>
          </jonas-config-property>
          <jonas-config-property>
            <jonas-config-property-name>URL</jonas-config-property-name>
            <jonas-config-property-value>jdbc:mysql://malte/db_jonas</jonas-config-property-value>
          </jonas-config-property>
          <jonas-config-property>
            <jonas-config-property-name>dsClass</jonas-config-property-name>
            <jonas-config-property-value>org.gjt.mm.mysql.Driver</jonas-config-property-value>
          </jonas-config-property>
          <jonas-config-property>
            <jonas-config-property-name>mapperName</jonas-config-property-name>
            <jonas-config-property-value>rdb.mysql</jonas-config-property-value>
          </jonas-config-property>
    

To create a PostGreSQL RAR configured as jdbc_3 in JNDI, it should be described in a file called PostGreSQL3_DM.rar, with the following properties configured in the jonas-ra.xml file:

          <jndiname>jdbc_3</jndiname>
          <rarlink>JOnASJDBC_DM</rarlink>
          .
          .
          <jonas-config-property>
            <jonas-config-property-name>user</jonas-config-property-name>
            <jonas-config-property-value>jonas</jonas-config-property-value>
          </jonas-config-property>
          <jonas-config-property>
            <jonas-config-property-name>password</jonas-config-property-name>
            <jonas-config-property-value>jonas</jonas-config-property-value>
          </jonas-config-property>
          <jonas-config-property>
            <jonas-config-property-name>loginTimeout</jonas-config-property-name>
            <jonas-config-property-value></jonas-config-property-value>
          </jonas-config-property>
          <jonas-config-property>
            <jonas-config-property-name>URL</jonas-config-property-name>
            <jonas-config-property-value>jdbc:postgresql:/malte:5432/db_jonas</jonas-config-property-value>
          </jonas-config-property>
          <jonas-config-property>
            <jonas-config-property-name>dsClass</jonas-config-property-name>
            <jonas-config-property-value>org.postgresql.Driver</jonas-config-property-value>
          </jonas-config-property>
          <jonas-config-property>
            <jonas-config-property-name>mapperName</jonas-config-property-name>
            <jonas-config-property-value>rdb.mpostgres</jonas-config-property-value>
          </jonas-config-property>
    

The database user and password can be handled in one of two ways: 1) put it in the jonas-ra.xml file in the RAR file and have the Application Components use the getConnection() method, or 2) not have it in the RAR file and have the Application Component use the getConnection(String username, String password) method.

Using CMP2.0/JORM

For implementing the EJB 2.0 persistence (CMP2.0), JOnAS relies on the JORM framework. JORM must adapt its object-relational mapping to the underlying database, and makes use of adapters called "mappers" for this purpose. Thus, for each type of database (and more precisely for each JDBC driver), the corresponding mapper must be specified in the jonas-ra.xml file of the deployed RAR. The mapperName element is provided for this purpose.

property name description possible values
mapperName JORM database mapper
  • rdb: generic mapper (JDBC standard driver ...)
  • rdb.postgres: mapper for PostgreSQL
  • rdb.oracle8: mapper for Oracle 8 and lesser versions
  • rdb.oracle: mapper for Oracle 9
  • rdb.mckoi: mapper for McKoi Db
  • rdb.mysql: mapper for MySQL
  • rdb.sqlserver: mapper for MS SQL Server
  • Refer to JORM documentation for a complete updated list.

ConnectionManager Configuration

Each RAR uses a connection manager that can be configured via the additional properties described in the following table. The Postgres1.jonas-ra.xml file provides an example of the settings. These settings all have default values and they are not required.

pool-params elements
property name description default value
pool-init Initial number of connections 0
pool-min Minimum number of connections 0
pool-max Maximum number of connections -1 (unlimited)
pool-max-age Number of milliseconds to keep the connection 0 (unlimited)
pstmt-max Maximum number of PreparedStatements cached per connection 10

jdbc-conn-params elements
property name description default value
jdbc-check-level JDBC connection checking level 0 (no check)
jdbc-test-statement test statement

jdbc-test-statement is not used when jdbc-check-level is equal to 0 or 1.

Tracing SQL Requests through P6Spy

The P6Spy tool is integrated into JOnAS and it provides an easy way to trace the SQL requests sent to the database.

To enable this tracing feature, perform the following configuration steps:

Example:

jonas-ra.xml file content:

        <jonas-resource>
          <jndiname>jdbc_3</jndiname>
          <rarlink>JOnASJDBC_DM</rarlink>
          <native-lib></native-lib>
          <log-enabled>true</log-enabled>
          <log-topic>org.objectweb.jonas.jdbc.DMPostgres</log-topic>
          <pool-params>
            <pool-init>0</pool-init>
            <pool-min>0</pool-min>
            <pool-max>100</pool-max>
            <pool-max-age>0</pool-max-age>
            <pstmt-max>10</pstmt-max>
          </pool-params>
          <jdbc-conn-params>
            <jdbc-check-level>0</jdbc-check-level>
            <jdbc-test-statement></jdbc-test-statement>
          </jdbc-conn-params>
          <jonas-config-property>
            <jonas-config-property-name>user</jonas-config-property-name>
            <jonas-config-property-value>jonas</jonas-config-property-value>
          </jonas-config-property>
          <jonas-config-property>
            <jonas-config-property-name>password</jonas-config-property-name>
            <jonas-config-property-value>jonas</jonas-config-property-value>
          </jonas-config-property>
          <jonas-config-property>
            <jonas-config-property-name>loginTimeout</jonas-config-property-name>
            <jonas-config-property-value></jonas-config-property-value>
          </jonas-config-property>
          <jonas-config-property>
            <jonas-config-property-name>URL</jonas-config-property-name>
            <jonas-config-property-value>jdbc:postgresql://your_host:port/your_db</jonas-config-property-value>
          </jonas-config-property>
          <jonas-config-property>
            <jonas-config-property-name>dsClass</jonas-config-property-name>
            <jonas-config-property-value>com.p6spy.engine.spy.P6SpyDriver</jonas-config-property-value>
          </jonas-config-property>
          <jonas-config-property>
            <jonas-config-property-name>mapperName</jonas-config-property-name>
            <jonas-config-property-value>rdb.postgres</jonas-config-property-value>
          </jonas-config-property>
          <jonas-config-property>
            <jonas-config-property-name>logTopic</jonas-config-property-name>
            <jonas-config-property-value>org.objectweb.jonas.jdbc.DMPostgres</jonas-config-property-value>
          </jonas-config-property>
        </jonas-resource>
    

In $JONAS_BASE/conf/spy.properties file:

   realdriver=org.postgresql.Driver
    

In $JONAS_BASE/conf/trace.properties:

   logger.org.objectweb.jonas.jdbc.sql.level  DEBUG
    

Migration from dbm service to the JDBC RA

The migration of a Database.properties file to a similar Resource Adapter can be accomplished through the execution of the following RAConfig tool command. Refer to RAConfig description for a complete description.

   RAConfig -dm -p MySQL $JONAS_ROOT/rars/autoload/JOnAS_jdbcDM MySQL

This command will create a MySQL.rar file based on the MySQL.properties file, as specified by the -p parameter. It will also include the <rarlink> to the JOnAS_jdbcDM.rar, as specified by the -dm parameter.

The jonas-ra.xml created by the previous command can be updated further, if desired. Once the additional properties have been configured, update the MySQL.rar file using the following command:

   RAConfig -u jonas-ra.xml MySQL