Chapter 8. Datasources

JBoss Enterprise Application Platform is shipped with an example datasource configured to allow it to operate out of the box with the included Hypersonic database. The datasource is bound to the JNDI name java:/DefaultDS and its descriptor is the <$JBOSS_HOME>/jboss-as/server/<PROFILE>/deploy/hsqldb-ds.xml file.
The DefaultDS JNDI name and hsqldb-ds.xml configuration is not required for normal platform operation. Delete this datasource before deploying a production instance.

Accessing the Database Manager of the Default Hypersonic Database

To access and edit the Hypersonic database that is available by default, do the following:
  1. Make sure JBoss Enterprise Application Platform is running.
  2. Open the JMX console located by default on http://localhost:8080/jmx-console/.
  3. On the displayed JMX Console page, click the database=localDB,service=Hypersonic entry in the jboss section.
  4. On the JMX MBean View page of the Hypersonic MBean, click Invoke in the startDatabaseManager row to invoke the GUI interface of the database manager.
The HSQL Database Manager window with the default local Hypersonic database appears.

Warning

The default persistence configuration is intended only for development purposes and to allow JBoss Enterprise Application Platform to run out of the box. However, Hypersonic is not supported in production and should not be used in a production environment.
Known issues with the Hypersonic database include the following:
  • no transaction isolation
  • thread and socket leaks ( connection.close() does not tidy up resources)
  • persistence quality (logs commonly become corrupted after a failure, preventing automatic recovery)
  • database corruption
  • stability under load (database processes cease when dealing with too much data)
  • not viable in clustered environments.

8.1. Configuring Datasources

When configuring a custom datasource, you need to create the datasource configuration file, so that the JCA deployer detects and deploys the datasource: a datasource configuration file name has the -ds.xml suffix. The docs/examples/jca directory contains example files for several databases and it is recommended to adapt one of these files to create your configuration file.

Note

The full description of the configuration format is available in the docs/dtd/jboss-ds_1_5.dtd file. Additional documentation on the files and the JBoss JCA implementation are available in the Administration and Configuration Guide.
Local transaction datasources are configured using the local-tx-datasource element and XA-compliant ones using xa-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.
The example files firebird-ds.xml, facets-ds.xml and sap3-ds.xml are defined with the connection-factories root element rather than datasources. That is because they 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 <JBOSS_HOME>/jboss-as/server/<PROFILE>/deploy/messaging/jms-ds.xml file to configure the JMS resource adapter.