| Contains static methods for sending e-mails to recipients using JNDI-supplied
JavaMail
Sessions supplied by a web container (preferred) or configured via
jspwiki.properties; both methods are described below.
Because most e-mail servers require authentication,
for security reasons implementors are strongly encouraged to use
container-managed JavaMail Sessions so that passwords are not exposed in
jspwiki.properties.
To enable e-mail functions within JSPWiki, administrators must do three things:
ensure that the required JavaMail JARs are on the runtime classpath, configure
JavaMail appropriately, and (recommdended) configure the JNDI JavaMail session factory.
JavaMail runtime JARs
The first step is easy: JSPWiki bundles
recent versions of the required JavaMail mail.jar and
activation.jar into the JSPWiki WAR file; so, out of the box
this is already taken care of. However, when using JNDI-supplied
Session factories, these should be moved, not copied, to a classpath location
where the JARs can be shared by both the JSPWiki webapp and the container. For example,
Tomcat 5 provides the directory $CATALINA_HOME>/common/lib
for storage of shared JARs; move mail.jar and activation
there instead of keeping them in /WEB-INF/lib.
JavaMail configuration
Regardless of the method used for supplying JavaMail sessions (JNDI container-managed
or via jspwiki.properties, JavaMail needs certain properties
set in order to work correctly. Configurable properties are these:
| Property |
Default |
Definition |
jspwiki.mail.jndiname |
mail/Session |
The JNDI name of the JavaMail session factory |
mail.smtp.host |
127.0.0.1 |
The SMTP mail server from which messages will be sent. |
mail.smtp.port |
25 |
The port number of the SMTP mail service. |
mail.smtp.account |
(not set) |
The user name of the sender. If this value is supplied, the JavaMail
session will attempt to authenticate to the mail server before sending
the message. If not supplied, JavaMail will attempt to send the message
without authenticating (i.e., it will use the server as an open relay).
In real-world scenarios, you should set this value. |
mail.smtp.password |
(not set) |
The password of the sender. In real-world scenarios, you
should set this value. |
mail.from |
${user.name}@${mail.smtp.host}* |
The e-mail address of the sender. |
mail.smtp.timeout |
5000* |
Socket I/O timeout value, in milliseconds. The default is 5 seconds. |
mail.smtp.connectiontimeout |
5000* |
Socket connection timeout value, in milliseconds. The default is 5 seconds. |
mail.smtp.starttls.enable |
true* |
If true, enables the use of the STARTTLS command (if
supported by the server) to switch the connection to a
TLS-protected connection before issuing any login commands.
Note that an appropriate trust store must configured so that
the client will trust the server's certificate. By default,
the JRE trust store contains root CAs for most public certificate
authorities. |
*These defaults apply only if the stand-alone Session factory is used
(that is, these values are obtained from jspwiki.properties).
If using a container-managed JNDI Session factory, the container will
likely supply its own default values, and you should probably override
them (see the next section).
Container JNDI Session factory configuration
You are strongly encouraged to use a container-managed JNDI factory for
JavaMail sessions, rather than configuring JavaMail through jspwiki.properties.
To do this, you need to two things: uncomment the <resource-ref> block
in /WEB-INF/web.xml that enables container-managed JavaMail, and
configure your container's JavaMail resource factory. The web.xml
part is easy: just uncomment the section that looks like this:
<resource-ref>
<description>Resource reference to a container-managed JNDI JavaMail factory for sending e-mails.</description>
<res-ref-name>mail/Session</res-ref-name>
<res-type>javax.mail.Session</res-type>
<res-auth>Container</res-auth>
</resource-ref>
To configure your container's resource factory, follow the directions supplied by
your container's documentation. For example, the
Tomcat
5.5 docs state that you need a properly configured <Resource>
element inside the JSPWiki webapp's <Context> declaration. Here's an example shows
how to do it:
<Context ...>
...
<Resource name="mail/Session" auth="Container"
type="javax.mail.Session"
mail.smtp.host="127.0.0.1"/>
mail.smtp.port="25"/>
mail.smtp.account="your-account-name"/>
mail.smtp.password="your-password"/>
mail.from="Snoop Dogg <snoop@dogg.org>"/>
mail.smtp.timeout="5000"/>
mail.smtp.connectiontimeout="5000"/>
mail.smtp.starttls.enable="true"/>
...
</Context>
Note that with Tomcat (and most other application containers) you can also declare the JavaMail
JNDI factory as a global resource, shared by all applications, instead of as a local JSPWiki
resource as we have done here. For example, the following entry in
$CATALINA_HOME/conf/server.xml creates a global resource:
<GlobalNamingResources>
<Resource name="mail/Session" auth="Container"
type="javax.mail.Session"
...
mail.smtp.starttls.enable="true"/>
</GlobalNamingResources>
This approach — creating a global JNDI resource — yields somewhat decreased
deployment complexity because the JSPWiki webapp no longer needs its own JavaMail resource
declaration. However, it is slightly less secure because it means that all other applications
can now obtain a JavaMail session if they want to. In many cases, this is what
you want.
NOTE: Versions of Tomcat 5.5 later than 5.5.17, and up to and including 5.5.23 have a
b0rked version of $CATALINA_HOME/common/lib/naming-factory.jar
that prevents usage of JNDI. To avoid this problem, you should patch your 5.5.23 version
of naming-factory.jar with the one from 5.5.17. This is a known issue
and the bug report (#40668) is
here.
author:
Christoph Sauer
author:
Dan Frankowski
author:
Andrew Jaquith | 