Author: markt
Date: Mon Dec 14 18:04:54 2009
New Revision: 890417
URL: http://svn.apache.org/viewvc?rev=890417&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/trunk/webapps/docs/jndi-resources-howto.xml
Modified: tomcat/trunk/webapps/docs/jndi-resources-howto.xml
URL:
http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/jndi-resources-howto.xml?rev=890417&r1=890416&r2=890417&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/jndi-resources-howto.xml (original)
+++ tomcat/trunk/webapps/docs/jndi-resources-howto.xml Mon Dec 14 18:04:54 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
