Author: markt
Date: Mon Dec 14 18:11:45 2009
New Revision: 890421
URL: http://svn.apache.org/viewvc?rev=890421&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/tc5.5.x/trunk/container/webapps/docs/changelog.xml
tomcat/tc5.5.x/trunk/container/webapps/docs/jndi-resources-howto.xml
Modified: tomcat/tc5.5.x/trunk/container/webapps/docs/changelog.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc5.5.x/trunk/container/webapps/docs/changelog.xml?rev=890421&r1=890420&r2=890421&view=diff
==============================================================================
--- tomcat/tc5.5.x/trunk/container/webapps/docs/changelog.xml (original)
+++ tomcat/tc5.5.x/trunk/container/webapps/docs/changelog.xml Mon Dec 14
18:11:45 2009
@@ -152,6 +152,11 @@
replacement in configuration files. (markt)
</fix>
<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/tc5.5.x/trunk/container/webapps/docs/jndi-resources-howto.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc5.5.x/trunk/container/webapps/docs/jndi-resources-howto.xml?rev=890421&r1=890420&r2=890421&view=diff
==============================================================================
--- tomcat/tc5.5.x/trunk/container/webapps/docs/jndi-resources-howto.xml
(original)
+++ tomcat/tc5.5.x/trunk/container/webapps/docs/jndi-resources-howto.xml Mon
Dec 14 18:11:45 2009
@@ -37,32 +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 5, these entries in per-web-application
-<code>InitialContext</code> are configured in the
-<code><strong><Context></strong></code> elements that can be specified
-in either <code>$CATALINA_HOME/conf/server.xml</code> or, preferably,
-the per-web-application context XML file (either
<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 5 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_HOME/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
@@ -77,46 +71,25 @@
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/#download";>Java Naming and
- Directory Interface</a> (included in JDK 1.4, available separately for
- prior JDK versions)</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 <code><strong><Context></strong></code>
+<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>
@@ -144,25 +117,70 @@
</ul>
<p>Any number of these elements may be nested inside a
-<a href="config/context.html"><Context></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 <code>conf/server.xml</code>
+<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>
+<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 5 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>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
