Creating a Tomcat context file

In an enterprise environment databases are often accessed through a data source. This guide will show you how to configure your Tomcat with a data source that connects to a local MySQL database server.

In Tomcat data sources are defined within the applications context. The context may be declared either embedded or external to the application. When the context is embedded it is defined in the file context.xml, which must be located inside the WAR file inside the META-INF folder. When declared externally the file must be located in Tomcat's /conf/Catalina/localhost folder and the name of the file must be ManagementConsole.xml (same name as the deployed WAR file). Although Tomcat recommends deploying with an embedded context, as it provides a single deployment unit, we will use an external context definition in this guide, as it makes modifying the file easier. Once you have refined your configuration, you can embed the context file and deploy the War file to your production environment.

Adding platform data source

Create the file ManagementConsole.xml inside Tomcat's/conf/Catalina/localhost folder and add the following content:

    <Context useHttpOnly="true">
        <!-- Default set of monitored resources -->
        <WatchedResource>WEB-INF/web.xml</WatchedResource>

        <Resource name="jdbc/kapow/platform" auth="Container" type="javax.sql.DataSource"
               maxActive="100" maxIdle="30" maxWait="-1"
               validationQuery="/* ping */" testOnBorrow="true"
               username="MyUser" password="MyPassword" driverClassName="com.mysql.jdbc.Driver"
               url="jdbc:mysql://localhost:3306/KAPOW_MC?useUnicode=yes&amp;characterEncoding=UTF-8&amp;rewriteBatchedStatements=true"/>

    </Context>

The url parameter above is a JDBC URL. The username and password attributes are used by Tomcat to create a connection pool used when connecting to the database.

The data sources are defined differently for other databases. For instance, if you are using Microsoft SQL Server 2005/2008, the relevant three lines above should instead be:

                       username="MyUser" password="MyPassword"
                       driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
                       validationQuery="SELECT 1" testOnBorrow="true"
                       url="jdbc:sqlserver://localhost:1433;DatabaseName=MyDbName"/> 

Note that if you are using Microsoft SQL Server, you need to configure it to use mixed mode authentication. Generally, you should consult the JDBC documentation to identify which values to use in the data sources.

The URL jdbc:mysql://localhost:3306/KAPOW_MC?useUnicode=yes&amp;characterEncoding=UTF-8 refers to a database named KAPOW_MC in our local MySQL. For MySQL it is recommended that you add ?useUnicode=yes&characterEncoding=UTF-8 to all connection strings, otherwise the JDBC driver will not handle Chinese, Japanese or other 3-byte utf-8 characters correctly, since we can't have & directly inside the context xml file, we must encode it as &amp;

rewriteBatchedStatements=true instructs the MySQL JDBC driver batch inserts/updates, this should give improved insert performance for kapplet robots.

The driverClassName parameter controls which JDBC driver is used; each database vendor provides a JDBC driver for their database, which you will have to download. The JDBC driver, typically a single .jar file, must be copied into the /lib folder on Tomcat 6/7, or commons/lib on Tomcat 5.5.

The validationQuery is used by Tomcat to verify that the connection obtained from the connection pool is still valid (as the database server may have closed the connection). The validation query is lightweight and uses very few resources on the database server, this list contains validation queries for the supported databases.

Database

Query

MySQL

/* ping */

Microsoft SQL Server 2005/2008

SELECT 1

Sybase Adaptive Server Enterprise

SELECT 1

IBM DB2

VALUES(1)

Oracle

SELECT 1 FROM DUAL

Validation queries


Note that the MySQL JDBC driver supports a special lightweight /* ping */ 'request', check JConnector manual section 6.1 for details

For more information on context configuration and data sources, see JNDI Resources HOW-TO and JNDI data source HOW-TO.

We are now ready to start the Tomcat server