Tomcat – Howtos

1. How do I install the Administration web app?

If you install Tomcat 5.5 binaries, the Administration web app is not bundled with it; this describes how to add the Administration web app to your Tomcat 5.5 installation. (Tomcat 4.1 comes with the Administration web app as part of the binary).

The following refers to a Tomcat 5.5 set up on Windows 2000, so your path names will be different on *nix platforms. In this example, Tomcat 5.5.17 in installed in c:\Program Files\Apache Software Foundation\Tomcat 5.5 (this is my CATALINA_HOME).

  1. Unzip or untar (be careful to use GNU tar) the file containing the administration web app files (eg. to a temporary directory, eg. c:\temp.

  2. Copy c:\temp\apache-tomcat-5.5.17\conf\Catalina\localhost\admin.xml to the directory c:\Program Files\Apache Software Foundation\Tomcat 5.5\conf\Catalina\localhost.

  3. Copy the entire directory tree c:\temp\apache-tomcat-5.5.17\server\webapps\admin

to the directory c:\Program Files\Apache Software Foundation\Tomcat 5.5\server\webapps. This is an overlay, so \server\webapps is just pointing you to the \server\webapps, and the admin directory with its contents will be the only thing you see added there.

  1. Add a line to your c:\Program Files\Apache Software Foundation\Tomcat 5.5\conf\tomcat-users.xml file so that you have a user who has admin role. For example, add this line just before the last line (containing </tomcat-users>) of the file:

    • <user username=”admin” password=”makesomethingup” roles=”admin,manager”/>

  2. Restart Tomcat.
  3. Now when you visit http://localhost:8080/admin you should see a page that asks for a user name and password. If you still see the “no longer loaded” error message in your browser, you must either force a full reload of the web page (in Firefox, hold down Shift key while clicking on the Reload button) or just restart your browser completely.

2. How do I use DataSources with Tomcat?

When developing J2EE web applications, the task of database connection management can be daunting. Best practice involves using a J2EE DataSource to provide connection pooling, but configuring DataSources in web application servers and connecting your application to them is often a cumbersome process and poorly documented.

The usual procedure requires the application developer to set up a DataSource in the web application server, specifying the driver class, JDBC URL (connect string), username, password, and various pooling options. Then, the developer must reference the DataSource in his application’s web.xml configuration file, and then access it properly in his servlet or JSP. Particularly during development, setting all of this up is tedious and error-prone.

With Tomcat 5.5, the process is vastly simplified. Tomcat allows you to configure DataSources for your J2EE web application in a context.xml file that is stored in your web application project. You don’t have to mess with configuring the DataSource separately in the Tomcat server.xml, or referencing it in your application’s web.xml file. Here’s how:

Install the JDBC Driver

Install the .jar file(s) containing the JDBC driver in Tomcat’s common/lib folder. You do not need to put them in your application’s WEB-INF/lib folder. When working with J2EE DataSources, the web application server manages connections for your application.

Create META-INF/context.xml

In the root of your web app directory structure, create a folder named META-INF (all caps). Inside that folder, create a file named context.xml that contains a Resource like this:

<?xml version="1.0" encoding="UTF-8"?>
  <Resource name="jdbc/WallyDB" auth="Container"
            type="javax.sql.DataSource" username="wally" password="wally"

This example shows how to configure a DataSource for a SQL Server database named mytest located on the development machine. Simply edit the Resource name, driverClassName, username, password, and url to provide values appropriate for your JDBC driver.

Access the DataSource in Your Application

From a Servlet

Here’s how you might access the data in a servlet:

  InitialContext ic = new InitialContext();
  DataSource ds = (DataSource) ic.lookup("java:comp/env/jdbc/WallyDB");
  Connection c = ds.getConnection();

Notice that, when doing the DataSource lookup, you must prefix the JNDI name of the resource with java:comp/env/

Sample Project

Here’s a sample web application project that shows where all the files go. This one shows how to access data from from a JSP page: datasourcedemo.war

Known-Working examples for other Databases

    <Resource name="jdbc/denali" auth="Container" type="javax.sql.DataSource"
              username="denali" url="jdbc:postgresql://localhost:5432/demo"
              maxActive="20" maxIdle="10"/>
    <Resource name="jdbc/ccsdatasource" auth="Container" type="javax.sql.DataSource"
              username="ccs" password="secret" url="jdbc:mysql://localhost:3306/ccs"
              maxActive="20" maxIdle="10"/>

Please Note

This technique is Tomcat-specific. If you deploy your web application to another application server (or even an older version of Tomcat), you will need to configure the database according to your application server’s documentation, and reference it in your application’s web.xml.