Note: At the moment, these directions are primarily aimed at a deployment of JSPWiki on Tomcat 6.0. However, you will find essential hints on configuring JSPWiki's newly added (NewIn2.6) support for container-managed e-mail factories here. Feel free to extend this page regarding other servlet containers!

For some general information on JNDI with Tomcat 6 see Apache Tomcat 6.0 JNDI Resources HOW-TO.

Resources#

Process#

  • Install JSPWiki
  • Edit Configurations
  • Move Files

Configurations To Be Edited#

Global Naming Resources#

Update <TOMCAT_HOME>/conf/server.xml as appropriate for your mail server and account.

<GlobalNamingResources>
    <!-- JavaMail JNDI Mail Session -->
    
    <Resource name="mail/Session" auth="Container"
        type="javax.mail.Session"
        username="<mail account username>"
        password="<mail account password>"
        mail.debug="false"
        mail.user="<mail account username>"
        mail.from="My wiki &lt;email@domain.com&gt;"
        mail.transport.protocol="smtp" 
        mail.smtp.host= "<smtp mail host>"
        mail.smtp.auth= "true"
        mail.smtp.port= "<SMTP Server Port>" <!-- Default 25 -->
        mail.smtp.starttls.enable="true"
        description="Global E-Mail Resource"
    />

If anything goes wrong, you may want to set mail.debug="true" here and log4j.rootCategory from INFO to DEBUG in jspwiki.properties.

If mail.from is defined here, you'll have to escape the "less than" and "greater than" characters via &lt; and &gt;, since we're speaking XML here: mail.from="My wiki &lt;email@domain.com&gt;"
In this case, the defined value is used by JSPWiki, too.
If mail.from is not defined here, you can configure which address to use in jspwiki.properties.

Note if you're using an SMTP mail server that requires authentication: This won't work if only mail.user and mail.password are set because these aren't automatically used for authentication. Therefore, you have to set username and password to the same values (or other values that authenticate you properly). For details see http://forum.java.sun.com/thread.jspa?threadID=615393&messageID=3422166

JSPWiki Context#

Next you have to link the global resource into JSPWiki's Context. For Tomcat 6, there are several ways to do this (for details see Apache Tomcat Configuration Reference - The Context Container).

The Context can be defined for example in:

  • <TOMCAT_HOME>/conf/catalina/localhost/<your JSPWiki name>.xml
  • <TOMCAT_HOME>/webapps/<Your JSPWiki Name>/META-INF/context.xml

The first location allows the JSPWiki Context to remain in place through multiple deployments.

<Context path="/Wiki" docBase="C:/Apps/Tools/JSPWiki/JSPWiki.war" debug="true">
    <Parameter name="jspwiki.propertyfile"
        value="C:/WebContent/Wiki/jspwiki.properties" override="false"
    />
    <ResourceLink
        name="mail/Session"
        global="mail/Session"
        type="javax.mail.Session"
    />
</Context>

Mail Session Resource Reference#

Location: <TOMCAT_HOME>/webapps/<your JSPWiki name>/WEB-INF/web.xml

Edit web.xml and uncomment the following lines:

<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>

JSPWiki Mail Properties#

Location: <TOMCAT_HOME>/webapps/<your JSPWiki name>/WEB-INF/jspwiki.properties or as defined and relocated in the JSPWiki Context specification.
###########################################################################
#
#  JavaMail configuration 
#  If you wish to allow your users to recover their passwords via email,
#  you should configure these properties. JavaMail can use either a 
#  container-managed JNDI resource factory (recommended, and the default), 
#  or a stand-alone factory whose properties are configured with mail.* 
#  properties in this file (below).

#  The address from which the email appears to come. This is required
#  for either of the mail configuration methods
mail.from =JSPWiki <email@my domain>
#
#  A. JNDI Resource Factory Configuration. JSPWiki will try this first.
#     You will need to configure your container to provide a JavaMail
#     resource factory. See your container documentation, or check our
#     fairly complete documentation (with examples for Tomcat) in
#     the JavaDocs for com.ecyrd.jspwiki.util.MailUtil.
#
#  JNDI resource name. (mail/Session is the default)
jspwiki.mail.jndiname = mail/Session

Files To Be Moved#

Location: <TOMCAT_HOME>/webapps/<your JSPWiki name>/WEB-INF/lib

mail.jar#

Move (don't copy) mail.jar to Tomcat's lib directory (<TOMCAT_HOME>/lib).

activation.jar#

If you are using Java Runtime Environment (JRE) 1.5 or earlier, move activation.jar to Tomcat's lib same as mail.jar. If you are using JRE 1.6 or greater, then the activation.jar is included in it, so simply delete JSPWiki's copy of it.

Acknowledgment #

Thanks to Florian Holeczek for identifying the needed configuration and a bug in the JSPWiki code. He identified the crucial information that allowed the Mail Session to be correctly authenticated.

Thanks to Dave Wolf for creating the initial version of this page and testing these configuration hints.


Category Documentation
Category Tips

Add new attachment

Only authorized users are allowed to upload new attachments.
« This page (revision-37) was last changed on 25-Sep-2010 23:14 by 81.83.56.111