Home > wikikonf >  tom/actions/by kikonf > datasrc



Action : tom.datasrc   (Category : tom, Name : datasrc, By : kikonf)
Complete Name :
Version : 4.0        License : Modified BSD License

Purpose of the tom category :
Easy to customize. This category use in background the Kikonf Repoz tools to create and configure Apache Tomcat root installs and Catalina bases at any level (server.xml, hosts or defaults).
You can use it to manage the whole Tomcat Architecture.

Purpose of this datasrc plugin : This Action configures a JDBC Datasource (JNDI).

The following shows in what part of a typical Architecture is likely to be found, the Resource configured by Action : tom.datasrc

This Action configures a JDBC Datasource (JNDI).


In order the DataSource layer to work into your Tomcat configuration you should consider these two points :

1.1. In Tomcat a dataSource is a specific kind of Resource factory based on the DBCP connection pool,
it mays not be installed by default.
So you may need to install it from the Apache Commons subproject at

A known limitation of the DBCP connection pool is that it is single-threaded.
If you seek for better performance you may want also to check and rather install the
SpringSource tc Server 6.0 Tomcat JDBC Connection Pool.

1.2 The Kikonf datasrc Action is bound to a specific Database through the Attribute datasrc@dbtype currently
supporting: Derby(TM), HSQL(TM), PostgreSQL, MySQL(TM), Oracle(TM) and DB2(TM).

You have to install the Drivers jar files for the provider of any of those Database (Generally picked up
from a sub folder named "java" from the installation directory of the Database software itself)
into either $CATALINA_HOME/common/lib or CATALINA_BASE/lib.

The known file for each Editor are the following.
(Excerpt from the Tomcat official site, jndi-datasource-examples-howto)

Apache Derby drivers:

Hypersonic SQL drivers:
HSQL driver JAR

PostgreSQL drivers:
Postgres JDBC jar.

MySQL drivers:
Versions of MySQL and JDBC drivers that have been reported to work:
* MySQL 3.23.47, MySQL 3.23.47 using InnoDB,, MySQL 3.23.58, MySQL 4.0.1alpha
* Connector/J 3.0.11-stable (the official JDBC Driver)
* mm.mysql 2.0.14 (an old 3rd party JDBC Driver)

Oracle drivers:
Drivers for older Oracle versions may be distributed as *.zip files rather than *.jar files.
Therefore or will need to be renamed with a .jar extension.
Since jarfiles are zipfiles, there is no need to unzip and jar these files - a simple rename will suffice.

For Oracle 9i onwards you should use oracle.jdbc.OracleDriver rather than oracle.jdbc.driver.OracleDriver as
Oracle have stated that oracle.jdbc.driver.OracleDriver is deprecated and support for this driver class
will be discontinued in the next major release.

DB2 drivers:
db2jcc_license_cisuz.jar and/or db2jcc_license_cu.jar


The following is a general rule for all for all the JNDI Resources configured inside Tomcat >= 5.

JNDI Resources can de declared at the global level or at the context level.

(Excerpt from the tomcat standard documentation at jndi-resources-howto.html:)
Tomcat 5 maintains a separate namespace of global resources for the entire server. 
These are configured in the <GlobalNamingResources> element of $CATALINA_BASE/conf/server.xml.
You may expose these resources to web applications by using a <ResourceLink> to include it in the per-web-application context.

Converted into the Kikonf scheme the previous stanza means that the scope for a JNDI Resource is either :
_ Global using  scope : true
_ Local using scope context (and/or an affiliated :,, default_context)

When the Global Scope is requested for an Action setting to "true" into the Action file.
The use of context (and/or an affiliated :,, default_context) is allowed.
In this case the resource is declared at the Global level.
But a ResourceLink is also created for the provided context Scope.
This is the reason why, all the Kikonf Actions for Tomcat JNDI Resources always support a "link" tag.


The following is a short tutorial about how to use a DataSource with Tomcat.

3.1 The JDBC Datasource declaration

Only if the Kikonf datasrc Action 's Tag "resource" has been filled.

3.1.1 New entry into server.xml or the context file

The Kikonf datasrc Action adds this entry (either the Global Level inside the the node GlobalNamingResource of the
CATALINA_HOME/conf/server.xml or at the context Level)


3.2 Referencing the DB2 JDBC Resource

Only if the Kikonf datasrc Action 's Tag "link" has been filled and information about the target Context is provided
into the "scope" Tag.

3.2.1  New entry into the Tomcat context file

The Kikonf datasrc Action adds this entry inside the Context node:

<ResourceLink global="jdbc/SOMETHING" name="jdbc/SOMETHING" type="javax.sql.DataSource"/ >

(Excerpt from the tomcat standard documentation at jndi-resources-howto.html:)
If a resource has been defined using a <ResourceLink>, it is not necessary for that resource to be defined in
However, it is recommended to keep the entry in /WEB-INF/web.xml to document the resource requirements for
the web application.

3.2.2  New entry into the Web Application web.xml

As recommended (but not required if you use filled <datasrc/link>) you may add this entry into your
web application deployment descriptor (/WEB-INF/web.xml).
By convention, all such names should resolve to the subcontext (relative to the standard java:comp/env naming context
that is  the root of all provided resource factories. A typical web.xml entry might look like this:

<description>DB Connection Pool </description>
<res-ref-name >jdbc/SOMETHING</res-ref-name>

Trademarks :
  • "IBM", "WebSphere MQ", "Db2" and "AIX" are registred trademarks of International Business Machines Corporation.
  • "Oracle", "MySql", "Java" and "JVM" are a registred trademarks of Oracle and/or its affiliates.
  • "Linux" is a trademark registred to Linus Torvalds
  • "MS SQL Server" is a registred trademark of Microsoft Corporation.
  • "Apache", "Apache Tomcat" and "Tomcat" are trademarks of the Apache Software Foundation.
  • "Java" and "JVM" are a registred trademarks of Oracle and/or its affiliates.
  • Other names may be trademarks of their respective owners.

Copyright © 2011 - Patrick Placidoux, Hélène Malamoud