Overview

Tomcat is an open source Java 2 Enterprise Edition (J2EE) servlet container that is used as the reference implementation for Java Servlet and JavaServer Pages technology. The implementation is accurate, fast, easy to use, and offered free of charge under the Apache Software License.

Cloudscape is a small footprint, standards based, database manager implemented entirely in Java. It can be completely embedded in any Java application, enabling a silent install and a single administration scope. Unlike other database managers that run in a separate process, embedded Cloudscape runs in the same Java virtual machine as your application. This significantly reduces database overhead. Yet it supports complex SQL, transactions, and JDBC without compromise so you can be sure your application can be migrated to IBM® DB2® Universal Database™ when it grows large enough to require enterprise wide capacity.

Assumptions

The materials and techniques discussed here are based on the following software platforms.

• Windows XP Professional with all service packs and updates as of June 1, 2004 (see http://www.microsoft.com/windows)
• Java Version 1.4.1 (IBM Windows 32 build cn1411-20030930) (see http://www.ibm.com/java and search for "IBM developer kits")
• Tomcat Version 5.0.19 (see http://jakarta.apache.org/tomcat/)
• Cloudscape Version 5.1.60.2 (see http://www.ibm.com/software/data/cloudscape).

You should be able to apply the information in this article to other operating systems and subsequent versions, but there is always a chance that platform changes and product enhancements can render it inaccurate or obsolete. Keep this is mind when you apply this information to your environment.

Alternative integration scenarios

There is more than one way to integrate Cloudscape with Tomcat. To illustrate the most useful alternatives, I have collected them into three sample scenarios:

The prototype integration

If you are developing a Web application for a prototype or proof-of-concept exercise, this scenario may suffice. No changes are required to the Tomcat configuration and everything can be contained in your Web application's archive (WAR).

The casual integration

If you need a database manager to implement a realm for Tomcat's user authentication or if you need your database manager to support multiple Web applications, this scenario would be more suitable. In this scenario, Cloudscape JAR files are added to the Tomcat configuration together with a class that implements the Tomcat LifecyleEvent interface. This class initializes and shuts down Cloudscape as the Tomcat server initializes and terminates.

The enterprise integration

If you need efficient connection pooling to support multiple simultaneous users and you want to keep your Web application independent of the JDBC URL specifications and database names, you need this scenario. In this scenario, Tomcat references and, therefore, has access to the entire Cloudscape library in the Cloudscape installation directory. JNDI Data Source definitions provide efficient connection pooling. In addition, the Cloudscape Network Service is started so that remote applications and administration tools can access the database while it is being used by Web applications.

Typically, you will choose the scenario that most closely matches your situation and use the alternatives described there. If, for some reason, the scenario contains an alternative that proves to be unsuitable, check the other scenarios for a better alternative.

HelloCloudscape.jsp

HelloCloudscape.jsp is a very simple JavaServer Page (JSP) that is used to verify that Cloudscape has been correctly integrated with Tomcat. It has been extended from the hello.jsp included with the Tomcat sample programs.

To match the integration, each scenario has a slightly different implementation of this JSP. The differences are explained in the scenario details, but in all cases, HelloCloudscape.jsp provides an HTML form for obtaining the information necessary to create a connection and execute a SQL command.

• In the Prototype Scenario and the Casual Scenario, the first field in the form obtains the Cloudscape database connection Universal Resource Locator (URL) and the second field is used to enter the SQL command to be executed.
  
  
• In the Enterprise Scenario, the first field in the form obtains the JNDI resource name of the JDBC data source and the second field is used to enter the SQL command to be executed.

When the form is submitted, the request is sent back to HelloCloudscape.jsp which

1. Redisplays the input form
2. Echoes the information submitted on the form
3. Acquires a connection to the database
4. Executes the provided SQL command
5. Displays the results of the SQL command.

If an Exception is thrown during this process, HelloCloudscape.jsp does its best to display the Exception message and the Java stack trace.

Note: Do not install HelloCloudscape.jsp on a production Web site. Make sure HelloCloudscape.jsp is removed from your Web application before it is deployed to a production Web site. HelloCloudscape.jsp would expose sensitive data because an attacker can use it to examine and modify any Cloudscape database at your site.

Example cloudscape database connection URLs

A Java database connection (JDBC) URL provides the information used to identify and establish a connection to a particular database.

For embedded Cloudscape systems, the Cloudscape JDBC driver name is com.ibm.db2j.jdbc.DB2jDriver and the URL has the following form.

jdbc:db2j:database[;attributes]

where

jdbc

is the standard prefix for all JDBC URLs.

db2j

is the subprotocol identifier for a URL that is to be interpreted by the Cloudscape JDBC driver.

database

is replaced with an identifier that references the Cloudscape database and is typically expressed as a qualified path to the directory that contains the database.

attributes

are optional attributes, separated by semicolons, to be applied to the connection.

Here are some useful examples.

• jdbc:db2j:C:\Cloudscape_5.1\demo\databases\toursDB will establish a connection to the sample Tours database provided with Cloudscape assuming that Cloudscape was installed in the directory named C:\Cloudscape_5.1, the default installation directory on a Windows platform. Note that Cloudscape is not confused by the Windows drive notation or the backslash separators.
  
  
• jdbc:db2j:C:\Temp\Demo\NewDatabase;create=true will create a new database in the C:\Temp\Demo\NewDatabase directory named 'NewDatabase' and establish a connection. If necessary the Temp and Demo directories are created as well. If the database cannot be created, a SQLException is thrown indicating that the database cannot be found. If the database already exists, a connection is established and a SQLWarning is issued.
  
  
• jdbc:db2j:C:\Temp\Demo\Data;user=Mary;password=contrary will establish a connection to the database named 'Data' located in the C:\Temp\Demo\Data directory using Mary as the user identifier and contrary as the password.
  
  
• jdbc:db2j:C:\Temp\Demo\Data;shutdown=true will cause Cloudscape to shutdown the database named 'Data' located in the C:\Temp\Demo\Data directory. This form will shutdown a single database by performing a final checkpoint. The Cloudscape system and any other active database remains active.
  
  
• jdbc:db2j:;shutdown=true will cause Cloudscape to shutdown the entire system. A final checkpoint is performed on all active databases, the Cloudscape JDBC driver is removed from the driver registry, and a SQLException is thrown to indicate that shutdown was successful and no connection was returned.
  
  

For client applications that connect to a Cloudscape network server, the Cloudscape JDBC driver name is com.ibm.db2j.jcc.DB2jDriver and the URL has the following form.

jdbc:db2j:net://host:port/"database[;attributes]"

where

jdbc

is the standard prefix for all JDBC URLs.

db2j

is the subprotocol identifier for a URL that is to be interpreted by the Cloudscape JDBC driver.

net

is the subsubprotocol identifier for a URL that references a remote network server.

host

is replaced with the host name or IP address where the target Cloudscape network server resides.

port

is replaced with the port number where the target Cloudscape network server is listening for requests (1527 by default).

database

is replaced with an identifier that references the Cloudscape database and is typically expressed as a qualified path to the directory that contains the database.

attributes

are optional attributes, separated by semicolons, to be applied to the connection.

Here are some useful examples.

• jdbc:db2j:net://localhost:1527/"C:\Temp\Demo\Data;create=true;
user=Mary;password=contrary"
  will establish a remote connection to a Cloudscape network server on the local host, listening on port 1527. It will create a new database in the C:\Temp\Demo\NewDatabase directory and establish a connection. If necessary the Temp and Demo directories are created as well. If the database cannot be created, a SQLException is thrown indicating that the database cannot be found. If the database already exists, a connection is established and a SQLWarning is issued. For this connection, Mary is the user identifier and contrary is the password.
  
  
• jdbc:db2j:net://localhost:1527/"C:\Temp\Demo\Data;shutdown=true"
  will cause the Cloudscape network server on the local host, listening on part 1527, to shutdown the database located in the C:\Temp\Demo\Data directory. This form will shutdown a single database by performing a final checkpoint. The Cloudscape system and any other active database remains active.
  
  

Improper shutdown and subsequent restart recovery

Note: If Tomcat is shutdown without issuing the proper Cloudscape shutdown, Cloudscape will act as though the system failed. No information will be lost, but when the first database connection is made after Cloudscape is restarted, Cloudscape will use its log files to recover committed transactions and roll back uncommitted transactions. This places the database into a consistent valid state. Recovery can be costly, so using the proper shutdown command improves startup performance.

Back to top

The prototype scenario

This is the simplest scenario. It sacrifices run time efficiency for simplicity. It is usually sufficient for prototype and proof-of-concept development exercises. This scenario has the following properties.

• Everything you need is included in your Web application archive. After installing your finished Web application, there is no need for additional installation tasks to modify the Tomcat configuration.
  
  
• The Cloudscape library can only be accessed by the Web application under development.
  
  
• Every time a form is submitted to HelloCloudscape.jsp, it dynamically loads the Cloudscape JDBC driver. Loading the driver the first time initializes the Cloudscape system. Subsequent loading incurs a little overhead, but otherwise has no effect.
  
  
• Every time a form is submitted to HelloCloudscape.jsp, it creates a new connection.
  
  
• For a given database, Cloudscape activates the database when the first connection is established.
  
  
• If Tomcat is shutdown while a Cloudscape database is active, it is equivalent to a system failure. No database changes are lost, but Cloudscape will have to perform recovery the next time the database is activated.
  
  
• Once the database is active, it cannot be used by any other Cloudscape system until the database is shutdown.

If you have not installed the Web application under development, use these instructions.

1. Stop the Tomcat server.
   
   
2. Download the fixme.zip file and extract to obtain CloudscapeDemo.zip.
   
   
3. Extract CloudscapeDemo.zip into the Tomcat webapps directory (typically InstallDir\webapps where InstallDir is replaced with the Tomcat installation directory name).
   
   
4. Copy db2j.jar from the Cloudscape library into the library for the demonstration Web application (typically InstallDir\webapps\CloudscapeDemo\WEB-INF\lib where InstallDir is replaced with the Tomcat installation directory name).
   
   
5. Start the Tomcat server.
   
   
6. Start your browser and navigate to HelloCloudscape.jsp (typically http://localhost/CloudscapeDemo/HelloCloudscape.jsp).
   
   
7. Test the integration by submitting appropriate JDBC URL and SQL commands in the form provided by HelloCloudscape.jsp.
   
   
8. Develop your Web application. Use the database logic from HelloCloudscape.jsp as sample code for the database logic in your Web application.
   
   
9. Delete HelloCloudscape.jsp from your Web application as soon as it is practical.
   
   

If you have already installed the Web application under development, use these instructions.

1. Download the fixme.zip file and extract to obtain HelloCloudscape.jsp.
   
   
2. Copy HelloCloudscape.jsp into the directory where you place common JSP files for your application (typically InstallDir\webapps\appl where InstallDir is replaced with the Tomcat installation directory name and appl is replaced with your Web application directory name).
   
   
3. Copy db2j.jar from the Cloudscape library into the library for your Web application (typically InstallDir\webapps\appl\WEB-INF\lib where InstallDir is replaced with the Tomcat installation directory name and appl is replaced with your Web application directory name).
   
   
4. Start the Tomcat server.
   
   
5. Start your browser and navigate to HelloCloudscape.jsp (typically http://localhost/appl/HelloCloudscape.jsp where appl is replaced with your application directory name).
   
   
6. Test the integration by submitting appropriate JDBC URL and SQL commands in the form provided.
   
   
7. Continue your Web application development. Use the database logic from HelloCloudscape.jsp as sample code for the database logic in your Web application.
   
   
8. Delete HelloCloudscape.jsp from your Web application as soon as it is practical.
   
   

Back to top

The casual scenario

This scenario allows multiple Web applications and even a Tomcat JDBC realm to use Cloudscape at the same time. In addition, the Tomcat server lifecycle events are used to trigger Cloudscape initialization and shutdown. This scenario has the following properties.

• Minor changes are required to the Tomcat configuration.
  
  
• The Cloudscape library is placed in Tomcat's common library.
  
  
• ServerLifecycleListener, a Java class that implements Tomcat's LifecycleEvent interface is added to the common library.
  
  
• The Tomcat server configuration (server.xml) is modified to register the ServerLifecycleListener class.
  
  
• When Tomcat starts, the ServerLifecycleListener will load the Cloudscape JDBC driver, thus initializing Cloudscape.
  
  
• When Tomcat stops, the ServerLifecycleListener will shutdown the Cloudscape system, thus forcing a final checkpoint to every active database and eliminating the need for recovery processing when the databases are reactivated.
  
  
• Every time a form is submitted to HelloCloudscape.jsp, it creates a new connection.
  
  
• For a given database, Cloudscape activates the database when the first connection is established.
  
  
• Once the database is active, it cannot be used by an other Cloudscape system until the database is shutdown.

For this scenario, follow these instructions.

1. Stop the Tomcat server.
   
   
2. Download the fixme.zip file and extract to obtain CloudscapeCasual.zip and ServerListener.zip.
   
   
3. Extract CloudscapeCasual.zip into the Tomcat webapps directory (typically InstallDir\webapps where InstallDir is replaced with the Tomcat installation directory name).
   
   
4. Extract ServerListener.zip into a convenient directory and review ServerListener\com\ibm\db2j\tomcat\ServerLifecycleListener.java.
   
   
5. Copy the ServerListener\classes directory into Tomcat's server directory (typically InstallDir\server where InstallDir is replaced with the Tomcat installation directory name).
   
   
6. Copy db2j.jar from the Cloudscape library into Tomcat's common library (typically InstallDir\common\lib where InstallDir is replaced with the Tomcat installation directory name).
   
   
7. Backup and edit the Tomcat server configuration (InstallDir\conf\server.xml where InstallDir s replaced with the Tomcat installation directory name) and add the following element at the beginning of the <Server> element.
   
   <Listener
className="com.ibm.db2j.tomcat.ServerLifecycleListener"
debug="0" />
   
   
8. Start the Tomcat server.
   
   
9. Start your browser and navigate to HelloCloudscape.jsp (typically http://localhost/CloudscapeCasual/HelloCloudscape.jsp).
   
   
10. Test the integration by submitting appropriate JDBC URL and SQL commands in the form provided.
    
    
11. Continue your Web application development. Use the database logic from HelloCloudscape.jsp as sample code for the database logic in your Web application.
    
    
12. Delete the CloudscapeCasual directory from your Tomcat Web applications as soon as it is practical.
    
    

Back to top

The enterprise scenario

Like the casual scenario, this scenario allows multiple Web applications and even a Tomcat security realm to use Cloudscape at the same time. Unlike the casual Scenario, it adds a Cloudscape network server so that remote applications and administration tools can access the database while it is being used by Web applications. This scenario has the following properties.

• Changes are required to the Tomcat configuration.
  
  
• The catalina.properties files is modified so that the entire Cloudscape library is included in common classpath.
  
  
• ServerLifecycleListenerWithNetworkServer, a Java class that implements Tomcat's Lifecycle Event interface, is added to the common library.
  
  
• The tomcat server configuration (server.xml) is modified to
  
  
• Register the ServerLifecycleListenerWithNetworkServer class
  
  
• Define a global JNDI resource for a Cloudscape data source
  
  
• Define a default context that links to the global Cloudscape data source
  
  
• There is no need to copy the jar files into the Tomcat directory tree. Instead, the Cloudscape JAR files are included in the classpath common to Tomcat and all Web applications. Fixes and upgrades can be applied to the Cloudscape installation and the Tomcat site will automatically use them.
  
  
• When Tomcat starts, the ServerLifecycleListenerWithNetworkServer will load the Cloudscape JDBC driver, thus initializing Cloudscape, and start a network server to handle remote requests.
  
  
• When Tomcat stops, the ServerLifecycleListenerWithNetworkServer will shutdown the network server and Cloudscape, thus forcing a final checkpoint to every active database and eliminating the need for recovery processing when the databases are reactivated.
  
  
• When a form is submitted to HelloCloudscape.jsp, it uses the data source name provided to obtain a connection from the connection pool managed by the data source.
  
  
• As always, for a given database, Cloudscape activates the database when the first connection is established.
  
  
• When a database is active, other Cloudscape systems can still access the database by using remote access.

For this scenario, follow these instructions.

1. Stop the Tomcat server.
   
   
2. Download the fixme.zip file and extract to obtain CloudscapeEnterprise.zip and ServerListener.zip files.
   
   
3. Extract CloudscapeEnterprise.zip into the Tomcat webapps directory (typically InstallDir\webapps where InstallDir is replaced with the Tomcat installation directory name).
   
   
4. Extract ServerListener.zip into a convenient directory and review ServerListener\com\ibm\db2j\tomcat\ServerLifecycleListenerWithNetworkServer.java.
   
   
5. Copy the ServerListener\classes directory into Tomcat's server directory (typically InstallDir\server where InstallDir is replaced with the Tomcat installation directory name).
   
   
6. Backup and edit the catalina.properties file (typically InstallDir\conf\catalina.properties where InstallDir is replaced with the Tomcat installation directory name).
   
   
1. Find the common.loader key.
   
   
2. At the end of the value assigned to this key, add a comma and a wildcard for all the Cloudscape jar files (typically CloudDir/lib/*.jar where CloudDir is replaced with the Cloudscape installation directory name). This will add all the Cloudscape JAR files to the classpath that is common to Tomcat and all the Web applications.
   
   
3. Save the updated file.
   
   
7. Backup and edit the Tomcat server configuration (InstallDir\conf\server.xml where InstallDir is replaced with the Tomcat installation directory name).
   
   
1. Find the <Server> element in the configuration document.
   
   
2. Add the following element at the beginning of the <Server> element.
   
   <Listener className=
"com.ibm.db2j.tomcat.ServerLifecycleListener
WithNetworkServer" debug="0" />
   
   
3. Find the <GlobalNamingResources> element in the configuration document.
   
   
4. Add the following element into the <GlobalNamingResources> element.
   

   <!-- Datasource for Cloudscape sample database --> <Resource name="jdbc/Tours" type="javax.sql.DataSource" auth="Container" description="Cloudscape sample database" />

   
   Note that the value specified for the name attribute becomes the data source name and must match the references in the other elements.
   
   
5. Add the following element into the <GlobalNamingResources> element after the <Resource> element added above.
   

   <!-- Resource parameters for the Cloudscape sample database --> <ResourceParams name="jdbc/Tours"> <parameter> <name>maxWait</name> <value>5000</value> </parameter> <parameter> <name>maxActive</name> <value>4</value> </parameter> <parameter> <name>url</name> <value>jdbc:db2j:C:/Cloudscape_5.1/demo/databases/toursDB</value> </parameter> <parameter> <name>driverClassName</name> <value>com.ibm.db2j.jdbc.DB2jDriver</value> </parameter> <parameter> <name>maxIdle</name> <value>2</value> </parameter> </ResourceParams>

   
   Note that the value of the name attribute must be the same as the value specified for the name attribute in the matching <Resource> element.
   
   In this example, the url parameter specifies the sample database provided with Cloudscape and you may need to change the value to match your environment. In addition, if your database requires user authentication, you will need to add parameter definitions for user and password.
   
   
6. Find the <Engine>> element in the configuration document.
   
   
7. If the current <Engine> element does not have a <DefaultContext>, add the following segment at the beginning of the <Engine> element. Otherwise, copy the <ResourceLink> element from this example into the existing <DefaultContext>.
   

   <!-- The default context element is used to provide configuration settings to represent default configuration properties for contexts that are automatically created. --> <DefaultContext> <!-- This resource link adds the global data source to all Web applications. --> <ResourceLink name="jdbc/Tours" global="jdbc/Tours" type="javax.sql.DataSource" /> </DefaultContext>

   
   Note that the value of the name attribute must be the same as the value specified for the name attribute in the matching <Resource> element.
   
   This example assumes that the data source is to have a global scope. Alternatively, to limit the scope of a data source, the <ResourceLink> element can be placed in the context of each Web application that will reference the data source. See the Tomcat configuration documentation for more information.
   
   
8. Save the updated file.
   
   
8. Backup and edit the Web application deployment descriptor (InstallDir\webapps\CloudscapeEnterprise\WEB-INF\web.xml where InstallDir s replaced with the Tomcat installation directory name).
   
   
1. Find the example <resource-ref> element in the document. It will look like this.
   

   <resource-ref> <description> This element references a resource factory for a data source that provides java.sql.Connection instances that connect to a particular database that is configured in the server.xml file. Its resource reference name must match the resource name defined there. By using a resource reference, the servlets and JavaServer pages remain independent of the JDBC driver names and JDBC URLs while gaining the performance advantage of a connection pool. </description> <res-ref-name> jdbc/Tours </res-ref-name> <res-type> javax.sql.DataSource </res-type> <res-auth> Container </res-auth> </resource-ref>

   
   Note that the body of the <res-ref-name> element must be the same as the value of the name attribute of the matching <Resource> element in the Tomcat configuration.
   
   
2. If you have not modified the resource name used in this example, no change is needed. If you have modified the resource name, modify the body of <res-ref-name> element to match. If you have added additional data source definitions, use this <resource-ref> element as a template and add a reference to each data source that you would like to test.
   
   
3. Save the modified file
   
   
9. Start the Tomcat server.
   
   
10. Start your browser and navigate to HelloCloudscape.jsp (typically http://localhost/CloudscapeEnterprise/HelloCloudscape.jsp).
    
    
11. Test the integration by submitting the appropriate JDBC data source name (""jdbc/Tours"" if you followed this example) and SQL commands in the form provided.
    
    
12. Continue your Web application development. Use the database logic from HelloCloudscape.jsp as sample code for the database logic in your Web application. Use the example configuration changes described here as templates to create the JDBC data source definitions for your application. Remember, you must restart Tomcat whenever you change the server configuration.
    
    
13. Tune your data source as necessary
    
    
14. Remove the example data source from the Tomcat configuration and delete the CloudscapeEnterprise directory from your Tomcat Web applications as soon as it is practical.
    
    

Back to top

Implementing a Tomcat realm with Cloudscape

A realm is a repository of

• Logon identifiers (also known as user names) that identify a user
• Passwords that are used to authenticate a given logon identifier
• Roles that each user is authorized to assume.

Tomcat implements container managed security by connecting to a realm and using the data stored there to authenticate users and verify their right to access servlets and JavaServer pages. Cloudscape tables can be used as the repository for the realm.

To implement a realm in a database, Tomcat requires

• A table, often called the users table, that contains at least two columns, one for the logon identifier and one for the password.
  
  
• Another table, often called the roles table, that contains a least two columns, one for the logon identifier that uses the same column name as the users table, and one for the name of a role assigned to that logon identifier.

Note that a given logon identifier must be unique but can be assigned to any number of roles. You are free to choose any table name and any column name because Tomcat can be configured to use the names you have chosen.

Follow these instructions to create a realm.

1. Download the fixme.zip file and extract to obtain the Sql.zip file.
   
   
2. Extract Sql.zip into a convenient directory and review the files provided.
   
   CrtUsers.bat is used to create and initialize your tables. It uses the Cloudscape ij utility to process the CrtUsers.sql SQL script.
   
   DrpUsers.bat is used to drop your tables. It is handy when you have made an error so severe, the best option is to erase the tables and start over. Like CrtUsers.bat, it uses the Cloudscape ij utility to process the DrpUsers.sql SQL script.
   
   
3. In CrtUsers.bat, check the values of the CLOUD_HOME and CATALINA_HOME environment variables. If necessary, edit the file and change the values to match your installation.
   
   
4. Similarly, in DrpUsers.bat, check the values of the CLOUD_HOME and CATALINA_HOME environment variables. If necessary, edit the file and change the values to match your installation.
   
   
5. Edit CrtUsers.sql.
   
   
1. If necessary, modify the CONNECT statement so that the JDBC URL specifies the directory where you would like the database to be created.
   
   
2. If necessary, modify the schema for the tables named Users and Roles.
   
   
3. Modify the first INSERT statement to define your site administrator. If you have modified the Users table schema, be sure to make the matching changes to the Insert statement.
   
   
4. If necessary, add INSERT statements for any other users and roles that you would like to add during initialization.
   
   
5. To be compatible with the Tomcat demonstration programs, the script contains definitions for 3 users, named tomcat, both, and role1. If you intend to use the sample programs, modify these definitions to match your schema changes. Otherwise, just delete the user definitions and their role definitions.
   
   
6. Save the modified SQL script.
   
   
6. Edit DrpUsers.sql.
   
   
1. If necessary, modify the CONNECT statement so that the JDBC URL matches the value specified in CrtUsers.sql.
   
   
2. If necessary, modify the DROP statements so that the table names match the names specified in CrtUsers.sql.
   
   
3. Save the modified script.
   
   
7. Open a command prompt, change the current directory to the directory that contains the scripts, and execute CrtUsers.bat. Examine the output to verify that all the commands were processed successfully. If there are errors or if you decide to make changes, execute DrpUsers.bat to drop the tables and start over.

Once you have implemented a realm in Cloudscape tables, you must configure Tomcat to use the realm. There are two alternatives.

1. Define a JDBC realm. This is the simplest solution if the database is used exclusively by Tomcat for container managed security.
   
   
2. Define a data source realm. This is the best solution if Web applications also read and/or update the information in the realm's tables. In this case, you will benefit from efficient connection pooling and keep all the Web applications independent of the database driver and JDBC URL.

Back to top

Configuring a Tomcat JDBC realm that uses Cloudscape

Follow these instructions to configure a JDBC realm that uses Cloudscape.

1. Stop the Tomcat server.
   
   
2. Backup and edit the Tomcat server configuration (InstallDir\conf\server.xml where InstallDir is replaced with the Tomcat installation directory name).
   
   
1. Find the <Engine>> element in the configuration document.
   
   
2. If necessary, remove any existing <Realm> elements nested in the <Engine> element.
   
   
3. Add the following <Realm> element to the <Engine> element.
   

   <Realm className="org.apache.catalina.realm.JDBCRealm" debug="99" driverName="com.ibm.db2j.jdbc.DB2jDriver" connectionURL= "jdbc:db2j:C:\Program Files\Apache Software Foundation\Tomcat 5.0\Realm" userTable="Users" userNameCol="LogonId" userCredCol="Password" userRoleTable="Roles" roleNameCol="Role" />

   
   If necessary, replace the attribute values for userTable, userNameCol, userCredCol, userRoleTable, and roleNameCol to match the values used in your schema.
   
   In this example, the connectionURL parameter specifies the Cloudscape database that implements the realm. It should match the URL that was used to create the tables so you may need to change the value to match your environment. In addition, if your database requires user authentication, you will need to add values for connectionUser and connectionPassword attributes.
   
   
4. Save the updated file.
   
   
3. Start the Tomcat server.
   
   
4. Test the logon identifiers and roles that you defined in your initial realm. Be sure that the Tomcat administrator can use the administration Web application. Exercise both valid and invalid use cases.
   
   
5. Remove the extraneous users and roles from the realm as soon as it is practical. Update your realm as necessary.
   
   

Back to top

Configuring a Tomcat data source realm that uses Cloudscape

Follow these instructions to configure a data source realm that uses Cloudscape.

1. Stop the Tomcat server.
   
   
2. Backup and edit the Tomcat server configuration (InstallDir\conf\server.xml where InstallDir is replaced with the Tomcat installation directory name).
   
   
1. Find the <GlobalNamingResources> element in the configuration document.
   
   
2. Add the following element into the <GlobalNamingResources> element.
   

   <!-- Datasource for Cloudscape realm database --> <Resource name="jdbc/Realm" type="javax.sql.DataSource" auth="Container" description="Cloudscape sample database" />

   
   Note that the value specified for the name attribute becomes the data source name and must match the references in the other elements.
   
   
3. Add the following element into the <GlobalNamingResources> element after the <Resource> element added above.
   
   

   <!-- Resource parameters for the Cloudscape realm database --> <ResourceParams name="jdbc/Realm"> <parameter> <name>maxWait</name> <value>5000</value> </parameter> <parameter> <name>maxActive</name> <value>4</value> </parameter> <parameter> <name>url</name> <value>jdbc:db2j:C:\Program Files\Apache Software Foundation\Tomcat 5.0\Realm</value> </parameter> <parameter> <name>driverClassName</name> <value>com.ibm.db2j.jdbc.DB2jDriver</value> </parameter> <parameter> <name>maxIdle</name> <value>2</value> </parameter> </ResourceParams>

   
   Note that the value of the name attribute must be the same as the value specified for the name attribute in the matching <Resource> element.
   
   In this example, the url parameter specifies the Cloudscape database that implements the realm. It should match the URL that was used to create the tables so you may need to change the value to match your environment. In addition, if your database requires user authentication, you will need to add parameter definitions for user and password.
   
   
4. Find the <Engine>> element in the configuration document.
   
   
5. If the current <Engine> element does not have a <DefaultContext>, add the following segment at the beginning of the <Engine> element. Otherwise, copy the <ResourceLink> element from this example into the existing <DefaultContext>.
   

   <!-- The default context element is used to provide configuration settings to represent default configuration properties for contexts that are automatically created. --> <DefaultContext> <!-- This resource link adds the global data source to all Web applications. --> <ResourceLink name="jdbc/Realm" global="jdbc/Realm" type="javax.sql.DataSource" /> </DefaultContext>

   
   Note that the value of the name attribute must be the same as the value specified for the name attribute in the matching <Resource> element.
   
   This example assumes that the data source is to have a global scope. Alternatively, to limit the scope of a data source, the <ResourceLink> element can be placed in the context of each Web application that will reference the data source. See the Tomcat configuration documentation for more information.
   
   
6. If necessary, remove any existing <Realm> elements nested in the <Engine> element.
   
   
7. Add the following <Realm> element to the <Engine> element.
   

   <Realm className="org.apache.catalina.realm.DataSourceRealm" debug="99" dataSourceName="jdbc/Realm" userTable="Users" userNameCol="LogonId" userCredCol="Password" userRoleTable="Roles" roleNameCol="Role" />

   
   If necessary, replace the attribute values for userTable, userNameCol, userCredCol, userRoleTable, and roleNameCol to match the values used in your schema.
   
   
8. Save the updated file.
   
   
3. For each Web application that will read or update the Cloudscape realm, backup and edit the Web application deployment descriptor (InstallDir\webapps\AppName\WEB-INF\web.xml where InstallDir is replaced with the Tomcat installation directory name and AppName is replaced with the Web application directory name).
   
   
1. In the position dictated by the document type definition (DTD), add a <resource-ref> element. Use this as a template.
   

   <resource-ref> <description> This element references a resource factory for a data source that provides the Cloudscape realm. </description> <res-ref-name> jdbc/Realm </res-ref-name> <res-type> javax.sql.DataSource </res-type> <res-auth> Container </res-auth> </resource-ref>

   
   Note that the body of the <res-ref-name> element must be the same as the value of the name attribute of the matching <Resource> element in the Tomcat configuration.
   
   
2. Save the modified file
   
   
4. Start the Tomcat server.
   
   
5. Test the logon identifiers and roles that you defined in your initial realm. Be sure that the Tomcat administrator can use the administration Web application. Exercise both valid and invalid use cases.
   
   
6. Remove the extraneous users and roles from the realm as soon as it is practical. Update your realm and tune the data source as necessary.
   
   

Back to top

Configuring a Tomcat data source realm that uses Cloudscape

Follow these instructions to configure a data source realm that uses Cloudscape.

1. Stop the Tomcat server.
   
   
2. Backup and edit the Tomcat server configuration (InstallDir\conf\server.xml where InstallDir is replaced with the Tomcat installation directory name).
   
   
1. Find the <GlobalNamingResources> element in the configuration document.
   
   
2. Add the following element into the <GlobalNamingResources> element.
   

   <!-- Datasource for Cloudscape realm database --> <Resource name="jdbc/Realm" type="javax.sql.DataSource" auth="Container" description="Cloudscape sample database" />

   
   Note that the value specified for the name attribute becomes the data source name and must match the references in the other elements.
   
   
3. Add the following element into the <GlobalNamingResources> element after the <Resource> element added above.
   
   

   <!-- Resource parameters for the Cloudscape realm database --> <ResourceParams name="jdbc/Realm"> <parameter> <name>maxWait</name> <value>5000</value> </parameter> <parameter> <name>maxActive</name> <value>4</value> </parameter> <parameter> <name>url</name> <value>jdbc:db2j:C:\Program Files\Apache Software Foundation\Tomcat 5.0\Realm</value> </parameter> <parameter> <name>driverClassName</name> <value>com.ibm.db2j.jdbc.DB2jDriver</value> </parameter> <parameter> <name>maxIdle</name> <value>2</value> </parameter> </ResourceParams>

   
   Note that the value of the name attribute must be the same as the value specified for the name attribute in the matching <Resource> element.
   
   In this example, the url parameter specifies the Cloudscape database that implements the realm. It should match the URL that was used to create the tables so you may need to change the value to match your environment. In addition, if your database requires user authentication, you will need to add parameter definitions for user and password.
   
   
4. Find the <Engine>> element in the configuration document.
   
   
5. If the current <Engine> element does not have a <DefaultContext>, add the following segment at the beginning of the <Engine> element. Otherwise, copy the <ResourceLink> element from this example into the existing <DefaultContext>.
   

   <!-- The default context element is used to provide configuration settings to represent default configuration properties for contexts that are automatically created. --> <DefaultContext> <!-- This resource link adds the global data source to all Web applications. --> <ResourceLink name="jdbc/Realm" global="jdbc/Realm" type="javax.sql.DataSource" /> </DefaultContext>

   
   Note that the value of the name attribute must be the same as the value specified for the name attribute in the matching <Resource> element.
   
   This example assumes that the data source is to have a global scope. Alternatively, to limit the scope of a data source, the <ResourceLink> element can be placed in the context of each Web application that will reference the data source. See the Tomcat configuration documentation for more information.
   
   
6. If necessary, remove any existing <Realm> elements nested in the <Engine> element.
   
   
7. Add the following <Realm> element to the <Engine> element.
   

   <Realm className="org.apache.catalina.realm.DataSourceRealm" debug="99" dataSourceName="jdbc/Realm" userTable="Users" userNameCol="LogonId" userCredCol="Password" userRoleTable="Roles" roleNameCol="Role" />

   
   If necessary, replace the attribute values for userTable, userNameCol, userCredCol, userRoleTable, and roleNameCol to match the values used in your schema.
   
   
8. Save the updated file.
   
   
3. For each Web application that will read or update the Cloudscape realm, backup and edit the Web application deployment descriptor (InstallDir\webapps\AppName\WEB-INF\web.xml where InstallDir is replaced with the Tomcat installation directory name and AppName is replaced with the Web application directory name).
   
   
1. In the position dictated by the document type definition (DTD), add a <resource-ref> element. Use this as a template.
   

   <resource-ref> <description> This element references a resource factory for a data source that provides the Cloudscape realm. </description> <res-ref-name> jdbc/Realm </res-ref-name> <res-type> javax.sql.DataSource </res-type> <res-auth> Container </res-auth> </resource-ref>

   
   Note that the body of the <res-ref-name> element must be the same as the value of the name attribute of the matching <Resource> element in the Tomcat configuration.
   
   
2. Save the modified file
   
   
4. Start the Tomcat server.
   
   
5. Test the logon identifiers and roles that you defined in your initial realm. Be sure that the Tomcat administrator can use the administration Web application. Exercise both valid and invalid use cases.
   
   
6. Remove the extraneous users and roles from the realm as soon as it is practical. Update your realm and tune the data source as necessary.
   
   

Back to top

Addenda

Installing Tomcat to use the IBM Java development kit

There are several Tomcat packages that can be installed on a Windows platform. For Tomcat Version 5.0.19, one of those packages, the file with a .EXE suffix, includes a Windows installer that simplifies the install process, but the installer contains a defect that prevents automatic integration with the IBM Java development kit.

The defective Windows installer attempts to obtain information about the installed Jave development kit by using the Windows registry. Apparently, it searches for the registry keys created when the Sun Java development kit is installed. When the IBM Java development kit is installed, it uses different registry keys and the installer does not find the information it requires. As a result, even if the installation appears to be successful, Tomcat scripts fail because the Jave development kit cannot be found.

This defect can be circumvented by duplicating the IBM Java development kit registry information using the Sun Java development kit keys. Here is an example procedure.

1. Install the IBM Jave development kit by following the directions supplied with the package.
2. Create a new system environment variable named JAVA_HOME with a value that contains the directory name where the IBM Java development kit was installed.
3. Start regedit and navigate to the key named HKEY_LOCAL_MACHINE\SOFTWARE\IBM\Java2 Runtime Environment. Examine each value in the tree and record its data.
4. Download the fixme.zip file and extract to obtain TomcatRegistryFix.reg.
5. Use notepad or your favorite text editor to edit TomcatRegistryFix.reg and, if necessary, change the data to match the data recorded from the IBM keys above.
6. Use the regedit import function to import TomcatRegistryFix.reg into the registry.
7. Install Tomcat using the Windows installer.

Modifying the Default Tomcat SSL Connector to use the IBM Java Virtual Machine

The Secure Sockets Layer (SSL) protects Web messages as they fly through the network. When SSL is used, Web messages cannot be modified or observed by attackers at any intermediate node.

SSL implementations are not part of the common Java runtime. Instead, each vendor is responsible for obtaining a license for the SSL technology and providing an SSL implementation for their Java virtual machine (JVM). This means that SSL configuration depends on the SSL implementation provided by the vendor.

In the Tomcat server configuration (typically InstallDir\conf\server.xml where InstallDir is replaced with the Tomcat installation directory name), SSL support is configured on a <Connector> element. When using the IBM Java Virtual Machine, the following attributes must be configured properly for the IBM SSL implementation.

See the SSL Configuration HOW-TO in the Tomcat documentation for more information.

Back to top

Download

Name	Size	Download method
fixme.zip	8.47 KB	FTP | HTTP

Information about download methods

Resources

Download the fixme.zip file and unzip to obtain the following files, referenced in this article:

catalina.properties

An example Tomcat configuration file taken from the site where these materials were tested. Residing at InstallDir\conf, where InstallDir is replaced with the Tomcat installation directory name, this file contains the properties used to initialize the class path information for the various Tomcat loaders. This file has been modified so that the Cloudscape libraries (JAR files) are included in the class path of the loader common to Tomcat and all the Web applications.

CloudscapeCasual.zip

A compressed archive that contains the Web application used to test a casual integration. This Web application can be deployed by extracting the contents of this file into InstallDir\webapps, where InstallDir is replaced with the Tomcat installation directory name.

CloudscapeDemo.zip

A compressed archive that contains the Web application used to test a prototype or proof-of-concept integration. This Web application can be deployed by extracting the contents of this file into InstallDir\webapps, where InstallDir is replaced with the Tomcat installation directory name.

CloudscapeEnterprise.zip

A compressed archive that contains the Web application used to test an enterprise integration. This web application can be deployed by extracting the contents of this file into InstallDir\webapps, where InstallDir is replaced with the Tomcat installation directory name.

HelloCloudscape.jsp

The test program from CloudscapeDemo.zip, provided as a stand-alone file for those who want to mix it into their existing Web application.

server.xml

An example Tomcat configuration file taken from the site where these materials were tested. Residing at InstallDir\conf, where InstallDir is replaced with the Tomcat installation directory name, this file contains the Tomcat server configuration. This file has been modified for the enterprise integration, including a data source realm.

ServerListener.zip

A compressed archive that contains Java classes that implement the Tomcat EventListener interface. When properly registered with the Tomcat server, these classes start and stop Cloudscape when the Tomcat server starts and stops.

Sql.zip

A compressed archive that contains scripts that create and drop Cloudscape database tables used to implement an example realm.

TomcatRegistryFix.reg

A Windows registry import file that shows example definitions that register the IBM Java libraries using the Sun Java registry keys. Be sure to verify that the values in this file match your configuration before you import it into your Windows registry.

Additional information may be found in these references.

• Apache Tomcat is a subproject in the Jakarta Project. Binaries and source are available for download.
  
  
• Tomcat documentation explains how to setup and use the Tomcat servlet container.
  
  
• Cloudscape is a database product offered by IBM. An evaluation download and developer support is available.
  
  
• Tomcat: The Definitive Guide (O'Reilly & Associates; 2003), by Jason Brittain and Ian F. Darwin, is an excellent reference on all aspects of Jakarta Tomcat, including installation on all platforms, interactions with the Web server, security administration, and Web application deployment.
  
  

About the author

Lance D Bader is a Senior Software Engineer on the Business Partner Technical Support team in the United States. On this team, he supports IBM Business Partners who need to integrate their software with IBM WebSphere products. He has over a quarter century experience in data communications spanning from dumb terminal support in IBM Series/1 minicomputers through High Performance Routing in IBM's System Network Architecture (SNA) to business application integration in IBM WebSphere Commerce. He holds a Bachelor of Science degree in Computer Science from North Dakota State University.

Rate this article

Comments

Back to top

Table of contents

• Overview
• The prototype scenario
• The casual scenario
• The enterprise scenario
• Implementing a Tomcat realm with Cloudscape
• Configuring a Tomcat JDBC realm that uses Cloudscape
• Configuring a Tomcat data source realm that uses Cloudscape
• Configuring a Tomcat data source realm that uses Cloudscape
• Addenda
• Download
• Resources
• About the author
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

Dig deeper into Information Management on developerWorks

Discover knowledge paths

Skill-building guides for Information Management, Linux, open source, cloud, Java, business analytics, and more.

Special offers