About James

Apache Software Foundation

Writing a Custom Mailet

Implementing a custom mailet is generally a simple task, most of whose complexity
lies in coding the actual work to be done by the mailet. This is largely due to the
simplicity of the Mailet interface and the fact that a GenericMailet class is provided
as part of the Mailet package.

In this discussion we will assume that any mailet being implemented is a subclass of
GenericMailet. The GenericMailet class serves to abstract away of the configuration and
logging details. While it provides a noop implementation of the init() and destroy() methods,
these can be easily overridden to provide useful functionality.

In general, the only four methods that you should need to implement are init(), destroy(),
getMailetInfo(), and service(Mail). And only the last is required in all cases.

Configuration

As described in the SpoolManager configuration
section, mailets are configured with a set of String (name, value) pairs. These values are
passed into the Mailet upon initialization (although the details of this process are hidden by
the GenericMailet implementation). GenericMailet provides access to this configuration
information through use of the getInitParameter(String) method. Passing in the name of the
requested configuration value will yield the value if set, and null otherwise. Configuration
values are available inside the init(), destroy(), and service(Mail) methods.

Logging

There is a simple logging mechanism provided by the Mailet API. It does not support
logging levels, so any log filtering will have to be implemented in the Mailet code.
Logging is done by calling one of the two logging methods on GenericMailet - log(String)
or log(String,Throwable). Logging is available inside the init(), destroy(), and service(Mail)
methods.

The value of getMailetInfo() for the Mailet is prepended to the log entries for that
Mailet. So it may be desirable for you to override this method so you can distinguish mailet
log entries by Mailet.

Initialization

As part of the Mailet lifecycle, a Mailet is guaranteed to be initialized immediately after
being instantiated. This happens once and only once for each Mailet instance. The
Initialization phase is where configuration parsing and per-Mailet resource creation generally
take place. Depending on your Mailet, it may or may not be necessary to do any initialization
of the mailet. Initialization logic is implemented by overriding the init() method of
GenericMailet.

Servicing

The bulk of the Mailet logic is expected to be invoked from the service(Mail) method. This
method is invoked each time a mail message is to be processed by the mailet. The message is
passed in as an instance of the Mail interface, which is part of the Mailet API.

The Mail interface is essentially a light wrapper around JavaMail's MimeMessage class with a
few important differences. See the Javadoc for the interface for a description of the additional
methods available on this wrapper.

Destruction

As part of the Mailet lifecycle, a Mailet is guaranteed to be destroyed when the container
cleans up the Mailet. This happens once and only once for each Mailet instance. The
Destruction phase is where per-Mailet resource release generally takes place. Depending
on your Mailet, it may or may not be necessary to do any destruction
of the mailet. Destruction logic is implemented by overriding the destroy() method of
GenericMailet.

Deploying a Custom Mailet

Once a Mailet has been successfully implemented there are only a couple of
additional steps necessary to actually deploy the Mailet.

Adding Your Mailet to the Classpath

The Mailet must be added to James' classpath so that the Mailet can be loaded by James. There
are two ways to add a custom Mailet to the classpath so that James will be able to load the
Mailet. These are:

1. Download the source distribution, add a jar file containing the custom files to the lib
directory of the unpacked source distribution, and build a new .sar file by following the
directions here. This new .sar file will now
include your custom classes.

or

2. Place a jar file containing the custom class files in the lib subdirectory of the James
installation. It will also be necessary to unpack the JavaMail and James jar files from
the provided .sar file and add them to this directory.

James Configuration

Configuration of the processor chain is discussed
elsewhere in this documentation. The
details of configuring mailet deployment is discussed at length. Here we will only comment
that it is important to add the appropriate mailet package for your custom mailet to the
<mailetpackages> list and that the name of your mailet should not conflict with any of
the mailets described here.