JBoss.org Community Documentation

18.1.1. Server Side Configuration

The biggest configuration difference between HA-JMS in the all configuration and the non-HA version found in the default configuration is the location of most configuration files. For HA-JMS, most configuration files are found in the deploy-hasingleton/jms directory, not in deploy/jms. Your queues and topics must be deployed in deploy-hasingleton (or a subdirectory of it like deploy-hasingleton/jms.) Application components that act as clients to HA-JMS (e.g., MDBs and other JMS clients) do not need to be deployed in deploy-hasingleton. They should only be deployed there if you only want them running on one node in the cluster at a time.

To use the singleton fail-over HA-JMS service, you must configure JMS services identically on all nodes in the cluster. That includes all JMS related service MBeans and all deployed queues and topics. However, applications that use JMS (e.g., MDBs and other JMS clients) do not need to be deployed identically across the cluster.

The JMS server is configured to persist its data in the DefaultDS. By default, that is the embedded HSQLDB. However, for the HA-JMS service fail-over to work, the newly started HA-JMS server needs to be able to find the data persisted by the old server. That's not likely to happen if the data is persisted in files written by the old servers' HSQLDB. In almost any cluster environments, all nodes need to persist data against a shared database. So, the first thing to do before you start clustered JMS is to setup a shared database for JMS. You need to do the following:

  • Configure DefaultDS to point to the database server of your choice. That is to replace the deploy/hsqlsb-ds.xml file with the xxx-ds.xml file in the docs/examples/jca directory, where xxx is the name of the target shared database (e.g., mysql-ds.xml).

  • Replace the hsqldb-jdbc2-service.xml file under the server/all/deploy-hasingleton/jms directory with one tuned to the specific database. For example if you use MySQL the file is mysql-jdbc2-service.xml. Configuration files for a number of RDBMS are bundled with the JBoss AS distribution. They can be found under docs/examples/jms.


There is no need to replace the hsqldb-jdbc-state-service.xml file under the server/all/deploy-hasingleton/jms directory. Despite the hsql in its name, it works with all SQL92 compliant databases, including HSQL, MySQL, SQL Server, and more. It automatically uses the DefaultDS for storage, which we configured above.