jigsaws: Cocoon 2 - Sendmail Logicsheet

Introduction

The novelty of sending and receiving email worn of ages ago, untill I tried to run the sendmail logic sheet. I was one very happy boy when that first email send with Cocoon ended up in my inbox and going by the amount of questions on the subject in the Cocoon users list I am not the only one. So here is step-by-step how to get it working.

The environment: Win2K, JDK 1.3.1, Tomcat 4.0.1 and Cocoon 2.0.2.

What You Need

Besides a Java Development Kit you need the following software to make this work:

Tomcat: Pick the latest distribution from The Jakarta Project Download page, currently Tomcat 4.0.4 Beta 2. Some people, including myself had problems running Cocoon with 4.0.2 and 4.0.3. I'm going to assume that you know how to install Tomcat.
JavaMail: You can download JavaMail from the Sun site. Follow the included installation instructions, very simple.
Java Activation Framework (JAF): You can download JAF from the Sun site. Follow the included installation instructions, very simple.
Cocoon 2: If you don't have this yet go to the Cocoon 2 Download page and pick the latest source distribution, not a binary one, currently cocoon-2.0.2-src.
Latest sendmail.xsl: I'm sure this won't be required soon but for now get it from http://cvs.apache.org/.
Other files: You can download this zip file that contains sendmail.xsp and cocoon.xconf.

(Re-)Building Cocoon

After you have installed Tomcat, JavaMail and JAF do the following:

Unzip the Cocoon distribution to where ever you like. You will end up with a directory called cocoon-2.0.2.
Copy sendmail.xsl to cocoon-2.0.2\src\java\org\apache\cocoon\components\language\markup\xsp\java.
Copy mail.jar and activation.jar to cocoon-2.0.2\lib\optional. I'm not 100% sure if this is required but it doesn't do any harm.

Copy sendmail.xsp to cocoon-2.0.2\src\webapp\docs\samples\xsp. You can put it anywhere you like but in this location you don't need to make any modification to sitemap.xmap

You need to edit sendmail.xsp to point to your mail server. You can use your ISP's if you don't have your own.

Look for <sendmail:smtphost>youMailServerAddress</sendmail:smtphost> and your mail server address.

<?xml version="1.0" encoding="UTF-8"?>
<xsp:page
 language="java"
 xmlns:xsp="http://apache.org/xsp"
 xmlns:xsp-request="http://apache.org/xsp/request/2.0"
 xmlns:sendmail="http://apache.org/cocoon/sendmail/1.0">
 <page>
  <xsp:logic>
   String text =
   "Hi,\n"+
   "this mail has been send through a web form ...\n";
  </xsp:logic>
  <sendmail:send-mail>
   <sendmail:charset>ISO-8859-1</sendmail:charset>
   <sendmail:from>user@mydomain.com</sendmail:from>
   <sendmail:to>perry@inflexions.com</sendmail:to>
   <sendmail:subject>Cocoon send mail test</sendmail:subject>
   <!-- Modify the next line to point to your mail server -->
   <sendmail:smtphost>youMailServerAddress</sendmail:smtphost>
   <sendmail:body>
    <xsp:expr>text</xsp:expr>
   </sendmail:body>
  </sendmail:send-mail>
 </page>
</xsp:page>

We need to make one addition to cocoon.xconf which you'll find in cocoon-2.0.2\src\webapp\WEB-INF.

Look for:

<markup-languages>
 <xsp-language logger="core.markup.xsp" name="xsp">
  <parameter name="prefix" value="xsp"/>
  <parameter name="uri" value="http://apache.org/xsp"/>
  <target-language name="java">
   ...
  </target-language>

In this section you'll find a number of <builtin-logicsheet> tags and we'll need to add one for the sendmail logicsheet. Add the following to this section:

<builtin-logicsheet>
 <parameter name="prefix" value="sendmail"/>
 <parameter name="uri"
     value="http://apache.org/cocoon/sendmail/1.0"/>
 <parameter name="href"
  value="resource://org/apache/cocoon/components/
    language/markup/xsp/java/sendmail.xsl"/>
</builtin-logicsheet>

Open a command window and cd to cocoon-2.0.2 and type:
```
build.bat -Dinclude.webapp.libs=yes
          -Dinstall.war={path-to-Tomcat-webapps-dir} install
```
The build will take a few minutes depending on your PC specs.

Running sendmail.xsp

Make sure your mail server is running or you are connected to your ISP if you're using their mail server.
Start Tomcat.
Go to http://localhost:8080/cocoon/xsp/sendmail.
Check your inbox... and smile.

Finally

A thank you to the people who answered all the questions and fixed bugs. If you find any errors in this how-to or find bits missing, please let me know.