Configuring JDBC DataSources

Target Audience and Content

The target audience for this guide is the bean or application deployer. It describes how the Datasources should be configured in order to connect the application to databases.

The content of this guide is the following:

  1. Target Audience and Content
  2. Configuring DataSources
  3. The case of CMP2.0/JORM
  4. ConnectionManager Configuration
  5. Customizing JDBC DataSources (alpha release)

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 provided at the application server level, the DataSource. The DataSource interface is defined in the JDBC 2.0 standard extensions. A DataSource object identifies a database and a mean to access it via JDBC (a JDBC driver). An application server may propose access to several databases and thus provide the corresponding DataSource objects. One may add DataSource objects available on the platform; they are defined in the jonas.properties file. This section explains how DataSource objects may be defined and configured in the JOnAS server.

In order to support distributed transactions, JOnAS requires the use of a JDBC2-XA compliant driver. Such drivers implementing the XADataSource interface are not yet available for all relational databases, also 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 2-phase commit for distributed database transactions.

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

The way to define DataSource objects in order to make them available to a J2EE platform is not specified in the EJB or J2EE specifications. Therefore, the remainder of this section, 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 by the way of the resource manager connection factory references (example in 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", you should add its 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 (say Oracle1), named jdbc_1 in JNDI, and using the Oracle thin JDBC driver, should be described in a file called Oracle1.properties, as in the example below:

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 may use the Oracle OCI JDBC driver; in this case the URL to be used is jdbc:oracle:oci7: or jdbc:oracle:oci8:, depending of your Oracle release. Oracle JDBC drivers may be downloaded at their Web site.

If you intend to create an InstantDB DataSource object (say InstantDB1), named jdbc_2 in JNDI, it should be described 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
    

If you intend to create an PostGreSQL DataSource object, named jdbc_3 in JNDI, it should be described 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 kind of persistence storage.

For the database user and password, you may choose to put it in the DataSource description (<DataSource name>.properties file) and your Application Components use the getConnection() method, or not to have it in the DataSource description and having your Application Component 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.

The case of 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. So for each kind 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.oracle: mapper for Oracle
  • 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. Look at 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.