Custom test mails are usefull to test specific configurations or functionalities of your mail server.
Take for example virus checking. You want to make sure that mails containing a virus are recognized and flagged in the right way.
To achieve this, you make Postage generate mock-up virus mails. When working correctly, the server for example marks those mails by adding a warning header. Postage picks up the mail and a custom validator checks if the header is present.
At validation time, custom code has access to the complete mail, including headers and body parts available for validation.
Depending on the result, you mark the mail's result record as valid/invalid making the result appear in the detailed report.
MailFactory and MailValidator are two interfaces which must be implemented. Both can be found in package org.apache.james.postage.mail.
MailFactory generates the test mail, MailValidator analyzes the received mail and checks if it conforms to the expected result, whatever 'result' may be in the particular use case.
To comply with Postage best practices, it is recommended not to implement MailFactory directly. The most convenient way is to subclass org.apache.james.postage.mail.AbstractMailFactory. Two methods must be implemented:
abstract protected void populateMessage(MimeMessage message, MailSender mailSender, MailProcessingRecord mailProcessingRecord) throws MessagingException;
populateMessage receives an initialized MimeMessage which is missing only use case specific data.
See DefaultMailFactory.java for an example.
abstract protected Class getValidatorClass();
getValidatorClass must simply return the validators class object.
Each <send> element in the Postage configuration file has an optional attribute, mail-factory-class.
It simply receives the fully-qualified class name. Here is an example:
<profile name="int-ext" source="intern" target="extern">
<send count-per-min="10" subject="int2ext"
text-size-min="10" text-size-max="1000" binary-size-min="1" binary-size-max="1000"
mail-factory-class="my.own.custom.TestMailFactory"
/>
</profile>
The validator class is responsible for judging whether the resulting mail matches the expected criteria.
The DefaultMailValidator for example checks if binary and text body parts have the same sizes
as when they were originally created by DefaultMailFactory.
Other potential validations include checking headers, added footers, removed attachments, introspecting mime contents and many more.
All validators are required to implement interface org.apache.james.postage.mail.MailValidator, declaring one method:
boolean validate(Message message, MailProcessingRecord record);
The MailFactory adds a Postage header to the test email, specifying which validator class has to be instantiated. If this header is missing, the validation cannot be invoked.