http://issues.apache.org/bugzilla/show_bug.cgi?id=29584
Index: jndi-resources-howto.xml
===================================================================
RCS file:
/home/cvspublic/jakarta-tomcat-catalina/webapps/docs/jndi-resources-howto.xml,v
retrieving revision 1.5
diff -u -r1.5 jndi-resources-howto.xml
--- jndi-resources-howto.xml 9 Aug 2003 18:59:22 -0000 1.5
+++ jndi-resources-howto.xml 19 Jun 2004 00:53:36 -0000
@@ -17,10 +17,29 @@
<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
+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. Entries in this <code>InitialContext</code>
-are configured in the <code>$CATALINA_HOME/conf/server.xml</code> file, and
+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 file <code>$CATALINA_HOME/conf/HOSTNAME/WEBAPP.xml</code>.
+<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 resource 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,7 +58,7 @@
<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>
@@ -75,8 +94,8 @@
<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
@@ -94,11 +113,15 @@
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
-<a href="config/context.html"><Context></a> element (to be associated
+<a href="config/context.html"><Context></a> element(to be associated
only with that particular web application) or inside a
<a href="config/defaultcontext.html"><DefaultContext></a> element
(used to set the default configuration characteristics for automatically
@@ -116,7 +139,8 @@
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>
Index: globalresources.xml
===================================================================
RCS file:
/home/cvspublic/jakarta-tomcat-catalina/webapps/docs/config/globalresources.xml,v
retrieving revision 1.2
diff -u -r1.2 globalresources.xml
--- globalresources.xml 15 Jan 2003 03:40:44 -0000 1.2
+++ globalresources.xml 19 Jun 2004 01:16:25 -0000
@@ -16,10 +16,16 @@
<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 +44,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 +115,14 @@
<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
@@ -259,6 +269,26 @@
</attributes>
+ </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>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
