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