|
Mailets and Matchers
Download and Installation
One of the neat things about James is its use of mailets and matchers:
- A mailet is a Java class that does something with a mail message, like adding a footer, forwarding the message, notifying the postmaster about the receipt of the message, or whatever else a mail server may want to do.
- A matcher is a Java class that says "Yes, apply this mailet's instructions to that message for these recipients," and "No, don't apply this mailet's instructions to that message for those other recipients."
How Matchers and Mailets Work Together
To clarify this Matcher/Mailet business a bit further:
- Each mailet contains a method named service. A typical service method looks like this:
public void service(Mail mail) throws MessagingException {
MimeMessage mimeMessage = mail.getMessage();
// Do things with the message
mimeMessage.saveChanges();
}
The MimeMessage class belongs to the javax.mail.internet package, and the Mail class is part of the org.apache.mailet package.
- Each matcher contains a method named match. A typical match method looks like this:
public Collection match(Mail mail) {
if ( /* something or other is true */ ) {
return mail.getRecipients();
} else {
return null;
}
}
Despite this simplified explanation, an invocation of the match method doesn't return "yes" or "no." Instead, the match method returns a list of recipients for which a mailet should be processed.
Take, for instance, an AddFooter mailet that pastes the words "FOR YOUR EYES ONLY" at the bottom a message body. A particular message may have recipients Alan, Barry, Carol, and Diane. So the skeletal match method above may return a collection containing Alan, Barry, Carol, and Diane. This collection tells James to add "FOR YOUR EYES ONLY" to the copies sent to all four recipients.
On the other hand, the match method above may return null. In that case, James adds "FOR YOUR EYES ONLY" to none of the message's recipients. Of course, if you rewrite the match method, you may return a collection containing only Barry and Carol, or some other bunch from the message's original list of recipients.
How do you associate a matcher with a mailet? The James config.xml file contains mailet tags. Here's a nice mailet tag:
<mailet match="SizeGreaterThan=1k" class="AddFooter">
<text>Warning: Attachments may contain viruses!</text>
</mailet>
The tag uses a matcher named SizeGreaterThan and a mailet named AddFooter. Both of these classes (the SizeGreaterThan matcher and the AddFooter mailet) are provided as part of the James distribution. When you write a mailet tag, you normally supply parameters to both the mailet and the matcher.
- A parameter to a mailet is an XML element. For example, in the tag above, the text element tells the AddFooter mailet what text the footer must contain.
- A parameter to a matcher is buried inside the mailet tag's match attribute. In the tag above, the match attribute specifies the name of the matcher class (SizeGreaterThan) and the 1k (1 kilobyte) parameter value. If a message has size greater than 1 kilobyte, then James adds a Warning: Attachments may contain viruses! footer at the bottom of the message.
Matcher and Mailet Classes
To give James a test run, and as an excuse to write a matcher and a mailet, we dreamt up a fairly frivolous scenario. Here's how it goes:
We're strong advocates of Java technology, and thus, we are dismayed by any mention of .NET. So, when we receive e-mail messages containing the characters ".NET," we want to blot out those characters and replace them with some alternate text. What we really need is a ReplacePlainText mailet. The mailet looks for all occurrences of a certain string, and replaces such occurrences with other (less upsetting) text.
There's only one exception. We have a mutual friend named Manny, who works with both Java and .NET. (Manny's ongoing effort is to port portions of the Java API to the .NET platform.)
Manny has many e-mail addresses, each of the form Manny@some-domain-or-other. Our goal is to allow mail from Manny@anything-at-all (and no other mail) to display the word .NET. So our SenderIsNot matcher class takes an incoming e-mail message.
- If the sender isn't Manny@some-domain-or-other, then the matcher returns all the message's recipients. That is, the matcher tells James to apply the ReplacePlainText mailet to every recipient's copy of the message.
- If the sender is Manny@some-domain-or-other, then the matcher returns null. This tells James to apply the ReplacePlainText mailet to none of the recipients' copies.
The matcher and mailet classes are in Listings Listing 1
and 2
respectively. The XML tag to make James use the matcher with the mailet is in Listing 3
.
Both the matcher and the mailet contain init methods. In each init method, the Java program reads parameters from the mailet tag.
- The matcher's init method calls getCondition, which reads the word Manny from Listing 3
.
- The mailet's init method calls getInitParameter, which reads the strings \.NET and !^#% from Listing 3
.
Inside the mailet tag, the match attribute's value takes the form
match="matcher-class-name=parameters"
The getCondition method reads the parameters string, which in Listing 3
is the word Manny. When a mail message arrives, James calls the match method in Listing 1
. If the message's sender is Manny, the match method says, "Don't apply the mailet to any of the message's recipients." If the message's sender isn't Manny, the match method says "Apply the mailet to all of the message's recipients."
By the way, some matchers have what you'd normally think of as several parameters. For instance, I may want to allow the word .NET to appear in messages from three people named Manny, Moe, and Jack. In that case I'd stuff all three names into one delimited string.
match="SenderIsNot=Manny,Moe,Jack"
Then I'd write business logic inside the match method to parse the string and use the three names appropriately.
So, assume that Fred@dotnetlover.com sends me an e-mail message containing the word .NET. Then the match method in Listing 1
tells James to apply the mailet's logic to this message. In response, James calls the service method of Listing 2
, and replaces all occurrences of .NET with the string !^#%. (In Listing 3
, the backslash before .NET ensures that the replaceAll method doesn't mistake the dot for a regular expression's "any character" symbol.)
Click here for the full sample code.
A Good Choice
James is an efficient, robust e-mail server with an architecture that's ripe for future expansion. Upcoming releases of James may support instant messaging, new e-mail protocols, and other exciting features. James's plug-in design goes hand-in-hand with Java portability, making James a good choice for an enterprise-level e-mail server.
New on the Java Boutique:
New Review:
Time Management Made Easy with the Quartz Enterprise Job Scheduler
Why not just use the Java timer API? This open source scheduling
API boasts simplicity, ease-of-integration, a well-rounded feature
set, and it's free!
New Applet:
Reverse Complement
Reverse Complement is a simple applet that converts DNA or RNA
sequences into three useful formats.
Elsewhere on internet.com:
WebDeveloper Java
Lots of Java information on webdeveloper.com
WDVL Java
Thorough Java resource at the Web Developer's Virtual Library.
ScriptSearch Java
Hundreds of free Java code files to download.
jGuru: Your View of the Java Universe
Customizable portal with online training, FAQs, regular news updates, and tutorials.
|
