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:
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 "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 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.
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 |
|
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.
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 :
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) |