THIS CHAPTER IS PRIMARILY RELEVANT TO JBOSS 3 (RABBITHOLE) VERSIONS BEFORE RC1

THE MBEANS FOR CONFIGURING DATASOURCES/ADAPTERS IN RC1 ARE COMPLETELY DIFFERENT FROM THOSE DESCRIBED HERE. FOR DESCRIPTIONS OF EACH ATTRIBUTE, CONSULT THE GENERATED JMX-API DOCUMENTATION.

You will probably have to generate this documentation yourself. Check out jboss-all and run build/build.sh all. You should find a build/output/jboss-###/docs/jmx-api directory, and following the package structure to org.jboss.resource.connectionmanager should reveal the documentation .

In order for your ejbs to do much useful work, they will need to communicate with a transactional resource manager such as a relational database, transactional message queue, or other enterprise information system. Jboss now supports all such communication using Resource Adapters following the jca 1.0 specification. This technology provides a uniform way to combine the application server's transaction management and connection pooling functionalities with a resource adapter's ability to connect to and do work with a resource manager.

Jboss provides the ability to deploy any compliant resource adapter, and connections from any adapter may be pooled by jboss, obtained from connection factories bound in jndi, and used by client code. At the moment, however, only connection factories implementing javax.sql.DataSource and connections implementing java.sql.Connection may be used with CMP beans and the jboss ejb persistence manager to automate database access.

Since few database vendors have supplied resource adapters for their database products, the usual strategy for accessing relational databases consists of using a generic resource adapter that wraps a jdbc driver into a jca resource adapter. Jboss comes with two such adapters, one for jdbc 1 drivers without xa transaction support, and one for jdbc 2 drivers implementing xa support with XADataSource, XAResource, and XAConnection.

As well as providing a systematic, well thought out framework for pooling and transaction control that can be used for relational databases, jca also provides another specification ("cci") for connection factories and connections unrelated to jdbc. An adaptor could use these to provide predefined access to stored procedures in a relational database, or these could be used to access a message que, or enterprise information system such as CICS or SAP. Although there are no particular conceptual difficulties in using such resource adapters to automatically manage persistence of CMP beans, support for this is not yet integrated into jboss.

Most often connections to resource managers such as relational databases take a significant amount of time to set up and consume a significant amount of resources. It would be unacceptably inefficient to construct, use, and tear down a physical connection for each client request in an application server environment, nor would it usually be appropriate to reserve a connection for each user. Some means of sharing and reusing expensive connections is necessary. The jca solution to this involves ManagedConnections, which are "physical" connections to the resource manager provided by the resource adapter, and which are pooled by the ConnectionManager provided by the application server, and short lived connection handles to these ManagedConnections, which can be handed out on demand and returned (closed) when done with. Note that there are three layers here: a client (or persistence framework such as JAWS) requests a (resource adapter-specific) connection from a (resource-adapter-specific) connection factory; the connection factory basically typecasts a generic connection handle from the (jboss supplied) ConnectionManager, which has just obtained the connection handle from a ManagedConnection (from the resource adapter) that it retrieved (from a pool) or created.

There are three levels of transaction support mentioned in the jca specification: full xa support for distributed transactions with two phase commit, single phase local (to a single resource manager/adapter) transactions, and no transaction support. Since the ConnectionManager mediates all connection handles supplied to clients, it is also the component that mediates between the transaction manager and the connections, making sure that each managed connection is enrolled in the correct transaction for the client that currently has its connection handle. For example, database XADataSource-based drivers can be wrapped into resource adapters supporting xa transactions, whereas database jdbc 1.0 drivers can be wrapped into resource adapters supporting local transactions.

We will start with an overview of the components of a resource adapter and related parts of an application server, and how these are set up in jboss. We proceed with a description of how to configure a connection factory for an arbitrary resource adapter, followed by instructions for using the specific jdbc wrapper resource adapters provided with jboss for non xa and xa jdbc drivers. This will be followed by a detailed discussion with examples of how to set up these wrappers for the most commonly used databases. If you are using a database not listed here, please contribute a working setup to help others. Finally we discuss migration from the previous jboss implementation, the XADataSourceLoader.