65Deploying miscellaneous applications

You can define multiple data sources within a single *-ds.xml file, but we recommend that you define only a single data source per file. This makes the data sources easier to manage.

JBoss AS comes with a set of example *-ds.xml files for a variety of databases. You

can find them in the docs/examples/jca directory, which should be your first stop when defining a *-ds.xml file. Also, we provide several example *-ds.xml files in many of the chapters in this book.

Now that you have the *-ds.xml file for your database, what do you do with it? Well, two things. The *-ds.xml file goes into the deploy directory. Yes, that’s right; it’s

treated as an application, specifically as a service. Second, you must provide the JAR

file for the JDBC driver for the database. Place the driver JAR file in the server/xxx/lib

directory. Be careful with JDBC drivers that contain a version number as part of the

filename—you don’t want two versions of the same driver to be resident in the server/ xxx/lib directory at the same time.

Once the data source is deployed, the application server creates several MBeans for

the data source. These MBeans are defined in table 3.6, where XXX is the JNDI name

for the data source.

<xa-datasource-property> Identifies a property to pass to the javax.sql.DataSource

when establishing a database connection. Refer to the JDBC driver documentation for the valid properties. You can provide multiple <xa-datasource-property> entries. Valid only for

<xa-datasource>.

<transaction-isolation> Identifies the transaction isolation level to use with the database. Valid values include

TRANSACTION_READ_UNCOMMITTED TRANSACTION_READ_COMMITTED TRANSACTION_REPEATABLE_READ TRANSACTION_SERIALIZABLE TRANSACTION_NONE

Refer to your database’s JDBC documentation for a description of each level and which levels your database supports. Not valid for

<no-tx-datasource>.

Table 3.5 MBeans created for a data source

MBean Description

jboss.jca:name=XXX, service=DataSourceBinding

Manages the javax.sql.DataSource objects.

jboss.jca:name=XXX, service=LocalTxCM

Manages the connection manager, which is responsible for the connection pool. You can use this MBean to manage various aspects of distributed transactions, such as the local XA resource transaction timeout value. Created only for

<local-tx-datasource>. Table 3.4 Data source configuration options for *-ds.xml (continued)

When you deploy a *-ds.xml file to the deploy directory, that data source is available to all applications deployed to the application server. You can also package the *-ds.xml

file with your application. Let’s look at how to package a data source in an EAR file as

an example.

PACKAGING A DATA SOURCE IN AN EAR FILE

In chapter 7, we describe how to package web applications and EJBs into an EAR file.

You can also place the *-ds.xml file in the EAR file.

For example, assume that the web application is packaged in inventory.war, and

the EJBs are packaged in inventory.jar. You could place those archives and the data

source descriptor into a single EAR file that has the contents illustrated in figure 3.5.

In addition, because the *-ds.xml file is located within the

package, you can also place the JAR file for the JDBC driver

there. If you add a class loader repository to the EAR file

descriptor, then only this application would have access to

the JDBC driver.

The application.xml file enumerates the archives pack-

aged within the EAR file, but it’s a standard Java EE descriptor

and, because data source descriptors aren’t part of standard

Java EE, they can’t be referenced in that file. Instead, you use

a META-INF/jboss-app.xml file which references the data source descriptor, as follows:

<!DOCTYPE jboss-app PUBLIC "-//JBoss//DTD J2EE Application 1.4//EN" "http://www.jboss.org/j2ee/dtd/jboss-app_4_0.dtd"> <jboss-app> <module> <service>inventory-ds.xml</service> jboss.jca:name=XXX, service=XATxCM

Manages the connection manager, which is responsible for the connection pool. You can use this MBean to manage various aspects of distributed transactions, such as the distrib- uted XA resource transaction timeout value. Created only for

<xa-datasource>.

jboss.jca:name=XXX, service=NoTxCM

Manages the connection manager, which is responsible for the connection pool. Created only for <no-tx-datasource>.

jboss.jca:name=XXX,

service=ManagedConnectionFactory

Manages the connection factory, which creates database connections.

jboss.jca:name=XXX,

service=ManagedConnectionPool

Manages the pool of database connections. You can use this MBean to monitor the number of active connections and even change the min and max connection count.

jboss.jdbc:service=metadata, datasource=XXX

You can use this MBean to change the type mapping. Doesn’t appear if the data source is defined as a no transaction data source.

Table 3.5 MBeans created for a data source (continued)

MBean Description

Figure 3.5 The contents of the inventory.ear

package, showing the embedded *-ds.xml file

67