Creating a Notes/Domino plug-in with Eclipse

Follow along with this article to create a simple Notes/Domino plug-in with the Eclipse PDE. The plug-in accesses the Notes/Domino back-end Java classes using the Notes.jar file and displays birthdays/anniversaries from your Personal Address Book.

Share:

Ian Connor, Software Engineer, IBM Corporation

Ian Connor is a maintenance software engineer with IBM, working with the external support team to fix bugs from escalated support incidents. Ian also works on Lotus Team Workplace (QuickPlace) incidents and spent some time last year working directly for the Lotus Team Workplace team on upload control, programmability, Web services, and Notes integration. Ian enjoys raising chickens, skiing, travelling, and spending time with his wife. His personal goal of understanding emptiness has now taken second place to renovating his 1874 house in Concord, MA.



09 November 2004

In the last article, we told you how you could use the Eclipse integrated development environment (IDE) to develop Java agents and programs with Lotus Notes/Domino. Now, we want to turn our attention to how you can use Eclipse to access the Notes/Domino back-end Java classes. With this method, it is possible to interact with the Notes/Domino backend and to display information through the Eclipse Standard Widget Toolkit (SWT) model.

The IBM Workplace Client Technology rich client edition is also based on the Eclipse SWT framework, so any plug-ins that you develop to work within the native Eclipse environment will also work from the IBM Workplace Client Technology. As a result, any skills you gain in developing plug-ins with Lotus Notes/Domino puts you in a very good position when it comes time to use the IBM Workplace Client Technology with your existing databases.

This article is intended for experienced Notes/Domino application developers with knowledge of Java. Some experience with Eclipse is helpful, but not required.

Getting started

We suggest that you first read the earlier article on this subject, "Using Lotus Notes with Eclipse to manage and run your Java programs"; however, it is not necessary to follow it through to the conclusion. For the sake of brevity, we assume that you have already installed Eclipse 3. In older versions of Eclipse, you may have needed to also install the plug-in development environment (PDE) and the samples, but in recent versions of the software, this is not necessary. See the Eclipse.org Web site download page, if you do not already have Eclipse installed. In this article, we use Eclipse 3 because it has the ability to include a manifest file in the project, which simplifies the process and allows more advanced control of the classpath for a plug-in. We discuss the manifest file later in this article.

We will not go into too much detail on the many and wide variety of Standard Widget Toolkit (SWT) widgets (UI objects) or the extension point framework. There are a number of good books and tutorials published on the matter. We will just stick to the examples and show you the minimum amount of Notes/Domino Java you need to get started. From there, we will leave you to explore the rest and to develop some really cool and useful plug-ins. Focusing on a simple sample plug-in and wizard-generated code keeps the Notes/Domino aspect obvious, so you can take it from there.

Start with the plug-in wizard

Eclipse has a lot of wizards to simplify tasks, and it is possible to build your own wizards. Going through a wizard gives you a good understanding of how Eclipse is designed to work, and it is an easy way to get started. For our purposes, we create a new plug-in based on a view example. Eclipse offers a few different types of design elements much like Lotus Notes. There are views for data similar to Notes views. There are also other elements, such as forms that are like Notes forms. For more information about Eclipse design elements, you may want to refer to the book, The Java Developer's Guide to Eclipse by Sherry Shavor, et al.

In Eclipse, choose File - New - Project, then select the Plug-in Project option. (If you do not see this option, then the PDE from Eclipse is not installed.) For our plug-in project, we give it the name NotesView, although you can use any name you prefer.

Figure 1. New Plug-in Project dialog box
New Plug-in Project dialog box

Eclipse comes with a number of examples referred to as templates, and it is a good idea to see some of the examples and how they all fit together. In this article, we want to create a view, so we select the "Create a plug-in using one of the templates" option, then select the "Plug-in with a view" template, which serves as the basis of our plug-in.

We suggest that you change the view name and category so that the view will be easy to find when you run the sample later. Click Finish when done to generate the plug-in project and code.

Figure 2. New plug-in project with a sample view dialog box
New plug-in project with a sample view dialog box

Testing the view in debug mode

The wizard creates all the code you need to get started. After the wizard is finished, go through the class code it has generated for you. You will see it has created a fair amount to get you started compared to the amount of code you get from Domino Designer when you start an agent. In Notes development, we typically go to the help file and copy and paste the relevant code. We have found with Eclipse that we go through the wizard and then take it from there -- no copying and pasting of code is necessary.

Eclipse has a number of perspectives that you can switch to that help you focus on which activity you are currently performing. For instance, when you are debugging, you switch to the debug perspective (choose Window - Open Perspective - Debug) where you can set/remove break points, watch variables, and step through code. There is a perspective that is targeted towards plug-in development as well as general Java development.

By default, the plug-in perspective is launched. You are presented with an overview page. Click the "Launch a runtime workbench" link to start another Eclipse desktop that includes the new plug-in. Your plug-in should look like this if all went well.

Figure 3. Notes View plug-in
Notes View plug-in

If the workbench does not display properly, choose the Window - Show View - Other menu option. In the dialog box, look for the category that you specified when you created your project to find your view. In our case, it is Notes Category (see figure 2).


Linking to Lotus Notes/Domino

To link the project to Lotus Notes/Domino, you must have Lotus Notes installed. Unlike the previous article in which a specific version of the Notes client was required to enable the java_enable_debug setting in the Notes.ini file, you can use any version of Lotus Notes with this project. We need to link to the Notes.jar library as a required library for runtime. The Notes.jar file is the Java archive file that contains all the Notes/Domino back-end classes; it knows how to interact with Lotus Notes/Domino.

NOTE: You can also use the CORBA API Java archive file to access IIOP-enabled Domino servers. In this article, we focus only on using the local access API method.

Specify Notes.jar as a required runtime library

You need to add Notes.jar as a required library for runtime in your plug-in description. In the window titled Plug-in Development, select the Runtime tab. In the Runtime libraries section, click New. Enter Notes.jar when prompted and click OK to save. After you add the Notes.jar file, the plugin.xml file, which was generated when you created when you created the plug-in project and which describes your plug-in, lists both the Notes View JAR file and the Notes.jar file in the runtime. Click the plugin.xml tab to see the code.

<runtime>
      <library name="Notes_View.jar">
         <export name="*"/>
      </library>
      <library name="Notes.jar">
         <export name="*"/>
      </library>
</runtime>

Plug-in manifest file

In Eclipse 3, you have the ability to create a manifest file (Manifest.MF), which you need to run your plug-in. The manifest file is new in Eclipse 3. It provides extra information about the requirements for the plug-in and ensures that the classpath includes the Notes.jar file when we declare it. This is similar to setting the class path for your plug-in. Without it, you get errors that the plug-in cannot load. When we did this the first time, we had to dive into Eclipse code to find that the error came about when the first Notes class was referenced. This meant that the Notes.jar file was not being loaded by the Eclipse JVM and that the classes were not available. By declaring them in the manifest file, they are loaded correctly.

To create a manifest file (Manifest.MF), select the Runtime tab, then click the "Create a manifest file" link. The manifest file contains the following code:

Manifest-Version: 1.0
Bundle-Name: Notes_View Plug-in
Bundle-SymbolicName: Notes_View; singleton=true
Bundle-Version: 1.0.0
Bundle-ClassPath: Notes_View.jar,
 Notes.jar 
Bundle-Activator: Notes_View.Notes_ViewPlugin
Bundle-Localization: plugin
Require-Bundle: org.eclipse.ui,
 org.eclipse.core.runtime
Eclipse-AutoStart: true

In the manifest file, you need to include the full path to your Notes.jar file. This ensures that Eclipse loads the file properly and that you have access to the classes. Edit the bold line above to include the full Notes.jar path, for instance:

Bundle-ClassPath: NotesView.jar,
c:\lotus\notes\notes.jar

Next, you import the Notes.jar file as a library into the project. This allows you to build the files and to import the lotus.domino.* classes into the project. To import the JAR file, right-click the project in the Package Explorer pane and select Properties. In the Properties box, select Java Build Path, click the Libraries tab, and then click the Add External JARs button to add Notes.jar.

Figure 4. Properties for Notes View project
Properties for Notes View project

After you have included the Notes.jar file in your build path, you can add the import directive and create a simple view. In the Package Explorer pane, click the src directory to open it, then open Notes_View.views. Open NotesView.java and select ViewContentProvider. Add the following import directives to the code:

import java.util.Vector;
import lotus.domino.*;

To change what our view displays, modify the default code for the ViewContentProvider inner class. This class has a method, getElements. By removing the default response of three strings and replacing with the code below, the view can display Domino data. In this case, the data is the birthday and anniversary list in the local address book (names.nsf). Replace the default ViewContentProvider class code with the following:

Click to see code listing

class ViewContentProvider implements IStructuredContentProvider {
	public void inputChanged(Viewer v, Object oldInput, Object newInput) {
	}
	public void dispose() {
	}
	public Object[] getElements(Object parent) {

		Session s;
		String[] list = null;
		try {
			NotesThread.sinitThread();
			s = NotesFactory.createSession();
			//Get the local address book
			Database nab = s.getDatabase("",s.getAddressBooks().elementAt(0).toString());
			if (nab.isOpen() == false)
				nab.open();	
			//Get the Birthdays & Anniversaries view			
			View baview = nab.getView("BA");
			ViewEntryCollection eba = baview.getAllEntries();
			ViewEntry entry = eba.getFirstEntry();
				
			list = new String[eba.getCount()];
			int count = 0;
				
			while (entry != null) {
					
				Vector vals = entry.getColumnValues();
						 
				list[count]= vals.elementAt(1).toString() + " " + vals.elementAt(2).toString();
					
				entry = eba.getNextEntry();
				count++;
			}
			NotesThread.stermThread();

		} catch (NotesException e) {
			// TODO Auto-generated catch block
			e.printStackTrace();
		}

			
		return list;

	}
}

A message, such as “An error has occurred when creating this view,” may mean either that Eclipse cannot find the Notes.jar in the path and cannot create the Notes objects or that Eclipse cannot initialize Lotus Notes. Make sure your runtime library is set, and you have the full path in your manifest file. Then make sure to specify your Notes path, for instance, c:\lotus\notes, in your Path variable.

If all worked out well, you should see a list that reflects the birthdays listed in your local address book.

Figure 5. Notes View with local address book entries
Notes View with local address book entries

Conclusion

We have just covered the basics of getting Lotus Notes/Domino to interact with Eclipse 3. From here, you can build any plug-in that you can imagine that requires access to the Notes/Domino back-end Java classes. You can open databases, create documents, send mail, read from view, trigger agents, and anything else that you would expect from Lotus Notes/Domino. The difference is that you can now take full advantage of the SWT widgets and Eclipse framework. By building upon these skills, you can add value and features to the IBM Workplace Client Technology as well as the Eclipse integrated development environment.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus
ArticleID=31715
ArticleTitle=Creating a Notes/Domino plug-in with Eclipse
publish-date=11092004