40.1. Configuring Resource Adapters

For both container-managed or bean-managed persistence, the JDBC Resource Adapter (JDBC 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 Chapter 41 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 always 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, PostgreSQL, 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; that is, via the resource manager connection factory references (refer to the example in Section 8.6 Writing Database Access Operations (Bean-Managed Persistence) in Chapter 8 Developing Entity Beans).

An RAR file must be configured and deployed (for example, 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 Chapter 41 Configuring Resource Adapters.

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

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

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, you can 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 http://otn.oracle.com/software/tech/java/sqlj_jdbc/content.html.

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:

• Put it in the jonas-ra.xml file in the RAR file and have the Application Components use the getConnection() method.

• Not have it in the RAR file and have the Application Component use the getConnection(String username, String password) method.