Author: markt Date: Sun Jan 20 14:16:24 2008 New Revision: 613689 URL: http://svn.apache.org/viewvc?rev=613689&view=rev Log: Update JNDI docs to refer to context elements rather than server.xml for configuration of resources.
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=613689&r1=613688&r2=613689&view=diff ============================================================================== --- tomcat/trunk/webapps/docs/jndi-resources-howto.xml (original) +++ tomcat/trunk/webapps/docs/jndi-resources-howto.xml Sun Jan 20 14:16:24 2008 @@ -41,14 +41,16 @@ 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. +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 -<code><strong><Context></strong></code> elements that can be specified -in either <code>$CATALINA_HOME/conf/server.xml</code> or, preferably, -the per-web-application context XML file (either <code>META-INF/context.xml</code>). +<a href="config/context.html"><code><Context></code></a> elements that +can be specified in either <code>$CATALINA_HOME/conf/server.xml</code> or, +preferably, the per-web-application context XML file ( +<code>META-INF/context.xml</code>). </p> <p>Tomcat 6 maintains a separate namespace of global resources for the @@ -103,9 +105,8 @@ 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/#download">Java Naming and - Directory Interface</a> (included in JDK 1.4, available separately for - prior JDK versions)</li> +<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> @@ -116,8 +117,8 @@ <section name="Configuring JNDI Resources"> <p>Each available JNDI Resource is configured based on inclusion of the -following elements in the <code><strong><Context></strong></code> or -<code><strong><DefaultContext></strong></code> elements:</p> +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> - @@ -144,16 +145,17 @@ </ul> <p>Any number of these elements may be nested inside a -<a href="config/context.html"><Context></a> element (to be associated -only with that particular web application).</p> +<a href="config/context.html"><code><Context></code></a> element (to 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 <code>conf/server.xml</code> +well, overriding corresponding values from the +<a href="config/context.html"><code><Context></code></a> element <strong>only</strong> if allowed by the corresponding -<code><Environment></code> element (by setting the -<code>override</code> attribute to "true").</p> +<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 @@ -170,10 +172,11 @@ <p>Tomcat 6 includes a series of standard resource factories that can provide services to your web applications, but give you configuration - flexibility (in <code>$CATALINA_HOME/conf/server.xml</code>) without - modifying the web application or the deployment descriptor. Each - subsection below details the configuration and usage of the standard - resource factories.</p> + flexibility (via the + <a href="config/context.html"><code><Context></code></a> element) + without modifying the web application or the deployment descriptor. Each + subsection below details the configuration and usage of the standard resource + factories.</p> <p>See <a href="#Adding Custom Resource Factories">Adding Custom Resource Factories</a> for information about how to create, install, @@ -280,9 +283,10 @@ <h3>4. Configure Tomcat's Resource Factory</h3> - <p>To configure Tomcat's resource factory, add an elements like this to the - <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the - <code>Context</code> element for this web application.</p> + <p>To configure Tomcat's resource factory, add an element like this to the + <a href="config/context.html"><code><Context></code></a> element for + this web application.</p> + <source> <Context ...> ... @@ -318,7 +322,7 @@ <p>Tomcat 6 includes a standard resource factory that will create <code>javax.mail.Session</code> session instances for you, already - connected to the SMTP server that is configured in <code>server.xml</code>. + 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.</p> @@ -380,14 +384,16 @@ <p>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 - <code>$CATALINA_HOME/conf/server.xml</code>, as described below.</p> + is matched up against the resource factory that is configured in the + <a href="config/context.html"><code><Context></code></a> element + for the web application as described below.</p> <h3>3. Configure Tomcat's Resource Factory</h3> <p>To configure Tomcat's resource factory, add an elements like this to the - <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the - <code>Context</code> element for this web application.</p> + <a href="config/context.html"><code><Context></code></a> element for + this web application.</p> + <source> <Context ...> ... @@ -415,7 +421,7 @@ 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. - <strong>Note:</strong> placing these jars in both common/lib and a + <strong>Note:</strong> 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. </p> @@ -428,12 +434,13 @@ sends the mail message is in <code>/WEB-INF/classes/SendMailServlet.java</code>.</p> - <p><strong>WARNING</strong> - The default configuration assumes that - there is an SMTP server listing on port 25 on <code>localhost</code>. - If this is not the case, edit the - <code>$CATALINA_HOME/conf/server.xml</code> file, and modify the - parameter value for the <code>mail.smtp.host</code> parameter to be - the host name of an SMTP server on your network.</p> + <p><strong>WARNING</strong> - The default configuration assumes that there + is an SMTP server listing on port 25 on <code>localhost</code>. If this is + not the case, edit the + <a href="config/context.html"><code><Context></code></a> element for + this web application and modify the parameter value for the + <code>mail.smtp.host</code> parameter to be the host name of an SMTP server + on your network.</p> </subsection> @@ -466,8 +473,8 @@ <p><strong>NOTE</strong> - The default data source support in Tomcat is based on the <strong>DBCP</strong> connection pool from the - <a href="http://jakarta.apache.org/commons">Jakarta Commons</a> - subproject. However, it is possible to use any other connection pool + <a href="http://commons.apache.org/">Commons</a> + project. However, it is possible to use any other connection pool that implements <code>javax.sql.DataSource</code>, by writing your own custom resource factory, as described <a href="#Adding Custom Resource Factories">below</a>.</p> @@ -495,7 +502,8 @@ <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 @@ conn.close(); </source> - <p>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 - <code>$CATALINA_HOME/conf/server.xml</code>, as described below.</p> + <p>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 + <a href="config/context.html"><code><Context></code></a> element for + the web application as described below.</p> <h3>4. Configure Tomcat's Resource Factory</h3> <p>To configure Tomcat's resource factory, add an element like this to the - <code>/META-INF/context.xml</code> file in the web application.</p> + <a href="config/context.html"><code><Context></code></a> element for + the web application.</p> + <source> <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> </source> @@ -592,13 +608,14 @@ <section name="Adding Custom Resource Factories"> - <p>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 <code>conf/server.xml</code> configuration - file. In the example below, we will create a factory that only knows how - to create <code>com.mycompany.MyBean</code> beans, from the - <a href="#Generic JavaBean Resources">Generic JavaBean Resources</a> - example, above.</p> + <p>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 + <a href="config/context.html"><code><Context></code></a> element for + the web application. In the example below, we will create a factory that only + knows how to create <code>com.mycompany.MyBean</code> beans from the + <a href="#Generic JavaBean Resources">Generic JavaBean Resources</a> example + above.</p> <h3>1. Write A Resource Factory Class</h3> @@ -609,12 +626,12 @@ called, with the following arguments:</p> <ul> <li><strong>Object obj</strong> - 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 - <code>javax.naming.Reference</code>, which contains the class name - of this factory class, as well as the configuration properties - (from <code>conf/server.xml</code>) to use in creating objects - to be returned.</li> + location or reference information that can be used in creating an object. + For Tomcat, this will always be an object of type + <code>javax.naming.Reference</code>, which contains the class name of + this factory class, as well as the configuration properties (from the + <a href="config/context.html"><code><Context></code></a> for the + web application) to use in creating objects to be returned.</li> <li><strong>Name name</strong> - The name to which this factory is bound relative to <code>nameCtx</code>, or <code>null</code> if no name is specified.</li> @@ -741,8 +758,9 @@ <h3>4. Configure Tomcat's Resource Factory</h3> <p>To configure Tomcat's resource factory, add an elements like this to the - <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the - <code>Context</code> element for this web application.</p> + <a href="config/context.html"><code><Context></code></a> element for + this web application.</p> + <source> <Context ...> ... @@ -772,8 +790,6 @@ compatible APIs.</p> </section> - - </body> --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]