# 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. ConnectionManager Configuration
4. 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 EJB 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 EJB 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 EJB server, although this is more an administrator task than a bean developer task.

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 "Customizing JDBC DataSource" section describes how it is now possible to use a real JDBC2-XA compliant driver or to customize the behavior of the driver-wrapper for a given database server.

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 and InstantDB (a free, 100% java, Relational Database Management System).

The way to define DataSource objects in order to make them available to an EJB platform is not specified in the EJB specification. 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 Enterprise Bean 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 EJB 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 Enterprise Beans use the getConnection() method, or not to have it in the DataSource description and having your Enterprise Bean 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 Bean.

## 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 | 1 with 0(low) to 4(hight)
jdbc.connmaxage | max age for jdbc connections | 30
jdbc.connteststmt | test statement | select 1

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

## Customizing JDBC DataSources (alpha release)

In order to support customized or third party JDBC drivers, JOnAS exposes two layers for configuration of the DataSources, this configuration slightly differs from the standard configuration explained above. The top layer is the pool and the bottom layer the JDBC2-XA driver or driver-wrapper. Configuration properties specific to the pool start with jdbc.

The only layer that can be replaced is the JDBC2-XA driver, this achieved using the datasource.factory property. The specified class must implement the org.objectweb.jonas.dbm.CommonDataSource interface. JOnAS ships with the following implementations:

org.objectweb.jonas.dbm.JonasStandardXADataSource | generic factory for Jdbc1 drivers
org.objectweb.jonas.dbm.JonasIdbXADataSource | factory for the XA driver for InstantDB
org.objectweb.jonas.dbm.JonasInformixXADataSource | factory for the XA driver for InformixB
org.objectweb.jonas.dbm.JonasOracleXADataSource | factory for Oracle jdbc 2.0 XA driver
org.objectweb.jonas.dbm.JonasSybaseXADataSource | factory for Sybase database

org.objectweb.jonas.dbm.JonasStandardXADataSource is a generic driver-wrapper for JDBC1 drivers that do not support the XA interface. From a functional point of view this wrapper is very similar to the generic driver-wrapper described in Configuring JDBC DataSources section. However, the implementing classes are not the sames. JonasIdbXADataSource, JonasInformixXADataSource and JonasSybaseXADataSource extends this driver-wrapper.

org.objectweb.jonas.dbm.JonasIdbXADataSource allows to extend the driver wrapper to the JDBC 2.0 InstantDB driver. This class is not compiled by the global Makefile mechanism from Jonas. To compile it, you need to compile the instantdb package from jonas/externals/jdbc/src/org/enhydra/jdbc/instantdb. You just have to add to the Makefile from the jdbc directory, an entry for the instantdb package. When this package is compiled, you need to compile the Jonas'hat for InstantDB (jonas/src/org/objectweb/jonas/dbm/JonasIdbXADataSource). You just need to add this file to the current Makefile.

org.objectweb.jonas.dbm.JonasInformixXADataSource extends the JonasStandardXADataSource driver-wrapper to take Informix driver specific behaviors into account. In order to use this driver-wrapper, you just need to compile this file (jonas/src/org/objectweb/jonas/dbm/JonasSybaseXADataSource), and setup the properties file.

org.objectweb.jonas.dbm.JonasOracleXADataSource allows to use the JDBC 2.0 driver from Oracle (classes12.zip file). In this case, the driver wrapper from Jonas is not used. To use this possibility, you need to compile some classes in adding them into the Makefile from the dbm package :

- JonasOracleXAConnection.java
- JonasOracleXAPreparedStatement
- JonasOracleXADataSource
- JonasOracleXAStatement

org.objectweb.jonas.dbm.JonasSybaseXADataSource extends the JonasStandardXADataSource driver-wrapper to take Sybase driver specific behaviors into account. In order to use this driver-wrapper, you just need to compile this file (jonas/src/org/objectweb/jonas/dbm/JonasInformixXADataSource), and setup the properties file.

Currently only the XADataSource implementation can be changed, since there is no configuration options to change the pool implementation. If you are interested in writing new XADataSource, you can read the "How-to write a new driver wrapper for Jonas".

The configuration for the DataSource is done using a property file as described in the Configuring JDBC DataSources section with additional properties listed below. The only required properties are the datasource.factory and the datasource.xadataname. If the datasource.factory is not defined, the "generic driver-wrapper" of Jonas will be used, as described at the beginning of the Configuring JDBC DataSources section.

property name | Description | default value
datasource.factory | Name of the class implementing the XADataSource | org.objectweb.jonas.dbm.JonasStandardXADataSource
datasource.xadataname | JNDI name use to bind the XADataSource | idb_xa
datasource.mincon | Minimum number of physical connection used by the XADataSource | 5
datasource.maxcon | Maximum number of physical connection used bythe XADataSource | 10
jdbc.minconpool | Minimum number of XAConnection used by the pool | 10
jdbc.maxconpool | Maximum number of XAConnection used by the pool | 20
jdbc.sleeptimepool | Time between two clean-up of old unused connection | 300000(ms)
jdbc.gcpool | Force the gc to be launchedwhen cleaning up | false
jdbc.deadlockpool | In case of no connection in the pool, deadlockpool is the global time to re-try before throwing an exception | 300000(ms)
jdbc.loopwaitpool | In case of no connection in the pool, loopwaitpool is the unit time to re-try | 10000(ms)