source: nutchez-0.1/tomcat/webapps/docs/jndi-resources-howto.html @ 134

Last change on this file since 134 was 66, checked in by waue, 16 years ago

NutchEz - an easy way to nutch
File size: 53.2 KB
RevLine 
[66]1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 - JNDI Resources HOW-TO</title><meta value="Craig R. McClanahan" name="author"><meta value="craigmcc@apache.org" name="email"><meta value="Yoav Shapira" name="author"><meta value="yoavs@apache.org" name="email"></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img border="0" alt="
2      The Apache Tomcat Servlet/JSP Container
3    " align="right" src="./images/tomcat.gif"></a></td><td><font face="arial,helvetica,sanserif"><h1>Apache Tomcat 6.0</h1></font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img border="0" alt="Apache Logo" align="right" src="./images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--LEFT SIDE NAVIGATION--><td nowrap="true" valign="top" width="20%"><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 align="left" valign="top" width="80%"><table cellspacing="4" width="100%" border="0"><tr><td valign="top" align="left"><h1>Apache Tomcat 6.0</h1><h2>JNDI Resources HOW-TO</h2></td><td nowrap="true" valign="top" align="right"><small><a href="printer/jndi-resources-howto.html"><img alt="Printer Friendly Version" border="0" src="./images/printer.gif"><br>print-friendly<br>version
4                    </a></small></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
5
6<p>Tomcat 6 provides a JNDI <strong>InitialContext</strong> implementation
7instance for each web application running under it, in a manner that is
8compatible with those provided by a
9<a href="http://java.sun.com/j2ee">Java2 Enterprise Edition</a> application
10server.
11
12The J2EE standard provides a standard set of elements in
13the <code>/WEB-INF/web.xml</code> file to reference resources; resources
14referenced in these elements must be defined in an application-server-specific
15configuration.
16</p>
17
18<p>For Tomcat 6, these entries in per-web-application
19<code>InitialContext</code> are configured in the
20<a href="config/context.html"><code>&lt;Context&gt;</code></a> elements that
21can be specified in either <code>$CATALINA_BASE/conf/server.xml</code> or,
22preferably, the per-web-application context XML file (
23<code>META-INF/context.xml</code>).
24</p>
25
26<p>Tomcat 6 maintains a separate namespace of global resources for the
27entire server.  These are configured in the
28<a href="config/globalresources.html">
29<code><strong>&lt;GlobalNameingResources&gt;</strong></code></a> element of
30<code>$CATALINA_BASE/conf/server.xml</code>. You may expose these resources to
31web applications by using
32<code><strong>&lt;ResourceLink&gt;</strong></code> elements.
33</p>
34
35<p>The resources defined in these elements
36may be referenced by the following elements in the web application deployment
37descriptor (<code>/WEB-INF/web.xml</code>) of your web application:</p>
38<ul>
39<li><code><strong>&lt;env-entry&gt;</strong></code> - Environment entry, a
40    single-value parameter that can be used to configure how the application
41    will operate.</li>
42<li><code><strong>&lt;resource-ref&gt;</strong></code> - Resource reference,
43    which is typically to an object factory for resources such as a JDBC
44    <code>DataSource</code>, a JavaMail <code>Session</code>, or custom
45    object factories configured into Tomcat 6.</li>
46<li><code><strong>&lt;resource-env-ref&gt;</strong></code> - Resource
47    environment reference, a new variation of <code>resource-ref</code>
48    added in Servlet 2.4 that is simpler to configure for resources
49    that do not require authentication information.</li>
50</ul>
51
52<p>The <code>InitialContext</code> is configured as a web application is
53initially deployed, and is made available to web application components (for
54read-only access).  All configured entries and resources are placed in
55the <code>java:comp/env</code> portion of the JNDI namespace, so a typical
56access to a resource - in this case, to a JDBC <code>DataSource</code> -
57would look something like this:</p>
58
59<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
60// Obtain our environment naming context
61Context initCtx = new InitialContext();
62Context envCtx = (Context) initCtx.lookup("java:comp/env");
63
64// Look up our data source
65DataSource ds = (DataSource)
66  envCtx.lookup("jdbc/EmployeeDB");
67
68// Allocate and use a connection from the pool
69Connection conn = ds.getConnection();
70... use this connection to access the database ...
71conn.close();
72</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
73
74<p>See the following Specifications for more information about programming APIs
75for JNDI, and for the features supported by Java2 Enterprise Edition (J2EE)
76servers, which Tomcat emulates for the services that it provides:</p>
77<ul>
78<li><a href="http://java.sun.com/products/jndi">Java Naming and Directory
79    Interface</a> (included in JDK 1.4 onwards)</li>
80<li><a href="http://java.sun.com/j2ee/download.html">J2EE Platform
81    Specification</a> (in particular, see Chapter 5 on <em>Naming</em>)</li>
82</ul>
83
84</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Configuring JNDI Resources"><strong>Configuring JNDI Resources</strong></a></font></td></tr><tr><td><blockquote>
85
86<p>Each available JNDI Resource is configured based on inclusion of the
87following elements in the
88<a href="config/context.html"><code>&lt;Context&gt;</code></a> element:</p>
89
90<ul>
91<li><a href="config/context.html#Environment Entries">&lt;Environment&gt;</a> -
92    Configure names and values for scalar environment entries that will be
93    exposed to the web application through the JNDI
94    <code>InitialContext</code> (equivalent to the inclusion of an
95    <code>&lt;env-entry&gt;</code> element in the web application
96    deployment descriptor).</li>
97<li><a href="config/context.html#Resource Definitions">&lt;Resource&gt;</a> -
98    Configure the name and data type of a resource made available to the
99    application (equivalent to the inclusion of a
100    <code>&lt;resource-ref&gt;</code> element in the web application
101    deployment descriptor).</li>
102<li><a href="config/context.html#Resource Links">&lt;ResourceLink&gt;</a> -
103    Add a link to a resource defined in the global JNDI context. Use resource
104    links to give a web application access to a resource defined in
105    the<a href="config/globalresources.html">&lt;GlobalNamingResources&gt;</a>
106    child element of the <a href="config/server.html">&lt;Server&gt;</a>
107    element.</li>
108<li><a href="config/context.html#Transaction">&lt;Transaction&gt;</a> -
109    Add a resource factory for instantiating the UserTransaction object
110    instance that is available at <code>java:comp/UserTransaction</code>.</li>
111
112</ul>
113
114<p>Any number of these elements may be nested inside a
115<a href="config/context.html"><code>&lt;Context&gt;</code></a> element (to be
116associated only with that particular web application).</p>
117
118<p>In addition, the names and values of all <code>&lt;env-entry&gt;</code>
119elements included in the web application deployment descriptor
120(<code>/WEB-INF/web.xml</code>) are configured into the initial context as
121well, overriding corresponding values from the
122<a href="config/context.html"><code>&lt;Context&gt;</code></a> element
123<strong>only</strong> if allowed by the corresponding
124<code>&lt;Environment&gt;</code> element (by setting the <code>override</code>
125attribute to "true").</p>
126
127<p>Global resources can be defined in the server-wide JNDI context, by adding
128the resource elements described above to the
129<a href="config/globalresources.html">&lt;GlobalNamingResources&gt;</a>
130child element of the <a href="config/server.html">&lt;Server&gt;</a>
131element and using a
132<a href="config/context.html#Resource Links">&lt;ResourceLink&gt;</a> to
133include it in the per-web-application context.</p>
134
135</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Tomcat Standard Resource Factories"><strong>Tomcat Standard Resource Factories</strong></a></font></td></tr><tr><td><blockquote>
136
137  <p>Tomcat 6 includes a series of standard resource factories that can
138  provide services to your web applications, but give you configuration
139  flexibility (via the
140  <a href="config/context.html"><code>&lt;Context&gt;</code></a> element)
141  without modifying the web application or the deployment descriptor. Each
142  subsection below details the configuration and usage of the standard resource
143  factories.</p>
144
145  <p>See <a href="#Adding Custom Resource Factories">Adding Custom
146  Resource Factories</a> for information about how to create, install,
147  configure, and use your own custom resource factory classes with
148  Tomcat 6.</p>
149
150  <p><em>NOTE</em> - Of the standard resource factories, only the
151  "JDBC Data Source" and "User Transaction" factories are mandated to
152  be available on other platforms, and then they are required only if
153  the platform implements the Java2 Enterprise Edition (J2EE) specs.
154  All other standard resource factories, plus custom resource factories
155  that you write yourself, are specific to Tomcat and cannot be assumed
156  to be available on other containers.</p>
157
158  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Generic JavaBean Resources"><strong>Generic JavaBean Resources</strong></a></font></td></tr><tr><td><blockquote>
159
160    <h3>0.  Introduction</h3>
161
162    <p>This resource factory can be used to create objects of <em>any</em>
163    Java class that conforms to standard JavaBeans naming conventions (i.e.
164    it has a zero-arguments constructor, and has property setters that
165    conform to the setFoo() naming pattern.  The resource factory will
166    create a new instance of the appropriate bean class every time a
167    <code>lookup()</code> for this entry is made.</p>
168
169    <p>The steps required to use this facility are described below.</p>
170
171    <h3>1.  Create Your JavaBean Class</h3>
172
173    <p>Create the JavaBean class which will be instantiated each time
174    that the resource factory is looked up.  For this example, assume
175    you create a class <code>com.mycompany.MyBean</code>, which looks
176    like this:</p>
177
178<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
179package com.mycompany;
180
181public class MyBean {
182
183  private String foo = "Default Foo";
184
185  public String getFoo() {
186    return (this.foo);
187  }
188
189  public void setFoo(String foo) {
190    this.foo = foo;
191  }
192
193  private int bar = 0;
194
195  public int getBar() {
196    return (this.bar);
197  }
198
199  public void setBar(int bar) {
200    this.bar = bar;
201  }
202
203
204}
205</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
206
207  <h3>2.  Declare Your Resource Requirements</h3>
208
209  <p>Next, modify your web application deployment descriptor
210  (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under which
211  you will request new instances of this bean.  The simplest approach is
212  to use a <code>&lt;resource-env-ref&gt;</code> element, like this:</p>
213
214<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
215&lt;resource-env-ref&gt;
216  &lt;description&gt;
217    Object factory for MyBean instances.
218  &lt;/description&gt;
219  &lt;resource-env-ref-name&gt;
220    bean/MyBeanFactory
221  &lt;/resource-env-ref-name&gt;
222  &lt;resource-env-ref-type&gt;
223    com.mycompany.MyBean
224  &lt;/resource-env-ref-type&gt;
225&lt;/resource-env-ref&gt;
226</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
227
228    <p><strong>WARNING</strong> - Be sure you respect the element ordering
229    that is required by the DTD for web application deployment descriptors!
230    See the
231    <a href="http://java.sun.com/products/servlet/download.html">Servlet
232    Specification</a> for details.</p>
233
234  <h3>3.  Code Your Application's Use Of This Resource</h3>
235
236  <p>A typical use of this resource environment reference might look
237  like this:</p>
238
239<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
240Context initCtx = new InitialContext();
241Context envCtx = (Context) initCtx.lookup("java:comp/env");
242MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory");
243
244writer.println("foo = " + bean.getFoo() + ", bar = " +
245               bean.getBar());
246</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
247
248    <h3>4.  Configure Tomcat's Resource Factory</h3>
249
250    <p>To configure Tomcat's resource factory, add an element like this to the
251    <a href="config/context.html"><code>&lt;Context&gt;</code></a> element for
252    this web application.</p>
253
254<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
255&lt;Context ...&gt;
256  ...
257  &lt;Resource name="bean/MyBeanFactory" auth="Container"
258            type="com.mycompany.MyBean"
259            factory="org.apache.naming.factory.BeanFactory"
260            bar="23"/&gt;
261  ...
262&lt;/Context&gt;
263</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
264
265    <p>Note that the resource name (here, <code>bean/MyBeanFactory</code>
266    must match the value specified in the web application deployment
267    descriptor.  We are also initializing the value of the <code>bar</code>
268    property, which will cause <code>setBar(23)</code> to be called before
269    the new bean is returned.  Because we are not initializing the
270    <code>foo</code> property (although we could have), the bean will
271    contain whatever default value is set up by its constructor.</p>
272
273  </blockquote></td></tr></table>
274
275
276  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="JavaMail Sessions"><strong>JavaMail Sessions</strong></a></font></td></tr><tr><td><blockquote>
277
278    <h3>0.  Introduction</h3>
279
280    <p>In many web applications, sending electronic mail messages is a
281    required part of the system's functionality.  The
282    <a href="http://java.sun.com/products/javamail">Java Mail</a> API
283    makes this process relatively straightforward, but requires many
284    configuration details that the client application must be aware of
285    (including the name of the SMTP host to be used for message sending).</p>
286
287    <p>Tomcat 6 includes a standard resource factory that will create
288    <code>javax.mail.Session</code> session instances for you, already
289    configured to connect to an SMTP server.
290    In this way, the application is totally insulated from changes in the
291    email server configuration environment - it simply asks for, and receives,
292    a preconfigured session whenever needed.</p>
293
294    <p>The steps required for this are outlined below.</p>
295
296    <h3>1.  Declare Your Resource Requirements</h3>
297
298    <p>The first thing you should do is modify the web application deployment
299    descriptor (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under
300    which you will look up preconfigured sessions.  By convention, all such
301    names should resolve to the <code>mail</code> subcontext (relative to the
302    standard <code>java:comp/env</code> naming context that is the root of
303    all provided resource factories.  A typical <code>web.xml</code> entry
304    might look like this:</p>
305<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
306&lt;resource-ref&gt;
307  &lt;description&gt;
308    Resource reference to a factory for javax.mail.Session
309    instances that may be used for sending electronic mail
310    messages, preconfigured to connect to the appropriate
311    SMTP server.
312  &lt;/description&gt;
313  &lt;res-ref-name&gt;
314    mail/Session
315  &lt;/res-ref-name&gt;
316  &lt;res-type&gt;
317    javax.mail.Session
318  &lt;/res-type&gt;
319  &lt;res-auth&gt;
320    Container
321  &lt;/res-auth&gt;
322&lt;/resource-ref&gt;
323</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
324
325    <p><strong>WARNING</strong> - Be sure you respect the element ordering
326    that is required by the DTD for web application deployment descriptors!
327    See the
328    <a href="http://java.sun.com/products/servlet/download.html">Servlet
329    Specification</a> for details.</p>
330
331    <h3>2.  Code Your Application's Use Of This Resource</h3>
332
333    <p>A typical use of this resource reference might look like this:</p>
334<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
335Context initCtx = new InitialContext();
336Context envCtx = (Context) initCtx.lookup("java:comp/env");
337Session session = (Session) envCtx.lookup("mail/Session");
338
339Message message = new MimeMessage(session);
340message.setFrom(new InternetAddress(request.getParameter("from"));
341InternetAddress to[] = new InternetAddress[1];
342to[0] = new InternetAddress(request.getParameter("to"));
343message.setRecipients(Message.RecipientType.TO, to);
344message.setSubject(request.getParameter("subject"));
345message.setContent(request.getParameter("content"), "text/plain");
346Transport.send(message);
347</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
348
349    <p>Note that the application uses the same resource reference name
350    that was declared in the web application deployment descriptor.  This
351    is matched up against the resource factory that is configured in the
352    <a href="config/context.html"><code>&lt;Context&gt;</code></a> element
353    for the web application as described below.</p>
354
355    <h3>3.  Configure Tomcat's Resource Factory</h3>
356
357    <p>To configure Tomcat's resource factory, add an elements like this to the
358    <a href="config/context.html"><code>&lt;Context&gt;</code></a> element for
359    this web application.</p>
360
361<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
362&lt;Context ...&gt;
363  ...
364  &lt;Resource name="mail/Session" auth="Container"
365            type="javax.mail.Session"
366            mail.smtp.host="localhost"/&gt;
367  ...
368&lt;/Context&gt;
369</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
370
371    <p>Note that the resource name (here, <code>mail/Session</code>) must
372    match the value specified in the web application deployment descriptor.
373    Customize the value of the <code>mail.smtp.host</code> parameter to
374    point at the server that provides SMTP service for your network.</p>
375
376    <h3>4.  Install the JavaMail libraries</h3>
377
378    <p><a href="http://java.sun.com/products/javamail/downloads/index.html">
379    Download the JavaMail API</a>.  The JavaMail API requires the Java Activation
380    Framework (JAF) API as well.  The Java Activation Framework can be downloaded
381    from <a href="http://java.sun.com/products/javabeans/glasgow/jaf.html">Sun's site</a>.
382    </p>
383
384    <p>This download includes 2 vital libraries for the configuration;
385    activation.jar and mail.jar. Unpackage both distributions and place
386    them into $CATALINA_HOME/lib so that they are available to
387    Tomcat during the initialization of the mail Session Resource.
388    <strong>Note:</strong> placing these jars in both $CATALINA_HOME/lib and a
389    web application's lib folder will cause an error, so ensure you have
390    them in the $CATALINA_HOME/lib location only.
391    </p>
392
393    <h3>Example Application</h3>
394
395    <p>The <code>/examples</code> application included with Tomcat contains
396    an example of utilizing this resource factory.  It is accessed via the
397    "JSP Examples" link.  The source code for the servlet that actually
398    sends the mail message is in
399    <code>/WEB-INF/classes/SendMailServlet.java</code>.</p>
400
401    <p><strong>WARNING</strong> - The default configuration assumes that there
402    is an SMTP server listing on port 25 on <code>localhost</code>. If this is
403    not the case, edit the
404    <a href="config/context.html"><code>&lt;Context&gt;</code></a> element for
405    this web application and modify the parameter value for the
406    <code>mail.smtp.host</code> parameter to be the host name of an SMTP server
407    on your network.</p>
408
409  </blockquote></td></tr></table>
410
411  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="JDBC Data Sources"><strong>JDBC Data Sources</strong></a></font></td></tr><tr><td><blockquote>
412
413    <h3>0.  Introduction</h3>
414
415    <p>Many web applications need to access a database via a JDBC driver,
416    to support the functionality required by that application.  The J2EE
417    Platform Specification requires J2EE Application Servers to make
418    available a <em>DataSource</em> implementation (that is, a connection
419    pool for JDBC connections) for this purpose.  Tomcat 6 offers exactly
420    the same support, so that database-based applications you develop on
421    Tomcat using this service will run unchanged on any J2EE server.</p>
422
423    <p>For information about JDBC, you should consult the following:</p>
424    <ul>
425    <li><a href="http://java.sun.com/products/jdbc/">http://java.sun.com/products/jdbc/</a> -
426        Home page for information about Java Database Connectivity.</li>
427    <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> -
428        The JDBC 2.1 API Specification.</li>
429    <li><a href="http://java.sun.com/products/jdbc/jdbc20.stdext.pdf">http://java.sun.com/products/jdbc/jdbc20.stdext.pdf</a> -
430        The JDBC 2.0 Standard Extension API (including the
431        <code>javax.sql.DataSource</code> API).  This package is now known
432        as the "JDBC Optional Package".</li>
433    <li><a href="http://java.sun.com/j2ee/download.html">http://java.sun.com/j2ee/download.html</a> -
434        The J2EE Platform Specification (covers the JDBC facilities that
435        all J2EE platforms must provide to applications).</li>
436    </ul>
437
438    <p><strong>NOTE</strong> - The default data source support in Tomcat
439    is based on the <strong>DBCP</strong> connection pool from the
440    <a href="http://commons.apache.org/">Commons</a>
441    project.  However, it is possible to use any other connection pool
442    that implements <code>javax.sql.DataSource</code>, by writing your
443    own custom resource factory, as described
444    <a href="#Adding Custom Resource Factories">below</a>.</p>
445
446    <h3>1.  Install Your JDBC Driver</h3>
447
448    <p>Use of the <em>JDBC Data Sources</em> JNDI Resource Factory requires
449    that you make an appropriate JDBC driver available to both Tomcat internal
450    classes and to your web application.  This is most easily accomplished by
451    installing the driver's JAR file(s) into the
452    <code>$CATALINA_HOME/lib</code> directory, which makes the driver
453    available both to the resource factory and to your application.</p>
454
455    <h3>2.  Declare Your Resource Requirements</h3>
456
457    <p>Next, modify the web application deployment descriptor
458    (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under
459    which you will look up preconfigured data source.  By convention, all such
460    names should resolve to the <code>jdbc</code> subcontext (relative to the
461    standard <code>java:comp/env</code> naming context that is the root of
462    all provided resource factories.  A typical <code>web.xml</code> entry
463    might look like this:</p>
464<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
465&lt;resource-ref&gt;
466  &lt;description&gt;
467    Resource reference to a factory for java.sql.Connection
468    instances that may be used for talking to a particular
469    database that is configured in the &lt;Context&gt;
470    configurartion for the web application.
471  &lt;/description&gt;
472  &lt;res-ref-name&gt;
473    jdbc/EmployeeDB
474  &lt;/res-ref-name&gt;
475  &lt;res-type&gt;
476    javax.sql.DataSource
477  &lt;/res-type&gt;
478  &lt;res-auth&gt;
479    Container
480  &lt;/res-auth&gt;
481&lt;/resource-ref&gt;
482</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
483
484    <p><strong>WARNING</strong> - Be sure you respect the element ordering
485    that is required by the DTD for web application deployment descriptors!
486    See the
487    <a href="http://java.sun.com/products/servlet/download.html">Servlet
488    Specification</a> for details.</p>
489
490    <h3>3.  Code Your Application's Use Of This Resource</h3>
491
492    <p>A typical use of this resource reference might look like this:</p>
493<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
494Context initCtx = new InitialContext();
495Context envCtx = (Context) initCtx.lookup("java:comp/env");
496DataSource ds = (DataSource)
497  envCtx.lookup("jdbc/EmployeeDB");
498
499Connection conn = ds.getConnection();
500... use this connection to access the database ...
501conn.close();
502</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
503
504    <p>Note that the application uses the same resource reference name that was
505    declared in the web application deployment descriptor. This is matched up
506    against the resource factory that is configured in the
507    <a href="config/context.html"><code>&lt;Context&gt;</code></a> element for
508    the web application as described below.</p>
509
510    <h3>4.  Configure Tomcat's Resource Factory</h3>
511
512    <p>To configure Tomcat's resource factory, add an element like this to the
513    <a href="config/context.html"><code>&lt;Context&gt;</code></a> element for
514    the web application.</p>
515
516<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
517&lt;Context ...&gt;
518  ...
519  &lt;Resource name="jdbc/EmployeeDB"
520            auth="Container"
521            type="javax.sql.DataSource"
522            username="dbusername"
523            password="dbpassword"
524            driverClassName="org.hsql.jdbcDriver"
525            url="jdbc:HypersonicSQL:database"
526            maxActive="8"
527            maxIdle="4"/&gt;
528  ...
529&lt;/Context&gt;
530</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
531
532    <p>Note that the resource name (here, <code>jdbc/EmployeeDB</code>) must
533    match the value specified in the web application deployment descriptor.</p>
534
535    <p>This example assumes that you are using the HypersonicSQL database
536    JDBC driver.  Customize the <code>driverClassName</code> and
537    <code>driverName</code> parameters to match your actual database's
538    JDBC driver and connection URL.</p>
539
540    <p>The configuration properties for Tomcat's standard data source
541    resource factory
542    (<code>org.apache.tomcat.dbcp.dbcp.BasicDataSourceFactory</code>) are
543    as follows:</p>
544    <ul>
545    <li><strong>driverClassName</strong> - Fully qualified Java class name
546        of the JDBC driver to be used.</li>
547    <li><strong>maxActive</strong> - The maximum number of active instances
548        that can be allocated from this pool at the same time.</li>
549    <li><strong>maxIdle</strong> - The maximum number of connections that
550        can sit idle in this pool at the same time.</li>
551    <li><strong>maxWait</strong> - The maximum number of milliseconds that the
552        pool will wait (when there are no available connections) for a
553        connection to be returned before throwing an exception.</li>
554    <li><strong>password</strong> - Database password to be passed to our
555        JDBC driver.</li>
556    <li><strong>url</strong> - Connection URL to be passed to our JDBC driver.
557        (For backwards compatibility, the property <code>driverName</code>
558        is also recognized.)</li>
559    <li><strong>user</strong> - Database username to be passed to our
560        JDBC driver.</li>
561    <li><strong>validationQuery</strong> - SQL query that can be used by the
562        pool to validate connections before they are returned to the
563        application.  If specified, this query MUST be an SQL SELECT
564        statement that returns at least one row.</li>
565    </ul>
566    <p>For more details, please refer to the commons-dbcp documentation.</p>
567
568  </blockquote></td></tr></table>
569
570</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Adding Custom Resource Factories"><strong>Adding Custom Resource Factories</strong></a></font></td></tr><tr><td><blockquote>
571
572  <p>If none of the standard resource factories meet your needs, you can write
573  your own factory and integrate it into Tomcat 6, and then configure the use
574  of this factory in the
575  <a href="config/context.html"><code>&lt;Context&gt;</code></a> element for
576  the web application. In the example below, we will create a factory that only
577  knows how to create <code>com.mycompany.MyBean</code> beans from the
578  <a href="#Generic JavaBean Resources">Generic JavaBean Resources</a> example
579  above.</p>
580
581  <h3>1.  Write A Resource Factory Class</h3>
582
583  <p>You must write a class that implements the JNDI service provider
584  <code>javax.naming.spi.ObjectFactory</code> inteface.  Every time your
585  web application calls <code>lookup()</code> on a context entry that is
586  bound to this factory, the <code>getObjectInstance()</code> method is
587  called, with the following arguments:</p>
588  <ul>
589  <li><strong>Object obj</strong> - The (possibly null) object containing
590      location or reference information that can be used in creating an object.
591      For Tomcat, this will always be an object of type
592      <code>javax.naming.Reference</code>, which contains the class name of
593      this factory class, as well as the configuration properties (from the
594      <a href="config/context.html"><code>&lt;Context&gt;</code></a> for the
595      web application) to use in creating objects to be returned.</li>
596  <li><strong>Name name</strong> - The name to which this factory is bound
597      relative to <code>nameCtx</code>, or <code>null</code> if no name
598      is specified.</li>
599  <li><strong>Context nameCtx</strong> - The context relative to which the
600      <code>name</code> parameter is specified, or <code>null</code> if
601      <code>name</code> is relative to the default initial context.</li>
602  <li><strong>Hashtable environment</strong> - The (possibly null)
603      environment that is used in creating this object.  This is generally
604      ignored in Tomcat object factories.</li>
605  </ul>
606
607  <p>To create a resource factory that knows how to produce <code>MyBean</code>
608  instances, you might create a class like this:</p>
609
610<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
611package com.mycompany;
612
613import java.util.Enumeration;
614import java.util.Hashtable;
615import javax.naming.Context;
616import javax.naming.Name;
617import javax.naming.NamingException;
618import javax.naming.RefAddr;
619import javax.naming.Reference;
620import javax.naming.spi.ObjectFactory;
621
622public class MyBeanFactory implements ObjectFactory {
623
624  public Object getObjectInstance(Object obj,
625      Name name, Context nameCtx, Hashtable environment)
626      throws NamingException {
627
628      // Acquire an instance of our specified bean class
629      MyBean bean = new MyBean();
630
631      // Customize the bean properties from our attributes
632      Reference ref = (Reference) obj;
633      Enumeration addrs = ref.getAll();
634      while (addrs.hasMoreElements()) {
635          RefAddr addr = (RefAddr) addrs.nextElement();
636          String name = addr.getType();
637          String value = (String) addr.getContent();
638          if (name.equals("foo")) {
639              bean.setFoo(value);
640          } else if (name.equals("bar")) {
641              try {
642                  bean.setBar(Integer.parseInt(value));
643              } catch (NumberFormatException e) {
644                  throw new NamingException("Invalid 'bar' value " + value);
645              }
646          }
647      }
648
649      // Return the customized instance
650      return (bean);
651
652  }
653
654}
655</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
656
657  <p>In this example, we are unconditionally creating a new instance of
658  the <code>com.mycompany.MyBean</code> class, and populating its properties
659  based on the parameters included in the <code>&lt;ResourceParams&gt;</code>
660  element that configures this factory (see below).  You should note that any
661  parameter named <code>factory</code> should be skipped - that parameter is
662  used to specify the name of the factory class itself (in this case,
663  <code>com.mycompany.MyBeanFactory</code>) rather than a property of the
664  bean being configured.</p>
665
666  <p>For more information about <code>ObjectFactory</code>, see the
667  <a href="http://java.sun.com/products/jndi/docs.html">JNDI 1.2 Service
668  Provider Interface (SPI) Specification</a>.</p>
669
670  <p>You will need to compile this class against a class path that includes
671  all of the JAR files in the <code>$CATALINA_HOME/lib</code> directory.  When you are through,
672  place the factory class (and the corresponding bean class) unpacked under
673  <code>$CATALINA_HOME/lib</code>, or in a JAR file inside
674  <code>$CATALINA_HOME/lib</code>.  In this way, the required class
675  files are visible to both Catalina internal resources and your web
676  application.</p>
677
678  <h3>2.  Declare Your Resource Requirements</h3>
679
680  <p>Next, modify your web application deployment descriptor
681  (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under which
682  you will request new instances of this bean.  The simplest approach is
683  to use a <code>&lt;resource-env-ref&gt;</code> element, like this:</p>
684
685<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
686&lt;resource-env-ref&gt;
687  &lt;description&gt;
688    Object factory for MyBean instances.
689  &lt;/description&gt;
690  &lt;resource-env-ref-name&gt;
691    bean/MyBeanFactory
692  &lt;/resource-env-ref-name&gt;
693  &lt;resource-env-ref-type&gt;
694    com.mycompany.MyBean
695  &lt;/resource-env-ref-type&gt;
696&lt;resource-env-ref&gt;
697</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
698
699    <p><strong>WARNING</strong> - Be sure you respect the element ordering
700    that is required by the DTD for web application deployment descriptors!
701    See the
702    <a href="http://java.sun.com/products/servlet/download.html">Servlet
703    Specification</a> for details.</p>
704
705  <h3>3.  Code Your Application's Use Of This Resource</h3>
706
707  <p>A typical use of this resource environment reference might look
708  like this:</p>
709
710<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
711Context initCtx = new InitialContext();
712Context envCtx = (Context) initCtx.lookup("java:comp/env");
713MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory");
714
715writer.println("foo = " + bean.getFoo() + ", bar = " +
716               bean.getBar());
717</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
718
719    <h3>4.  Configure Tomcat's Resource Factory</h3>
720
721    <p>To configure Tomcat's resource factory, add an elements like this to the
722    <a href="config/context.html"><code>&lt;Context&gt;</code></a> element for
723    this web application.</p>
724
725<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
726&lt;Context ...&gt;
727  ...
728  &lt;Resource name="bean/MyBeanFactory" auth="Container"
729            type="com.mycompany.MyBean"
730            factory="com.mycompany.MyBeanFactory"
731            bar="23"/&gt;
732  ...
733&lt;/Context&gt;
734</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
735
736    <p>Note that the resource name (here, <code>bean/MyBeanFactory</code>
737    must match the value specified in the web application deployment
738    descriptor.  We are also initializing the value of the <code>bar</code>
739    property, which will cause <code>setBar(23)</code> to be called before
740    the new bean is returned.  Because we are not initializing the
741    <code>foo</code> property (although we could have), the bean will
742    contain whatever default value is set up by its constructor.</p>
743
744    <p>You will also note that, from the application developer's perspective,
745    the declaration of the resource environment reference, and the programming
746    used to request new instances, is identical to the approach used for the
747    <em>Generic JavaBean Resources</em> example.  This illustrates one of the
748    advantages of using JNDI resources to encapsulate functionality - you can
749    change the underlying implementation without necessarily having to
750    modify applications using the resources, as long as you maintain
751    compatible APIs.</p>
752
753</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em>
754        Copyright &copy; 1999-2008, Apache Software Foundation
755        </em></font></div></td></tr></table></body></html>
Note: See TracBrowser for help on using the repository browser.