4.1. Configuring DataSources

For both container-managed and 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 (see http://java.sun.com/products/jdbc/). A DataSource object identifies a database and a means to access it via 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 always available for all relational databases. JOnAS provides a generic driver-wrapper that emulates the XADataSource interface on a regular JDBC driver.

	Important
	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 databases, such as Oracle and PostgreSQL.

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 Section 8.6 Writing Database Access Operations (Bean-Managed Persistence)).

A DataSource object should be defined in a file called DataSourcename.properties (for example, Oracle1.properties for an Oracle DataSource), as delivered with the platform.

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

jonas.service.dbm.datasources Oracle1,PostgreSQL

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

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 can be downloaded at the Oracle web site: http://otn.oracle.com/software/tech/java/sqlj_jdbc/content.html

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.

If the database user and password are placed in the DataSource description (the DataSource-name.properties file), then Application Components should use the getConnection() method. If the database user and password are omitted from the DataSource description file, then Application Components should use the getConnection(String username, String password) method. The resource reference of the associated datasource in the standard deployment descriptor, the <res-auth> element, should have the corresponding value: Container if the user and password are given in the DataSource description, Application if the user and password are provided by the Application.