Configuring JBoss 4.0 JDBC Connectivity

by Deepak Vohra
02/25/2004

JBoss 4.0, developer edition, is an open source application server configured to use HypersonicDB by default. However, some Java 2 Platform Enterprise Edition (J2EE) developers would like to use databases other than HypersonicDB to develop and deploy applications. In this tutorial, we'll look at how to configure JBoss to use other databases.

Overview

The JBoss 4.0 server makes use of Java Database Connectivity (JDBC) configuration files to configure the server. The JBoss application server provides data source access for Enterprise Java Beans (EJB) persistence, and other for J2EE applications. To use the server with a database other than the default database, Hypersonic, these configuration files have to be modified. This article is structured into the following sections:

1. JBoss Deployment Descriptors for EJBs
2. Oracle Database Configuration
3. MySQL Database Configuration
4. Sybase Database Configuration
5. DB2 Database Configuration
6. Informix Database Configuration

JBoss Deployment Descriptors for EJBs

standardjaws.xml is the standard deployment descriptor for the mapping of Container Managed Persistence (CMP) entity EJBs. To use a custom configuration for mapping CMP entity EJBs, you use the jaws.xml file instead. In both cases, the file is copied to the META-INF directory of the EJB .jar file. Whichever file is used configures the following:

Related Reading JDBC Pocket Reference By Donald Bales

• Specify a data source and a type mapping for the data source.
• Specify how tables are built/used.
• Define finder methods to access the entity beans.
• Define type mappings.

A data source is a Java Naming and Directory Interface (JNDI) object used to obtain a connection from a connection pool to a database. The default data source configured with JBoss 4.0 is the HypersonicDB data source. To use another database, you need to modify jaws.xml or standardjaws.xml.

standardjbosscmp-jdbc.xml is the standard deployment descriptor to configure the JBoss CMP container. It can be replaced with a custom configuration version, called jbosscmp-jdbc.xml. As before, this file goes in the META-INF directory of the EJB .jar file. And once again, JBoss 4.0 defaults to a Hypersonic version, in this case HypersonicDB cmp. To use another database, we need to edit this file.

Oracle Configuration

Oracle is a very popular enterprise database used for its performance and reliability. To configure JBoss 4.0 with Oracle, we first need to put Oracle's driver classes in the CLASSPATH. Copy Oracle's JDBC driver .zip file /jdbc/lib/classes12.zip to the server/default/lib directory.

To use Oracle's transactional (XA) data source, copy /docs/examples/jca/oracle-xa-ds.xml to the /server/default/deploy directory. To configure with the non-XA data source, copy /docs/examples/jca/oracle-ds.xml instead, to /server/default/deploy dir.

Next, we need to modify the oracle-ds.xml configuration file. The <driver-class/> and <connection-url/> settings for Oracle are as follows:

Oracle OCI Type 2 Driver

• Class: oracle.jdbc.driver.OracleDriver
• URL: jdbc:oracle:oci8:@<database>

Oracle OCI Thin Type 4 Driver

• Class: oracle.jdbc.driver.OracleDriver
• URL: jdbc:oracle:thin:@<host>:<port>:<database>

Oracle OCI XA Type 2 Driver

• Class: oracle.jdbc.xa.client.OracleXADataSource
• URL: jdbc:oracle:thin:@<host>:<port>:<database>

Oracle OCI Type 2 Driver

• Class: oracle.jdbc.driver.OracleDriver
• URL: jdbc:oracle:oci8:@<database>

In the Connection URL setting, <host> is the HOST value specified in the /network/ADMIN/tnsnames.ora file, and <port> is the PORT value specified in the tnsnames.ora file, and <database> is the database name.

Next, we modify the standardjaws.xml or jaws.xml configuration file. Set the <datasource> and <type-mapping> elements as follows:

<jaws>
   <datasource>java:/OracleDS</datasource>
   <type-mapping>Oracle8</type-mapping>
</jaws> 

Next, we modify the standardjbosscmp-jdbc.xml or jbosscmp-jdbc.xml configuration file, setting the <datasource> and <datasource-mapping> elements to use Oracle:

<jbosscmp-jdbc>
   <defaults>
      <datasource>java:/OracleDS</datasource>
      <datasource-mapping>Oracle8</datasource-mapping>
   </defaults>
</jbosscmp-jdbc> 

Finally, we need to modify login-config.xml to use Oracle. Add the following <application-policy> element to login-config.xml:

<application-policy name = "OracleDbRealm"> 
   <authentication> 
      <login-module code =  
  "org.jboss.resource.security.ConfiguredIdentityLoginModule" 
                            flag = "required"> 
         <module-option name = "principal">sa</module-option> 
         <module-option name = "userName">sa</module-option> 
         <module-option name = "password"></module-option> 
         <module-option name ="managedConnectionFactoryName">  
                   jboss.jca:service=LocalTxCM,name=OracleDS 
         </module-option> 
      </login-module> 
   </authentication> 
</application-policy>

By modifying the oracle-ds.xml, standardjaws.xml, standardjbosscmp-jdbc.xml, and login-config.xml files, the JBoss 4.0 server is configured to be used with a Oracle database.

MySQL Database Configuration

MySQL is an open source database used by many open source projects and small organizations. To use JBoss 4.0 with MySQL, we first need to put the MySQL driver classes into the CLASSPATH. Copy the .jar file mysql-connector-java-3.0.9-stable-bin.jar to the /server/default/lib directory.

To use the MySQL data source, copy /docs/examples/jca/mysql-ds.xml to the /server/default/deploy directory. Modify the mysql-ds.xml configuration file by setting <driver-class/> to com.mysql.jdbc.Driver and <connection-url/> to jdbc:mysql://<mysqlhost>/<database>, where <mysqlhost> is the MySQL host server and <database> is the MySQL database.

Next, we need to set the <datasource> and <type-mapping> elements in the standardjaws.xml or jaws.xml file:

<jaws>
  <datasource>java:/MySqlDS</datasource> 
  <type-mapping>mySQL</type-mapping>
</jaws> 

We also need to set the <datasource> and <datasource-mapping> elements in the standardjbosscmp-jdbc.xml or jbosscmp-jdbc.xml file:

<jbosscmp-jdbc>
    <defaults>
       <datasource>java:/MySqlDS</datasource>
       <datasource-mapping>mySQL</datasource-mapping>
  </defaults>
</jbosscmp-jdbc>

Finally, we modify login-config.xml with MySQL database settings. Add the following <application-policy/> element to login-config.xml:

<application-policy name = "MySqlDbRealm"> 
   <authentication> 
      <login-module code =  
  "org.jboss.resource.security.ConfiguredIdentityLoginModule" 
                            flag = "required"> 
         <module-option name ="principal">sa</module-option> 
         <module-option name ="userName">sa</module-option> 
         <module-option name ="password"></module-option> 
         <module-option name ="managedConnectionFactoryName">  
            jboss.jca:service=LocalTxCM,name=MySqlDS 
         </module-option> 
      </login-module> 
   </authentication> 
</application-policy>  

By modifying the mysql-ds.xml, standardjaws.xml, standardjbosscmp-jdbc.xml, and login-config.xml files, the JBoss 4.0 server is configured to be used with a MySQL database.

Sybase Database Configuration

Sybase Adaptive Server Enterprise (ASE) is a database server by Sybase Inc. ASE is used on both UNIX and Linux platforms. As before, the first step is getting the database driver classes into the CLASSPATH, by copying the .jar file jconn2.jar to the /server/default/lib directory. Then use its data source by copying /docs/examples/jca/sybase-ds.xml to /server/default/deploy dir.

Modify the sybase-ds.xml configuration file, setting <driver-class/> to com.sybase.jdbc2.jdbc.SybDriver and <connection-url/> to jdbc:sybase:Tds:<host>:<port>/<database>, where <host> is the Sybase host server, <port> is the Sybase host server port number, and <database> is the Sybase database name.

Then, as before, we need to modify standardjaws.xml or jaws.xml to set the <datasource> and<type-mapping> elements:

<jaws>
  <datasource>java:/SybaseDS</datasource>
  <type-mapping>Sybase</type-mapping>
</jaws>

We also need to modify standardjbosscmp-jdbc.xml or jbosscmp-jdbc.xml to set the <datasource> and <datasource-mapping> elements:

<jbosscmp-jdbc>
   <defaults>
      <datasource>java:/SybaseDS</datasource>
      <datasource-mapping>Sybase</datasource-mapping>
   </defaults>
</jbosscmp-jdbc>

Finally, we modify login-config.xml to use the Sybase database. Add the following <application-policy/> element to the file:

<application-policy name = "SybaseDbRealm"> 
   <authentication> 
      <login-module code =  
  "org.jboss.resource.security.ConfiguredIdentityLoginModule" 
                            flag = "required"> 
         <module-option name ="principal">sa</module-option> 
         <module-option name = "userName">sa</module-option> 
         <module-option name = "password"></module-option> 
         <module-option name = "managedConnectionFactoryName">  
                   jboss.jca:service=LocalTxCM,name=SybaseDS 
         </module-option> 
      </login-module> 
   </authentication> 
</application-policy>

By modifying the sybase-ds.xml, standardjaws.xml, standardjbosscmp-jdbc.xml, and login-config.xml, the JBoss 4.0 server is configured to be used with a Sybase database.

DB2 Database Configuration

IBM's DB2 Universal Database is a full-featured, robust, scalable, and easy-to-use database server that may be used on Linux, UNIX, and Windows platforms.

We begin by adding its driver to the CLASSPATH: copy db2java.zip to the /server/default/lib directory. To configure the JBoss server with the DB2 data source, copy /docs/examples/jca/db2-ds.xml to the /server/default/deploy directory.

Next we modify the db2-ds.xml configuration file, by setting <driver-class/> to COM.ibm.db2.jdbc.app.DB2Driver and <connection-url/> to jdbc:db2:<database>, where <database> is the DB2 database name.

Then we modify standardjaws.xml (or jaws.xml) to set <datasource> and <type-mapping>.

<jaws>
   <datasource>java:/DB2DS</datasource>
   <type-mapping>DB2</type-mapping>
</jaws>

And standardjbosscmp-jdbc.xml (or jbosscmp-jdbc.xml):

<jbosscmp-jdbc>
   <defaults>
      <datasource>java:/DB2DS</datasource>
      <datasource-mapping>DB2</datasource-mapping>
   </defaults>
</jbosscmp-jdbc>

Finally, we add the following <application-policy/> element to login-config.xml:

<application-policy name = "DB2DbRealm"> 
   <authentication> 
      <login-module code =  
  "org.jboss.resource.security.ConfiguredIdentityLoginModule"
                           flag = "required"> 
         <module-option name =  
"principal">sa</module-option>
         <module-option name =  
"userName">sa</module-option> 
         <module-option name =  
"password"></module-option> 
         <module-option name ="managedConnectionFactoryName">  
                   jboss.jca:service=LocalTxCM,name=DB2DS 
         </module-option> 
      </login-module> 
   </authentication> 
</application-policy>

These configuration changes allow us to use DB2 with JBoss.

Informix Database Configuration

IBM's Informix database servers are used for data warehousing, analysis, and reporting. To use the JBoss 4.0 server with an Informix database, we start by putting Informix's .jar into the CLASSPATH: add ifxjdbc.jar to the /server/default/lib directory. Then configure the data source by copying /docs/examples/jca/informix-ds.xml to the /server/default/deploy directory. If you are using the XA JDBC Informix driver, copy /docs/examples/jca/informix-xa-ds.xml instead.

Next we modify the informix-ds.xml configuration file by setting the <driver-class/> to com.informix.jdbc.IfxDriver and <connection-url/> to jdbc:informix-sqli://<host>:<port>:informixserver=<ifx_server>, where <host> is the host server, <port> is the Informix server port number, and <ifx_server> is the Informix database name.

We set the <datasource> and <type-mapping> elements in standardjaws.xml or jaws.xml like this:

<jaws>
   <datasource>java:/InformixDS</datasource>
   <type-mapping>InformixDB</type-mapping>
</jaws>

We set the <datasource> and <datasource-mapping> elements of standardjbosscmp-jdbc.xml or jbosscmp-jdbc.xml like this:

<jbosscmp-jdbc>
   <defaults>
      <datasource>java:/InformixDS</datasource>
      <datasource-mapping>InformixDB</datasource-mapping>
   </defaults>
</jbosscmp-jdbc> 

Finally, we add an <application-policy/> element to login-config.xml:

<application-policy name = "InformixDbRealm"> 
   <authentication> 
   <login-module code =  
   "org.jboss.resource.security.ConfiguredIdentityLoginModule" 
                            flag = "required"> 
         <module-option name = "principal">sa</module-option>
         <module-option name = "userName">sa</module-option> 
         <module-option name = "password"></module-option> 
         <module-option name ="managedConnectionFactoryName">  
            jboss.jca:service=LocalTxCM,name=InformixDS 
         </module-option> 
      </login-module> 
   </authentication> 
</application-policy>

These configuration changes allow us to use JBoss with an Informix database.

Conclusion

The JBoss 4.0 server is configured with the Hypersonic database by default, but as we've seen, it is a simple matter of changing a few configuration files to use any one of a number of popular databases.

Resource

JBoss Documentation

Deepak Vohra is a NuBean consultant and a web developer.

---

Return to ONJava.com.