Creating Domino agents with Netbeans

Introduction

Netbeans is an open source IDE, that is created and executed in a Java environment. It is a flexible and powerful IDE, and if you are tired of the lack of debugging capabilities for Java in the Lotus Domino Designer client, you may want to look at Netbeans.
In this short tutorial, I will try to explain how you can set up your environment, to allow you to create, debug and run your agents from Netbeans.

Before we start

To follow the tutorial, you will have to download the latest version of Netbeans, that was version 3.3 when this article was written. Please refer to the Netbeans documentation on how to install it.
I assume that you have installed Lotus Domino Designer R5 and Lotus Notes R5. If not, please buy it, or download an evaluation copy from notes.net.

You also need the Java Development Kit 1.1.8 to compile Java files in the format that Domino / Notes uses internally, AND the Java Development Kit 1.3.x to be able to start Netbeans. In Lotus Domino Rnext, the Java Virtual Machine will be upgraded to 1.3x.
There might be differences in platform specific things, like environment variables. This tutorial is aimed towards the MS Windows 2000 platform.

Configuring Agent Runner

The main subject when designing agents outside the Lotus Domino Designer, is the AgentRunner. The AgentRunner is a part of the Lotus Domino Java package, and allows external Java programs to communicate with Domino as if it were an agent. There is an AgentRunner database in the Notes data directory. This database is used to keep track of the AgentContexts we will create. Let´s head straight for the code!

• Make sure you have a local AgentRunner.nsf database. If it does not exist, create it!
• Create a new local database with the filename AgentRunnerTests.nsf.
• Create a “dummy agent” (which should be a “Run once”-agent) in this test database, with the following code:

import lotus.domino.*;

public class AgentRunnerTest extends DebugAgentBase {
public void NotesMain() {
}
}

AgentRunnerTest.java

• Name the agent “AgentRunner Test”.
• Save and run it.
• Look at the Java Debug console in the File\Tools menu. Note that it says “AgentContext dumped to file AgentRunner.nsf for agent: AgentRunner Test AgentRunnerTests.nsf Local”
• Open the AgentRunner.nsf database.
• Look in the view “AgentContext”, and you will see a document that has been created for you! Open it in edit mode. You will see something like this:
  
• Make sure that “Agents runs on” is “Run once” for now. In the future, set this field to a value matching the real agent.
• Save your changes

Configuring Netbeans

To let Netbeans know about the Java-classes that we are about to use, we must mount a JAR file as a Netbeans filesystem.

• In the FileSystem browser, right click on “FileSystem”, and select “Mount”, “Archive (JAR, zip)”.
• Browse to your Lotus Notes program directory, usually c:\Lotus\Notes\, and select the file “Notes.jar” and click OK.
• Netbeans adds the JAR file to the FileSystem browser, and also adds it to the internal CLASSPATH.

Configuring JAVA_HOME environment variable

We also have to set up Netbeans to use the external JDK when compiling. This is because you can not run Lotus Domino agents that has been compiled with a JDK that is newer than version 1.1.8, and Netbeans uses JDK 1.2 or higher for internal compiling. There are two ways to set up Netbeans to use an external compiler. The first is to set the environment variable JAVA_HOME to the JDK 1.1.8 directory (i.e. c:\jdk1.1.8) and specify which class that should be compiled with the external compiler. The second is to configure Netbeans to use a specific javac program when compiling the Java class. The first is the simplest, so I will explain that here. If you know how to set up an environment variable, please skip this section.

• Open the “System” item in the “Control Panel”.
• Go to the “Advanced” tab.
• Click “Environment Variables…”
• In the “System variables” section, find the “JAVA_HOME” variable. If it does not exist, click “New…”.
• Make sure the “JAVA_HOME” variable value is set to the path where your JDK 1.1.8 is installed, i.e. c:\jdk1.1.8 (note that there should not be any backward slash at the end).
• Click “OK” in all dialog boxes.
• A reboot might be necessary in some circumstances…

One thing remains, and that is to tell Netbeans what source files to compile with the external compiler. I will come to this in a moment…

Our first agent

When all is configured, let us create an agent OUTSIDE of the Lotus Domino Designer!

• Create a new Java main class in Netbeans using the wizard, but press finish right after naming the class to “DominoAgentTest”
• Import the lotus.domino package and make the agent extend DebugAgentBase
• To run an agent from outside of Domino, we must make a call to the static main method in lotus.domino.AgentRunner, something like this:


public static void main(String args[]) {
try {
AgentRunner.main(new String[] {
"AgentRunner Test", // Agent name
"AgentRunnerTests.nsf", // Database
"local"}); // Server
} catch(Exception e) {
e.printStackTrace();
}
}


• Write the NotesMain method as you would in a “normal”, agent that you create in the Lotus Domino Designer, for example:


public void NotesMain() {
try {
Session session = getSession();
AgentContext agentContext = session.getAgentContext();
Database currentDb = agentContext.getCurrentDatabase();
System.out.println("Current database: " +
currentDb.getTitle());
} catch(Exception e) {
e.printStackTrace();
}
}

Full source of the first agent, with some extra code: DominoAgentTest.java

• Save the file.
• Show the property box of your class, by right clicking on the file in the FileSystem, and selecting “Properties”.
• Go to the “Execution” tab
• At the “Compiler” option, select “External Compilation”. By default, this option uses the JAVA_HOME environment variable explained above.
• Compile the file by choosing “Compile” in the “Build” menu.
• If the compilation went alright, you can now try to run it! Choose “Execute” in the “Build” menu.
• The “Output window” should now show some printed text from your agent, that has retrieved information from the Notes environment!

Useful links

• “Getting yourself ready to create servlets”, an article at codestore.net, explaining how to create servlets for Domino in Netbeans.
• Lotus Domino Toolkit for Java/CORBA, a must if you want to get all information about Java programming in Lotus Domino.
• Apache Jakarta, an open source community for Java developers.
• Lotus Developers Network, an informational site of developing in Lotus products.
• Lotus Developer Domain, from the creators of Notes / Domino. Many useful sources, like discussions, documentation, tutorials, articles etc.
• Sun Java Developer Connection, all documentation, discussions, tutorials etc. of the Java language.