From 1b6d87f4f1bd3bbc9573f02c03012dddc5e8ce33 Mon Sep 17 00:00:00 2001 From: markt Date: Mon, 14 Dec 2009 18:04:54 +0000 Subject: [PATCH] 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 git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@890417 13f79535-47bb-0310-9956-ffa450edef68 --- webapps/docs/jndi-resources-howto.xml | 161 +++++++++++++++++++--------------- 1 file changed, 88 insertions(+), 73 deletions(-) diff --git a/webapps/docs/jndi-resources-howto.xml b/webapps/docs/jndi-resources-howto.xml index b9b98d453..6186cf843 100644 --- a/webapps/docs/jndi-resources-howto.xml +++ b/webapps/docs/jndi-resources-howto.xml @@ -37,34 +37,26 @@ instance for each web application running under it, in a manner that is compatible with those provided by a Java2 Enterprise Edition application -server. +server. The J2EE standard provides a standard set of elements in the +/WEB-INF/web.xml file to reference/define resources.

-The J2EE standard provides a standard set of elements in -the /WEB-INF/web.xml file to reference resources; resources -referenced in these elements must be defined in an application-server-specific -configuration. -

+

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:

+ -

For Tomcat 6, these entries in per-web-application -InitialContext are configured in the -<Context> elements that -can be specified in either $CATALINA_BASE/conf/server.xml or, -preferably, the per-web-application context XML file ( -META-INF/context.xml). -

+ -

Tomcat 6 maintains a separate namespace of global resources for the -entire server. These are configured in the - -<GlobalNameingResources> element of -$CATALINA_BASE/conf/server.xml. You may expose these resources to -web applications by using -<ResourceLink> elements. -

+
-

The resources defined in these elements -may be referenced by the following elements in the web application deployment -descriptor (/WEB-INF/web.xml) of your web application:

+

The following elements may be used in the web application deployment +descriptor (/WEB-INF/web.xml) of your web application to define +resources:

-

The InitialContext 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 java:comp/env portion of the JNDI namespace, so a typical -access to a resource - in this case, to a JDBC DataSource - -would look something like this:

- - -// 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(); - - -

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:

- - +

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 /WEB-INF/web.xml to +create the resource.

+
-
+

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 <Context> elements that +can be specified in either $CATALINA_BASE/conf/server.xml or, +preferably, the per-web-application context XML file +(META-INF/context.xml).

-

Each available JNDI Resource is configured based on inclusion of the -following elements in the -<Context> element:

+

Tomcat specific resource configuration is performed using the following +elements in the <Context> +element:

  • <Environment> - @@ -145,28 +117,71 @@ following elements in the

Any number of these elements may be nested inside a -<Context> element (to be -associated only with that particular web application).

- -

In addition, the names and values of all <env-entry> -elements included in the web application deployment descriptor -(/WEB-INF/web.xml) are configured into the initial context as -well, overriding corresponding values from the -<Context> element +<Context> element and will +be associated only with that particular web application.

+ +

If a resource has been defined in a +<Context> element it is not +necessary for that resource to be defined in /WEB-INF/web.xml. +However, it is recommended to keep the entry in /WEB-INF/web.xml +to document the resource requirements for the web application.

+ +

Where the same resource name has been defined for a +<env-entry> element included in the web application +deployment descriptor (/WEB-INF/web.xml) and in an +<Environment> element as part of the +<Context> element for the +web application, the values in the deployment descriptor will take precedence only if allowed by the corresponding <Environment> element (by setting the override attribute to "true").

-

Global resources can be defined in the server-wide JNDI context, by adding -the resource elements described above to the -<GlobalNamingResources> -child element of the <Server> -element and using a +

+ +
+ +

Tomcat 6 maintains a separate namespace of global resources for the +entire server. These are configured in the + +<GlobalNameingResources> element of +$CATALINA_BASE/conf/server.xml. You may expose these resources to +web applications by using a <ResourceLink> to include it in the per-web-application context.

+

If a resource has been defined using a +<ResourceLink>, it is not +necessary for that resource to be defined in /WEB-INF/web.xml. +However, it is recommended to keep the entry in /WEB-INF/web.xml +to document the resource requirements for the web application.

+
+
+ +

The InitialContext 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 java:comp/env portion of the JNDI namespace, so a typical +access to a resource - in this case, to a JDBC DataSource - +would look something like this:

+ + +// 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(); + + +
-- 2.11.0