Using Lotus Notes with Eclipse to manage and run your Java programs

Take advantage of the Eclipse IDE to develop Java agents for Lotus Notes/Domino. Download and install Eclipse and then see how easy it is to create a project, debug Java, refactor your agents with Eclipse, and import your agent into Domino Designer.


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.

20 September 2004

Java and Lotus Notes/Domino are a natural development combination. Together they allow Notes/Domino developers to take full advantage of all the existing Java code and packages available today within their usual development environment: Domino Designer.

Eclipse is one of the best integrated development environments around and offers wonderfully rich features including context-sensitive actions, views, a rich debugger, and refactoring. Refactoring is the ability to rename, move, push-up, and extract Java code to new methods to make light work of cleaning up your initial coding attempt and to get it ready to be neat, easy to read, and something you would want to show another developer. For many, it is the single best feature of Eclipse.

With the ability to debug Java agents in Lotus Notes/Domino 7, we now have the opportunity to leverage both Lotus Notes/Domino and Eclipse to create a well designed and debuggable Java agent project for your Notes/Domino applications.

Any development for Lotus Workplace requires a solid understanding of how Eclipse works. Lotus Notes/Domino 7 offers an excellent reason to start learning Eclipse today for Notes/Domino work, building skills that you can also apply to Lotus Workplace projects in the future.

This article covers how to install Eclipse, how to create a project for Lotus Notes/Domino, and how to import this project into a Domino Java agent that can then be debugged. This article also shares some tips and traps of debugging these agents.

Installing Eclipse

WebSphere Studio Application Developer is based on Eclipse, so if you have that product installed, you can follow along with this article using WebSphere Studio Application Developer. If you do not have Eclipse or WebSphere Studio Application Developer installed, you will need to obtain them first. Eclipse is freely available for download from the Eclipse foundation. Trial versions of WebSphere Studio Application Developer are also available.

Download Eclipse or WebSphere Studio Application Developer. Eclipse is easy to install; there are installation instructions on the Eclipse Web site. After you download the ZIP file for Windows, run the eclipse.exe file. WebSphere Studio Application Developer is more sophisticated. Refer to the documentation for installation instructions.

Note: The steps that follow describe Eclipse 3.0. If you install another version of Eclipse, you may find that the user interface--and therefore, the steps--differ from those in this article.

Eclipse and Rational ClearCase for source code control

If you want to integrate Eclipse with the Rational ClearCase source control system, you can also download and install the IBM Rational ClearCase SCM adapters for Eclipse 2.11. Otherwise, the default source control system is CVS.

Creating a new Java project in Eclipse

After you install Eclipse and any plug-ins, you can now create a project to start your Notes/Domino work. You must store all Java code within a project. You can have multiple projects within your workspace. It is also possible to have multiple workspaces on your computer, and you can use the –data switch with eclipse.exe to point to a different workspace.

To create a new Java project, open Eclipse and choose File - New - Project. In the New Project dialog box, choose Java Project, then click Next.

Figure 1. New Project dialog box
New Project dialog box

Enter a title for your project, then click Finish. After you create the project, change the path in the project properties to point to your Notes.jar file. Right-click the project in the Package Explorer tab, and select Properties. In the Properties dialog box, select Java Build Path and then select the Libraries tab. Click the Add External JARs button and navigate to the Notes.jar file to add it to the class path.

Figure 2. Properties dialog box
Properties dialog box

After adding the JAR file, you can use the classes and interfaces defined by the Notes Java API in your project. Documentation for the Notes Java API is available with the Domino Designer on-line help.

Next, you need to download the Sun 1.3.1 JRE. Alternatively, if you have a Domino server installed on your machine, you can use that server’s JVM. The Notes client and Domino server version should match to ensure that you are building with the same JVM that your agents and program will run when invoked from the server task or agent manager task.

Current versions of Lotus Notes/Domino use Java 1.3.1, so you must have this installed to build your project with the right version. (Lotus Notes/Domino 7 uses JDK 1.4.) Although many Java agents and programs will compile without a problem, you may run into some issues building with one JDK version and running on another. If you installed Eclipse 3.0, it is based on Java 1.4.2, so remove the JDK System Library and create a new one that points to your JDK 1.3.1 install. To do this, in the Properties dialog box on the Libraries tab select JRE System Library and click Remove.

To add a new library, click the Add Library button. In the Add Library dialog box, select JRE System Library, and then click Next. Select the Alternative JRE option (if not already selected). Then click the Installed JREs button. Click Add, and complete the Add JRE dialog box to add JDK 1.3.1.

Figure 3. Add JRE dialog box
Add JRE dialog box

Save the changes to your project.

Creating your first Java agent

Domino Designer automatically populates your first Java agent for you to get you started. However, Eclipse will not, so we need to create a new class that implements the correct AgentBase interface and obtains the Domino session and agentcontext objects. Use the code from Domino Designer as a guide.

Figure 4. Domino Designer Java agent
Domino Designer Java agent

Copy the skeleton Java code from Domino Designer directly into a new class in your Eclipse project. We recommend that you create a new package in which to store your agents. It will help you organize your project and conform to general Java design principles. To create a new package, choose File - New - Package.

Figure 5. New Java Package dialog box
New Java Package dialog box

We created a package called because we work at IBM, and this is our Notes Java project. This is where we will store our agents. Other common packages you may see are com.sun.*, org.apache.*, and java.lang.* for core Java language functions. There is a whole science to the organization of packages that is well beyond the scope of this article, but it is important that you don’t put all your agents and code in the default package because it is messy and unprofessional.

Now that you have a new package, you can create a new Java class. To create a new Java class in Eclipse, choose File – New – Class. Eclipse is highly efficient, so if you have your package already selected, it will populate the package name for you. From there, you can add the name and superclass. For a Notes agent, the superclass must always be lotus.domino.AgentBase. This is automatically done for you in Domino Designer, but you have to do this manually in Eclipse.

Figure 6. New Java Class dialog box
New Java Class dialog box

After you create the class, you can enter the rest of the agent code so that it looks like the agent from the Domino Designer example.

Figure 7. JavaAgent in Eclipse
JavaAgent in Eclipse

When you build this agent, it will create a JavaAgent.class file in the package directory. Now that you have the class file, you can import that into the agent in Domino Designer and manage the code from within Eclipse. In the Domino Designer on-line help, see the "Import Java" topic for more information. After importing, you can run the Java code that you have written when this agent is called. Now you are ready to debug this code using the Eclipse debugger.

Debugging the Java code

Eclipse wraps the Java debugger to allow you to step through, to alter variables, to watch items, and to add break points in your Java code. The first step is to load the JVM in Lotus Domino in debug mode. This forces the JVM to stop and wait for a debugger to be attached before proceeding. This feature is in Lotus Notes/Domino 6 and later and can be enabled by adding the Notes.ini variable JavaEnableDebug=1 and restarting the server.

The next stage is to run the agent on the server and wait for the server to freeze the agent’s execution. When it freezes, the JVM is waiting for a debugger to be attached to the TCP/IP port 9788.

Open Eclipse and your project. Then choose Run - Debug to open the Debug dialog box. Select Remote Java Application, then click New to create a new debug session. On the Connect tab, specify the host name of your server or localhost if it is on the same machine that you are debugging.

Figure 8. Debug dialog box
Debug dialog box

For advanced users, you can alter the port number and debug settings like this:


Suspend=n does not freeze the server waiting for the debug connection, so you may miss the start of the agent. This debug setting lets you pass extra parameters to the JVM debugger on the server. If you have your own favorite settings, use them here.

It is a good idea to already have your break point set in the agent code. When you attach to the server with Eclipse in debug mode, it should automatically break and then let you inspect the variables, set other breakpoints, and perform all the other debugging tasks that you need to use.

Other Eclipse pointers

Now that you have your project in Eclipse, it offers many enhanced development and organizational tasks that are not available for large Java projects within Domino Designer. Domino Designer is good for smaller Java tasks, such as getting or setting a few values or simple reports. However, once you start separating your code into different packages, defining interfaces, and delegating work to others, your projects can become more complex to manage.

Eclipse has built-in tools for team work including CVS source control integration. The Rational ClearCase source control plug-in allows you to attach to Eclipse projects stored in ClearCase. It provides automatic or prompted check-in and check-out of code, neat decorators to easily identify which objects are in source control, and their status.

Another really useful feature in Eclipse is the ability to refactor your projects. One example of this is that you can select a portion of code and move it to its own method. If you have a very large method and want to break it down into smaller steps, this can be automated, and Eclipse can help you. The following code snippet is a refactoring example:

Initial function

	public void NotesMain() {

		try {
			Session session = getSession();
			AgentContext agentContext = session.getAgentContext();

			Database db;
			// I am running this, use the server - or it can assume it is local
			if (session.getUserName().equals("CN=Ian Connor/OU=Westford/O=IBM") == true)
				db = session.getDatabase("support/iris","support/retain.nsf");
				db = session.getDatabase("","support/retain.nsf");

		} catch(Exception e) {

You can select the portion of code to move to its own function and choose Refactor - Extract Method. This determines which parameters you need to pass in and what the return should be. All you need to do is select a method name. Then you can preview the changes beforehand to see what it will do. This will help better organize your code and make it easier to maintain for anyone else trying to figure it out. As all developers are well aware, a neat well-organized code base with smaller functions is much easier to work with than very long 1000 line functions that seem to go on and on.

public void NotesMain() {

		try {
			Session session = getSession();
			AgentContext agentContext = session.getAgentContext();

			Database db;
			db = getRetainDatabase(session);

		} catch(Exception e) {

	private Database getRetainDatabase(Session session) throws NotesException {
		Database db;
		// I am running this, use the server - or it can assume it is local
		if (session.getUserName().equals("CN=Ian Connor/OU=Westford/O=IBM") == true)
			db = session.getDatabase("support/iris","support/retain.nsf");
			db = session.getDatabase("","support/retain.nsf");
		return db;

Refactoring is an essential part of any development effort. The first cut of code is never something that we want to share right away. This is especially true when you are working with a new API or way of working. You spend a lot of time writing small portions of code to test how it works and then when you get it running, you like to step back and properly organize the code so that it makes sense to someone who has to read it.


Eclipse is a very functional platform that Notes developers can use in their current and future projects. It helps developers today by better organizing their projects, sharing code with others on their team, and taking advantage of Java design techniques such as interfaces and code separation. As Lotus Workplace and Lotus Notes/Domino continue to grow more integrated, Java and Eclipse will play an important role. Notes developers can build on their collaboration and groupware skills today while preparing for the challenges of tomorrow.

A new product or way of working has to have some critical features or benefits that assure its adoption. For a Notes developer who has to deliver well-written applications that provide solid Java code, Eclipse delivers debugging, refactoring, and source control. All of these are critical features in any serious development effort and all of these will assure that the time you invest in learning how to use Eclipse for Notes development will be well worth the effort involved.





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

ArticleTitle=Using Lotus Notes with Eclipse to manage and run your Java programs