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.

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.