In JBoss 3.0.x, DataSources and Java Connector Architecture (JCA) resource adaptors were configured as simple MBean services using -service.xml files or service archives (SARs). Although flexible, this mechanism proved to be too complex for common use and, starting with JBoss 3.2.x, an additional, simpler approach was provided.

In JBoss 3.2.x, DataSources and JCA ConnectionFactory's can be deployed using -ds.xml files. These have a simpler structure and provide defaults for many of the attributes that are not commonly adjusted; however, overrides can still be provided if required.

On deployment, a -ds.xml file is transformed using XSLT into the equivalent -service.xml configuration. Only the external form has changed.

This guide describes the different -ds.xml files in use for three common scenarios:

  • Defining a JDBC DataSource for use in a non-XA transaction (where the DataSource is the sole resource involved)
  • Defining an XA DataSource for use with XA transactions (where multiple resources may be involved)
  • Defining a ConnectionFactory for other types of connector

There are many example -ds.xml files included in the JBoss 3.2.x distribution; these can be found in the docs/jca/examples directory. An easy way to get started is to use one of these files that covers your database and modify it as required.

Structure of a -ds.xml File

The top level element of a -ds.xml file is <connection-factories> or (deprecated) <datasources>. Within this you can include any number of datasource or connection factory configurations, and any mbean configurations in the format of the -service.xml file.

Since datasources from the JBoss JCA wrappers are the most common ConnectionFactory type, there is simplified configuration for them. For a single ConnectionFactory or Datasource configuration, the possible top level elements are <no-tx-datasource>, <local-tx-datasource>, <xa-datasource>, <no-tx-connection-factory>, and <tx-connection-factory>. The <tx-connection-factory> element can be configured for either local or xa transaction support.