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:
- Make sure JBoss Enterprise Application Platform is running.
- Open the JMX console located by default on http://localhost:8080/jmx-console/.
- On the displayed JMX Console page, click the
database=localDB,service=Hypersonic
entry in thejboss
section. - On the
JMX MBean View
page of the Hypersonic MBean, click Invoke in thestartDatabaseManager
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.