Author: markt
Date: Mon Dec 14 18:11:24 2009
New Revision: 890420
URL: http://svn.apache.org/viewvc?rev=890420&view=rev
Log:
Fix https://issues.apache.org/bugzilla/show_bug.cgi?id=47769
Reword JNDI docs in an attempt to make clear why resource-ref elements appear
to be optional
Modified:
tomcat/tc6.0.x/trunk/ (props changed)
tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml
tomcat/tc6.0.x/trunk/webapps/docs/jndi-resources-howto.xml
Propchange: tomcat/tc6.0.x/trunk/
------------------------------------------------------------------------------
--- svn:mergeinfo (original)
+++ svn:mergeinfo Mon Dec 14 18:11:24 2009
@@ -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,753039,757335,757774,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,770809,770876,77
2872,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,817442,817822,819339,819361,820110,820132,820874,820954,821397,828196,828201,828210,828225,828759,830378-830379,831106,831774,831785,831828,831850,831860,832218,833121,833545,834047,835036,835336,889363
+/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,753039,757335,757774,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,770809,770876,77
2872,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,817442,817822,819339,819361,820110,820132,820874,820954,821397,828196,828201,828210,828225,828759,830378-830379,831106,831774,831785,831828,831850,831860,832218,833121,833545,834047,835036,835336,889363,890417
Modified: tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml?rev=890420&r1=890419&r2=890420&view=diff
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml (original)
+++ tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml Mon Dec 14 18:11:24 2009
@@ -486,6 +486,11 @@
application. (kkolinko)
</update>
<fix>
+ <bug>47769</bug>: Clarify the JNDI docs with repect to use of
+ <resource-ref> and related elements, specifically when they are
+ required and when they may be omitted. (markt)
+ </fix>
+ <fix>
<bug>48381</bug>: Add information on how Tomcat treats host names to
the
host configuration documentation. (markt)
</fix>
Modified: tomcat/tc6.0.x/trunk/webapps/docs/jndi-resources-howto.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/jndi-resources-howto.xml?rev=890420&r1=890419&r2=890420&view=diff
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/jndi-resources-howto.xml (original)
+++ tomcat/tc6.0.x/trunk/webapps/docs/jndi-resources-howto.xml Mon Dec 14
18:11:24 2009
@@ -37,34 +37,26 @@
instance for each web application running under it, in a manner that is
compatible with those provided by a
<a href="http://java.sun.com/j2ee";>Java2 Enterprise Edition</a> application
-server.
+server. The J2EE standard provides a standard set of elements in the
+<code>/WEB-INF/web.xml</code> file to reference/define resources.</p>
-The J2EE standard provides a standard set of elements in
-the <code>/WEB-INF/web.xml</code> file to reference resources; resources
-referenced in these elements must be defined in an application-server-specific
-configuration.
-</p>
-
-<p>For Tomcat 6, these entries in per-web-application
-<code>InitialContext</code> are configured in the
-<a href="config/context.html"><code><Context></code></a> elements that
-can be specified in either <code>$CATALINA_BASE/conf/server.xml</code> or,
-preferably, the per-web-application context XML file (
-<code>META-INF/context.xml</code>).
-</p>
+<p>See the following Specifications for more information about programming APIs
+for JNDI, and for the features supported by Java2 Enterprise Edition (J2EE)
+servers, which Tomcat emulates for the services that it provides:</p>
+<ul>
+<li><a href="http://java.sun.com/products/jndi";>Java Naming and Directory
+ Interface</a> (included in JDK 1.4 onwards)</li>
+<li><a href="http://java.sun.com/j2ee/download.html";>J2EE Platform
+ Specification</a> (in particular, see Chapter 5 on <em>Naming</em>)</li>
+</ul>
-<p>Tomcat 6 maintains a separate namespace of global resources for the
-entire server. These are configured in the
-<a href="config/globalresources.html">
-<code><strong><GlobalNameingResources></strong></code></a> element of
-<code>$CATALINA_BASE/conf/server.xml</code>. You may expose these resources to
-web applications by using
-<code><strong><ResourceLink></strong></code> elements.
-</p>
-
-<p>The resources defined in these elements
-may be referenced by the following elements in the web application deployment
-descriptor (<code>/WEB-INF/web.xml</code>) of your web application:</p>
+</section>
+
+<section name="web.xml configuration" >
+
+<p>The following elements may be used in the web application deployment
+descriptor (<code>/WEB-INF/web.xml</code>) of your web application to define
+resources:</p>
<ul>
<li><code><strong><env-entry></strong></code> - Environment entry, a
single-value parameter that can be used to configure how the application
@@ -79,46 +71,26 @@
that do not require authentication information.</li>
</ul>
-<p>The <code>InitialContext</code> is configured as a web application is
-initially deployed, and is made available to web application components (for
-read-only access). All configured entries and resources are placed in
-the <code>java:comp/env</code> portion of the JNDI namespace, so a typical
-access to a resource - in this case, to a JDBC <code>DataSource</code> -
-would look something like this:</p>
-
-<source>
-// Obtain our environment naming context
-Context initCtx = new InitialContext();
-Context envCtx = (Context) initCtx.lookup("java:comp/env");
-
-// Look up our data source
-DataSource ds = (DataSource)
- envCtx.lookup("jdbc/EmployeeDB");
-
-// Allocate and use a connection from the pool
-Connection conn = ds.getConnection();
-... use this connection to access the database ...
-conn.close();
-</source>
-
-<p>See the following Specifications for more information about programming APIs
-for JNDI, and for the features supported by Java2 Enterprise Edition (J2EE)
-servers, which Tomcat emulates for the services that it provides:</p>
-<ul>
-<li><a href="http://java.sun.com/products/jndi";>Java Naming and Directory
- Interface</a> (included in JDK 1.4 onwards)</li>
-<li><a href="http://java.sun.com/j2ee/download.html";>J2EE Platform
- Specification</a> (in particular, see Chapter 5 on <em>Naming</em>)</li>
-</ul>
-
+<p>Providing that Tomcat is able to identify an appropriate resource factory to
+use to create the resource and that no further configuration information is
+required, Tomcat will use the information in <code>/WEB-INF/web.xml</code> to
+create the resource.</p>
</section>
+<section name="context.xml configuration">
-<section name="Configuring JNDI Resources">
+<p>If Tomcat is unable to identify the appropriate resource factory and/or
+additional configuration information is required, additional Tomcat specific
+configuration must be specified before Tomcat can create the resource.
+Tomcat specific resource configuration is entered in
+the <a href="config/context.html"><code><Context></code></a> elements
that
+can be specified in either <code>$CATALINA_BASE/conf/server.xml</code> or,
+preferably, the per-web-application context XML file
+(<code>META-INF/context.xml</code>).</p>
-<p>Each available JNDI Resource is configured based on inclusion of the
-following elements in the
-<a href="config/context.html"><code><Context></code></a> element:</p>
+<p>Tomcat specific resource configuration is performed using the following
+elements in the <a href="config/context.html"><code><Context></code></a>
+element:</p>
<ul>
<li><a href="config/context.html#Environment Entries"><Environment></a> -
@@ -145,28 +117,71 @@
</ul>
<p>Any number of these elements may be nested inside a
-<a href="config/context.html"><code><Context></code></a> element (to be
-associated only with that particular web application).</p>
+<a href="config/context.html"><code><Context></code></a> element and will
+be associated only with that particular web application.</p>
-<p>In addition, the names and values of all <code><env-entry></code>
-elements included in the web application deployment descriptor
-(<code>/WEB-INF/web.xml</code>) are configured into the initial context as
-well, overriding corresponding values from the
-<a href="config/context.html"><code><Context></code></a> element
+<p>If a resource has been defined in a
+<a href="config/context.html"><code><Context></code></a> element it is
not
+necessary for that resource to be defined in <code>/WEB-INF/web.xml</code>.
+However, it is recommended to keep the entry in <code>/WEB-INF/web.xml</code>
+to document the resource requirements for the web application.</p>
+
+<p>Where the same resource name has been defined for a
+<code><env-entry></code> element included in the web application
+deployment descriptor (<code>/WEB-INF/web.xml</code>) and in an
+<code><Environment></code> element as part of the
+<a href="config/context.html"><code><Context></code></a> element for the
+web application, the values in the deployment descriptor will take precedence
<strong>only</strong> if allowed by the corresponding
<code><Environment></code> element (by setting the <code>override</code>
attribute to "true").</p>
-<p>Global resources can be defined in the server-wide JNDI context, by adding
-the resource elements described above to the
-<a href="config/globalresources.html"><GlobalNamingResources></a>
-child element of the <a href="config/server.html"><Server></a>
-element and using a
+</section>
+
+<section name="Global configuration">
+
+<p>Tomcat 6 maintains a separate namespace of global resources for the
+entire server. These are configured in the
+<a href="config/globalresources.html">
+<code><strong><GlobalNameingResources></strong></code></a> element of
+<code>$CATALINA_BASE/conf/server.xml</code>. You may expose these resources to
+web applications by using a
<a href="config/context.html#Resource Links"><ResourceLink></a> to
include it in the per-web-application context.</p>
+<p>If a resource has been defined using a
+<a href="config/context.html#Resource Links"><ResourceLink></a>, it is
not
+necessary for that resource to be defined in <code>/WEB-INF/web.xml</code>.
+However, it is recommended to keep the entry in <code>/WEB-INF/web.xml</code>
+to document the resource requirements for the web application.</p>
+
</section>
+<section name="Using resources">
+
+<p>The <code>InitialContext</code> is configured as a web application is
+initially deployed, and is made available to web application components (for
+read-only access). All configured entries and resources are placed in
+the <code>java:comp/env</code> portion of the JNDI namespace, so a typical
+access to a resource - in this case, to a JDBC <code>DataSource</code> -
+would look something like this:</p>
+
+<source>
+// Obtain our environment naming context
+Context initCtx = new InitialContext();
+Context envCtx = (Context) initCtx.lookup("java:comp/env");
+
+// Look up our data source
+DataSource ds = (DataSource)
+ envCtx.lookup("jdbc/EmployeeDB");
+
+// Allocate and use a connection from the pool
+Connection conn = ds.getConnection();
+... use this connection to access the database ...
+conn.close();
+</source>
+
+</section>
<section name="Tomcat Standard Resource Factories">
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
