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

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

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