The documentation is on the wiki (wiki.jboss.org). We have no similar concept to "matchers" but have a similar concept to mailets. Writing specific "how to do your own mail listener" doco is on my todo list when I get back from Milan.
Mail listeners are attached to chains. They are activated (if you use all the default stuff) first on the completion of the DATA command (however the body is directly streamed to the DB in order to save memory). Secondly, on the evaluation of delivery to a user mailbox.
Mail listeners are JMX MBeans. Listener chains are an ordered aggregate grouping of listeners and are JMX MBeans. A POJO can be an MBean. You must expose the MailListener interface.
For now the easiest thing to do is take the default mail listeners http://fisheye.labs.jboss.com/viewrep/JBoss/jboss-mail/src/java/org/jboss/mail/maillistener
and use them as an example along with the config created by your installation. We will GREATFULLY accept any filters that you're willing to donate. Eventually I expect to set up a seperate repository ala CPAN for listeners. And we plan to go the direction of JRuby or some kind of scripting language for writing generic listeners.
Thanks for your kind words. Welcome.
I'd like to develop and contribute some MailListeners, but I'm unclear on the mail processing lifecycle in the JB Mail (now Collaboration) Server.
Would you please explain the mail processing lifecycle and how MailListeners can interact with, and possibly interrupt, that lifecycle?
For instance, are the MailListeners notified early enough to be able to drop the connection; i.e. send a 550 error code if the sending IP is a known spammer IP? Or, are all e-mails received, but simply not stored if a MailListener returns null from the send()?
In the future *please* start new threads for things likes this "From James" has very little to do with this issue. It is helpful for people scanning to see if it applies to them.
No presently MailListeners cannot prevent the initial receipt of a mail. I was planning to add the concept of a "filter" but other things have gotten prioritized ahead of this. At present you'd have to override the Service MBean or the SMTP CmdData and/or IMAP Append commands (the IMAP append command being a great deal more complicated). I'd be happy if someone could work on an extensibility here:
ConnectionListener (listends for connection events but cannot directly listen to the stream)
Filter (can listen to and interupt the incoming stream)
So presently mail bodies are completely received and stored before MailListeners are invoked. MailListeners are aggregated in chains. They must return a mail object or null (if they wish to terminate its delivery). They can process it or do whatever they like really.
There are three chains (by default) at present. An incoming chain which is invoked by CmdData after receipt of \r\n.\r\n. The basic chain contains only the JMSMailListener which posts the headers on a queue. That queue is processed by DeliveryMDB which deligates to the remote and/or local remote delivery chain.
Recently I've added another instance of the delivery MDB which processes another queue for mail lists. These are processed by yet another chain.
It does not make sense for most mail listeners to be on the incoming chain since they can do their work asyncronously "out of band".