63Deploying miscellaneous applications

Which transaction type should you use? In most cases, you’ll use <local-tx-data-

source> because it handles transactions within a single application server. If you’re clustering your application servers or wanting to use distributed transactions among

multiple application servers, then you should use <xa-datasource>. Note that both

<local-tx-datasource> and <xa-datasource> handle distributed transactions

involving multiple data sources. The difference is that <local-tx-datasource> han-

dles them only within a single running application server, whereas <xa-datasource>

handles them among many running application servers. On the other end of the spec-

trum, if your applications only read from the database, then using <no-tx-data-

source> would be appropriate.

NOTE XA is an API defined by The Open Group’s Distributed Transaction Pro-

cessing model. This model provides communications mechanisms between a Transaction Monitor and several resource managers, which perform updates against databases. The Transaction Monitor is responsi- ble for coordinating the individual transactions handled by the resource managers to ensure transactional semantics when multiple resource man- agers are involved in a single transaction.

Within the transaction type, you can specify a wide variety of configuration options. Table 3.5 describes the various configuration options in the *-ds.xml file. A complete set of configuration options, along with a description of each option, can be found in the docs/dtd/jboss-ds_5_0.dtd file.

Table 3.4 Data source configuration options for *-ds.xml

Tag Description

<jndi-name> Name used to look up the data source in the JNDI namespace. The

java: prefix is automatically added to this name.

<connection-url> The URL used by the JDBC driver to establish a database connection. This URL is specific to the database and the driver for the database. In the example, the name of the database is jbossdb, which must be a valid database in MySQL.

<driver-class> The class name for the JDBC driver. Valid only for <local-tx- datasource> and <no-tx-datasource>.

<xa-datasource-class> The class name for the distributed transaction data source. Valid only for <xa-datasource>.

<user-name> The user name for making the database connection.

<password> The password for the given user name.

<security-domain> References a security domain that uses an identity login module defined in login-config.xml. You can use this in place of <user- name> and <password> to provide an encrypted password to the database.

<min-pool-size> The minimum number of open connections maintained by the appli- cation server. Note that the application server doesn’t open any con- nections until the first request for a connection, at which time it opens the specified number of connections. To establish connec- tions when the application server is started, you can write a simple service that does nothing but ask for a connection.

<max-pool-size> The maximum number of open connections maintained by the appli- cation server. If the application server runs out of connections, it allo- cates a new connection to fulfill that request, until it hits the maximum number of connection. At that point, it queues the requests until connections are freed. Therefore, it’s important that applications close any connections that they obtain.

<idle-timeout-minutes> If a surplus connection isn’t in use for the specified number of min- utes, then that connection is closed. Note that the number of open connections never goes below the <min-pool-size>.

<blocking-timeout-millis> The number of milliseconds a requestor waits for a connection to become available before the wait times out. The requestor then gets an exception.

<exception-sorter-class-name> Identifies a class used to determine if an error number returned by the database is fatal.

<check-valid-connection-sql> Identifies an SQL to be executed when the connection is established to verify the connection’s validity. In the example, FooBar must be a table in the jbossdb database specified in the connection URL.

<valid-connection-checker- class-name>

Identifies a class that can be used when the connection is estab- lished to verify the connection’s validity. The class specified must implement the org.jboss.resource.adapter.jdbc. ValidConnectionChecker interface. Use this option instead of <check-valid-connection-sql> when you want to use more than a single SQL statement to check the connection’s validity. Be aware that any application making a connection request that causes a connection to be established must wait until the connec- tion checker is finished.

<type-mapping> Used by the container-managed persistence (CMP) code to identify the database and adjust its database handling accordingly. The name use must match one of the names in the standardjbosscmp- jdbc.xml file. Additionally, you can add new entries to the standardj- bosscmp-jdbc.xml to customize the database interaction. Note that this is used only for EJB 2.1, not for EJB3.

<connnection-property> Identifies a property to pass to the java.sql.Driver when establishing a database connection. In the example, the property name is xxx and the value is yyy. Refer to your JDBC driver docu- mentation for the valid properties. You can provide multiple

<connection-property> entries. Valid only for <local-tx- datasource> and <no-tx-datasource>.

Table 3.4 Data source configuration options for *-ds.xml (continued)

65