Gitiles
Code Review Sign In
source.supwisdom.com / portal_platform / tomcat-cms / 07b3087b89f4c23810bb2a7902fe5a06f392b984 / . / webapps / docs / jndi-resources-howto.html
blob: 1e44b0b0a48262ed9aa62dd9dfe2d06c08c10b1a [file] [log] [blame]
Cheng Tang07b30872014-04-27 16:37:18 +0800[diff] [blame^]1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 7 (7.0.42) - JNDI Resources HOW-TO</title><meta name="author" content="Craig R. McClanahan"><meta name="author" content="Yoav Shapira"><style type="text/css" media="print">
2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4 </style><style type="text/css">
5 code {background-color:rgb(224,255,255);padding:0 0.1em;}
6 code.attributeName, code.propertyName {background-color:transparent;}
7 </style><style type="text/css">
8 .wrapped-source code { display: block; background-color: transparent; }
9 .wrapped-source div { margin: 0 0 0 1.25em; }
10 .wrapped-source p { margin: 0 0 0 1.25em; text-indent: -1.25em; }
11 </style><style type="text/css">
12 p.notice {
13 border: 1px solid rgb(255, 0, 0);
14 background-color: rgb(238, 238, 238);
15 color: rgb(0, 51, 102);
16 padding: 0.5em;
17 margin: 1em 2em 1em 1em;
18 }
19 </style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="./images/tomcat.gif" align="right" alt="
20 The Apache Tomcat Servlet/JSP Container
21 " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.42, Jul 2 2013</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="./images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap class="noPrint"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul><p><strong>User Guide</strong></p><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="realm-howto.html">6) Realms and AAA</a></li><li><a href="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptor-howto.html">16) MBean Descriptor</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-hosting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</a></li><li><a href="maven-jars.html">27) Mavenized</a></li><li><a href="security-howto.html">28) Security Considerations</a></li><li><a href="windows-service-howto.html">29) Windows Service</a></li><li><a href="windows-auth-howto.html">30) Windows Authentication</a></li><li><a href="jdbc-pool.html">31) Tomcat's JDBC Pool</a></li><li><a href="web-socket-howto.html">32) WebSocket</a></li></ul><p><strong>Reference</strong></p><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Tomcat Javadocs</a></li><li><a href="servletapi/index.html">Servlet Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.2 Javadocs</a></li><li><a href="elapi/index.html">EL 2.2 Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li><li><a href="tribes/introduction.html">Tribes</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>JNDI Resources HOW-TO</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
22<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#web.xml_configuration">web.xml configuration</a></li><li><a href="#context.xml_configuration">context.xml configuration</a></li><li><a href="#Global_configuration">Global configuration</a></li><li><a href="#Using_resources">Using resources</a></li><li><a href="#Tomcat_Standard_Resource_Factories">Tomcat Standard Resource Factories</a><ol><li><a href="#Generic_JavaBean_Resources">Generic JavaBean Resources</a></li><li><a href="#UserDatabase_Resources">UserDatabase Resources</a></li><li><a href="#JavaMail_Sessions">JavaMail Sessions</a></li><li><a href="#JDBC_Data_Sources">JDBC Data Sources</a></li></ol></li><li><a href="#Adding_Custom_Resource_Factories">Adding Custom Resource Factories</a></li></ul>
23</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
24
25<p>Tomcat provides a JNDI <strong>InitialContext</strong> implementation
26instance for each web application running under it, in a manner that is
27compatible with those provided by a
28<a href="http://java.sun.com/j2ee">Java Enterprise Edition</a> application
29server. The Java EE standard provides a standard set of elements in the
30<code>/WEB-INF/web.xml</code> file to reference/define resources.</p>
31
32<p>See the following Specifications for more information about programming APIs
33for JNDI, and for the features supported by Java Enterprise Edition (Java EE)
34servers, which Tomcat emulates for the services that it provides:</p>
35<ul>
36<li><a href="http://java.sun.com/products/jndi">Java Naming and Directory
37 Interface</a> (included in JDK 1.4 onwards)</li>
38<li><a href="http://java.sun.com/j2ee/download.html">Java EE Platform
39 Specification</a> (in particular, see Chapter 5 on <em>Naming</em>)</li>
40</ul>
41
42</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="web.xml configuration"><!--()--></a><a name="web.xml_configuration"><strong>web.xml configuration</strong></a></font></td></tr><tr><td><blockquote>
43
44<p>The following elements may be used in the web application deployment
45descriptor (<code>/WEB-INF/web.xml</code>) of your web application to define
46resources:</p>
47<ul>
48<li><code><strong>&lt;env-entry&gt;</strong></code> - Environment entry, a
49 single-value parameter that can be used to configure how the application
50 will operate.</li>
51<li><code><strong>&lt;resource-ref&gt;</strong></code> - Resource reference,
52 which is typically to an object factory for resources such as a JDBC
53 <code>DataSource</code>, a JavaMail <code>Session</code>, or custom
54 object factories configured into Tomcat.</li>
55<li><code><strong>&lt;resource-env-ref&gt;</strong></code> - Resource
56 environment reference, a new variation of <code>resource-ref</code>
57 added in Servlet 2.4 that is simpler to configure for resources
58 that do not require authentication information.</li>
59</ul>
60
61<p>Providing that Tomcat is able to identify an appropriate resource factory to
62use to create the resource and that no further configuration information is
63required, Tomcat will use the information in <code>/WEB-INF/web.xml</code> to
64create the resource.</p>
65
66<p>Tomcat provides a number of Tomcat specific options for JNDI resources that
67cannot be specified in web.xml. These include <code>closeMethod</code> that
68enables faster cleaning-up of JNDI resources when a web application stops and
69<code>singleton</code> that controls whether or not a new instance of the
70resource is created for every JNDI lookup. To use these configuration options
71the resource must be specified in a web application's
72<a href="config/context.html"><code>&lt;Context&gt;</code></a> element or in the
73<a href="config/globalresources.html">
74<code><strong>&lt;GlobalNamingResources&gt;</strong></code></a> element of
75<code>$CATALINA_BASE/conf/server.xml</code>.</p>
76
77</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="context.xml configuration"><!--()--></a><a name="context.xml_configuration"><strong>context.xml configuration</strong></a></font></td></tr><tr><td><blockquote>
78
79<p>If Tomcat is unable to identify the appropriate resource factory and/or
80additional configuration information is required, additional Tomcat specific
81configuration must be specified before Tomcat can create the resource.
82Tomcat specific resource configuration is entered in
83the <a href="config/context.html"><code>&lt;Context&gt;</code></a> elements that
84can be specified in either <code>$CATALINA_BASE/conf/server.xml</code> or,
85preferably, the per-web-application context XML file
86(<code>META-INF/context.xml</code>).</p>
87
88<p>Tomcat specific resource configuration is performed using the following
89elements in the <a href="config/context.html"><code>&lt;Context&gt;</code></a>
90element:</p>
91
92<ul>
93<li><a href="config/context.html#Environment Entries">&lt;Environment&gt;</a> -
94 Configure names and values for scalar environment entries that will be
95 exposed to the web application through the JNDI
96 <code>InitialContext</code> (equivalent to the inclusion of an
97 <code>&lt;env-entry&gt;</code> element in the web application
98 deployment descriptor).</li>
99<li><a href="config/context.html#Resource Definitions">&lt;Resource&gt;</a> -
100 Configure the name and data type of a resource made available to the
101 application (equivalent to the inclusion of a
102 <code>&lt;resource-ref&gt;</code> element in the web application
103 deployment descriptor).</li>
104<li><a href="config/context.html#Resource Links">&lt;ResourceLink&gt;</a> -
105 Add a link to a resource defined in the global JNDI context. Use resource
106 links to give a web application access to a resource defined in
107 the <a href="config/globalresources.html">&lt;GlobalNamingResources&gt;</a>
108 child element of the <a href="config/server.html">&lt;Server&gt;</a>
109 element.</li>
110<li><a href="config/context.html#Transaction">&lt;Transaction&gt;</a> -
111 Add a resource factory for instantiating the UserTransaction object
112 instance that is available at <code>java:comp/UserTransaction</code>.</li>
113
114</ul>
115
116<p>Any number of these elements may be nested inside a
117<a href="config/context.html"><code>&lt;Context&gt;</code></a> element and will
118be associated only with that particular web application.</p>
119
120<p>If a resource has been defined in a
121<a href="config/context.html"><code>&lt;Context&gt;</code></a> element it is not
122necessary for that resource to be defined in <code>/WEB-INF/web.xml</code>.
123However, it is recommended to keep the entry in <code>/WEB-INF/web.xml</code>
124to document the resource requirements for the web application.</p>
125
126<p>Where the same resource name has been defined for a
127<code>&lt;env-entry&gt;</code> element included in the web application
128deployment descriptor (<code>/WEB-INF/web.xml</code>) and in an
129<code>&lt;Environment&gt;</code> element as part of the
130<a href="config/context.html"><code>&lt;Context&gt;</code></a> element for the
131web application, the values in the deployment descriptor will take precedence
132<strong>only</strong> if allowed by the corresponding
133<code>&lt;Environment&gt;</code> element (by setting the <code>override</code>
134attribute to "true").</p>
135
136</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Global configuration"><!--()--></a><a name="Global_configuration"><strong>Global configuration</strong></a></font></td></tr><tr><td><blockquote>
137
138<p>Tomcat maintains a separate namespace of global resources for the
139entire server. These are configured in the
140<a href="config/globalresources.html">
141<code><strong>&lt;GlobalNamingResources&gt;</strong></code></a> element of
142<code>$CATALINA_BASE/conf/server.xml</code>. You may expose these resources to
143web applications by using a
144<a href="config/context.html#Resource Links">&lt;ResourceLink&gt;</a> to
145include it in the per-web-application context.</p>
146
147<p>If a resource has been defined using a
148<a href="config/context.html#Resource Links">&lt;ResourceLink&gt;</a>, it is not
149necessary for that resource to be defined in <code>/WEB-INF/web.xml</code>.
150However, it is recommended to keep the entry in <code>/WEB-INF/web.xml</code>
151to document the resource requirements for the web application.</p>
152
153</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Using resources"><!--()--></a><a name="Using_resources"><strong>Using resources</strong></a></font></td></tr><tr><td><blockquote>
154
155<p>The <code>InitialContext</code> is configured as a web application is
156initially deployed, and is made available to web application components (for
157read-only access). All configured entries and resources are placed in
158the <code>java:comp/env</code> portion of the JNDI namespace, so a typical
159access to a resource - in this case, to a JDBC <code>DataSource</code> -
160would look something like this:</p>
161
162<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
163// Obtain our environment naming context
164Context initCtx = new InitialContext();
165Context envCtx = (Context) initCtx.lookup("java:comp/env");
166
167// Look up our data source
168DataSource ds = (DataSource)
169 envCtx.lookup("jdbc/EmployeeDB");
170
171// Allocate and use a connection from the pool
172Connection conn = ds.getConnection();
173... use this connection to access the database ...
174conn.close();
175</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
176
177</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Tomcat Standard Resource Factories"><!--()--></a><a name="Tomcat_Standard_Resource_Factories"><strong>Tomcat Standard Resource Factories</strong></a></font></td></tr><tr><td><blockquote>
178
179 <p>Tomcat includes a series of standard resource factories that can
180 provide services to your web applications, but give you configuration
181 flexibility (via the
182 <a href="config/context.html"><code>&lt;Context&gt;</code></a> element)
183 without modifying the web application or the deployment descriptor. Each
184 subsection below details the configuration and usage of the standard resource
185 factories.</p>
186
187 <p>See <a href="#Adding Custom Resource Factories">Adding Custom
188 Resource Factories</a> for information about how to create, install,
189 configure, and use your own custom resource factory classes with
190 Tomcat.</p>
191
192 <p><em>NOTE</em> - Of the standard resource factories, only the
193 "JDBC Data Source" and "User Transaction" factories are mandated to
194 be available on other platforms, and then they are required only if
195 the platform implements the Java Enterprise Edition (Java EE) specs.
196 All other standard resource factories, plus custom resource factories
197 that you write yourself, are specific to Tomcat and cannot be assumed
198 to be available on other containers.</p>
199
200 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Generic JavaBean Resources"><!--()--></a><a name="Generic_JavaBean_Resources"><strong>Generic JavaBean Resources</strong></a></font></td></tr><tr><td><blockquote>
201
202 <h3>0. Introduction</h3>
203
204 <p>This resource factory can be used to create objects of <em>any</em>
205 Java class that conforms to standard JavaBeans naming conventions (i.e.
206 it has a zero-arguments constructor, and has property setters that
207 conform to the setFoo() naming pattern. The resource factory will
208 create a new instance of the appropriate bean class every time a
209 <code>lookup()</code> for this entry is made.</p>
210
211 <p>The steps required to use this facility are described below.</p>
212
213 <h3>1. Create Your JavaBean Class</h3>
214
215 <p>Create the JavaBean class which will be instantiated each time
216 that the resource factory is looked up. For this example, assume
217 you create a class <code>com.mycompany.MyBean</code>, which looks
218 like this:</p>
219
220<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
221package com.mycompany;
222
223public class MyBean {
224
225 private String foo = "Default Foo";
226
227 public String getFoo() {
228 return (this.foo);
229 }
230
231 public void setFoo(String foo) {
232 this.foo = foo;
233 }
234
235 private int bar = 0;
236
237 public int getBar() {
238 return (this.bar);
239 }
240
241 public void setBar(int bar) {
242 this.bar = bar;
243 }
244
245
246}
247</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
248
249 <h3>2. Declare Your Resource Requirements</h3>
250
251 <p>Next, modify your web application deployment descriptor
252 (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under which
253 you will request new instances of this bean. The simplest approach is
254 to use a <code>&lt;resource-env-ref&gt;</code> element, like this:</p>
255
256<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
257&lt;resource-env-ref&gt;
258 &lt;description&gt;
259 Object factory for MyBean instances.
260 &lt;/description&gt;
261 &lt;resource-env-ref-name&gt;
262 bean/MyBeanFactory
263 &lt;/resource-env-ref-name&gt;
264 &lt;resource-env-ref-type&gt;
265 com.mycompany.MyBean
266 &lt;/resource-env-ref-type&gt;
267&lt;/resource-env-ref&gt;
268</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
269
270 <p><strong>WARNING</strong> - Be sure you respect the element ordering
271 that is required by the DTD for web application deployment descriptors!
272 See the
273 <a href="http://wiki.apache.org/tomcat/Specifications">Servlet
274 Specification</a> for details.</p>
275
276 <h3>3. Code Your Application's Use Of This Resource</h3>
277
278 <p>A typical use of this resource environment reference might look
279 like this:</p>
280
281<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
282Context initCtx = new InitialContext();
283Context envCtx = (Context) initCtx.lookup("java:comp/env");
284MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory");
285
286writer.println("foo = " + bean.getFoo() + ", bar = " +
287 bean.getBar());
288</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
289
290 <h3>4. Configure Tomcat's Resource Factory</h3>
291
292 <p>To configure Tomcat's resource factory, add an element like this to the
293 <a href="config/context.html"><code>&lt;Context&gt;</code></a> element for
294 this web application.</p>
295
296<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
297&lt;Context ...&gt;
298 ...
299 &lt;Resource name="bean/MyBeanFactory" auth="Container"
300 type="com.mycompany.MyBean"
301 factory="org.apache.naming.factory.BeanFactory"
302 bar="23"/&gt;
303 ...
304&lt;/Context&gt;
305</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
306
307 <p>Note that the resource name (here, <code>bean/MyBeanFactory</code>
308 must match the value specified in the web application deployment
309 descriptor. We are also initializing the value of the <code>bar</code>
310 property, which will cause <code>setBar(23)</code> to be called before
311 the new bean is returned. Because we are not initializing the
312 <code>foo</code> property (although we could have), the bean will
313 contain whatever default value is set up by its constructor.</p>
314
315 </blockquote></td></tr></table>
316
317
318 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="UserDatabase Resources"><!--()--></a><a name="UserDatabase_Resources"><strong>UserDatabase Resources</strong></a></font></td></tr><tr><td><blockquote>
319
320 <h3>0. Introduction</h3>
321
322 <p>UserDatabase resources are typically configured as global resources for
323 use by a UserDatabase realm. Tomcat includes a UserDatabaseFactoory that
324 creates UserDatabase resources backed by an XML file - usually
325 <code>tomcat-users.xml</code></p>
326
327 <p>The steps required to set up a global UserDatabase resource are described
328 below.</p>
329
330 <h3>1. Create/edit the XML file</h3>
331
332 <p>The XMl file is typically located at
333 <code>$CATALINA_BASE/conf/tomcat-users.xml</code> however, you are free to
334 locate the file anywhere on the file system. It is recommended that the XML
335 files are placed in <code>$CATALINA_BASE/conf</code>. A typical XML would
336 look like:</p>
337
338<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
339&lt;?xml version='1.0' encoding='utf-8'?&gt;
340&lt;tomcat-users&gt;
341 &lt;role rolename="tomcat"/&gt;
342 &lt;role rolename="role1"/&gt;
343 &lt;user username="tomcat" password="tomcat" roles="tomcat"/&gt;
344 &lt;user username="both" password="tomcat" roles="tomcat,role1"/&gt;
345 &lt;user username="role1" password="tomcat" roles="role1"/&gt;
346&lt;/tomcat-users&gt;
347</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
348
349 <h3>2. Declare Your Resource</h3>
350
351 <p>Next, modify <code>$CATALINA_BASE/conf/server.xml</code> to create the
352 UserDatabase resource based on your XMl file. It should look something like
353 this:</p>
354
355<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
356&lt;Resource name="UserDatabase"
357 auth="Container"
358 type="org.apache.catalina.UserDatabase"
359 description="User database that can be updated and saved"
360 factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
361 pathname="conf/tomcat-users.xml"
362 readonly="false" /&gt;
363</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
364
365 <p>The <code>pathname</code> attribute can be absolute or relative. If
366 relative, it is relative to <code>$CATALINA_BASE</code>.</p>
367
368 <p>The <code>readonly</code> attribute is optional and defaults to
369 <code>true</code> if not supplied. If the XML is writeable then it will be
370 written to when Tomcat starts. <strong>WARNING:</strong> When the file is
371 written it will inherit the default file permissions for the user Tomcat
372 is running as. Ensure that these are appropriate to maintain the security
373 of your installation.</p>
374
375 <h3>3. Configure the Realm</h3>
376
377 <p>Configure a UserDatabase Realm to use this resource as described in the
378 <a href="config/realm.html">Realm configuration documentation</a>.</p>
379
380 </blockquote></td></tr></table>
381
382
383 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="JavaMail Sessions"><!--()--></a><a name="JavaMail_Sessions"><strong>JavaMail Sessions</strong></a></font></td></tr><tr><td><blockquote>
384
385 <h3>0. Introduction</h3>
386
387 <p>In many web applications, sending electronic mail messages is a
388 required part of the system's functionality. The
389 <a href="http://java.sun.com/products/javamail">Java Mail</a> API
390 makes this process relatively straightforward, but requires many
391 configuration details that the client application must be aware of
392 (including the name of the SMTP host to be used for message sending).</p>
393
394 <p>Tomcat includes a standard resource factory that will create
395 <code>javax.mail.Session</code> session instances for you, already
396 configured to connect to an SMTP server.
397 In this way, the application is totally insulated from changes in the
398 email server configuration environment - it simply asks for, and receives,
399 a preconfigured session whenever needed.</p>
400
401 <p>The steps required for this are outlined below.</p>
402
403 <h3>1. Declare Your Resource Requirements</h3>
404
405 <p>The first thing you should do is modify the web application deployment
406 descriptor (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under
407 which you will look up preconfigured sessions. By convention, all such
408 names should resolve to the <code>mail</code> subcontext (relative to the
409 standard <code>java:comp/env</code> naming context that is the root of
410 all provided resource factories. A typical <code>web.xml</code> entry
411 might look like this:</p>
412<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
413&lt;resource-ref&gt;
414 &lt;description&gt;
415 Resource reference to a factory for javax.mail.Session
416 instances that may be used for sending electronic mail
417 messages, preconfigured to connect to the appropriate
418 SMTP server.
419 &lt;/description&gt;
420 &lt;res-ref-name&gt;
421 mail/Session
422 &lt;/res-ref-name&gt;
423 &lt;res-type&gt;
424 javax.mail.Session
425 &lt;/res-type&gt;
426 &lt;res-auth&gt;
427 Container
428 &lt;/res-auth&gt;
429&lt;/resource-ref&gt;
430</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
431
432 <p><strong>WARNING</strong> - Be sure you respect the element ordering
433 that is required by the DTD for web application deployment descriptors!
434 See the
435 <a href="http://wiki.apache.org/tomcat/Specifications">Servlet
436 Specification</a> for details.</p>
437
438 <h3>2. Code Your Application's Use Of This Resource</h3>
439
440 <p>A typical use of this resource reference might look like this:</p>
441<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
442Context initCtx = new InitialContext();
443Context envCtx = (Context) initCtx.lookup("java:comp/env");
444Session session = (Session) envCtx.lookup("mail/Session");
445
446Message message = new MimeMessage(session);
447message.setFrom(new InternetAddress(request.getParameter("from")));
448InternetAddress to[] = new InternetAddress[1];
449to[0] = new InternetAddress(request.getParameter("to"));
450message.setRecipients(Message.RecipientType.TO, to);
451message.setSubject(request.getParameter("subject"));
452message.setContent(request.getParameter("content"), "text/plain");
453Transport.send(message);
454</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
455
456 <p>Note that the application uses the same resource reference name
457 that was declared in the web application deployment descriptor. This
458 is matched up against the resource factory that is configured in the
459 <a href="config/context.html"><code>&lt;Context&gt;</code></a> element
460 for the web application as described below.</p>
461
462 <h3>3. Configure Tomcat's Resource Factory</h3>
463
464 <p>To configure Tomcat's resource factory, add an elements like this to the
465 <a href="config/context.html"><code>&lt;Context&gt;</code></a> element for
466 this web application.</p>
467
468<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
469&lt;Context ...&gt;
470 ...
471 &lt;Resource name="mail/Session" auth="Container"
472 type="javax.mail.Session"
473 mail.smtp.host="localhost"/&gt;
474 ...
475&lt;/Context&gt;
476</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
477
478 <p>Note that the resource name (here, <code>mail/Session</code>) must
479 match the value specified in the web application deployment descriptor.
480 Customize the value of the <code>mail.smtp.host</code> parameter to
481 point at the server that provides SMTP service for your network.</p>
482
483 <p>Additional resource attributes and values will be converted to properties
484 and values and passed to
485 <code>javax.mail.Session.getInstance(java.util.Properties)</code> as part of
486 the <code>java.util.Properties</code> collection. In addition to the
487 properties defined in Annex A of the JavaMail specification, individual
488 providers may also support additional properties.
489 </p>
490
491 <p>If the resource is configured with a <code>password</code> attribute and
492 either a <code>mail.smtp.user</code> or <code>mail.user</code> attribute
493 then Tomcat's resource factory will configure and add a
494 <code>javax.mail.Authenticator</code> to the mail session.</p>
495
496 <h3>4. Install the JavaMail libraries</h3>
497
498 <p><a href="http://www.oracle.com/technetwork/java/index-138643.html">
499 Download the JavaMail API</a>.</p>
500
501 <p>Unpackage the distribution and place mail.jar into $CATALINA_HOME/lib so
502 that it is available to Tomcat during the initialization of the mail Session
503 Resource. <strong>Note:</strong> placing this jar in both $CATALINA_HOME/lib
504 and a web application's lib folder will cause an error, so ensure you have
505 it in the $CATALINA_HOME/lib location only.
506 </p>
507
508 <h3>5. Restart Tomcat</h3>
509
510 <p>For the additional JAR to be visible to Tomcat, it is necessary for the
511 Tomcat instance to be restarted.</p>
512
513
514 <h3>Example Application</h3>
515
516 <p>The <code>/examples</code> application included with Tomcat contains
517 an example of utilizing this resource factory. It is accessed via the
518 "JSP Examples" link. The source code for the servlet that actually
519 sends the mail message is in
520 <code>/WEB-INF/classes/SendMailServlet.java</code>.</p>
521
522 <p><strong>WARNING</strong> - The default configuration assumes that there
523 is an SMTP server listing on port 25 on <code>localhost</code>. If this is
524 not the case, edit the
525 <a href="config/context.html"><code>&lt;Context&gt;</code></a> element for
526 this web application and modify the parameter value for the
527 <code>mail.smtp.host</code> parameter to be the host name of an SMTP server
528 on your network.</p>
529
530 </blockquote></td></tr></table>
531
532 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="JDBC Data Sources"><!--()--></a><a name="JDBC_Data_Sources"><strong>JDBC Data Sources</strong></a></font></td></tr><tr><td><blockquote>
533
534 <h3>0. Introduction</h3>
535
536 <p>Many web applications need to access a database via a JDBC driver,
537 to support the functionality required by that application. The Java EE
538 Platform Specification requires Java EE Application Servers to make
539 available a <em>DataSource</em> implementation (that is, a connection
540 pool for JDBC connections) for this purpose. Tomcat offers exactly
541 the same support, so that database-based applications you develop on
542 Tomcat using this service will run unchanged on any Java EE server.</p>
543
544 <p>For information about JDBC, you should consult the following:</p>
545 <ul>
546 <li><a href="http://java.sun.com/products/jdbc/">http://java.sun.com/products/jdbc/</a> -
547 Home page for information about Java Database Connectivity.</li>
548 <li><a href="http://java.sun.com/j2se/1.3/docs/guide/jdbc/spec2/jdbc2.1.frame.html">http://java.sun.com/j2se/1.3/docs/guide/jdbc/spec2/jdbc2.1.frame.html</a> -
549 The JDBC 2.1 API Specification.</li>
550 <li><a href="http://java.sun.com/products/jdbc/jdbc20.stdext.pdf">http://java.sun.com/products/jdbc/jdbc20.stdext.pdf</a> -
551 The JDBC 2.0 Standard Extension API (including the
552 <code>javax.sql.DataSource</code> API). This package is now known
553 as the "JDBC Optional Package".</li>
554 <li><a href="http://java.sun.com/j2ee/download.html">http://java.sun.com/j2ee/download.html</a> -
555 The Java EE Platform Specification (covers the JDBC facilities that
556 all Java EE platforms must provide to applications).</li>
557 </ul>
558
559 <p><strong>NOTE</strong> - The default data source support in Tomcat
560 is based on the <strong>DBCP</strong> connection pool from the
561 <a href="http://commons.apache.org/">Commons</a>
562 project. However, it is possible to use any other connection pool
563 that implements <code>javax.sql.DataSource</code>, by writing your
564 own custom resource factory, as described
565 <a href="#Adding Custom Resource Factories">below</a>.</p>
566
567 <h3>1. Install Your JDBC Driver</h3>
568
569 <p>Use of the <em>JDBC Data Sources</em> JNDI Resource Factory requires
570 that you make an appropriate JDBC driver available to both Tomcat internal
571 classes and to your web application. This is most easily accomplished by
572 installing the driver's JAR file(s) into the
573 <code>$CATALINA_HOME/lib</code> directory, which makes the driver
574 available both to the resource factory and to your application.</p>
575
576 <h3>2. Declare Your Resource Requirements</h3>
577
578 <p>Next, modify the web application deployment descriptor
579 (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under
580 which you will look up preconfigured data source. By convention, all such
581 names should resolve to the <code>jdbc</code> subcontext (relative to the
582 standard <code>java:comp/env</code> naming context that is the root of
583 all provided resource factories. A typical <code>web.xml</code> entry
584 might look like this:</p>
585<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
586&lt;resource-ref&gt;
587 &lt;description&gt;
588 Resource reference to a factory for java.sql.Connection
589 instances that may be used for talking to a particular
590 database that is configured in the &lt;Context&gt;
591 configurartion for the web application.
592 &lt;/description&gt;
593 &lt;res-ref-name&gt;
594 jdbc/EmployeeDB
595 &lt;/res-ref-name&gt;
596 &lt;res-type&gt;
597 javax.sql.DataSource
598 &lt;/res-type&gt;
599 &lt;res-auth&gt;
600 Container
601 &lt;/res-auth&gt;
602&lt;/resource-ref&gt;
603</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
604
605 <p><strong>WARNING</strong> - Be sure you respect the element ordering
606 that is required by the DTD for web application deployment descriptors!
607 See the
608 <a href="http://wiki.apache.org/tomcat/Specifications">Servlet
609 Specification</a> for details.</p>
610
611 <h3>3. Code Your Application's Use Of This Resource</h3>
612
613 <p>A typical use of this resource reference might look like this:</p>
614<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
615Context initCtx = new InitialContext();
616Context envCtx = (Context) initCtx.lookup("java:comp/env");
617DataSource ds = (DataSource)
618 envCtx.lookup("jdbc/EmployeeDB");
619
620Connection conn = ds.getConnection();
621... use this connection to access the database ...
622conn.close();
623</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
624
625 <p>Note that the application uses the same resource reference name that was
626 declared in the web application deployment descriptor. This is matched up
627 against the resource factory that is configured in the
628 <a href="config/context.html"><code>&lt;Context&gt;</code></a> element for
629 the web application as described below.</p>
630
631 <h3>4. Configure Tomcat's Resource Factory</h3>
632
633 <p>To configure Tomcat's resource factory, add an element like this to the
634 <a href="config/context.html"><code>&lt;Context&gt;</code></a> element for
635 the web application.</p>
636
637<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
638&lt;Context ...&gt;
639 ...
640 &lt;Resource name="jdbc/EmployeeDB"
641 auth="Container"
642 type="javax.sql.DataSource"
643 username="dbusername"
644 password="dbpassword"
645 driverClassName="org.hsql.jdbcDriver"
646 url="jdbc:HypersonicSQL:database"
647 maxActive="8"
648 maxIdle="4"/&gt;
649 ...
650&lt;/Context&gt;
651</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
652
653 <p>Note that the resource name (here, <code>jdbc/EmployeeDB</code>) must
654 match the value specified in the web application deployment descriptor.</p>
655
656 <p>This example assumes that you are using the HypersonicSQL database
657 JDBC driver. Customize the <code>driverClassName</code> and
658 <code>driverName</code> parameters to match your actual database's
659 JDBC driver and connection URL.</p>
660
661 <p>The configuration properties for Tomcat's standard data source
662 resource factory
663 (<code>org.apache.tomcat.dbcp.dbcp.BasicDataSourceFactory</code>) are
664 as follows:</p>
665 <ul>
666 <li><strong>driverClassName</strong> - Fully qualified Java class name
667 of the JDBC driver to be used.</li>
668 <li><strong>username</strong> - Database username to be passed to our
669 JDBC driver.</li>
670 <li><strong>password</strong> - Database password to be passed to our
671 JDBC driver.</li>
672 <li><strong>url</strong> - Connection URL to be passed to our JDBC driver.
673 (For backwards compatibility, the property <code>driverName</code>
674 is also recognized.)</li>
675 <li><strong>initialSize</strong> - The initial number of connections
676 that will be created in the pool during pool initialization. Default: 0</li>
677 <li><strong>maxActive</strong> - The maximum number of connections
678 that can be allocated from this pool at the same time. Default: 8</li>
679 <li><strong>minIdle</strong> - The minimum number of connections that
680 will sit idle in this pool at the same time. Default: 0</li>
681 <li><strong>maxIdle</strong> - The maximum number of connections that
682 can sit idle in this pool at the same time. Default: 8</li>
683 <li><strong>maxWait</strong> - The maximum number of milliseconds that the
684 pool will wait (when there are no available connections) for a
685 connection to be returned before throwing an exception. Default: -1 (infinite)</li>
686 </ul>
687 <p>Some additional properties handle connection validation:</p>
688 <ul>
689 <li><strong>validationQuery</strong> - SQL query that can be used by the
690 pool to validate connections before they are returned to the
691 application. If specified, this query MUST be an SQL SELECT
692 statement that returns at least one row.</li>
693 <li><strong>validationQueryTimeout</strong> - Timeout in seconds
694 for the validation query to return. Default: -1 (infinite)</li>
695 <li><strong>testOnBorrow</strong> - true or false: whether a connection
696 should be validated using the validation query each time it is
697 borrowed from the pool. Default: true</li>
698 <li><strong>testOnReturn</strong> - true or false: whether a connection
699 should be validated using the validation query each time it is
700 returned to the pool. Default: false</li>
701 </ul>
702 <p>The optional evictor thread is responsible for shrinking the pool
703 by removing any conections which are idle for a long time. The evictor
704 does not respect <code>minIdle</code>. Note that you do not need to
705 activate the evictor thread if you only want the pool to shrink according
706 to the configured <code>maxIdle</code> property.</p>
707 <p>The evictor is disabled by default and can be configured using
708 the following properties:</p>
709 <ul>
710 <li><strong>timeBetweenEvictionRunsMillis</strong> - The number of
711 milliseconds between consecutive runs of the evictor.
712 Default: -1 (disabled)</li>
713 <li><strong>numTestsPerEvictionRun</strong> - The number of connections
714 that will be checked for idleness by the evitor during each
715 run of the evictor. Default: 3</li>
716 <li><strong>minEvictableIdleTimeMillis</strong> - The idle time in
717 milliseconds after which a connection can be removed from the pool
718 by the evictor. Default: 30*60*1000 (30 minutes)</li>
719 <li><strong>testWhileIdle</strong> - true or false: whether a connection
720 should be validated by the evictor thread using the validation query
721 while sitting idle in the pool. Default: false</li>
722 </ul>
723 <p>Another optional feature is the removal of abandoned connections.
724 A connection is called abandoned if the application does not return it
725 to the pool for a long time. The pool can close such connections
726 automatically and remove them from the pool. This is a workaround
727 for applications leaking connections.</p>
728 <p>The abandoning feature is disabled by default and can be configured
729 using the following properties:</p>
730 <ul>
731 <li><strong>removeAbandoned</strong> - true or false: whether to
732 remove abandoned connections from the pool. Default: false</li>
733 <li><strong>removeAbandonedTimeout</strong> - The number of
734 seconds after which a borrowed connection is assumed to be abandoned.
735 Default: 300</li>
736 <li><strong>logAbandoned</strong> - true or false: whether to log
737 stack traces for application code which abandoned a statement
738 or connection. This adds serious overhead. Default: false</li>
739 </ul>
740 <p>Finally there are various properties that allow further fine tuning
741 of the pool behaviour:</p>
742 <ul>
743 <li><strong>defaultAutoCommit</strong> - true or false: default
744 auto-commit state of the connections created by this pool.
745 Default: true</li>
746 <li><strong>defaultReadOnly</strong> - true or false: default
747 read-only state of the connections created by this pool.
748 Default: false</li>
749 <li><strong>defaultTransactionIsolation</strong> - This sets the
750 default transaction isolation level. Can be one of
751 <code>NONE</code>, <code>READ_COMMITTED</code>,
752 <code>READ_UNCOMMITTED</code>, <code>REPEATABLE_READ</code>,
753 <code>SERIALIZABLE</code>. Default: no default set</li>
754 <li><strong>poolPreparedStatements</strong> - true or false: whether to
755 pool PreparedStatements and CallableStatements. Default: false</li>
756 <li><strong>maxOpenPreparedStatements</strong> - The maximum number of open
757 statements that can be allocated from the statement pool at the same time.
758 Default: -1 (unlimited)</li>
759 <li><strong>defaultCatalog</strong> - The name of the default catalog.
760 Default: not set</li>
761 <li><strong>connectionInitSqls</strong> - A list of SQL statements
762 run once after a Connection is created. Separate multiple statements
763 by semicolons (<code>;</code>). Default: no statement</li>
764 <li><strong>connectionProperties</strong> - A list of driver specific
765 properties passed to the driver for creating connections. Each
766 property is given as <code>name=value</code>, multiple properties
767 are separated by semicolons (<code>;</code>). Default: no properties</li>
768 <li><strong>accessToUnderlyingConnectionAllowed</strong> - true or false: whether
769 accessing the underlying connections is allowed. Default: false</li>
770 </ul>
771 <p>For more details, please refer to the commons-dbcp documentation.</p>
772
773 </blockquote></td></tr></table>
774
775</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Adding Custom Resource Factories"><!--()--></a><a name="Adding_Custom_Resource_Factories"><strong>Adding Custom Resource Factories</strong></a></font></td></tr><tr><td><blockquote>
776
777 <p>If none of the standard resource factories meet your needs, you can write
778 your own factory and integrate it into Tomcat, and then configure the use
779 of this factory in the
780 <a href="config/context.html"><code>&lt;Context&gt;</code></a> element for
781 the web application. In the example below, we will create a factory that only
782 knows how to create <code>com.mycompany.MyBean</code> beans from the
783 <a href="#Generic JavaBean Resources">Generic JavaBean Resources</a> example
784 above.</p>
785
786 <h3>1. Write A Resource Factory Class</h3>
787
788 <p>You must write a class that implements the JNDI service provider
789 <code>javax.naming.spi.ObjectFactory</code> inteface. Every time your
790 web application calls <code>lookup()</code> on a context entry that is
791 bound to this factory, the <code>getObjectInstance()</code> method is
792 called, with the following arguments:</p>
793 <ul>
794 <li><strong>Object obj</strong> - The (possibly null) object containing
795 location or reference information that can be used in creating an object.
796 For Tomcat, this will always be an object of type
797 <code>javax.naming.Reference</code>, which contains the class name of
798 this factory class, as well as the configuration properties (from the
799 <a href="config/context.html"><code>&lt;Context&gt;</code></a> for the
800 web application) to use in creating objects to be returned.</li>
801 <li><strong>Name name</strong> - The name to which this factory is bound
802 relative to <code>nameCtx</code>, or <code>null</code> if no name
803 is specified.</li>
804 <li><strong>Context nameCtx</strong> - The context relative to which the
805 <code>name</code> parameter is specified, or <code>null</code> if
806 <code>name</code> is relative to the default initial context.</li>
807 <li><strong>Hashtable environment</strong> - The (possibly null)
808 environment that is used in creating this object. This is generally
809 ignored in Tomcat object factories.</li>
810 </ul>
811
812 <p>To create a resource factory that knows how to produce <code>MyBean</code>
813 instances, you might create a class like this:</p>
814
815<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
816package com.mycompany;
817
818import java.util.Enumeration;
819import java.util.Hashtable;
820import javax.naming.Context;
821import javax.naming.Name;
822import javax.naming.NamingException;
823import javax.naming.RefAddr;
824import javax.naming.Reference;
825import javax.naming.spi.ObjectFactory;
826
827public class MyBeanFactory implements ObjectFactory {
828
829 public Object getObjectInstance(Object obj,
830 Name name, Context nameCtx, Hashtable environment)
831 throws NamingException {
832
833 // Acquire an instance of our specified bean class
834 MyBean bean = new MyBean();
835
836 // Customize the bean properties from our attributes
837 Reference ref = (Reference) obj;
838 Enumeration addrs = ref.getAll();
839 while (addrs.hasMoreElements()) {
840 RefAddr addr = (RefAddr) addrs.nextElement();
841 String name = addr.getType();
842 String value = (String) addr.getContent();
843 if (name.equals("foo")) {
844 bean.setFoo(value);
845 } else if (name.equals("bar")) {
846 try {
847 bean.setBar(Integer.parseInt(value));
848 } catch (NumberFormatException e) {
849 throw new NamingException("Invalid 'bar' value " + value);
850 }
851 }
852 }
853
854 // Return the customized instance
855 return (bean);
856
857 }
858
859}
860</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
861
862 <p>In this example, we are unconditionally creating a new instance of
863 the <code>com.mycompany.MyBean</code> class, and populating its properties
864 based on the parameters included in the <code>&lt;ResourceParams&gt;</code>
865 element that configures this factory (see below). You should note that any
866 parameter named <code>factory</code> should be skipped - that parameter is
867 used to specify the name of the factory class itself (in this case,
868 <code>com.mycompany.MyBeanFactory</code>) rather than a property of the
869 bean being configured.</p>
870
871 <p>For more information about <code>ObjectFactory</code>, see the
872 <a href="http://java.sun.com/products/jndi/docs.html">JNDI 1.2 Service
873 Provider Interface (SPI) Specification</a>.</p>
874
875 <p>You will need to compile this class against a class path that includes
876 all of the JAR files in the <code>$CATALINA_HOME/lib</code> directory. When you are through,
877 place the factory class (and the corresponding bean class) unpacked under
878 <code>$CATALINA_HOME/lib</code>, or in a JAR file inside
879 <code>$CATALINA_HOME/lib</code>. In this way, the required class
880 files are visible to both Catalina internal resources and your web
881 application.</p>
882
883 <h3>2. Declare Your Resource Requirements</h3>
884
885 <p>Next, modify your web application deployment descriptor
886 (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under which
887 you will request new instances of this bean. The simplest approach is
888 to use a <code>&lt;resource-env-ref&gt;</code> element, like this:</p>
889
890<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
891&lt;resource-env-ref&gt;
892 &lt;description&gt;
893 Object factory for MyBean instances.
894 &lt;/description&gt;
895 &lt;resource-env-ref-name&gt;
896 bean/MyBeanFactory
897 &lt;/resource-env-ref-name&gt;
898 &lt;resource-env-ref-type&gt;
899 com.mycompany.MyBean
900 &lt;/resource-env-ref-type&gt;
901&lt;resource-env-ref&gt;
902</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
903
904 <p><strong>WARNING</strong> - Be sure you respect the element ordering
905 that is required by the DTD for web application deployment descriptors!
906 See the
907 <a href="http://wiki.apache.org/tomcat/Specifications">Servlet
908 Specification</a> for details.</p>
909
910 <h3>3. Code Your Application's Use Of This Resource</h3>
911
912 <p>A typical use of this resource environment reference might look
913 like this:</p>
914
915<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
916Context initCtx = new InitialContext();
917Context envCtx = (Context) initCtx.lookup("java:comp/env");
918MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory");
919
920writer.println("foo = " + bean.getFoo() + ", bar = " +
921 bean.getBar());
922</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
923
924 <h3>4. Configure Tomcat's Resource Factory</h3>
925
926 <p>To configure Tomcat's resource factory, add an elements like this to the
927 <a href="config/context.html"><code>&lt;Context&gt;</code></a> element for
928 this web application.</p>
929
930<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
931&lt;Context ...&gt;
932 ...
933 &lt;Resource name="bean/MyBeanFactory" auth="Container"
934 type="com.mycompany.MyBean"
935 factory="com.mycompany.MyBeanFactory"
936 bar="23"/&gt;
937 ...
938&lt;/Context&gt;
939</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
940
941 <p>Note that the resource name (here, <code>bean/MyBeanFactory</code>
942 must match the value specified in the web application deployment
943 descriptor. We are also initializing the value of the <code>bar</code>
944 property, which will cause <code>setBar(23)</code> to be called before
945 the new bean is returned. Because we are not initializing the
946 <code>foo</code> property (although we could have), the bean will
947 contain whatever default value is set up by its constructor.</p>
948
949 <p>You will also note that, from the application developer's perspective,
950 the declaration of the resource environment reference, and the programming
951 used to request new instances, is identical to the approach used for the
952 <em>Generic JavaBean Resources</em> example. This illustrates one of the
953 advantages of using JNDI resources to encapsulate functionality - you can
954 change the underlying implementation without necessarily having to
955 modify applications using the resources, as long as you maintain
956 compatible APIs.</p>
957
958</blockquote></td></tr></table></td></tr><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions
959 on improving documentation for Apache Tomcat.<br><br>
960 If you have trouble and need help, read
961 <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
962 and ask your question on the tomcat-users
963 <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
964 Do not ask such questions here. This is not a Q&amp;A section.<br><br>
965 The Apache Comments System is explained <a href="/tomcat-7.0-doc/comments.html">here</a>.
966 Comments may be removed by our moderators if they are either
967 implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
968 var comments_shortname = 'tomcat';
969 var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/jndi-resources-howto.html';
970 (function(w, d) {
971 if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
972 d.write('<div id="comments_thread"><\/div>');
973 var s = d.createElement('script');
974 s.type = 'text/javascript';
975 s.async = true;
976 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
977 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
978 }
979 else {
980 d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
981 }
982 })(window, document);
983 //--><!]]></script></blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
984 Copyright &copy; 1999-2013, Apache Software Foundation
985 </em></font></div></td></tr></table></body></html>