yoavs 2004/07/21 12:24:00
Modified: webapps/docs changelog.xml jndi-resources-howto.xml
webapps/docs/config globalresources.xml
Log:
Addressed Bugzilla 29584, cleaning up JNDI documentation.
Revision Changes Path
1.73 +3 -0 jakarta-tomcat-catalina/webapps/docs/changelog.xml
Index: changelog.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-catalina/webapps/docs/changelog.xml,v
retrieving revision 1.72
retrieving revision 1.73
diff -u -r1.72 -r1.73
--- changelog.xml 21 Jul 2004 18:11:05 -0000 1.72
+++ changelog.xml 21 Jul 2004 19:24:00 -0000 1.73
@@ -23,6 +23,9 @@
<fix>
<bug>30238</bug>: Replaced isapi_redirector.dll isapi_redirect.dll in
installation script for consistency. (yoavs)
</fix>
+ <fix>
+ <bug>29584</bug>: Enhanced and clarified JNDI documentation. (yoavs)
+ </fix>
</changelog>
</subsection>
1.6 +57 -12 jakarta-tomcat-catalina/webapps/docs/jndi-resources-howto.xml
Index: jndi-resources-howto.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-catalina/webapps/docs/jndi-resources-howto.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- jndi-resources-howto.xml 9 Aug 2003 18:59:22 -0000 1.5
+++ jndi-resources-howto.xml 21 Jul 2004 19:24:00 -0000 1.6
@@ -7,8 +7,9 @@
&project;
<properties>
- <author email="[EMAIL PROTECTED]">Craig R. McClanahan</author>
- <title>JNDI Resources HOW-TO</title>
+ <author email="[EMAIL PROTECTED]">Craig R. McClanahan</author>
+ <author email="[EMAIL PROTECTED]">Yoav Shapira</author>
+ <title>JNDI Resources HOW-TO</title>
</properties>
<body>
@@ -17,10 +18,42 @@
<section name="Introduction">
<p>Tomcat 5 provides a JNDI <strong>InitialContext</strong> implementation
-instance to web applications 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. Entries in this <code>InitialContext</code>
-are configured in the <code>$CATALINA_HOME/conf/server.xml</code> file, and
+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.
+
+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> or
+<code><strong><DefaultContext></strong></code>
+elements of the
+<a href="config/server.html"><code><strong><Server></strong></code></a>
+element.
+
+The <code><strong><Context></strong></code> element can be specified
+in either <code>$CATALINA_HOME/conf/server.xml</code> or, preferably,
+the per-web-application context XML file.
+
+<code><strong><DefaultContext></strong></code> must be specified in
+<code>$CATALINA_HOME/conf/server.xml</code>.
+</p>
+
+<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>
<ul>
@@ -39,10 +72,11 @@
<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 will be placed in
+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();
@@ -75,8 +109,9 @@
<section name="Configuring JNDI Resources">
<p>Each available JNDI Resource is configured based on inclusion of the
-following elements in the <code>$CATALINA_HOME/conf/server.xml</code>
-file:</p>
+following elements in the <code><strong><Context></strong></code> or
+<code><strong><DefaultContext></strong></code> elements:</p>
+
<ul>
<li><a href="config/context.html#Environment Entries"><Environment></a> -
Configure names and values for scalar environment entries that will be
@@ -89,12 +124,20 @@
application (equivalent to the inclusion of a
<code><resource-ref></code> element in the web application
deployment descriptor).</li>
-<li><a href="config/context.html#Resource Parameters"><ResourceParams></a> -
+
+<li>
+ <a href="config/context.html#Resource Parameters"><ResourceParams></a> -
Configure the Java class name of the resource factory implementation to be
used, as well as JavaBeans properties used to configure that resource
factory.</li>
+
<li><a href="config/context.html#Resource Links"><ResourceLink></a> -
- Add a link to a resource defined in the global JNDI context.</li>
+ Add a link to a resource defined in the global JNDI context. Use resource
+ links to give a web application access to a resource defined in
+ the<a href="config/globalresources.html"><GlobalNamingResources></a>
+ child element of the <a href="config/server.html"><Server></a>
+ element.</li>
+
</ul>
<p>Any number of these elements may be nested inside a
@@ -116,7 +159,9 @@
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.</p>
+element and using a
+<a href="config/context.html#Resource Links"><ResourceLink></a> to
+include it in the per-web-application context.</p>
</section>
1.3 +48 -8 jakarta-tomcat-catalina/webapps/docs/config/globalresources.xml
Index: globalresources.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-catalina/webapps/docs/config/globalresources.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- globalresources.xml 15 Jan 2003 03:40:44 -0000 1.2
+++ globalresources.xml 21 Jul 2004 19:24:00 -0000 1.3
@@ -8,6 +8,7 @@
<properties>
<author email="[EMAIL PROTECTED]">Remy Maucherat</author>
+ <author email="[EMAIL PROTECTED]">Yoav Shapira</author>
<title>The GlobalNamingResources Component</title>
</properties>
@@ -16,9 +17,19 @@
<section name="Introduction">
- <p>The <strong>GlobalNamingResources</strong> element represents the global
- JNDI resources which are defined
- for the <a href="server.html">Server</a>.</p>
+ <p>The <strong>GlobalNamingResources</strong> element defines the global
+ JNDI resources for the <a href="server.html">Server</a>.</p>
+
+ <p>These resources are listed in the server's global JNDI resource context.
+ This context is distinct from the per-web-application JNDI contexts
+ described in
+ the <a href="../jndi-resources-howto.html">JNDI Resources HOW-TO</a>.
+ With the exception of <code><strong><Environment></strong></code>
+ values,
+ the resources defined in this element are <strong>not</strong> visible in
+ the per-web-application contexts unless you explicitly link them with
+ <a href="context.html#Resource Links"><ResourceLink></a> elements.
+ </p>
</section>
@@ -38,9 +49,9 @@
<subsection name="Environment Entries">
- <p>You can configure named values that will be made visible to
- web applications as environment entry resources, by nesting
- <code><Environment></code> entries inside this element. For
+ <p>You can configure named values that will be made visible to all
+ web applications as environment entry resources by nesting
+ <code><Environment></code> entries inside this element. For
example, you can create an environment entry like this:</p>
<source>
<GlobalNamingResources ...>
@@ -109,10 +120,16 @@
<subsection name="Resource Definitions">
- <p>You can declare the characteristics of the resource
+ <p>You can declare the characteristics of resources
to be returned for JNDI lookups of <code><resource-ref></code> and
<code><resource-env-ref></code> elements in the web application
- deployment descriptor. You <strong>MUST</strong> also define
+ deployment descriptor by defining them in this element and then linking
+ them with <a href="context.html#Resource Links"><ResourceLink></a>
+ elements
+ in the <code><strong><Context></strong></code>
+ or <code><strong><DefaultContext></strong></code> elements.
+
+ You <strong>MUST</strong> also define
<a href="#Resource Parameters">Resource Parameters</a>
for the same resource name, to configure
the object factory to be used (if not known to Tomcat already), and
@@ -186,6 +203,29 @@
</subsection>
+ <subsection name="Resource Links">
+ <p>Use <a href="context.html#Resource Links"><ResourceLink></a>
+ elements to link resources from the global context into
+ per-web-application contexts. Here is an example of making a custom
+ factory available to all applications in the server, based on the example
+ definition in the
+ <a href="../jndi-resource-howto.html#Generic JavaBean Resources">
+ JNDI Resource HOW-TO</a>:
+ </p>
+
+ <source>
+ <![CDATA[
+ <DefaultContext>
+ <ResourceLink
+ name="bean/MyBeanFactory"
+ global="bean/MyBeanFactory"
+ type="com.mycompany.MyBean"
+ />
+ </DefaultContext>
+ ]]>
+ </source>
+
+ </subsection>
<subsection name="Resource Parameters">
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
