Extending the IBM Lotus Notes V8 mail with Eclipse

This article focuses on how to extend the IBM Lotus Notes V8 client by writing Java code with the Eclipse PDE (programming development environment). Specifically, we show how to use Lotus Notes at home for personal email.

We focus on using core Eclipse technology, including extensions, activity sets, plug-ins, features, and update sites. You can use these technologies to deploy functionality to any Eclipse-based product. Here we focus on the Lotus Notes client and extend mail to include a new Mail Rule Runner that allows users to run their rules manually on the client.

NOTE: We use Lotus Notes mail as the primary client for POP3 and SMTP mail at home, and the one functionality missing is mail rules. As you know, the mail rules in Lotus Notes run on the SMTP server, and you do not have mail sorting without the Domino SMTP server. Although this tool is not perfect, it does show how to use Eclipse to extend Lotus Notes and to use the Lotus Notes Java backend classes for accessing and manipulating Lotus Notes data.

You start by using Eclipse to create your plug-in. The code and sample in the Downloads section were created with basic Eclipse version 3.2.1.

We want to create a new menu option that shows in the Lotus Notes mail views as an action (icon) that runs the mail rules locally. When the user clicks the Run Mail Rules button, a dialog box appears with all enabled mail rules selected, and then a combo box appears in which you can select the view or folder to run against. Figure 1 shows the Run Mail Rules dialog box. The blurred areas mask any personal information.

Figure 1. Run Mail Rules dialog box
Run Mail Rules dialog box
Run Mail Rules dialog box

The dialog box is a basic Eclipse SWT-based dialog box that uses the SWT GridLayout to define how the different UI elements are positioned on the screen.

After you click the Run button, the normal Eclipse progress dialog box is shown; see figure 2. You can run this dialog box in the background by clicking the Run in Background button. After the operation is finished, press F9 to refresh the view if the view you ran the rules against was open. You have an obvious opportunity to extend this tool to refresh the current screen when the mail rule operation is complete.

Figure 2. Run Mail Rules Job progress
Run Mail Rules Job progress
Run Mail Rules Job progress

Creating your plug-in

Like all plug-ins, creating them using the Eclipse plug-in wizard is the easy part. Although Eclipse does a lot of the work for you, it is like anything else in software development: It is just the start. For this sample, we used Eclipse 3.2.2, and we specified the installed Lotus Notes V8 Beta client as the target platform. We suggest that you always install Lotus Notes in the same place on all your machines – c:\notes. Set the target platform in Eclipse by choosing Window - Preferences. You specify the target platform by choosing Plug-in Development -Target Platform. Figure 3 shows Lotus Notes selected as the target platform. The key is to select the f\ramework\eclipse directory. This is the root directory for the Eclipse runtime. In this case, the directory is c:\notes\framework\eclipse.

Figure 3. Specifying the target platform
Specifying the target platform
Specifying the target platform

Now that you have selected the Lotus Notes runtime as the platform, you can create the new plug-in, set the dependencies, and then write code against them. By making Lotus Notes the target platform, you have all Eclipse, Lotus Expeditor, and Lotus Notes APIs and extensions available. In the Package Explorer, right-click and choose New - Project. Here you select an Eclipse plug-in project. Figure 4 shows the screen you should see, for the New Project wizard.

Figure 4. New Project wizard
New Project wizard
New Project wizard

Click Next, and then name the project This is the primary place for any mail utilities you may later decide to create. For the remainder of the wizard you can select the default values presented to you. When you get to the screen that asks you to base this plug-in on an existing template, deselect the template option and do not use any of them.

Now expand the newly created project in the Package Explorer and double-click MANIFEST.MF under the META-INF folder.

Navigate to the Dependencies tab, shown in figure 5, and add the bundle to the dependencies. This gives you access to all Lotus Domino Java backend classes.

Figure 5. Dependencies tab
Dependencies tab
Dependencies tab

In general, use the Imported Packages method to define the dependencies. Using imports means the OSGI framework resolves package imports and the requested classes, rather than your having to specify a particular bundle as we do here. If the one specified bundle were renamed or removed, the dependency would be broken, and the classes would not resolve at runtime. Alternatively, if you import all the packages you intend to use, then they could be exposed by any plug-in. After you code your plug-in, you can remove this dependency and import only the packages you need on the same screen. Now that you have the dependencies specified, you can begin coding.

Extending the CSI Views

You extend the CSI Views by adding a new action to the views toolbar. In the Lotus Notes V8 Beta, the action shows a button with the text Run Mail Rule, but in the shipping product, the correct icon will show. You can steal a screenshot of the Mail Rules icon from the mail outline and use that symbol. The keystroke Alt + PrtSc works well for this. Save the icon to an icons folder and name it mailrules.gif. In the end, the action looks like figure 6.

Figure 6. Mail Rules icon
Mail Rules icon

To make this icon to appear, define an extension to the Eclipse action sets. You can use the wizards and add the action sets, or you can simply copy the code in listing 1 into your plugin.xml. The plugin.xml may not be created at this point so you may want to go through the wizard to create it (or you can use the plugin.xml from the ZIP file in the Downloadable resources section). The first extension is the newly created action set, which defines the menu, toolbar path, tool tip, icon, and the actions to call when it is selected. The next extension ties the new action set with the CSIViews toolbar. The CSI Views are not necessarily public APIs, but because they are exposed as Eclipse extensions they are available to write against. This is the actionSetPartAssociations extension. You tie them together by specifying the action set ID ( with the part ID in which you want to show: This tells the Eclipse framework that you want the action set to be associated with the CSIViewPart and to display the contribution with that view part.

Listing 1. CSI Extension
        label="Mail Tools">
           label="Run Mail Rules">
           label="&Run Mail Rules"
           tooltip="Run Mail Rules"/>
<extension point="org.eclipse.ui.actionSetPartAssociations">
        <part id="" />      

Writing to the Java backend classes

Now that you have an entry point into your logic with the new action class you created, you can begin to develop the code that does the work. The RunMailRules class contains a run() method; this is where your code gets called when the button is clicked. Because we access backend Lotus Notes objects like databases, documents, and views, and because you call on the UI thread, you spawn a new thread in this method. As with all access to Lotus Domino objects, you need to initialize the thread with a call to NotesThread.sinitThread(). In your final block, you need to call NotesThread.stermThread().

The code starts by getting the mail database and a list of all folders and views in that database. You use this list to populate the drop-down combo box for the view against which your mail rules execute. Getting the session is the most important part of this exercise; the code in listing 2 shows how to get the session, the database handle, and the list of views and folders.

Listing 2. Getting the Lotus Notes session
Session session = null;
	session = NotesFactory.createSessionWithFullAccess();
	DbDirectory dbdir = session.getDbDirectory(null);
	Database mail = dbdir.openMailDatabase();
	Vector views = mail.getViews();
	Enumeration vEnum = views.elements();

	View rules = mail.getView("(Rules)");

Because we had to reverse-engineer the Mail Rule documents by looking at the template design and the data stored, we thought it would be nice to have a class that consumes the document and creates the various elements of the rule as Java objects. This class abstracts the details of the field implementation and makes it more readable in other parts of the plug-in. The MailRule object contains lists for the actions, conditions, and exceptions contained in the Mail Rule document. Because all of these (actions, conditions, and exceptions) come from the Mail Rule document, the objects are initialized with a Document object.

The code is structured in a way to easily be extended. The code was refactored several times with extensibility in mind. Adding new actions, exceptions, or Boolean logic is trivial. Figure 7 is a screenshot of the entire project.

Figure 7. Mail Utility project
Mail Utility Project

The main utils package contains the plug-in Activator, the main Eclipse Job (shown in the standard Eclipse progress dialog box when the rules are processed), the Mail Rule operation (which contains most of the rule logic), and an exception class that stops processing the rules under certain conditions.

We aim to keep anything related to the model under the models package and any dialog-related classes under the dialogs package. Many Eclipse samples show the content and label provider classes as subclasses in the dialogs class, but we prefer them to be extracted into their own files.

Deploying your plug-in to the Lotus Notes V8 client

The next step is to package the newly created plug-in with a feature and an update site to deploy it to the client. Eclipse packages plug-ins (or bundles) into Eclipse features. Thank the Eclipse contributors for some very easy-to-use wizards to get this done. First, create a feature that references the new plug-in. Create a new project as we did before, except this time select Feature Project as shown in figure 8.

Figure 8. New Feature wizard
New Feature Wizard
New Feature Wizard

For the sake of simplicity, name your new feature the same as the plug-in but include the word feature at the end, for example, In the next window select your plug-in from the list, and you are all set. If you created several plug-ins, you select the plug-ins to be included with this feature. You can always add more later.

Now you need an Eclipse update site so that a client can install the new feature. From the same New Project wizard dialog box shown in figure 8, select Update Site Project. After the site is created, add your feature to the site. The site.xml is basic and is shown in listing 3.

Listing 3. Update site.xml
<?xml version="1.0" encoding="UTF-8"?>
   <feature url="features/" 
   id="" version="1.0.0"/>

Before you click the Build All button, it is a good idea to clean all projects and have the binaries rebuilt. Choose Project - Clean from the File menu. After you click the Build All button, your site is ready to be deployed. The build operation for the site generates a features and plug-ins directory where the compiled features and plugins reside. You have the plug-in, you have the feature, and you have the Eclipse update site. Now the only thing to do is to enable the installation of features in the Lotus Notes V8 user interface.

Running your new contribution

As of the Lotus Notes V8 Beta, the client did not have the Eclipse menu option to install new features. As long as your administrator has not disabled this preference, you can turn this option on by editing the plugin_customization.ini in the <notes directory>/framework/rcp directory.

Add this line to the <notes directory>/framework/rcp/plugin_customization.ini file:

After you restart the Notes client, you see a new menu option: File - Application - Install. This is the standard Eclipse interface for installing features. In the first window of the wizard, select the second option ("Search for new features to install"). Click Next, and you see a window where you specify the location of the Eclipse update site you just created. Click the Add Folder Location button, and then navigate to the directory that contains the site.xml file you created earlier. Your window should look similar to figure 9.

Figure 9. Installing the Feature
Installing the Feature
Installing the Feature

Click Finish and accept the remaining prompts. You are asked if you want to install your plug-in even though it is not signed. This occurs because Lotus Notes has a signature verification that it checks before installing foreign plug-ins. Because you did not sign your plug-ins, they do not have signatures. Once the new features are installed, you are asked to restart Lotus Notes. After you restart, the new button appears throughout all your mail views.

Alternatively, we have provided an NSF-based update site for Lotus Notes V8 users. You can simply copy the NSF file shown in the Downloadable resources section of this article to your Lotus Notes data directory. When the database opens, you see the Mail Tools features to be installed in the standard Eclipse progress dialog box. After the installation is complete, you restart Lotus Notes, and the action is available.


We demonstrated how you can use Eclipse to extend the Lotus Notes client. Using basic Eclipse SWT user interface widgets, you created a completely cross-platform solution to the problem. Using this methodology means your contributions are separate from the Lotus Notes NSF and NTF; this means that your code is not in jeopardy when you upgrade to Lotus Notes V8. Last, we demonstrated how you can leverage existing Domino Java API skills in the new plug-in model. By using the Java backend APIs you have an easy connection to the Lotus Notes/Domino architecture. With the flexibility of the Eclipse framework and the proven grounds of Lotus Notes applications, this article shows how it can easily be extended with custom code and plug-ins.

Downloadable resources

Related topics

ArticleTitle=Extending the IBM Lotus Notes V8 mail with Eclipse