Author: kkolinko
Date: Wed Oct 19 12:26:46 2011
New Revision: 1186160
URL: http://svn.apache.org/viewvc?rev=1186160&view=rev
Log:
CTR: docs
Merged revisions r1186123, r1186137, r1186153 from tomcat/trunk:
Correct the markup. s/db/database/
Rearranged the introductory section for DBCP pool.
Removed mention of JVM 1.4.
There is a difference wrt TC7 version of this commit
that Tomcat 6 uses DBCP 1.3 / JDBC 3.0.
Modified:
tomcat/tc6.0.x/trunk/ (props changed)
tomcat/tc6.0.x/trunk/webapps/docs/jndi-datasource-examples-howto.xml
Propchange: tomcat/tc6.0.x/trunk/
------------------------------------------------------------------------------
--- svn:mergeinfo (original)
+++ svn:mergeinfo Wed Oct 19 12:26:46 2011
@@ -1 +1 @@
-/tomcat/trunk:601180,606992,612607,630314,640888,652744,653247,666232,673796,673820,677910,683969,683982,684001,684081,684234,684269-684270,685177,687503,687645,689402,690781,691392,691805,692748,693378,694992,695053,695311,696780,696782,698012,698227,698236,698613,699427,699634,701355,709294,709811,709816,710063,710066,710125,710205,711126,711600,712461,712467,713953,714002,718360,719119,719124,719602,719626,719628,720046,720069,721040,721286,721708,721886,723404,723738,726052,727303,728032,728768,728947,729057,729567,729569,729571,729681,729809,729815,729934,730250,730590,731651,732859,732863,734734,740675,740684,742677,742697,742714,744160,744238,746321,746384,746425,747834,747863,748344,750258,750291,750921,751286-751287,751289,751295,752323,753039,757335,757774,758249,758365,758596,758616,758664,759074,761601,762868,762929,762936-762937,763166,763183,763193,763228,763262,763298,763302,763325,763599,763611,763654,763681,763706,764985,764997,765662,768335,769979,770716,77
0809,770876,772872,776921,776924,776935,776945,777464,777466,777576,777625,778379,778523-778524,781528,781779,782145,782791,783316,783696,783724,783756,783762,783766,783863,783934,784453,784602,784614,785381,785688,785768,785859,786468,786487,786490,786496,786667,787627,787770,787985,789389,790405,791041,791184,791194,791224,791243,791326,791328,791789,792740,793372,793757,793882,793981,794082,794673,794822,795043,795152,795210,795457,795466,797168,797425,797596,797607,802727,802940,804462,804544,804734,805153,809131,809603,810916,810977,812125,812137,812432,813001,813013,813866,814180,814708,814876,815972,816252,817442,817822,819339,819361,820110,820132,820874,820954,821397,828196,828201,828210,828225,828759,830378-830379,830999,831106,831774,831785,831828,831850,831860,832214,832218,833121,833545,834047,835036,835336,836405,881396,881412,883130,883134,883146,883165,883177,883362,883565,884341,885038,885231,885241,885260,885901,885991,886019,888072,889363,889606,889716,8901
39,890265,890349-890350,890417,891185-891187,891583,892198,892341,892415,892464,892555,892812,892814,892817,892843,892887,893321,893493,894580,894586,894805,894831,895013,895045,895057,895191,895392,895703,896370,896384,897380-897381,897776,898126,898256,898468,898527,898555,898558,898718,898836,898906,899284,899348,899420,899653,899769-899770,899783,899788,899792,899916,899918-899919,899935,899949,903916,905020,905151,905722,905728,905735,907311,907513,907538,907652,907819,907825,907864,908002,908721,908754,908759,909097,909206,909212,909525,909636,909869,909875,909887,910266,910370,910442,910471,910485,910974,915226,915737,915861,916097,916141,916157,916170,917598,917633,918093,918489,918594,918684,918787,918792,918799,918803,918885,919851,919914,920025,920055,920298,920449,920596,920824,920840,921444,922010,926716,927062,927621,928482,928695,928732,928798,931709,932357,932967,935105,935983,939491,939551,940064,941356,941463,943112,944409,944416,945231,945808,945835,945841
,946686,948057,950164,950596,950614,950851,950905,951615,953434,954435,955648,955655,956832,957130,957830,958192,960701,961948,962865,962872,962881,962900,963106,963865,963868,964614,966177-966178,966292,966692,966863,981815,988448,991837,993042,1001955,1002185,1002263,1002274,1002349,1002359,1002362,1002481,1002514,1003461,1003481,1003488,1003556,1003572,1003581,1003861,1004393,1004409,1004415,1004868-1004869,1004912,1005452,1005467,1005647,1005802,1022120,1022134,1022323,1022415,1022606,1022623,1024224,1024251,1026042,1026784,1026912,1026920,1029767,1033415,1033448,1033842,1033897,1037715,1037794,1037887,1037924,1038041,1042022,1042029,1042447,1042452,1042494,1044944,1044987,1050249,1055055,1055236,1055458,1055975,1056264,1056828,1056889,1059881,1061412,1061442,1061446,1062398,1064652,1066244,1066772,1067039,1067139,1069824,1070139,1070420,1070609,1072042,1073393,1075458,1076212,1078409,1078412,1079801,1081334,1088179,1088460,1090022,1094069,1094089,1095138,1097899,1099575
,1099586,1099772,1099789,1100145,1100822,1101094,1101144,1124680,1130774,1133014,1137862,1137996,1138950,1138953,1140693,1141104,1141441,1142043,1142904,1143134,1143150,1148216,1148471,1152601,1156171,1156519,1164567,1167394,1172233-1172234,1172236,1173614,1174353,1175158,1175190,1176799,1177125,1177245,1177850,1177862,1178228,1178233,1184917,1184919,1185200,1185588,1186011,1186104
+/tomcat/trunk:601180,606992,612607,630314,640888,652744,653247,666232,673796,673820,677910,683969,683982,684001,684081,684234,684269-684270,685177,687503,687645,689402,690781,691392,691805,692748,693378,694992,695053,695311,696780,696782,698012,698227,698236,698613,699427,699634,701355,709294,709811,709816,710063,710066,710125,710205,711126,711600,712461,712467,713953,714002,718360,719119,719124,719602,719626,719628,720046,720069,721040,721286,721708,721886,723404,723738,726052,727303,728032,728768,728947,729057,729567,729569,729571,729681,729809,729815,729934,730250,730590,731651,732859,732863,734734,740675,740684,742677,742697,742714,744160,744238,746321,746384,746425,747834,747863,748344,750258,750291,750921,751286-751287,751289,751295,752323,753039,757335,757774,758249,758365,758596,758616,758664,759074,761601,762868,762929,762936-762937,763166,763183,763193,763228,763262,763298,763302,763325,763599,763611,763654,763681,763706,764985,764997,765662,768335,769979,770716,77
0809,770876,772872,776921,776924,776935,776945,777464,777466,777576,777625,778379,778523-778524,781528,781779,782145,782791,783316,783696,783724,783756,783762,783766,783863,783934,784453,784602,784614,785381,785688,785768,785859,786468,786487,786490,786496,786667,787627,787770,787985,789389,790405,791041,791184,791194,791224,791243,791326,791328,791789,792740,793372,793757,793882,793981,794082,794673,794822,795043,795152,795210,795457,795466,797168,797425,797596,797607,802727,802940,804462,804544,804734,805153,809131,809603,810916,810977,812125,812137,812432,813001,813013,813866,814180,814708,814876,815972,816252,817442,817822,819339,819361,820110,820132,820874,820954,821397,828196,828201,828210,828225,828759,830378-830379,830999,831106,831774,831785,831828,831850,831860,832214,832218,833121,833545,834047,835036,835336,836405,881396,881412,883130,883134,883146,883165,883177,883362,883565,884341,885038,885231,885241,885260,885901,885991,886019,888072,889363,889606,889716,8901
39,890265,890349-890350,890417,891185-891187,891583,892198,892341,892415,892464,892555,892812,892814,892817,892843,892887,893321,893493,894580,894586,894805,894831,895013,895045,895057,895191,895392,895703,896370,896384,897380-897381,897776,898126,898256,898468,898527,898555,898558,898718,898836,898906,899284,899348,899420,899653,899769-899770,899783,899788,899792,899916,899918-899919,899935,899949,903916,905020,905151,905722,905728,905735,907311,907513,907538,907652,907819,907825,907864,908002,908721,908754,908759,909097,909206,909212,909525,909636,909869,909875,909887,910266,910370,910442,910471,910485,910974,915226,915737,915861,916097,916141,916157,916170,917598,917633,918093,918489,918594,918684,918787,918792,918799,918803,918885,919851,919914,920025,920055,920298,920449,920596,920824,920840,921444,922010,926716,927062,927621,928482,928695,928732,928798,931709,932357,932967,935105,935983,939491,939551,940064,941356,941463,943112,944409,944416,945231,945808,945835,945841
,946686,948057,950164,950596,950614,950851,950905,951615,953434,954435,955648,955655,956832,957130,957830,958192,960701,961948,962865,962872,962881,962900,963106,963865,963868,964614,966177-966178,966292,966692,966863,981815,988448,991837,993042,1001955,1002185,1002263,1002274,1002349,1002359,1002362,1002481,1002514,1003461,1003481,1003488,1003556,1003572,1003581,1003861,1004393,1004409,1004415,1004868-1004869,1004912,1005452,1005467,1005647,1005802,1022120,1022134,1022323,1022415,1022606,1022623,1024224,1024251,1026042,1026784,1026912,1026920,1029767,1033415,1033448,1033842,1033897,1037715,1037794,1037887,1037924,1038041,1042022,1042029,1042447,1042452,1042494,1044944,1044987,1050249,1055055,1055236,1055458,1055975,1056264,1056828,1056889,1059881,1061412,1061442,1061446,1062398,1064652,1066244,1066772,1067039,1067139,1069824,1070139,1070420,1070609,1072042,1073393,1075458,1076212,1078409,1078412,1079801,1081334,1088179,1088460,1090022,1094069,1094089,1095138,1097899,1099575
,1099586,1099772,1099789,1100145,1100822,1101094,1101144,1124680,1130774,1133014,1137862,1137996,1138950,1138953,1140693,1141104,1141441,1142043,1142904,1143134,1143150,1148216,1148471,1152601,1156171,1156519,1164567,1167394,1172233-1172234,1172236,1173614,1174353,1175158,1175190,1176799,1177125,1177245,1177850,1177862,1178228,1178233,1184917,1184919,1185200,1185588,1186011,1186104,1186123,1186137,1186153
Modified: tomcat/tc6.0.x/trunk/webapps/docs/jndi-datasource-examples-howto.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/jndi-datasource-examples-howto.xml?rev=1186160&r1=1186159&r2=1186160&view=diff
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/jndi-datasource-examples-howto.xml
(original)
+++ tomcat/tc6.0.x/trunk/webapps/docs/jndi-datasource-examples-howto.xml Wed
Oct 19 12:26:46 2011
@@ -108,79 +108,87 @@ a <code>ServletContextListener</code>.
<section name="Database Connection Pool (DBCP) Configurations">
-<p>DBCP provides support for JDBC 2.0. On systems using a 1.4 JVM DBCP
-will support JDBC 3.0. Please let us know if you have used DBCP and its
-JDBC 3.0 features with a 1.4 JVM.
+<p>The default database connection pool implementation in Apache Tomcat
+relies on the libraries from the
+<a href="http://commons.apache.org/";>Apache Commons</a> project.
+The following libraries are used:
</p>
-<p>See the <a href="http://commons.apache.org/dbcp/configuration.html";>
-DBCP documentation</a> for a complete list of configuration parameters.
-</p>
-
-<subsection name="Installation">
-<p>DBCP uses the Commons Database Connection Pool. It relies on
-number of Commons components:
<ul>
<li>Commons DBCP</li>
<li>Commons Pool</li>
</ul>
+
+<p>
These libraries are located in a single JAR at
<code>$CATALINA_HOME/lib/tomcat-dbcp.jar</code>. However,
only the classes needed for connection pooling have been included, and the
packages have been renamed to avoid interfering with applications.
</p>
+<p>DBCP 1.3 provides support for JDBC 3.0.</p>
+
+<subsection name="Installation">
+
+<p>See the <a href="http://commons.apache.org/dbcp/configuration.html";>
+DBCP documentation</a> for a complete list of configuration parameters.
+</p>
+
</subsection>
-<subsection name="Preventing dB connection pool leaks">
+<subsection name="Preventing database connection pool leaks">
<p>
A database connection pool creates and manages a pool of connections
to a database. Recycling and reusing already existing connections
-to a dB is more efficient than opening a new connection.
+to a database is more efficient than opening a new connection.
</p>
<p>
There is one problem with connection pooling. A web application has
to explicitly close ResultSet's, Statement's, and Connection's.
Failure of a web application to close these resources can result in
-them never being available again for reuse, a db connection pool "leak".
-This can eventually result in your web application db connections failing
+them never being available again for reuse, a database connection pool "leak".
+This can eventually result in your web application database connections failing
if there are no more available connections.</p>
<p>
-There is a solution to this problem. Commons DBCP can be
-configured to track and recover these abandoned dB connections. Not
+There is a solution to this problem. The Apache Commons DBCP can be
+configured to track and recover these abandoned database connections. Not
only can it recover them, but also generate a stack trace for the code
which opened these resources and never closed them.</p>
<p>
-To configure a DBCP DataSource so that abandoned dB connections are
+To configure a DBCP DataSource so that abandoned database connections are
removed and recycled add the following attribute to the
<code>Resource</code> configuration for your DBCP DataSource:
-<source>
- removeAbandoned="true"
-</source>
-When available db connections run low DBCP will recover and recycle
-any abandoned dB connections it finds. The default is <code>false</code>.
+</p>
+
+<source>removeAbandoned="true"</source>
+
+<p>
+When available database connections run low DBCP will recover and recycle
+any abandoned database connections it finds. The default is <code>false</code>.
</p>
<p>
Use the <code>removeAbandonedTimeout</code> attribute to set the number
-of seconds a dB connection has been idle before it is considered abandoned.
-<source>
- removeAbandonedTimeout="60"
-</source>
+of seconds a database connection has been idle before it is considered
abandoned.
+</p>
+
+<source>removeAbandonedTimeout="60"</source>
+
+<p>
The default timeout for removing abandoned connections is 300 seconds.
</p>
<p>
The <code>logAbandoned</code> attribute can be set to <code>true</code>
if you want DBCP to log a stack trace of the code which abandoned the
-dB connection resources.
-<source>
- logAbandoned="true"
-</source>
+database connection resources.
+</p>
+<source>logAbandoned="true"</source>
+<p>
The default is <code>false</code>.
</p>
@@ -189,13 +197,14 @@ The default is <code>false</code>.
<subsection name="MySQL DBCP Example">
<h3>0. Introduction</h3>
-<p>Versions of <a
href="http://www.mysql.com/products/mysql/index.html";>MySQL</a> and JDBC
drivers that have been reported to work:
+<p>Versions of <a
href="http://www.mysql.com/products/mysql/index.html";>MySQL</a> and JDBC
+drivers that have been reported to work:
+</p>
<ul>
<li>MySQL 3.23.47, MySQL 3.23.47 using InnoDB,, MySQL 3.23.58, MySQL
4.0.1alpha</li>
<li><a href="http://www.mysql.com/products/connector-j";>Connector/J</a>
3.0.11-stable (the official JDBC Driver)</li>
<li><a href="http://mmmysql.sourceforge.net";>mm.mysql</a> 2.0.14 (an old 3rd
party JDBC Driver)</li>
</ul>
-</p>
<p>Before you proceed, don't forget to copy the JDBC Driver's jar into
<code>$CATALINA_HOME/lib</code>.</p>
@@ -207,6 +216,7 @@ Ensure that you follow these instruction
<p>Create a new test user, a new database and a single test table.
Your MySQL user <strong>must</strong> have a password assigned. The driver
will fail if you try to connect with an empty password.
+</p>
<source>
mysql> GRANT ALL PRIVILEGES ON *.* TO javauser@localhost
-> IDENTIFIED BY 'javadude' WITH GRANT OPTION;
@@ -221,9 +231,9 @@ mysql> create table testdata (
<strong>Note:</strong> the above user should be removed once testing is
complete!
</blockquote>
-</p>
<p>Next insert some test data into the testdata table.
+</p>
<source>
mysql> insert into testdata values(null, 'hello', 12345);
Query OK, 1 row affected (0.00 sec)
@@ -238,39 +248,37 @@ mysql> select * from testdata;
mysql>
</source>
-</p>
<h3>2. Context configuration</h3>
<p>Configure the JNDI DataSource in Tomcat by adding a declaration for your
resource to your <a href="config/context.html">Context</a>.</p>
-<p>For example:
-
+<p>For example:</p>
<source>
<Context>
- <!-- maxActive: Maximum number of dB connections in pool. Make sure you
+ <!-- maxActive: Maximum number of database connections in pool. Make
sure you
configure your mysqld max_connections large enough to handle
all of your db connections. Set to -1 for no limit.
-->
- <!-- maxIdle: Maximum number of idle dB connections to retain in pool.
+ <!-- maxIdle: Maximum number of idle database connections to retain in
pool.
Set to -1 for no limit. See also the DBCP documentation on this
and the minEvictableIdleTimeMillis configuration parameter.
-->
- <!-- maxWait: Maximum time to wait for a dB connection to become
available
+ <!-- maxWait: Maximum time to wait for a database connection to become
available
in ms, in this example 10 seconds. An Exception is thrown if
this timeout is exceeded. Set to -1 to wait indefinitely.
-->
- <!-- username and password: MySQL dB username and password for dB
connections -->
+ <!-- username and password: MySQL username and password for database
connections -->
<!-- driverClassName: Class name for the old mm.mysql JDBC driver is
org.gjt.mm.mysql.Driver - we recommend using Connector/J though.
Class name for the official MySQL Connector/J driver is
com.mysql.jdbc.Driver.
-->
- <!-- url: The JDBC connection url for connecting to your MySQL dB.
+ <!-- url: The JDBC connection url for connecting to your MySQL database.
-->
<Resource name="jdbc/TestDB" auth="Container" type="javax.sql.DataSource"
@@ -280,11 +288,10 @@ resource to your <a href="config/context
</Context>
</source>
-</p>
<h3>3. web.xml configuration</h3>
-<p>Now create a <code>WEB-INF/web.xml</code> for this test application.
+<p>Now create a <code>WEB-INF/web.xml</code> for this test application.</p>
<source>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
@@ -300,7 +307,6 @@ http://java.sun.com/xml/ns/j2ee/web-app_
</resource-ref>
</web-app>
</source>
-</p>
<h3>4. Test code</h3>
<p>Now create a simple <code>test.jsp</code> page for use later.
@@ -375,6 +381,7 @@ not the same as the tnsname). The schema
user scott.</p>
<p>Use of the OCI driver should simply involve a changing thin to oci in the
URL string.
+</p>
<source>
<Resource name="jdbc/myoracle" auth="Container"
type="javax.sql.DataSource"
driverClassName="oracle.jdbc.OracleDriver"
@@ -382,7 +389,6 @@ user scott.</p>
username="scott" password="tiger" maxActive="20" maxIdle="10"
maxWait="-1"/>
</source>
-</p>
<h3>2. web.xml configuration</h3>
<p>You should ensure that you respect the element ordering defined by the DTD
when you
@@ -578,13 +584,13 @@ Change the database connect string (of t
<p>Here are some common problems encountered with a web application which
uses a database and tips for how to solve them.</p>
-<subsection name="Intermittent dB Connection Failures">
+<subsection name="Intermittent Database Connection Failures">
<p>
Tomcat runs within a JVM. The JVM periodically performs garbage collection
(GC) to remove java objects which are no longer being used. When the JVM
performs GC execution of code within Tomcat freezes. If the maximum time
-configured for establishment of a dB connection is less than the amount
-of time garbage collection took you can get a db conneciton failure.
+configured for establishment of a database connection is less than the amount
+of time garbage collection took you can get a database connection failure.
</p>
<p>To collect data on how long garbage collection is taking add the
@@ -610,6 +616,7 @@ connection just returns it to the pool f
it doesn't close the connection. And Tomcat uses multiple threads to
handle concurrent requests. Here is an example of the sequence
of events which could cause this error in Tomcat:
+</p>
<pre>
Request 1 running in Thread 1 gets a db connection.
@@ -629,8 +636,10 @@ of events which could cause this error i
Request 2 Thread 2 tries to use the db connection but fails
because Request 1 closed it.
</pre>
-Here is an example of properly written code to use a db connection
+<p>
+Here is an example of properly written code to use a database connection
obtained from a connection pool:
+</p>
<pre>
Connection conn = null;
Statement stmt = null; // Or PreparedStatement if needed
@@ -665,7 +674,6 @@ obtained from a connection pool:
}
}
</pre>
-</p>
</subsection>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
