Gitiles
Code Review Sign In
source.supwisdom.com / portal_platform / tomcat-cms / 07b3087b89f4c23810bb2a7902fe5a06f392b984 / . / webapps / docs / jndi-datasource-examples-howto.html
blob: 4f0ad83deea36bec0adab26bf2e2616c53c84e87 [file] [log] [blame]
Cheng Tang07b30872014-04-27 16:37:18 +0800[diff] [blame^]1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 7 (7.0.42) - JNDI Datasource HOW-TO</title><meta name="author" content="Les Hughes"><meta name="author" content="David Haraburda"><meta name="author" content="Glenn Nielsen"><meta name="author" content="Yoav Shapira"><style type="text/css" media="print">
2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4 </style><style type="text/css">
5 code {background-color:rgb(224,255,255);padding:0 0.1em;}
6 code.attributeName, code.propertyName {background-color:transparent;}
7 </style><style type="text/css">
8 .wrapped-source code { display: block; background-color: transparent; }
9 .wrapped-source div { margin: 0 0 0 1.25em; }
10 .wrapped-source p { margin: 0 0 0 1.25em; text-indent: -1.25em; }
11 </style><style type="text/css">
12 p.notice {
13 border: 1px solid rgb(255, 0, 0);
14 background-color: rgb(238, 238, 238);
15 color: rgb(0, 51, 102);
16 padding: 0.5em;
17 margin: 1em 2em 1em 1em;
18 }
19 </style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="./images/tomcat.gif" align="right" alt="
20 The Apache Tomcat Servlet/JSP Container
21 " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.42, Jul 2 2013</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="./images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap class="noPrint"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul><p><strong>User Guide</strong></p><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="realm-howto.html">6) Realms and AAA</a></li><li><a href="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptor-howto.html">16) MBean Descriptor</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-hosting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</a></li><li><a href="maven-jars.html">27) Mavenized</a></li><li><a href="security-howto.html">28) Security Considerations</a></li><li><a href="windows-service-howto.html">29) Windows Service</a></li><li><a href="windows-auth-howto.html">30) Windows Authentication</a></li><li><a href="jdbc-pool.html">31) Tomcat's JDBC Pool</a></li><li><a href="web-socket-howto.html">32) WebSocket</a></li></ul><p><strong>Reference</strong></p><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Tomcat Javadocs</a></li><li><a href="servletapi/index.html">Servlet Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.2 Javadocs</a></li><li><a href="elapi/index.html">EL 2.2 Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li><li><a href="tribes/introduction.html">Tribes</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>JNDI Datasource HOW-TO</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
22<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#DriverManager,_the_service_provider_mechanism_and_memory_leaks">DriverManager, the service provider mechanism and memory leaks</a></li><li><a href="#Database_Connection_Pool_(DBCP)_Configurations">Database Connection Pool (DBCP) Configurations</a><ol><li><a href="#Installation">Installation</a></li><li><a href="#Preventing_database_connection_pool_leaks">Preventing database connection pool leaks</a></li><li><a href="#MySQL_DBCP_Example">MySQL DBCP Example</a></li><li><a href="#Oracle_8i,_9i_&amp;_10g">Oracle 8i, 9i &amp; 10g</a></li><li><a href="#PostgreSQL">PostgreSQL</a></li></ol></li><li><a href="#Non-DBCP_Solutions">Non-DBCP Solutions</a></li><li><a href="#Oracle_8i_with_OCI_client">Oracle 8i with OCI client</a><ol><li><a href="#Oracle_8i_with_OCI_client/Introduction">Introduction</a></li><li><a href="#Putting_it_all_together">Putting it all together</a></li></ol></li><li><a href="#Common_Problems">Common Problems</a><ol><li><a href="#Intermittent_Database_Connection_Failures">Intermittent Database Connection Failures</a></li><li><a href="#Random_Connection_Closed_Exceptions">Random Connection Closed Exceptions</a></li><li><a href="#Context_versus_GlobalNamingResources">Context versus GlobalNamingResources</a></li><li><a href="#JNDI_Resource_Naming_and_Realm_Interaction">JNDI Resource Naming and Realm Interaction</a></li></ol></li></ul>
23</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
24
25<p>JNDI Datasource configuration is covered extensively in the
26JNDI-Resources-HOWTO. However, feedback from <code>tomcat-user</code> has
27shown that specifics for individual configurations can be rather tricky.</p>
28
29<p>Here then are some example configurations that have been posted to
30tomcat-user for popular databases and some general tips for db usage.</p>
31
32<p>You should be aware that since these notes are derived from configuration
33and/or feedback posted to <code>tomcat-user</code> YMMV :-). Please let us
34know if you have any other tested configurations that you feel may be of use
35to the wider audience, or if you feel we can improve this section in anyway.</p>
36
37<p>
38<b>Please note that JNDI resource configuration changed somewhat between
39Tomcat 5.0.x and Tomcat 5.5.x.</b> You will most likely need to modify older
40JNDI resource configurations to match the syntax in the example below in order
41to make them work in Tomcat 7.x.x.
42</p>
43
44<p>
45Also, please note that JNDI DataSource configuration in general, and this
46tutorial in particular, assumes that you have read and understood the
47<a href="config/context.html">Context</a> and
48<a href="config/host.html">Host</a> configuration references, including
49the section about Automatic Application Deployment in the latter reference.
50</p>
51</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="DriverManager, the service provider mechanism and memory leaks"><!--()--></a><a name="DriverManager,_the_service_provider_mechanism_and_memory_leaks"><strong>DriverManager, the service provider mechanism and memory leaks</strong></a></font></td></tr><tr><td><blockquote>
52
53<p><code>java.sql.DriverManager</code> supports the
54<a href="http://docs.oracle.com/javase/6/docs/api/index.html?java/sql/DriverManager.html">service
55provider</a> mechanism. This feature is that all the available JDBC drivers
56that announce themselves by providing a <code>META-INF/services/java.sql.Driver</code>
57file are automatically discovered, loaded and registered,
58relieving you from the need to load the database driver explicitly before
59you create a JDBC connection.
60However, the implementation is fundamentally broken in all Java versions for
61a servlet container environment. The problem is that
62<code>java.sql.DriverManager</code> will scan for the drivers only once.</p>
63
64<p>The <a href="config/listeners.html">JRE Memory Leak Prevention Listener</a>
65that is included with Apache Tomcat solves this by triggering the drivers scan
66during Tomcat startup. This is enabled by default. It means that only
67libraries visible to the listener such as the ones in
68<code>$CATALINA_BASE/lib</code> will be scanned for database drivers.
69If you are considering disabling this feature, note that
70the scan would be triggered by the first web application that is
71using JDBC, leading to failures when this web application is reloaded
72and for other web applications that rely on this feature.
73</p>
74
75<p>Thus, the web applications that have database drivers in their
76<code>WEB-INF/lib</code> directory cannot rely on the service provider
77mechanism and should register the drivers explicitly.</p>
78
79<p>The list of drivers in <code>java.sql.DriverManager</code> is also
80a known source of memory leaks. Any Drivers registered
81by a web application must be deregistered when the web application stops.
82Tomcat will attempt to automatically discover and deregister any
83JDBC drivers loaded by the web application class loader when the web
84application stops.
85However, it is expected that applications do this for themselves via
86a <code>ServletContextListener</code>.
87</p>
88
89</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Database Connection Pool (DBCP) Configurations"><!--()--></a><a name="Database_Connection_Pool_(DBCP)_Configurations"><strong>Database Connection Pool (DBCP) Configurations</strong></a></font></td></tr><tr><td><blockquote>
90
91<p>The default database connection pool implementation in Apache Tomcat
92relies on the libraries from the
93<a href="http://commons.apache.org/">Apache Commons</a> project.
94The following libraries are used:
95</p>
96
97<ul>
98<li>Commons DBCP</li>
99<li>Commons Pool</li>
100</ul>
101
102<p>
103These libraries are located in a single JAR at
104<code>$CATALINA_HOME/lib/tomcat-dbcp.jar</code>. However,
105only the classes needed for connection pooling have been included, and the
106packages have been renamed to avoid interfering with applications.
107</p>
108
109<p>DBCP 1.4 provides support for JDBC 4.0.</p>
110
111<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Installation"><strong>Installation</strong></a></font></td></tr><tr><td><blockquote>
112
113<p>See the <a href="http://commons.apache.org/dbcp/configuration.html">
114DBCP documentation</a> for a complete list of configuration parameters.
115</p>
116
117</blockquote></td></tr></table>
118
119<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Preventing database connection pool leaks"><!--()--></a><a name="Preventing_database_connection_pool_leaks"><strong>Preventing database connection pool leaks</strong></a></font></td></tr><tr><td><blockquote>
120
121<p>
122A database connection pool creates and manages a pool of connections
123to a database. Recycling and reusing already existing connections
124to a database is more efficient than opening a new connection.
125</p>
126
127<p>
128There is one problem with connection pooling. A web application has
129to explicitly close ResultSet's, Statement's, and Connection's.
130Failure of a web application to close these resources can result in
131them never being available again for reuse, a database connection pool "leak".
132This can eventually result in your web application database connections failing
133if there are no more available connections.</p>
134
135<p>
136There is a solution to this problem. The Apache Commons DBCP can be
137configured to track and recover these abandoned database connections. Not
138only can it recover them, but also generate a stack trace for the code
139which opened these resources and never closed them.</p>
140
141<p>
142To configure a DBCP DataSource so that abandoned database connections are
143removed and recycled add the following attribute to the
144<code>Resource</code> configuration for your DBCP DataSource:
145</p>
146
147<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>removeAbandoned="true"</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
148
149<p>
150When available database connections run low DBCP will recover and recycle
151any abandoned database connections it finds. The default is <code>false</code>.
152</p>
153
154<p>
155Use the <code>removeAbandonedTimeout</code> attribute to set the number
156of seconds a database connection has been idle before it is considered abandoned.
157</p>
158
159<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>removeAbandonedTimeout="60"</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
160
161<p>
162The default timeout for removing abandoned connections is 300 seconds.
163</p>
164
165<p>
166The <code>logAbandoned</code> attribute can be set to <code>true</code>
167if you want DBCP to log a stack trace of the code which abandoned the
168database connection resources.
169</p>
170<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>logAbandoned="true"</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
171<p>
172The default is <code>false</code>.
173</p>
174
175</blockquote></td></tr></table>
176
177<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="MySQL DBCP Example"><!--()--></a><a name="MySQL_DBCP_Example"><strong>MySQL DBCP Example</strong></a></font></td></tr><tr><td><blockquote>
178
179<h3>0. Introduction</h3>
180<p>Versions of <a href="http://www.mysql.com/products/mysql/index.html">MySQL</a> and JDBC
181drivers that have been reported to work:
182</p>
183<ul>
184<li>MySQL 3.23.47, MySQL 3.23.47 using InnoDB,, MySQL 3.23.58, MySQL 4.0.1alpha</li>
185<li><a href="http://www.mysql.com/products/connector-j">Connector/J</a> 3.0.11-stable (the official JDBC Driver)</li>
186<li><a href="http://mmmysql.sourceforge.net">mm.mysql</a> 2.0.14 (an old 3rd party JDBC Driver)</li>
187</ul>
188
189<p>Before you proceed, don't forget to copy the JDBC Driver's jar into <code>$CATALINA_HOME/lib</code>.</p>
190
191<h3>1. MySQL configuration</h3>
192<p>
193Ensure that you follow these instructions as variations can cause problems.
194</p>
195
196<p>Create a new test user, a new database and a single test table.
197Your MySQL user <strong>must</strong> have a password assigned. The driver
198will fail if you try to connect with an empty password.
199</p>
200<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
201mysql&gt; GRANT ALL PRIVILEGES ON *.* TO javauser@localhost
202 -&gt; IDENTIFIED BY 'javadude' WITH GRANT OPTION;
203mysql&gt; create database javatest;
204mysql&gt; use javatest;
205mysql&gt; create table testdata (
206 -&gt; id int not null auto_increment primary key,
207 -&gt; foo varchar(25),
208 -&gt; bar int);
209</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
210<blockquote>
211<strong>Note:</strong> the above user should be removed once testing is
212complete!
213</blockquote>
214
215<p>Next insert some test data into the testdata table.
216</p>
217<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
218mysql&gt; insert into testdata values(null, 'hello', 12345);
219Query OK, 1 row affected (0.00 sec)
220
221mysql&gt; select * from testdata;
222+----+-------+-------+
223| ID | FOO | BAR |
224+----+-------+-------+
225| 1 | hello | 12345 |
226+----+-------+-------+
2271 row in set (0.00 sec)
228
229mysql&gt;
230</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
231
232<h3>2. Context configuration</h3>
233<p>Configure the JNDI DataSource in Tomcat by adding a declaration for your
234resource to your <a href="config/context.html">Context</a>.</p>
235<p>For example:</p>
236<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
237&lt;Context&gt;
238
239 &lt;!-- maxActive: Maximum number of database connections in pool. Make sure you
240 configure your mysqld max_connections large enough to handle
241 all of your db connections. Set to -1 for no limit.
242 --&gt;
243
244 &lt;!-- maxIdle: Maximum number of idle database connections to retain in pool.
245 Set to -1 for no limit. See also the DBCP documentation on this
246 and the minEvictableIdleTimeMillis configuration parameter.
247 --&gt;
248
249 &lt;!-- maxWait: Maximum time to wait for a database connection to become available
250 in ms, in this example 10 seconds. An Exception is thrown if
251 this timeout is exceeded. Set to -1 to wait indefinitely.
252 --&gt;
253
254 &lt;!-- username and password: MySQL username and password for database connections --&gt;
255
256 &lt;!-- driverClassName: Class name for the old mm.mysql JDBC driver is
257 org.gjt.mm.mysql.Driver - we recommend using Connector/J though.
258 Class name for the official MySQL Connector/J driver is com.mysql.jdbc.Driver.
259 --&gt;
260
261 &lt;!-- url: The JDBC connection url for connecting to your MySQL database.
262 --&gt;
263
264 &lt;Resource name="jdbc/TestDB" auth="Container" type="javax.sql.DataSource"
265 maxActive="100" maxIdle="30" maxWait="10000"
266 username="javauser" password="javadude" driverClassName="com.mysql.jdbc.Driver"
267 url="jdbc:mysql://localhost:3306/javatest"/&gt;
268
269&lt;/Context&gt;
270</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
271
272<h3>3. web.xml configuration</h3>
273
274<p>Now create a <code>WEB-INF/web.xml</code> for this test application.</p>
275<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
276&lt;web-app xmlns="http://java.sun.com/xml/ns/j2ee"
277 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
278 xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
279http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
280 version="2.4"&gt;
281 &lt;description&gt;MySQL Test App&lt;/description&gt;
282 &lt;resource-ref&gt;
283 &lt;description&gt;DB Connection&lt;/description&gt;
284 &lt;res-ref-name&gt;jdbc/TestDB&lt;/res-ref-name&gt;
285 &lt;res-type&gt;javax.sql.DataSource&lt;/res-type&gt;
286 &lt;res-auth&gt;Container&lt;/res-auth&gt;
287 &lt;/resource-ref&gt;
288&lt;/web-app&gt;
289</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
290
291<h3>4. Test code</h3>
292<p>Now create a simple <code>test.jsp</code> page for use later.
293<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
294&lt;%@ taglib uri="http://java.sun.com/jsp/jstl/sql" prefix="sql" %&gt;
295&lt;%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %&gt;
296
297&lt;sql:query var="rs" dataSource="jdbc/TestDB"&gt;
298select id, foo, bar from testdata
299&lt;/sql:query&gt;
300
301&lt;html&gt;
302 &lt;head&gt;
303 &lt;title&gt;DB Test&lt;/title&gt;
304 &lt;/head&gt;
305 &lt;body&gt;
306
307 &lt;h2&gt;Results&lt;/h2&gt;
308
309&lt;c:forEach var="row" items="${rs.rows}"&gt;
310 Foo ${row.foo}&lt;br/&gt;
311 Bar ${row.bar}&lt;br/&gt;
312&lt;/c:forEach&gt;
313
314 &lt;/body&gt;
315&lt;/html&gt;
316</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
317</p>
318
319<p>That JSP page makes use of <a href="http://java.sun.com/products/jsp/jstl">JSTL</a>'s
320SQL and Core taglibs. You can get it from
321<a href="http://tomcat.apache.org/taglibs/standard/">Apache Tomcat Taglibs - Standard Tag Library</a>
322project &mdash; just make sure you get a 1.1.x or later release. Once you have
323JSTL, copy <code>jstl.jar</code> and <code>standard.jar</code> to your web app's
324<code>WEB-INF/lib</code> directory.
325
326</p>
327
328<p>Finally deploy your web app into <code>$CATALINA_BASE/webapps</code> either
329as a warfile called <code>DBTest.war</code> or into a sub-directory called
330<code>DBTest</code></p>
331<p>Once deployed, point a browser at
332<code>http://localhost:8080/DBTest/test.jsp</code> to view the fruits of
333your hard work.</p>
334
335</blockquote></td></tr></table>
336
337<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Oracle 8i, 9i &amp; 10g"><!--()--></a><a name="Oracle_8i,_9i_&amp;_10g"><strong>Oracle 8i, 9i &amp; 10g</strong></a></font></td></tr><tr><td><blockquote>
338<h3>0. Introduction</h3>
339
340<p>Oracle requires minimal changes from the MySQL configuration except for the
341usual gotchas :-)</p>
342<p>Drivers for older Oracle versions may be distributed as *.zip files rather
343than *.jar files. Tomcat will only use <code>*.jar</code> files installed in
344<code>$CATALINA_HOME/lib</code>. Therefore <code>classes111.zip</code>
345or <code>classes12.zip</code> will need to be renamed with a <code>.jar</code>
346extension. Since jarfiles are zipfiles, there is no need to unzip and jar these
347files - a simple rename will suffice.</p>
348
349<p>For Oracle 9i onwards you should use <code>oracle.jdbc.OracleDriver</code>
350rather than <code>oracle.jdbc.driver.OracleDriver</code> as Oracle have stated
351that <code>oracle.jdbc.driver.OracleDriver</code> is deprecated and support
352for this driver class will be discontinued in the next major release.
353</p>
354
355<h3>1. Context configuration</h3>
356<p>In a similar manner to the mysql config above, you will need to define your
357Datasource in your <a href="config/context.html">Context</a>. Here we define a
358Datasource called myoracle using the thin driver to connect as user scott,
359password tiger to the sid called mysid. (Note: with the thin driver this sid is
360not the same as the tnsname). The schema used will be the default schema for the
361user scott.</p>
362
363<p>Use of the OCI driver should simply involve a changing thin to oci in the URL string.
364</p>
365<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
366&lt;Resource name="jdbc/myoracle" auth="Container"
367 type="javax.sql.DataSource" driverClassName="oracle.jdbc.OracleDriver"
368 url="jdbc:oracle:thin:@127.0.0.1:1521:mysid"
369 username="scott" password="tiger" maxActive="20" maxIdle="10"
370 maxWait="-1"/&gt;
371</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
372
373<h3>2. web.xml configuration</h3>
374<p>You should ensure that you respect the element ordering defined by the DTD when you
375create you applications web.xml file.</p>
376<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
377&lt;resource-ref&gt;
378 &lt;description&gt;Oracle Datasource example&lt;/description&gt;
379 &lt;res-ref-name&gt;jdbc/myoracle&lt;/res-ref-name&gt;
380 &lt;res-type&gt;javax.sql.DataSource&lt;/res-type&gt;
381 &lt;res-auth&gt;Container&lt;/res-auth&gt;
382&lt;/resource-ref&gt;
383</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
384<h3>3. Code example</h3>
385<p>You can use the same example application as above (asuming you create the required DB
386instance, tables etc.) replacing the Datasource code with something like</p>
387<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
388Context initContext = new InitialContext();
389Context envContext = (Context)initContext.lookup("java:/comp/env");
390DataSource ds = (DataSource)envContext.lookup("jdbc/myoracle");
391Connection conn = ds.getConnection();
392//etc.
393</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
394</blockquote></td></tr></table>
395
396
397<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="PostgreSQL"><strong>PostgreSQL</strong></a></font></td></tr><tr><td><blockquote>
398<h3>0. Introduction</h3>
399<p>PostgreSQL is configured in a similar manner to Oracle.</p>
400
401<h3>1. Required files </h3>
402<p>
403Copy the Postgres JDBC jar to $CATALINA_HOME/lib. As with Oracle, the
404jars need to be in this directory in order for DBCP's Classloader to find
405them. This has to be done regardless of which configuration step you take next.
406</p>
407
408<h3>2. Resource configuration</h3>
409
410<p>
411You have two choices here: define a datasource that is shared across all Tomcat
412applications, or define a datasource specifically for one application.
413</p>
414
415<h4>2a. Shared resource configuration</h4>
416<p>
417Use this option if you wish to define a datasource that is shared across
418multiple Tomcat applications, or if you just prefer defining your datasource
419in this file.
420</p>
421<p><i>This author has not had success here, although others have reported so.
422Clarification would be appreciated here.</i></p>
423
424<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
425&lt;Resource name="jdbc/postgres" auth="Container"
426 type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
427 url="jdbc:postgresql://127.0.0.1:5432/mydb"
428 username="myuser" password="mypasswd" maxActive="20" maxIdle="10" maxWait="-1"/&gt;
429</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
430<h4>2b. Application-specific resource configuration</h4>
431
432<p>
433Use this option if you wish to define a datasource specific to your application,
434not visible to other Tomcat applications. This method is less invasive to your
435Tomcat installation.
436</p>
437
438<p>
439Create a resource definition for your <a href="config/context.html">Context</a>.
440The Context element should look something like the following.
441</p>
442
443<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
444&lt;Context&gt;
445
446&lt;Resource name="jdbc/postgres" auth="Container"
447 type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
448 url="jdbc:postgresql://127.0.0.1:5432/mydb"
449 username="myuser" password="mypasswd" maxActive="20" maxIdle="10"
450maxWait="-1"/&gt;
451&lt;/Context&gt;
452</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
453
454<h3>3. web.xml configuration</h3>
455<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
456&lt;resource-ref&gt;
457 &lt;description&gt;postgreSQL Datasource example&lt;/description&gt;
458 &lt;res-ref-name&gt;jdbc/postgres&lt;/res-ref-name&gt;
459 &lt;res-type&gt;javax.sql.DataSource&lt;/res-type&gt;
460 &lt;res-auth&gt;Container&lt;/res-auth&gt;
461&lt;/resource-ref&gt;
462</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
463
464<h4>4. Accessing the datasource</h4>
465<p>
466When accessing the datasource programmatically, remember to prepend
467<code>java:/comp/env</code> to your JNDI lookup, as in the following snippet of
468code. Note also that "jdbc/postgres" can be replaced with any value you prefer, provided
469you change it in the above resource definition file as well.
470</p>
471
472<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
473InitialContext cxt = new InitialContext();
474if ( cxt == null ) {
475 throw new Exception("Uh oh -- no context!");
476}
477
478DataSource ds = (DataSource) cxt.lookup( "java:/comp/env/jdbc/postgres" );
479
480if ( ds == null ) {
481 throw new Exception("Data source not found!");
482}
483</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
484
485</blockquote></td></tr></table>
486</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Non-DBCP Solutions"><!--()--></a><a name="Non-DBCP_Solutions"><strong>Non-DBCP Solutions</strong></a></font></td></tr><tr><td><blockquote>
487<p>
488These solutions either utilise a single connection to the database (not recommended for anything other
489than testing!) or some other pooling technology.
490</p>
491</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Oracle 8i with OCI client"><!--()--></a><a name="Oracle_8i_with_OCI_client"><strong>Oracle 8i with OCI client</strong></a></font></td></tr><tr><td><blockquote>
492<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Oracle 8i with OCI client/Introduction"><!--()--></a><a name="Oracle_8i_with_OCI_client/Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
493<p>Whilst not strictly addressing the creation of a JNDI DataSource using the OCI client, these notes can be combined with the
494Oracle and DBCP solution above.</p>
495<p>
496In order to use OCI driver, you should have an Oracle client installed. You should have installed
497Oracle8i(8.1.7) client from cd, and download the suitable JDBC/OCI
498driver(Oracle8i 8.1.7.1 JDBC/OCI Driver) from <a href="http://otn.oracle.com/">otn.oracle.com</a>.
499</p>
500<p>
501After renaming <code>classes12.zip</code> file to <code>classes12.jar</code>
502for Tomcat, copy it into <code>$CATALINA_HOME/lib</code>.
503You may also have to remove the <code>javax.sql.*</code> classes
504from this file depending upon the version of Tomcat and JDK you are using.
505</p>
506</blockquote></td></tr></table>
507
508<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Putting it all together"><!--()--></a><a name="Putting_it_all_together"><strong>Putting it all together</strong></a></font></td></tr><tr><td><blockquote>
509<p>
510Ensure that you have the <code>ocijdbc8.dll</code> or <code>.so</code> in your <code>$PATH</code> or <code>LD_LIBRARY_PATH</code>
511 (possibly in <code>$ORAHOME\bin</code>) and also confirm that the native library can be loaded by a simple test program
512using <code>System.loadLibrary("ocijdbc8");</code>
513</p>
514<p>
515You should next create a simple test servlet or jsp that has these
516<strong>critical lines</strong>:
517</p>
518<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
519DriverManager.registerDriver(new
520oracle.jdbc.driver.OracleDriver());
521conn =
522DriverManager.getConnection("jdbc:oracle:oci8:@database","username","password");
523</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
524<p>
525where database is of the form <code>host:port:SID</code> Now if you try to access the URL of your
526test servlet/jsp and what you get is a
527<code>ServletException</code> with a root cause of <code>java.lang.UnsatisfiedLinkError:get_env_handle</code>.
528</p>
529<p>
530First, the <code>UnsatisfiedLinkError</code> indicates that you have
531<ul>
532<li>a mismatch between your JDBC classes file and
533your Oracle client version. The giveaway here is the message stating that a needed library file cannot be
534found. For example, you may be using a classes12.zip file from Oracle Version 8.1.6 with a Version 8.1.5
535Oracle client. The classeXXXs.zip file and Oracle client software versions must match.
536</li>
537<li>A <code>$PATH</code>, <code>LD_LIBRARY_PATH</code> problem.</li>
538<li>It has been reported that ignoring the driver you have downloded from otn and using
539the classes12.zip file from the directory <code>$ORAHOME\jdbc\lib</code> will also work.
540</li>
541</ul>
542</p>
543<p>
544Next you may experience the error <code>ORA-06401 NETCMN: invalid driver designator</code>
545</p>
546<p>
547The Oracle documentation says : "Cause: The login (connect) string contains an invalid
548driver designator. Action: Correct the string and re-submit."
549
550Change the database connect string (of the form <code>host:port:SID</code>) with this one:
551<code>(description=(address=(host=myhost)(protocol=tcp)(port=1521))(connect_data=(sid=orcl)))</code>
552</p>
553<p>
554<i>Ed. Hmm, I don't think this is really needed if you sort out your TNSNames - but I'm not an Oracle DBA :-)</i>
555</p>
556</blockquote></td></tr></table>
557</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Common Problems"><!--()--></a><a name="Common_Problems"><strong>Common Problems</strong></a></font></td></tr><tr><td><blockquote>
558<p>Here are some common problems encountered with a web application which
559uses a database and tips for how to solve them.</p>
560
561<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Intermittent Database Connection Failures"><!--()--></a><a name="Intermittent_Database_Connection_Failures"><strong>Intermittent Database Connection Failures</strong></a></font></td></tr><tr><td><blockquote>
562<p>
563Tomcat runs within a JVM. The JVM periodically performs garbage collection
564(GC) to remove java objects which are no longer being used. When the JVM
565performs GC execution of code within Tomcat freezes. If the maximum time
566configured for establishment of a database connection is less than the amount
567of time garbage collection took you can get a database connection failure.
568</p>
569
570<p>To collect data on how long garbage collection is taking add the
571<code>-verbose:gc</code> argument to your <code>CATALINA_OPTS</code>
572environment variable when starting Tomcat. When verbose gc is enabled
573your <code>$CATALINA_BASE/logs/catalina.out</code> log file will include
574data for every garbage collection including how long it took.</p>
575
576<p>When your JVM is tuned correctly 99% of the time a GC will take less
577than one second. The remainder will only take a few seconds. Rarely,
578if ever should a GC take more than 10 seconds.</p>
579
580<p>Make sure that the db connection timeout is set to 10-15 seconds.
581For the DBCP you set this using the parameter <code>maxWait</code>.</p>
582
583</blockquote></td></tr></table>
584
585<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Random Connection Closed Exceptions"><!--()--></a><a name="Random_Connection_Closed_Exceptions"><strong>Random Connection Closed Exceptions</strong></a></font></td></tr><tr><td><blockquote>
586<p>
587These can occur when one request gets a db connection from the connection
588pool and closes it twice. When using a connection pool, closing the
589connection just returns it to the pool for reuse by another request,
590it doesn't close the connection. And Tomcat uses multiple threads to
591handle concurrent requests. Here is an example of the sequence
592of events which could cause this error in Tomcat:
593</p>
594<pre>
595 Request 1 running in Thread 1 gets a db connection.
596
597 Request 1 closes the db connection.
598
599 The JVM switches the running thread to Thread 2
600
601 Request 2 running in Thread 2 gets a db connection
602 (the same db connection just closed by Request 1).
603
604 The JVM switches the running thread back to Thread 1
605
606 Request 1 closes the db connection a second time in a finally block.
607
608 The JVM switches the running thread back to Thread 2
609
610 Request 2 Thread 2 tries to use the db connection but fails
611 because Request 1 closed it.
612</pre>
613<p>
614Here is an example of properly written code to use a database connection
615obtained from a connection pool:
616</p>
617<pre>
618 Connection conn = null;
619 Statement stmt = null; // Or PreparedStatement if needed
620 ResultSet rs = null;
621 try {
622 conn = ... get connection from connection pool ...
623 stmt = conn.createStatement("select ...");
624 rs = stmt.executeQuery();
625 ... iterate through the result set ...
626 rs.close();
627 rs = null;
628 stmt.close();
629 stmt = null;
630 conn.close(); // Return to connection pool
631 conn = null; // Make sure we don't close it twice
632 } catch (SQLException e) {
633 ... deal with errors ...
634 } finally {
635 // Always make sure result sets and statements are closed,
636 // and the connection is returned to the pool
637 if (rs != null) {
638 try { rs.close(); } catch (SQLException e) { ; }
639 rs = null;
640 }
641 if (stmt != null) {
642 try { stmt.close(); } catch (SQLException e) { ; }
643 stmt = null;
644 }
645 if (conn != null) {
646 try { conn.close(); } catch (SQLException e) { ; }
647 conn = null;
648 }
649 }
650</pre>
651
652</blockquote></td></tr></table>
653
654<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Context versus GlobalNamingResources"><!--()--></a><a name="Context_versus_GlobalNamingResources"><strong>Context versus GlobalNamingResources</strong></a></font></td></tr><tr><td><blockquote>
655<p>
656 Please note that although the above instructions place the JNDI declarations in a Context
657 element, it is possible and sometimes desirable to place these declarations in the
658 <a href="config/globalresources.html">GlobalNamingResources</a> section of the server
659 configuration file. A resource placed in the GlobalNamingResources section will be shared
660 among the Contexts of the server.
661</p>
662</blockquote></td></tr></table>
663
664<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="JNDI Resource Naming and Realm Interaction"><!--()--></a><a name="JNDI_Resource_Naming_and_Realm_Interaction"><strong>JNDI Resource Naming and Realm Interaction</strong></a></font></td></tr><tr><td><blockquote>
665<p>
666 In order to get Realms to work, the realm must refer to the datasource as
667 defined in the &lt;GlobalNamingResources&gt; or &lt;Context&gt; section, not a datasource as renamed
668 using &lt;ResourceLink&gt;.
669</p>
670</blockquote></td></tr></table>
671
672</blockquote></td></tr></table></td></tr><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions
673 on improving documentation for Apache Tomcat.<br><br>
674 If you have trouble and need help, read
675 <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
676 and ask your question on the tomcat-users
677 <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
678 Do not ask such questions here. This is not a Q&amp;A section.<br><br>
679 The Apache Comments System is explained <a href="/tomcat-7.0-doc/comments.html">here</a>.
680 Comments may be removed by our moderators if they are either
681 implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
682 var comments_shortname = 'tomcat';
683 var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/jndi-datasource-examples-howto.html';
684 (function(w, d) {
685 if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
686 d.write('<div id="comments_thread"><\/div>');
687 var s = d.createElement('script');
688 s.type = 'text/javascript';
689 s.async = true;
690 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
691 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
692 }
693 else {
694 d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
695 }
696 })(window, document);
697 //--><!]]></script></blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
698 Copyright &copy; 1999-2013, Apache Software Foundation
699 </em></font></div></td></tr></table></body></html>