Creating an Email Java Class

Jake Howlett, 5 March 2001

Category: Java; Keywords: mail send java class

Sending email from Agents is a part of everyday life for most domino developers working on workflow applications. How many times have you written code similar to the following:

Dim s As New NotesSession
Dim db As NotesDatabase
Dim mail As Notesdocument
Dim body As NotesRichTextItem

Set db = s.CurrentDatabase
Set mail = db.Createdocument
Set body = New NotesRichTextItem(mail, "Body")

mail.Form = "Memo"
mail.Subject = "A simple message"
mail.SendTo = "you@example.com"
mail.ReplyTo = "me@example.com"
Call body.AppendText("Your application has been:")
Call body.AddnewLine(2)
Call body.AppendText("APPROVED")
mail.Send(False)

Wouldn't it be nice if this were a little simpler!? I thought so. That's why (as well as learning Java at the time) I wrote a Java class to make the above LotusScript look more like the following Java:

Session ss = getSession();
AgentContext ac = ss.getAgentContext();
Database db = ac.getCurrentDatabase();

Email mm = new Email( db );
mm.setReplyTo( "me@example.com" );
mm.setSubject( "A simple message" );
mm.setBody( "Your application has been:\n\nAPPROVED" );
mm.setSendTo( "you@example.com" );
mm.sendMail( false );

How? Well, I've attached the file called Email.java for you to look at the source. This is what you would use to create the Email.class file.

This .class file then needs to be imported in to your agent via the Domino Designer IDE. Alternatively, if you use R5, you can paste the code in to Java Script-Library, called Email*. Then, using the "Edit Project" button in the Agent IDE create a reference to it, like below:

A closer look at the code will show that there is more to it than the above example shows. A full set of methods would be:

setSendTo (String)
setSendTo (Vector)
setCopyTo
setBlindCopyTo
setReplyTo
setSubject
setBody (String)
setBody (StringBuffer)
sendMail

This list can go on and it is easy for you to replicate functionality and add methods as needed. After all, if I can do it, anyone can ;-)

If you have gotten this far and are thinking "Why do I want an Email class in my agents?" Well that is up to you at the end of the day. The reason I'm taking the time to write this is that I learnt an awful lot about writing Java agents and classes whilst doing this. Being a great advocate of writing modular code I thought I would share what I learnt with you, the masses.

Let's consider the code, chunk by chunnk:

public class Email
{
private Document ml;
private Vector recipients = new Vector();
private boolean hasSubject = false;
private boolean hasBody = false;

//Constructor - sets up the mail that will be sent
Email ( Database db )
throws NotesException
{
ml = db.createDocument();
ml.replaceItemValue( "Form", "Memo" );
}

The first few lines of our class define the objects we are going to use throughout the class.

The first method we see is the constructor. This method (which ALWAYS has the same name as the class it belongs to) is similar to an initialize() method but that it gets called automatically when we create a new Email object: Email mm = new Email(db). This then creates a new "Memo" form for us within the Database we supply as an argument.

//Set value of SendTo field (String)
public void setSendTo( String SendTo )
{
recipients.addElement( SendTo );
}

//OverLoaded setSendTo method (Vector)
public void setSendTo( Vector SendTo )
{
recipients = SendTo;
}

Did you notice there were two methods both called "setSendTo" !? This is called overloading and allows different code to be executed depending on the number/type of arguments you supply. We can use this to make arguments optional and to allow different data tyes to get passed.

The send method of the Domino's Document class likes to have a Vector (similar to array) passed to it. That is why I declared the Vector called "recipients" and get these methods to add to it. That way we can ensure that the data type is consistent.

//Set value of CopyTo field
public void setCopyTo( String CopyTo )
throws NotesException
{
ml.replaceItemValue ( "CopyTo", CopyTo );
}

This method has not been overloaded and only allows a String to be passed to it. It uses this string to simply set the field value on out "Memo" form using the replaceItemValue method.

//Send the mail to recipient
public void sendMail ( boolean SaveMail )
throws NotesException
{
if ( ( hasSubject || hasBody) && recipients.isEmpty() == false ) {
ml.setSaveMessageOnSend( SaveMail );
ml.send( false, recipients );
ml.recycle();
}
} ///~)

The final method sends the "Memo". Before it does this it first checks that there are recipients for the mail by checking the Vector isn't empty. It also checks that the mail has either a Subject or a Body - without which there is not much point in sending it. These flags are declared at the start of the class and get set when the setSubject() or setBody() methods are called.

Before any Java experts start to attack me, I will be the first to admit this class is far from perfect. Hey, I'm just a beginner and it works. Areas for improvemnt:

Error Checking
Error Handling
Query properties as well as set them
Multiple recipints in CopyTo
Multiple recipints in BlindCopyTo
Access to more properties/fields
Garbage Collection (?)

Consider this open-source code - If you make any changes let us all know....

* Note that this is NOT the same as a JavaScript library.