Download: omikuji.zip
This is a sample auto-reply mail application running under James mail application server being developed in the Apache project.
James is a mail server compatible with STMP and POP3. In addition, the user can incorporate a custom mail application in James. You can create a James mail application as a class implementing the Mailet interface defined by Apache.
In this sample application, a shrine returns omikuji in reply to your mail. You can think of this application as an example of auto-reply mail application.
An omikuji is a piece of small paper telling your fortune in the near future. Many people in Japan try an omikuji when they visit a neary-by shrine for new year celebration. Remind a fortune cookie served in a Chinese restaurant in Western coutries.
I found a remarkable point while I wrote a sample for James. James completely frees processing of incoming mail to users, which, in the case of sendmail, is executed internally.
James judges how to handle an incoming mail using classes having the interface called Matcher. The matched mail is passed to the associated Mailet class for processing. The "matching" here doesn't mean a simple true-false decision, but means a list of recipients meeting the criteria.
For example, assume a message has arrived at a mail server that manages a domain named ssjava.net, and the recipients of the mail are omikuji@ssjava.net and president@microsoft.com. In James, a piece of mail is duplicated for each group of recipients and branched for further processing. In the default settings, a copy to omikuji@ssjava.net will be stored on the disk if the local user named omikuji exists. On the other hand, copy to president@microsoft.com will be discarded because it is not in the managed domain.
In James, the user can freely define the conditions, processings and orders of judgment for mail disposition by adding his/her own Matcher and/or Mailet classes and editing the configuration file. When using the Omikuji mailet, James-standard RecipientIs matcher is used to tell if it is the mail address of the shrine, and the matching mail is passed to the Omikuji mailet. If there are non-matching recipients, the mail is passed to the next decision step with the address of the shrine removed.
Assume the James mail server received the following mail:
MAIL FROM: someone@somewhere <- SMTP envelope RCPT TO: omikuji@ssjava.net RCPT TO: president@microsoft.com From: someone@somewhere <- message headers To: omikuji@ssjava.net To: president@microsoft.com Subject: Test Test mail to omikuji mailet. <- message body
Then, as a result of RecipientIs judgement, the mail is duplicated and branched to the two processing paths:
MAIL FROM: someone@somewhere
RCPT TO: omikuji@ssjava.net
From: someone@somewhere
To: omikuji@ssjava.net
To: president@microsoft.com
Subject: Test
Test mail to omikuji mailet.
MAIL FROM: someone@somewhere
RCPT TO: president@microsoft.com
From: someone@somewhere
To: omikuji@ssjava.net
To: president@microsoft.com
Subject: Test
Test mail to omikuji mailet.
The message copy on the left will be replied by the Omikuji mailet, and the copy on the right will be discarded.
Omikuji.java Source file for fortune teller mailet omikuji.jar JAR file containg the mailet <- Deleted (please compile) config.xml Sample configuration file for James omikuji-en.html This page
Here are steps for running the fortune teller mailet under James mail server.
The procedures are described.
There are two ways to install your mailet JAR into James according to documents for James 2.1.2 which I have used for testing. One way is to add your mailet when you build James from the source distribution. I didn't try this method.
The other method is to place the mailet JAR in lib directory directly beneath the James installation directory (called <james-home> below). You have to put other JAR's such as JavaMail in this directory together. I tried this method but failed.
The method I tried and was successful is to just insert the mailet JAR into james.sar placed in <james-home>/apps. However, this is not documented and I am not sure if this is a trouble-free method.
The mailet deployment methods are said to be greatly revised in the future. They may be very different in the newer versions of James. See James documents for detail.
You have to update <james-home>/apps/james/SAR-INF/config.xml in order to give James information about the mailet. I included a sample configuration file where the mailet information is added immediately after James installation (running with "localhost").
Add the following line in the <mailetpackages> element to specify the package name of the Omikuji mailet:
<mailetpackage>kobu.omikuji</mailetpackage>
Add the following element in the <processor name="transport"> element. This specifies a mail address matched by RecipientIs is passed to Omikuji mailet:
<mailet match="RecipientIs=omikuji@localhost" class="Omikuji">
<jinja>omikuji@localhost</jinja>
</mailet>
immediately after:
<mailet match="RecipientIsLocal" class="LocalDelivery"/>
This means the mailet is executed after delivery to valid users and before error mail processing for non-existent local users.
In this example, the address of the shrine is "omikuji@localhost." Change "localhost" to your mail server name if you run this mailet on the real mail server facing the Internet.
Restart the James server.
Send a mail to omikuji@localhost.
Read a mail that will be returned.
From: omikuji@localhost To: test@localhost Subject: Your fortune: Daikichi Congratulations! You have a best luck today.
The reply will be any one of Daikichi (best fortune), Kichi (good fortune) or Kyo (bad fortune).
Here is how to recompile the source file and creating the JAR file.
javac -classpath activation.jar;mail_1_3.jar;james.jar -d . Omikuji.java jar cf omikuji.jar kobu
The above command lines assume that you are in Windows and the required JAR files are in the same folder as the source file. Specify the location if the JAR files are in another folder. In UNIX, JAR file seperator is a colon (:), not semicolon (;).
Written: July 9, 2003
Updated: 2003/07/11
Written by: ARAI Bunkichi
Presented by: Kobu.Com (www.kobu.com/en)
The published sample code is a prototype and is not complete.
Please refrain from duplicating the sample code and its document in another place.
Copyright © 2003 Kobu.Com. All rights reserved.