Action :
tom.datasrc (Category :
tom, Name :
datasrc, By :
kikonf)
Complete Name :
tom.datasrc.by.kikonf
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).
1. PRERIQUISITES
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 http://commons.apache.org/dbcp/configuration.html.
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 http://tomcat.apache.org, jndi-datasource-examples-howto)
Apache Derby drivers:
---------------------
derby.jar
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 classes111.zip or classes12.zip 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.jar
db2jcc_license_cisuz.jar and/or db2jcc_license_cu.jar
2. TOMCAT JNDI RESOURCES NAMESPACES
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 resources.global : true
or
_ Local using scope context (and/or an affiliated : context.global, default_context.global, default_context)
Note:
-----
When the Global Scope is requested for an Action setting resources.global to "true" into the Action file.
The use of context (and/or an affiliated : context.global, default_context.global, 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.
3. USING JDBC DATASOURCE WITH TOMCAT
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)
e.g.:
<Resource
jndi_name="jdbc/SOMETHING"
username="USER"
password="PASSWORD
url="jdbc:db2://HOST:PORT/sample"
driverClassName="com.ibm.db2.jcc.DB2Driver"
type="javax.sql.DataSource"
maxActive="4"
maxIdle="2"
maxWait="5000"
validationQuery="SOME_SQL_REQUEST"
accessToUnderlyingConnectionAllowed="true"
/>
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"/ >
Note:
-----
(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
/WEB-INF/web.xml.
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:
<resource-ref>
<description>DB Connection Pool </description>
<res-ref-name >jdbc/SOMETHING</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
</resource-ref>
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.
