SpoolManager Configuration

The SpoolManager is controlled by a single configuration block in the config.xml. The spoolmanager tag defines the boundaries of the configuration block. The behavior of the SpoolManager, most importantly the routing of mail messages through the processor tree, is controlled by this block.

The spoolmanager tag has only one children. It is:

  • threads - This is a required positive integer element. It specifies the number of threads the SpoolManager will use to process messages in the spool. This parameter tends to substantially impact performance, so it is advisable to tune it in production configurations.
Spoolmanager depends on mailet and matcher packages, configured by these tags:
  • mailetpackages - This is a required container tag. It contains some number of mailetpackage children. The body of each of these mailetpackage elements is a Java package name. It is these packages that contain the classes to be instantiated as mailets.
  • matcherpackages - This is a required container tag. It contains some number of matcherpackage children. The body of each of these matcherpackage elements is a Java package name. It is these packages that contain the classes to be instantiated as matchers.
The remaining SpoolManager configuration elements are complex enough to require a more in-depth discussion.

Processor Configuration

In addition to the child elements discussed above, the SpoolManager tag can have several processor children. It is these tags and their children that define the processor tree for the SpoolManager.

Each processor has a required attribute, name. The value of this attribute must be unique for each processor tag. The name of a processor is significant. Certain processors are required (specifically root and error). The name "ghost" is forbidden as a processor name, as it is used to denote a message that should not undergo any further processing.

The James SpoolManager creates a correspondance between processor names and the "state" of a mail as defined in the Mailet API. Specifically, after each mailet processes a mail, the state of the message is examined. If the state has been changed, the message does not continue in the current processor. If the new state is "ghost" then processing of that message terminates completely. If the new state is anything else, the message is re-routed to the processor with the name matching the new state.

The root processor is a required processor. All new messages that the SpoolManager finds on the spool are directed to this processor.

The error processor is another required processor. Under certain circumstances James itself will redirect messages to the error processor. It is also the standard processor to which mailets redirect messages when an error condition is encountered.

The transport and spam processors are two useful, but optional, processors that are included in the out of the box configuration. These processors include logic for actual mail delivery and spam handling respectively. More information on these processors can be found in the default config.xml.

Each processor element has zero or more mailet child elements. Each of these elements describes a matcher/mailet pair. The ordering of the mailet children is crucial to the configuration, as it is the order in which pairs will be traversed in the processor.

It is this mailet element that is at the core of the SpoolManager configuration.

The Mailet Tag

Consider the following simple mailet tag:

<mailet match="RemoteAddrNotInNetwork=127.0.0.1" class="ToProcessor">

<processor>spam</processor>

</mailet>

The mailet tag has two required attributes, match and class.

The match attribute is set to the value of the specific Matcher class to be instantiated with a an optional argument. If present, the argument is separated from the Matcher class name by an '='. Semantic interpretation of the argument is left to the particular mailet.

The class attribute is set to the value of the Mailet class that is to be instantiated.

Finally, the children of the mailet tag define the configuration that is passed to the Mailet. The tags used in this section should have no attributes or children. The names and bodies of the elements will be passed to the mailet as (name, value) pairs.

So in the example above, a Matcher instance of RemoteAddrNotInNetwork would be instantiated, and the value "127.0.0.1" would be passed to the matcher. The Mailet of the pair will be an instance of ToProcessor, and it will be passed the (name, value) pair of ("processor", "spam").

James includes a number of pre-packaged Mailets and Matchers. A list of provided Mailets may be found here. A list of provided Matchers may be found here.