Configuring JDBC DataSources

Target Audience and Content

The target audience for this guide is the bean or application deployer. It describes how to configure the Datasources for connecting the application to databases.

The content of this guide is the following:

  1. Target Audience and Content
  2. Configuring DataSources
  3. CMP2.0/JORM
  4. ConnectionManager Configuration
  5. Tracing SQL Requests through P6Spy

Configuring DataSources

For both container-managed or bean-managed persistence, JOnAS makes use of relational storage systems through the JDBC interface. JDBC connections are obtained from an object, the DataSource, provided at the application server level. The DataSource interface is defined in the JDBC 2.0 standard extensions. A DataSource object identifies a database and a means to access it via JDBC (a JDBC driver). An application server may request access to several databases and thus provide the corresponding DataSource objects. Available DataSource objects can be added on the platform; they must be defined in the jonas.properties file. This section explains how DataSource objects can be defined and configured in the JOnAS server.

To support distributed transactions, JOnAS requires the use of a JDBC2-XA-compliant driver. Such drivers that implement the XADataSource interface are not yet available for all relational databases. JOnAS 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.

JOnAS's generic driver-wrapper provides an implementation of the DataSource interface that allows DataSource objects to be defined using a JDBC1-compliant driver for some relational database management server products, such as Oracle, PostGres, or InstantDB.

Neither the EJB specification nor the J2EE specification describe how to define DataSource objects so that they are available to a J2EE platform. Therefore, this document, which describes how to define and configure DataSource objects, is specific to JOnAS. However, the way to use these DataSource objects in the Application Component methods is standard, that is, by using the resource manager connection factory references (refer to the example in the section "Writing database access operations" of the Developing Entity Bean Guide).

A DataSource object should be defined in a file called <DataSource name>.properties (for example Oracle1.properties for an Oracle DataSource and InstantDB1.properties for an InstantDB DataSource, as delivered with the platform).

In the jonas.properties file, to define a DataSource "Oracle1." add the name "Oracle1" (name of the properties file) to the line jonas.service.dbm.datasources, as follows:

jonas.service.dbm.datasources Oracle1,InstantDB1,PostgreSQL

The property file defining a DataSource should contain the following information:

datasource.name  JNDI name of the DataSource 
datasource.url  The JDBC database URL : jdbc:<database_vendor_subprotocol>:...
datasource.classname Name of the class implementing the JDBC driver
datasource.username  Database user name 
datasource.password  Database user password 

A DataSource object for Oracle (for example, Oracle1), named jdbc_1 in JNDI, and using the Oracle thin JDBC driver, would be described in a file called Oracle1.properties, as in the following example:

datasource.name       jdbc_1
datasource.url        jdbc:oracle:thin:@malte:1521:ORA1
datasource.classname  oracle.jdbc.driver.OracleDriver
datasource.username   scott
datasource.password   tiger
    

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. If your application server is running on the same host as the Oracle DBMS, you can use the Oracle OCI JDBC driver; depending on the Oracle release, the URL to use for this would be jdbc:oracle:oci7, or jdbc:oracle:oci8. Oracle JDBC drivers may be downloaded at the Oracle Web site.

To create an InstantDB DataSource object (for example, InstantDB1) named jdbc_2 in JNDI, describe it as follows (in a file InstantDB1.properties):

datasource.name       jdbc_2 
datasource.url        jdbc:idb=db1.prp
datasource.classname  jdbc.idbDriver
datasource.username   useless
datasource.password   useless
    

To create a PostGreSQL DataSource object named jdbc_3 in JNDI, describe it as follows (in a file PostGreSQL.properties):

datasource.name       jdbc_3 
datasource.url        jdbc:postgresql://your_host/your_db
datasource.classname  org.postgresql.Driver
datasource.username   useless
datasource.password   useless
    

Properties having the "useless" value are not used for this type of persistence storage.

The database user and password can be placed in the DataSource description (<DataSource name>.properties file) and have the Application Components use the getConnection() method, or not placed in the DataSource description and have the Application Components use the getConnection(String username, String password) method. In the resource reference of the associated datasource in the standard deployment descriptor, the <res-auth> element should have the corresponding value, i.e. Container or Application.

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 DataSource. This is the purpose of the datasource.mapper property.

property name description possible values
datasource.mapper 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

ConnectionManager Configuration

Each Datasource is implemented as a connection manager that can be configured via some additional properties described in the following table. Refer to the Oracle1.properties file to see an example of settings. All these settings have default values and are not required.

property name description default value
jdbc.connchecklevel JDBC connection checking level 0 (no check), 1 (check connection), higher (call the test statement)
jdbc.connmaxage max age for jdbc connections 30
jdbc.connteststmt test statement select 1
jdbc.minconpool Minimum number of connections in the pool 0
jdbc.maxconpool Maximum number of connections in the pool -1 (no max boundary)

jdbc.connteststmt is not used when jdbc.connchecklevel is equal to 0 or 1.

jdbc.minconpool is used at DataSource creation time, and a modification is not taken into account for an already created DataSource.

jdbc.maxconpool can be dynamically increased or decreased.

Tracing SQL Requests through P6Spy

The P6Spy tool is integrated within JOnAS to provide a means for easily tracing the SQL requests that are sent to the database.

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

Example:

Datasource properties file content:

   datasource.name       jdbc_3
   datasource.url        jdbc:postgresql://your_host:port/your_db
   datasource.classname  com.p6spy.engine.spy.P6SpyDriver
   datasource.username   jonas
   datasource.password   jonas
   datasource.mapper     rdb.postgres
    

Within JONAS_BASE/conf/spy.properties file:

   realdriver=org.postgresql.Driver
    

Within JONAS_BASE/conf/trace.properties:

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