craigmcc 01/09/08 21:00:09
Modified: . BUILDING.txt build.properties.sample
catalina build.xml
catalina/src/conf server.xml
webapps/examples build.xml
webapps/examples/WEB-INF web.xml
webapps/examples/jsp index.html
webapps/tomcat-docs jndi-resources-howto.xml
Added: webapps/examples/WEB-INF/classes SendMailServlet.java
webapps/examples/jsp/mail sendmail.html sendmail.jsp
sendmail.txt
Log:
Update the "JNDI Resources" documentation to describe the resource factory
for javax.mail.Session objects. Add an example page and servlet to
illustrate the use of this feature, and update the build process
accordingly.
WARNING: The build process now requires that the Java Activation
Framework and JavaMail package distributions be available, and
"activation.jar" and "mail.jar" are now included automatically in the
Tomcat binary build (in directory $CATALINA_HOME/common/lib).
Revision Changes Path
1.2 +33 -9 jakarta-tomcat-4.0/BUILDING.txt
Index: BUILDING.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/BUILDING.txt,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- BUILDING.txt 2001/07/27 22:26:03 1.1
+++ BUILDING.txt 2001/09/09 04:00:07 1.2
@@ -1,4 +1,4 @@
-$Id: BUILDING.txt,v 1.1 2001/07/27 22:26:03 craigmcc Exp $
+$Id: BUILDING.txt,v 1.2 2001/09/09 04:00:07 craigmcc Exp $
Building The Tomcat 4.0 Servlet/JSP Container
@@ -208,8 +208,27 @@
it resides in its own subdirectory.
-(10) Download and Install the JSSE 1.0.2 Reference Implementation
+(10) Download and Install the Java Activation Framework 1.0.1
+* Download the Java Activation Framework package (version 1.0.1 or later) from
+
+ http://java.sun.com/products/javabeans/glasgow/jaf.html
+
+* Unpack the package into a convenient location so that it
+ resised in its own subdirectory.
+
+(11) Download and Install JavaMail 1.2
+
+* Download the JavaMail package (version 1.2 or later) from
+
+ http://java.sun.com/products/javamail/index.html
+
+* Unpack the package into a convenient location so that
+ it resides in its own subdirectory.
+
+
+(12) Download and Install the JSSE 1.0.2 Reference Implementation
+
* Download the Java Secure Sockets Extension (JSSE) package,
(version 1.0.2 or later) from
@@ -219,7 +238,7 @@
it resides in its own subdirectory.
-(11) Download and Install the Java Transaction APIs (OPTIONAL)
+(13) Download and Install the Java Transaction APIs (OPTIONAL)
NOTE: This step is only required if you wish to build the Tyrex connection
pool implementation for JNDI-accessed data sources.
@@ -232,7 +251,7 @@
own subdirectory.
-(12) Download and Install the JUnit Testing Package (OPTIONAL)
+(14) Download and Install the JUnit Testing Package (OPTIONAL)
NOTE: This step is only required if you wish to build and execute the unit
tests that are part of the Tomcat 4.0 source base.
@@ -245,7 +264,7 @@
own subdirectory.
-(13) Download and Install the Tyrex Data Source Package (OPTIONAL)
+(15) Download and Install the Tyrex Data Source Package (OPTIONAL)
NOTE: This step is only required if you wish to build the Tyrex connection
pool implementation for JNDI-accessed data sources.
@@ -258,7 +277,7 @@
own subdirectory.
-(13) Customize Build Properties For This Subproject
+(16) Customize Build Properties For This Subproject
Most Jakarta subprojects allow you to customize Ant properties (with default
values defined in the "build.xml" file. This is done by creating a text file
@@ -274,6 +293,9 @@
Property Name Description
---------------- --------------------------------------------------------
+ activation.home Pathname to directory containing the Java Activation
+ Framework package, version 1.0.1 or later
+
jmx.home Pathname to directory containing the Java Management
Extensions (JMX) Reference Implementation, version 1.0
or later
@@ -289,21 +311,23 @@
junit.jar Pathname to the "junit.jar" file from JUnit, version 3.7
or later
+ mail.home Pathname to the directory containing the JavaMail package,
+ version 1.2 or later
+
regexp.home Pathname to directory containing a binary distribution of
the Jakarta Regexp Project, version 1.2
servletapi.home Pathname to directory containing a binary distribution of
the Servlet 2.3/JSP 1.2 API classes
-FIXME: Properties for mail.jar, activation.jar, jdbc2_0-stdext.jar,
+FIXME: Properties for jdbc2_0-stdext.jar,
jta-spec1_0_1.jar, tyrex-0.9.7.0.jar
A short-cut to preparing your "build.properties" file is to make a copy of the
"build.properties.sample" file included in the Tomcat source distribution,
and then customize the paths within it.
-
-(14) Build A Binary Distribution
+(17) Build A Binary Distribution
Open a command line shell, and issue the following commands:
1.6 +9 -1 jakarta-tomcat-4.0/build.properties.sample
Index: build.properties.sample
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/build.properties.sample,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- build.properties.sample 2001/06/15 20:48:41 1.5
+++ build.properties.sample 2001/09/09 04:00:07 1.6
@@ -6,12 +6,16 @@
# to "build.properties" in the same directory that contains the top level
# "build.xml" file.
#
-# $Id: build.properties.sample,v 1.5 2001/06/15 20:48:41 amyroh Exp $
+# $Id: build.properties.sample,v 1.6 2001/09/09 04:00:07 craigmcc Exp $
# -----------------------------------------------------------------------------
# The path that is base for the rest of the paths in this file.
base.path=/usr/local
+# The directory that contains your binary distribution of the Java
+# Activation Framework, version 1.0.1 or later.
+activation.home=${base.path}/jaf-1.0.1
+
# The directory containing your binary distribution of JAXP and its
# associated declarations. You can customize the versions of JAXP used
# for Catalina and Jasper below. If you are using JAXP/1.0, replace
@@ -44,6 +48,10 @@
# The JAR file for the JUnit unit test suite you are using. This is required
# only if you wish to execute the unit tests
#junit.jar=${base.path}/junit3.5/junit.jar
+
+# The directory containing your binary distribution of JavaMail, version 1.2
+# or later.
+mail.home=${base.path}/javamail-1.2
# The directory containing your binary distribution of the Jakarta
# regular expressions package (jakarta-regexp), version 1.2.
1.54 +10 -7 jakarta-tomcat-4.0/catalina/build.xml
Index: build.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/catalina/build.xml,v
retrieving revision 1.53
retrieving revision 1.54
diff -u -r1.53 -r1.54
--- build.xml 2001/09/05 19:45:27 1.53
+++ build.xml 2001/09/09 04:00:08 1.54
@@ -22,6 +22,7 @@
<property name="test.webapp.war" value="${java.io.tmpdir}/webapp.war"/>
<!-- ================== Derived Property Values ========================= -->
+ <property name="activation.jar" value="${activation.home}/activation.jar"/>
<property name="jaxp.jar" value="${catalina.jaxp.home}/jaxp.jar"/>
<property name="parser.jar"
value="${catalina.jaxp.home}/${catalina.jaxp.parser.jar}"/>
<property name="jcert.jar" value="${jsse.home}/lib/jcert.jar"/>
@@ -29,6 +30,7 @@
<property name="jnet.jar" value="${jsse.home}/lib/jnet.jar"/>
<property name="jsse.jar" value="${jsse.home}/lib/jsse.jar"/>
<property name="jmxri.jar" value="${jmx.home}/lib/jmxri.jar"/>
+ <property name="mail.jar" value="${mail.home}/lib/mail.jar"/>
<property name="regexp.jar" value="${regexp.home}/jakarta-regexp-1.2.jar"/>
<property name="servlet.jar" value="${servletapi.home}/lib/servlet.jar"/>
@@ -38,11 +40,13 @@
<pathelement location="${jaxp.jar}"/>
<pathelement location="${regexp.jar}"/>
<pathelement location="${servlet.jar}"/>
+ <pathelement location="${activation.jar}"/>
<pathelement location="${jcert.jar}"/>
<pathelement location="${jnet.jar}"/>
<pathelement location="${jsse.jar}"/>
<pathelement location="${jmxri.jar}"/>
<pathelement location="${junit.jar}"/>
+ <pathelement location="${mail.jar}"/>
<pathelement location="${catalina.build}/classes"/>
<pathelement location="${catalina.build}/tests"/>
</path>
@@ -91,6 +95,11 @@
<copy file="${servlet.jar}" tofile="${catalina.build}/common/lib/servlet.jar" />
<!-- Copy the JNDI JAR file for use under JDK 1.2.2 -->
<copy file="${jndi.jar}" tofile="${catalina.build}/common/lib/jndi.jar" />
+ <!-- Copy activation.jar and mail.jar for the mail resource factories -->
+ <copy file="${activation.jar}"
+ tofile="${catalina.build}/common/lib/activation.jar"/>
+ <copy file="${mail.jar}"
+ tofile="${catalina.build}/common/lib/mail.jar"/>
<!-- Server Components -->
<!-- Catalina needs JAXP compliant XML parser -->
@@ -126,8 +135,6 @@
classname="javax.transaction.UserTransaction" />
<available property="avalon.present"
classname="org.apache.avalon.blocks.Block" />
- <available property="javamail.present"
- classname="javax.mail.internet.MimeMessage" />
<available property="jdk.1.3.present"
classname="java.lang.reflect.Proxy" />
<!-- Compile Service API -->
@@ -136,15 +143,11 @@
excludes="**/CVS/**" />
<!-- Compile internal server components -->
<javac srcdir="src/share" destdir="${catalina.build}/classes"
-
classpath="${parser.jar}:${jaxp.jar}:${regexp.jar}:${servlet.jar}:${jcert.jar}:${jnet.jar}:${jsse.jar}:${jmxri.jar}:${jndi.jar}"
+
classpath="${parser.jar}:${jaxp.jar}:${regexp.jar}:${servlet.jar}:${jcert.jar}:${jnet.jar}:${jsse.jar}:${jmxri.jar}:${jndi.jar}:${activation.jar}:${mail.jar}"
deprecation="off" debug="on" optimize="off" target="1.2"
excludes="**/CVS/**">
<exclude name="**/factory/Tyrex*.java"
unless="tyrex.present" />
- <exclude name="**/factory/MailSessionFactory.java"
- unless="javamail.present" />
- <exclude name="**/factory/SendMailFactory.java"
- unless="javamail.present" />
<exclude name="**/startup/CatalinaBlock.java"
unless="avalon.present" />
<exclude name="**/util/ProcessHelper.java"
1.29 +1 -1 jakarta-tomcat-4.0/catalina/src/conf/server.xml
Index: server.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/catalina/src/conf/server.xml,v
retrieving revision 1.28
retrieving revision 1.29
diff -u -r1.28 -r1.29
--- server.xml 2001/08/10 14:14:15 1.28
+++ server.xml 2001/09/09 04:00:08 1.29
@@ -260,7 +260,7 @@
<parameter><name>driverName</name>
<value>jdbc:HypersonicSQL:database</value></parameter>
</ResourceParams>
- <Resource name="mail/session" auth="CONTAINER"
+ <Resource name="mail/Session" auth="Container"
type="javax.mail.Session"/>
<ResourceParams name="mail/session">
<parameter>
1.10 +1 -1 jakarta-tomcat-4.0/webapps/examples/build.xml
Index: build.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/examples/build.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- build.xml 2001/08/27 16:47:57 1.9
+++ build.xml 2001/09/09 04:00:08 1.10
@@ -41,7 +41,7 @@
<javac srcdir="WEB-INF/classes"
destdir="${webapps.build}/${webapp.name}/WEB-INF/classes"
- classpath="${servlet.jar}:${jndi.jar}"
+ classpath="${servlet.jar}:${jndi.jar}:${activation.jar}:${mail.jar}"
deprecation="off" debug="on" optimize="off"
excludes="**/CVS/**"/>
1.20 +13 -1 jakarta-tomcat-4.0/webapps/examples/WEB-INF/web.xml
Index: web.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/examples/WEB-INF/web.xml,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- web.xml 2001/09/05 05:14:00 1.19
+++ web.xml 2001/09/09 04:00:08 1.20
@@ -95,6 +95,12 @@
</listener>
<!-- Define servlets that are included in the example application -->
+
+ <servlet>
+ <servlet-name>SendMailServlet</servlet-name>
+ <servlet-class>SendMailServlet</servlet-class>
+ </servlet>
+
<servlet>
<servlet-name>
snoop
@@ -113,6 +119,7 @@
<role-name>tomcat</role-name>
</run-as>
</servlet>
+
<servlet>
<servlet-name>
servletToJsp
@@ -141,6 +148,11 @@
</servlet-mapping>
<servlet-mapping>
+ <servlet-name>SendMailServlet</servlet-name>
+ <url-pattern>/SendMailServlet</url-pattern>
+ </servlet-mapping>
+
+ <servlet-mapping>
<servlet-name>
snoop
</servlet-name>
@@ -176,7 +188,7 @@
</taglib>
<resource-ref>
- <res-ref-name>mail/session</res-ref-name>
+ <res-ref-name>mail/Session</res-ref-name>
<res-type>javax.mail.Session</res-type>
<res-auth>Container</res-auth>
</resource-ref>
1.1
jakarta-tomcat-4.0/webapps/examples/WEB-INF/classes/SendMailServlet.java
Index: SendMailServlet.java
===================================================================
/* $Id: SendMailServlet.java,v 1.1 2001/09/09 04:00:08 craigmcc Exp $
*
*/
import java.io.IOException;
import java.io.PrintWriter;
import javax.mail.Message;
import javax.mail.Session;
import javax.mail.Transport;
import javax.mail.internet.InternetAddress;
import javax.mail.internet.MimeMessage;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.servlet.RequestDispatcher;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
/**
* Example servlet sending mail message via JNDI resource.
*
* @author Craig McClanahan
* @version $Revision: 1.1 $ $Date: 2001/09/09 04:00:08 $
*/
public class SendMailServlet extends HttpServlet {
public void doPost(HttpServletRequest request,
HttpServletResponse response)
throws IOException, ServletException
{
// Acquire request parameters we need
String from = request.getParameter("mailfrom");
String to = request.getParameter("mailto");
String subject = request.getParameter("mailsubject");
String content = request.getParameter("mailcontent");
if ((from == null) || (to == null) ||
(subject == null) || (content == null)) {
RequestDispatcher rd =
getServletContext().getRequestDispatcher("/jsp/mail/sendmail.jsp");
rd.forward(request, response);
return;
}
// Prepare the beginning of our response
PrintWriter writer = response.getWriter();
response.setContentType("text/html");
writer.println("<html>");
writer.println("<head>");
writer.println("<title>Example Mail Sending Results</title>");
writer.println("</head>");
writer.println("<body bgcolor=\"white\">");
try {
// Acquire our JavaMail session object
Context initCtx = new InitialContext();
Context envCtx = (Context) initCtx.lookup("java:comp/env");
Session session = (Session) envCtx.lookup("mail/Session");
// Prepare our mail message
Message message = new MimeMessage(session);
message.setFrom(new InternetAddress(from));
InternetAddress dests[] = new InternetAddress[]
{ new InternetAddress(to) };
message.setRecipients(Message.RecipientType.TO, dests);
message.setSubject(subject);
message.setContent(content, "text/plain");
// Send our mail message
Transport.send(message);
// Report success
writer.println("<strong>Message successfully sent!</strong>");
} catch (Throwable t) {
writer.println("<font color=\"red\">");
writer.println("ENCOUNTERED EXCEPTION: " + t);
writer.println("<pre>");
t.printStackTrace(writer);
writer.println("</pre>");
writer.println("</font>");
}
// Prepare the ending of our response
writer.println("<br><br>");
writer.println("<a href=\"jsp/mail/sendmail.jsp\">Create a new
message</a><br>");
writer.println("<a href=\"jsp/index.html\">Back to examples home</a><br>");
writer.println("</body>");
writer.println("</html>");
}
}
1.3 +8 -0 jakarta-tomcat-4.0/webapps/examples/jsp/index.html
Index: index.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/examples/jsp/index.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- index.html 2001/07/12 09:24:54 1.2
+++ index.html 2001/09/09 04:00:08 1.3
@@ -148,6 +148,14 @@
<td WIDTH="30%"><a href="simpletag/foo.html"><img SRC="../images/code.gif" HSPACE=4
BORDER=0 height=24 width=24 align=TOP></a><a href="simpletag/foo.html">Source</a></td>
</tr>
+
+<tr valign=TOP>
+<td>Send mail example</td>
+<td valign=TOP width="30%"><a href="mail/sendmail.jsp"><img
src="../images/execute.gif" hspace=4 border=0 align=top></a><a
href="mail/sendmail.jsp">Execute</a></td>
+
+<td width="30%"><a href="mail/sendmail.html"><img SRC="../images/code.gif" HSPACE=4
BORDER=0 height=24 width=24 align=TOP></a><a href="mail/sendmail.html">Source</a></td>
+</tr>
+
</table>
</body>
1.1 jakarta-tomcat-4.0/webapps/examples/jsp/mail/sendmail.html
Index: sendmail.html
===================================================================
<html>
<!--
Copyright (c) 1999 The Apache Software Foundation. All rights
reserved.
-->
<head>
<title>Untitled Document</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>
<body bgcolor="#FFFFFF">
<p><font color="#0000FF"><a href="snoop.jsp"><img src="../../images/execute.gif"
align="right" border="0"></a><a href="../index.html"><img
src="../../images/return.gif" width="24" height="24" align="right"
border="0"></a></font></p>
<h3><a href="sendmail.txt">Source Code for Send Mail Example<font
color="#0000FF"></a>
</font> </h3>
</body>
</html>
1.1 jakarta-tomcat-4.0/webapps/examples/jsp/mail/sendmail.jsp
Index: sendmail.jsp
===================================================================
<html>
<head>
<title>Example Mail Sending Form</title>
</head>
<body bgcolor="white">
<p>This page will send an electronic mail message via the
<code>javax.mail.Session</code> resource factory that is configured into
the JNDI context for this web application. Before it can be used
successfully, you must take note of the following:</p>
<ul>
<li>The default configuration assumes that there is an SMTP server running
on <strong>localhost</strong>. If this is not the case, edit your
<code>conf/server.xml</code> file and change the value for the
<code>mail.smtp.host</code> parameter to the name of a host that provides
SMTP service for your network.</li>
<li>The application logic assumes that no user authentication is required
by your SMTP server before accepting mail messages to be sent.</li>
<li>All of the fields below are required.</li>
</ul>
<form method="POST" action="../../SendMailServlet">
<table>
<tr>
<th align="center" colspan="2">
Enter The Email Message To Be Sent
</th>
</tr>
<tr>
<th align="right">From:</th>
<td align="left">
<input type="text" name="mailfrom" size="60">
</td>
</tr>
<tr>
<th align="right">To:</th>
<td align="left">
<input type="text" name="mailto" size="60">
</td>
</tr>
<tr>
<th align="right">Subject:</th>
<td align="left">
<input type="text" name="mailsubject" size="60">
</td>
</tr>
<tr>
<td colspan="2">
<textarea name="mailcontent" rows="10" cols="80">
</textarea>
</td>
</tr>
<tr>
<td align="right">
<input type="submit" value="Send">
</td>
<td align="left">
<input type="reset" value="Reset">
</td>
</tr>
</table>
</form>
</body>
</html>
1.1 jakarta-tomcat-4.0/webapps/examples/jsp/mail/sendmail.txt
Index: sendmail.txt
===================================================================
<html>
<head>
<title>Example Mail Sending Form</title>
</head>
<body bgcolor="white">
<p>This page will send an electronic mail message via the
<code>javax.mail.Session</code> resource factory that is configured into
the JNDI context for this web application. Before it can be used
successfully, you must take note of the following:</p>
<ul>
<li>The default configuration assumes that there is an SMTP server running
on <strong>localhost</strong>. If this is not the case, edit your
<code>conf/server.xml</code> file and change the value for the
<code>mail.smtp.host</code> parameter to the name of a host that provides
SMTP service for your network.</li>
<li>The application logic assumes that no user authentication is required
by your SMTP server before accepting mail messages to be sent.</li>
<li>All of the fields below are required.</li>
</ul>
<form method="POST" action="../../SendMailServlet">
<table>
<tr>
<th align="center" colspan="2">
Enter The Email Message To Be Sent
</th>
</tr>
<tr>
<th align="right">From:</th>
<td align="left">
<input type="text" name="mailfrom" size="60">
</td>
</tr>
<tr>
<th align="right">To:</th>
<td align="left">
<input type="text" name="mailto" size="60">
</td>
</tr>
<tr>
<th align="right">Subject:</th>
<td align="left">
<input type="text" name="mailsubject" size="60">
</td>
</tr>
<tr>
<td colspan="2">
<textarea name="mailcontent" rows="10" cols="80">
</textarea>
</td>
</tr>
<tr>
<td align="right">
<input type="submit" value="Send">
</td>
<td align="left">
<input type="reset" value="Reset">
</td>
</tr>
</table>
</form>
</body>
</html>
1.2 +132 -1 jakarta-tomcat-4.0/webapps/tomcat-docs/jndi-resources-howto.xml
Index: jndi-resources-howto.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/jndi-resources-howto.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- jndi-resources-howto.xml 2001/09/09 00:48:11 1.1
+++ jndi-resources-howto.xml 2001/09/09 04:00:09 1.2
@@ -46,7 +46,7 @@
<source>
// Obtain our environment naming context
Context initCtx = new InitialContext();
-Context envCtx = initCtx.lookup("java:comp/env");
+Context envCtx = (Context) initCtx.lookup("java:comp/env");
// Look up our data source
DataSource ds = (DataSource)
@@ -115,7 +115,138 @@
<section name="Tomcat Standard Resource Factories">
+ <p>Tomcat 4 includes a series of standard resource factories that can
+ provide services to your web applications, but give you configuration
+ flexibility (in <code>$CATALINA_HOME/conf/server.xml</code>) without
+ modifying the web application or the deployment descriptor. Each
+ subsection below details the configuration and usage of the standard
+ resource factories.</p>
+
+ <p>See <a href="#Adding Custom Resource Factories">Adding Custom
+ Resource Factories</a> for information about how to create, install,
+ configure, and use your own custom resource factory classes with
+ Tomcat 4.</p>
+
<subsection name="JavaMail Sessions">
+
+ <h3>0. Introduction</h3>
+
+ <p>In many web applications, sending electronic mail messages is a
+ required part of the system's functionality. The
+ <a href="http://java.sun.com/products/javamail";>Java Mail</a> API
+ makes this process relatively straightforward, but requires many
+ configuration details that the client application must be aware of
+ (including the name of the SMTP host to be used for message sending).</p>
+
+ <p>Tomcat 4 includes a standard resource factory that will create
+ <code>javax.mail.Session</code> session instances for you, already
+ connected to the SMTP server that is configured in <code>server.xml</code>.
+ In this way, the application is totally insulated from changes in the
+ email server configuration environment - it simply asks for, and receives,
+ a preconfigured session whenever needed.</p>
+
+ <p>The steps required for this are outlined below.</p>
+
+ <h3>1. Declare Your Resource Requirements</h3>
+
+ <p>The first thing you should do is modify the web application deployment
+ descriptor (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under
+ which you will look up preconfigured sessions. By convention, all such
+ names should resolve to the <code>mail</code> subcontext (relative to the
+ standard <code>java:comp/env</code> naming context that is the root of
+ all provided resource factories. A typical <code>web.xml</code> entry
+ might look like this:</p>
+<source>
+<resource-ref>
+ <description>
+ Resource reference to a factory for javax.mail.Session
+ instances that may be used for sending electronic mail
+ messages, preconfigured to connect to the appropriate
+ SMTP server.
+ </description>
+ <resource-ref-name>
+ mail/Session
+ </resource-ref-name>
+ <res-type>
+ javax.mail.Session
+ </res-type>
+ <res-auth>
+ Container
+ </res-auth>
+</resource-ref>
+</source>
+
+ <p><strong>WARNING</strong> - Be sure you respect the element ordering
+ that is required by the DTD for web application deployment descriptors!
+ See the
+ <a href="http://java.sun.com/products/servlet/download.html";>Servlet
+ Specification</a> for details.</p>
+
+ <h3>2. Code Your Application's Use Of This Resource</h3>
+
+ <p>A typical use of this resource reference might look like this:</p>
+<source>
+Context initCtx = new InitialContext();
+Context envCtx = (Context) initCtx.lookup("java:comp/env");
+Session session = (Session) envCtx.lookup("mail/Session");
+
+Message message = new MimeMessage(session);
+message.setFrom(new InternetAddress(request.getParameter("from"));
+InternetAddress to[] = new InternetAddress[1];
+to[0] = new InternetAddress(request.getParameter("to"));
+message.setRecipients(Message.RecipientType.TO, to);
+message.setSubject(request.getParameter("subject"));
+message.setContent(request.getParameter("content"), "text/plain");
+Transport.send(message);
+</source>
+
+ <p>Note that the application uses the same resource reference name
+ that was declared in the web application deployment descriptor. This
+ is matched up against the resource factory that is configured in
+ <code>$CATALINA_HOME/conf/server.xml</code>, as described below.</p>
+
+ <h3>3. Configure Tomcat's Resource Factory</h3>
+
+ <p>To configure Tomcat's resource factory, add an elements like this to the
+ <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
+ <code>Context</code> element for this web application (or nested inside
+ a <code>DefaultContext</code> element for the surrounding
+ <code><Host></code> or <code><Engine></code> element.</p>
+<source>
+<Context ...>
+ ...
+ <Resource name="mail/Session" auth="Container"
+ type="javax.mail.Session"/>
+ <ResourceParams name="mail/Session">
+ <parameter>
+ <name>mail.smtp.host</name>
+ <value>localhost</value>
+ </parameter>
+ </ResourceParams>
+ ...
+</Context>
+</source>
+
+ <p>Note that the resource name (here, <code>mail/Session</code>) must
+ match the value specified in the web application deployment descriptor.
+ Customize the value of the <code>mail.smtp.host</code> parameter to
+ point at the server that provides SMTP service for your network.</p>
+
+ <h3>Example Application</h3>
+
+ <p>The <code>/examples</code> application included with Tomcat contains
+ an example of utilizing this resource factory. It is accessed via the
+ "JSP Examples" link. The source code for the servlet that actually
+ sends the mail message is in
+ <code>/WEB-INF/classes/SendMailServlet.java</code>.</p>
+
+ <p><strong>WARNING</strong> - The default configuration assumes that
+ there is an SMTP server listing on port 25 on <code>localhost</code>.
+ If this is not the case, edit the
+ <code>$CATALINA_HOME/conf/server.xml</code> file, and modify the
+ parameter value for the <code>mail.smtp.host</code> parameter to be
+ the host name of an SMTP server on your network.</p>
+
</subsection>
<subsection name="JDBC Data Sources">
