From 6efee31f42bc2b007008d85a6e34428eb2f59b99 Mon Sep 17 00:00:00 2001 From: markt Date: Sun, 20 Jan 2008 22:16:24 +0000 Subject: [PATCH] Update JNDI docs to refer to context elements rather than server.xml for configuration of resources. git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@613689 13f79535-47bb-0310-9956-ffa450edef68 --- webapps/docs/jndi-resources-howto.xml | 140 +++++++++++++++++++--------------- 1 file changed, 78 insertions(+), 62 deletions(-) diff --git a/webapps/docs/jndi-resources-howto.xml b/webapps/docs/jndi-resources-howto.xml index 8f95625be..82fd71962 100644 --- a/webapps/docs/jndi-resources-howto.xml +++ b/webapps/docs/jndi-resources-howto.xml @@ -41,14 +41,16 @@ server. 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. +referenced in these elements must be defined in an application-server-specific +configuration.

For Tomcat 6, these entries in per-web-application InitialContext are configured in the -<Context> elements that can be specified -in either $CATALINA_HOME/conf/server.xml or, preferably, -the per-web-application context XML file (either META-INF/context.xml). +<Context> elements that +can be specified in either $CATALINA_HOME/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 @@ -103,9 +105,8 @@ conn.close(); for JNDI, and for the features supported by Java2 Enterprise Edition (J2EE) servers, which Tomcat emulates for the services that it provides:

@@ -116,8 +117,8 @@ servers, which Tomcat emulates for the services that it provides:

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

+following elements in the +<Context> element:

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

+<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 conf/server.xml +well, overriding corresponding values from the +<Context> element only if allowed by the corresponding -<Environment> element (by setting the -override attribute to "true").

+<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 @@ -170,10 +172,11 @@ include it in the per-web-application context.

Tomcat 6 includes a series of standard resource factories that can provide services to your web applications, but give you configuration - flexibility (in $CATALINA_HOME/conf/server.xml) without - modifying the web application or the deployment descriptor. Each - subsection below details the configuration and usage of the standard - resource factories.

+ flexibility (via the + <Context> element) + without modifying the web application or the deployment descriptor. Each + subsection below details the configuration and usage of the standard resource + factories.

See Adding Custom Resource Factories for information about how to create, install, @@ -280,9 +283,10 @@ writer.println("foo = " + bean.getFoo() + ", bar = " +

4. Configure Tomcat's Resource Factory

-

To configure Tomcat's resource factory, add an elements like this to the - $CATALINA_HOME/conf/server.xml file, nested inside the - Context element for this web application.

+

To configure Tomcat's resource factory, add an element like this to the + <Context> element for + this web application.

+ <Context ...> ... @@ -318,7 +322,7 @@ writer.println("foo = " + bean.getFoo() + ", bar = " +

Tomcat 6 includes a standard resource factory that will create javax.mail.Session session instances for you, already - connected to the SMTP server that is configured in server.xml. + configured to connect to an SMTP server. In this way, the application is totally insulated from changes in the email server configuration environment - it simply asks for, and receives, a preconfigured session whenever needed.

@@ -380,14 +384,16 @@ Transport.send(message);

Note that the application uses the same resource reference name that was declared in the web application deployment descriptor. This - is matched up against the resource factory that is configured in - $CATALINA_HOME/conf/server.xml, as described below.

+ is matched up against the resource factory that is configured in the + <Context> element + for the web application as described below.

3. Configure Tomcat's Resource Factory

To configure Tomcat's resource factory, add an elements like this to the - $CATALINA_HOME/conf/server.xml file, nested inside the - Context element for this web application.

+ <Context> element for + this web application.

+ <Context ...> ... @@ -415,7 +421,7 @@ Transport.send(message); activation.jar and mail.jar. Unpackage both distributions and place them into $CATALINA_HOME/lib so that they are available to Tomcat during the initialization of the mail Session Resource. - Note: placing these jars in both common/lib and a + Note: placing these jars in both $CATALINA_HOME/lib and a web application's lib folder will cause an error, so ensure you have them in the $CATALINA_HOME/lib location only.

@@ -428,12 +434,13 @@ Transport.send(message); sends the mail message is in /WEB-INF/classes/SendMailServlet.java.

-

WARNING - The default configuration assumes that - there is an SMTP server listing on port 25 on localhost. - If this is not the case, edit the - $CATALINA_HOME/conf/server.xml file, and modify the - parameter value for the mail.smtp.host parameter to be - the host name of an SMTP server on your network.

+

WARNING - The default configuration assumes that there + is an SMTP server listing on port 25 on localhost. If this is + not the case, edit the + <Context> element for + this web application and modify the parameter value for the + mail.smtp.host parameter to be the host name of an SMTP server + on your network.

@@ -466,8 +473,8 @@ Transport.send(message);

NOTE - The default data source support in Tomcat is based on the DBCP connection pool from the - Jakarta Commons - subproject. However, it is possible to use any other connection pool + Commons + project. However, it is possible to use any other connection pool that implements javax.sql.DataSource, by writing your own custom resource factory, as described below.

@@ -495,7 +502,8 @@ Transport.send(message); <description> Resource reference to a factory for java.sql.Connection instances that may be used for talking to a particular - database that is configured in the server.xml file. + database that is configured in the <Context> + configurartion for the web application. </description> <res-ref-name> jdbc/EmployeeDB @@ -529,22 +537,30 @@ Connection conn = ds.getConnection(); conn.close(); -

Note that the application uses the same resource reference name - that was declared in the web application deployment descriptor. This - is matched up against the resource factory that is configured in - $CATALINA_HOME/conf/server.xml, as described below.

+

Note that the application uses the same resource reference name that was + declared in the web application deployment descriptor. This is matched up + against the resource factory that is configured in the + <Context> element for + the web application as described below.

4. Configure Tomcat's Resource Factory

To configure Tomcat's resource factory, add an element like this to the - /META-INF/context.xml file in the web application.

+ <Context> element for + the web application.

+ <Context ...> ... - <Resource name="jdbc/EmployeeDB" auth="Container" - type="javax.sql.DataSource" username="dbusername" password="dbpassword" - driverClassName="org.hsql.jdbcDriver" url="jdbc:HypersonicSQL:database" - maxActive="8" maxIdle="4"/> + <Resource name="jdbc/EmployeeDB" + auth="Container" + type="javax.sql.DataSource" + username="dbusername" + password="dbpassword" + driverClassName="org.hsql.jdbcDriver" + url="jdbc:HypersonicSQL:database" + maxActive="8" + maxIdle="4"/> ... </Context> @@ -592,13 +608,14 @@ conn.close();
-

If none of the standard resource factories meet your needs, you can - write your own factory and integrate it into Tomcat 6, and then configure - the use of this factory in the conf/server.xml configuration - file. In the example below, we will create a factory that only knows how - to create com.mycompany.MyBean beans, from the - Generic JavaBean Resources - example, above.

+

If none of the standard resource factories meet your needs, you can write + your own factory and integrate it into Tomcat 6, and then configure the use + of this factory in the + <Context> element for + the web application. In the example below, we will create a factory that only + knows how to create com.mycompany.MyBean beans from the + Generic JavaBean Resources example + above.

1. Write A Resource Factory Class

@@ -609,12 +626,12 @@ conn.close(); called, with the following arguments:

  • Object obj - The (possibly null) object containing - location or reference information that can be used in creating an - object. For Tomcat, this will always be an object of type - javax.naming.Reference, which contains the class name - of this factory class, as well as the configuration properties - (from conf/server.xml) to use in creating objects - to be returned.
    • + location or reference information that can be used in creating an object. + For Tomcat, this will always be an object of type + javax.naming.Reference, which contains the class name of + this factory class, as well as the configuration properties (from the + <Context> for the + web application) to use in creating objects to be returned.
  • Name name - The name to which this factory is bound relative to nameCtx, or null if no name is specified.
    • @@ -741,8 +758,9 @@ writer.println("foo = " + bean.getFoo() + ", bar = " +

    4. Configure Tomcat's Resource Factory

    To configure Tomcat's resource factory, add an elements like this to the - $CATALINA_HOME/conf/server.xml file, nested inside the - Context element for this web application.

    + <Context> element for + this web application.

    + <Context ...> ... @@ -773,8 +791,6 @@ writer.println("foo = " + bean.getFoo() + ", bar = " +
- - -- 2.11.0