Chapter 7. Using other Databases
In the previous chapters, we’ve just been using the JBoss default datasource in our applications. This is provided by the embedded HSQL database instance and is bound to the JNDI name java:/DefaultDS. Having a database included with JBoss is very convenient for running examples and HSQL is adequate for many purposes. However, at some stage you will want to use another database, either to replace the default datasource or to access multiple databases from within the server.
7.1. DataSource Configuration Files
DataSource configuration file names end with the suffix -ds.xml so that they will be recognized correctly by the JCA deployer. The docs/example/jca directory contains sample files for a wide selection of databases and it is a good idea to use one of these as a starting point. For a full description of the configuration format the best place to look is the DTD file docs/dtd/jboss-ds_1_5.dtd. Additional documentation on the files and the JBoss JCA implementation can also be found in the
JBoss 4 Application Server Guide
.
Local transaction datasources are configured using the local-tx-datasource element and XA-compliant ones using xa-tx-datasource. The example file generic-ds.xml shows how to use both types and also some of the other elements that are available for things like connection pool configuration. Examples of both local and XA configurations are available for Oracle, DB2 and Informix.
If you look at the example files firebird-ds.xml, facets-ds.xml and sap3-ds.xml, you’ll notice that they have a completely different format, with the root element being connection-factories rather than datasources. These use an alternative, more generic JCA configuration syntax used with a pre-packaged JCA resource adapter. The syntax is not specific to datasource configuration and is used, for example, in the jms-ds.xml file to configure the JMS resource adapter.
Next, we’ll work through some step-by-step examples to illustrate what’s involved setting up a datasource for a specific database.
