Creating an Email 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
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 (?)
* Note that this is NOT the same as a JavaScript library.
Pls explain to novice...
Jake, I am just beginning to wrestle with the complexities of Java in Domino, so please bear with me if I ask obvious questions.
I too am very interested in modular code.
I was trying to create the email library script, but I don't know why I am unsuccessful ...
"...Alternatively, if you use R5, you can paste the code in to Java Script-Library, called Email*. ..."
How do I do this ?
<rant> Thanks again for the great advice on an impressive site - it really is difficult to find Java for Domino references! I have even contemplated taking a Lotus "Java for Domino" course, or more probably a View seminar ... </rant>
Reply
Re: Pls explain to novice...
Patrick, glad you like it. To create the script library. Under Resources there is Script Libraries. Create a new one of these and select Java as the code type. Simple as that...
Jake
Reply
Show the rest of this thread