Using Tomcat and JDBC

Tomcat provides valuable services for hosted Web applications that use JDBC connections. More specifically, Tomcat will enable running Web applications to do the following:

• Access JDBC data sources using standard JNDI lookup

• Use a connection pooling service

Providing JDBC Data Sources in Tomcat

You configure JDBC drivers as JNDI resources in Tomcat. These resources are made available during Web application run time via standard JNDI lookups. The steps are as follows:

1. First, a Web application obtains a JNDI initial context from Tomcat; it then performs a lookup on the JDBC data source by name.

2. Next, Tomcat handles the JNDI lookup by consulting the configuration files (the context XML file and web.xml) to determine the JDBC driver to use for obtaining a data source. Tomcat will also pool the physical connections made.

Even though no true JNDI-compatible directory services are involved, the Tomcat container emulates the action of a JNDI provider. This enables code that uses JNDI as the JDBC data source lookup mechanism to work within the Tomcat container.

Configuring JNDI JDBC Resources

Using JNDI resources in Tomcat to configure JDBC data sources is the recommended way to provide Web applications with access to JDBC connections. While other methods are possible— and you’ll see at least one alternative later—this approach will lead to portable code and easily maintainable Tomcat servers.

You must perform the following steps to configure JNDI resource for a JDBC data source:

1. Add <Resource> and <ResourceParams> tags in the <Context> element of the context XML file or in a <DefaultContext> subelement of the Tomcat 5.0.x <Host> element.

2. Ensure that the application developer has defined a <resource-ref> element, corresponding to the previous <Resource>, in the web.xml file of the Web application using the JDBC resource.

Using the Resource and ResourceParams Elements

The <Resource> element specifies the JNDI resource that represents a JDBC data source, and the <ResourceParams> element configures the associated data source factory. You saw a JDBC data source in Listing 10-1 repeats the code for Tomcat 5.0.x with some extra parameters.

Listing 10-1: Defining a JDBC Data Source for Tomcat 5.0.x

 <Context path="/tomcatBook"           docBase="tomcatBook"           crossContext="false"           debug="0"           reloadable="true" >    <Resource name="jdbc/CatalogDB" auth="SERVLET"              type="javax.sql.DataSource"/>    <ResourceParams name="jdbc/CatalogDB">      <parameter>        <name>driverClassName</name>        <value>com.mysql.jdbc.Driver</value>      </parameter>      <parameter>        <name>url</name>        <value>jdbc:mysql://localhost:3306/catalog</value>      </parameter>      <parameter>        <name>username</name>        <value>matthewm</value>      </parameter>      <parameter>        <name>password</name>        <value>m00die</value>      </parameter>      <parameter>        <name>maxActive</name>        <value>30</value>      </parameter>      <parameter>        <name>maxIdle</name>        <value>20000</value>      </parameter>      <parameter>        <name>maxWait</name>        <value>120</value>      </parameter>    </ResourceParams>  </Context> 

Listing 10-2 shows the same setup for Tomcat 5.5.

Listing 10-2: Defining a JDBC Data Source for Tomcat 5.5

 <Context path="/tomcatBook"           docBase="tomcatBook"           crossContext="false"           debug="0"           reloadable="true" >    <Resource name="jdbc/CatalogDB" auth="SERVLET"              type="javax.sql.DataSource"              driverClassName="com.mysql.jdbc.Driver"              url="jdbc:mysql://localhost:3306/catalog"              username="matthewm"              password="m00die"              maxActive="30"              maxIdle="20000"              maxWait="120"/>  </Context> 

Both these settings create a JNDI resource that the Web application can access from the context java:comp/env/jdbc/CatalogDB. The Web application can then use this context to look up the data source. The type of resource that will be returned during this lookup is a javax.sql.DataSource. It also specifies that the servlet should authenticate against the database on behalf of the Web application.

The actual name and value of the parameters depend on the data source connection factory that’s used. The previous settings assume you’re configuring the default DBCP factory. The DBCP factory will work with JDBC drivers for any database and return a data source as appropriate.

Chapter 7 has more details of the attributes allowed in the <Resource> and <ResourceParams> elements.

Transactions and Distributed Transactions Support

Databases offer varying levels of support for transactions. A transaction is a unit of work composed of multiple operations but can be committed only once all its operations complete successfully. If any of the constituent operations fail, the transaction is rolled back.

When a transaction involves work that crosses multiple physical databases, it’s called a distributed transaction. One standard that enables databases from different vendors to participate in the same distributed transaction is called XA. In the XA operation model, an external transaction manager coordinates a two-phase commit protocol between multiple resource managers (databases in this case). The two-phase commit protocol ensures that the pieces of work, scattered across multiple physical databases, either are all completed or are all rolled back.

JDBC 3.0 accommodates data sources that support XA operations. Administrators who work with XA data sources and data source factories should consult the vendor’s documentation to ensure they work with Tomcat.