The Domino AgentRunner

Lotus Domino is an application and messaging server with an integrated set of services that enable you
to create interactive business solutions for the Internet and corporate intranets. The Domino AgentRunner is a tool which can be used to build, run, and debug Domino agents in VisualAge for Java. The AgentRunner uses a set of debug classes that access Notes context information while you are running an agent in the IDE, on a Lotus Notes client.

To use the AgentRunner, you must follow these steps:

  1. Set up your Notes and VisualAge for Java environments.
  2. Create an agent in the IDE with a class that extends DebugAgentBase.
  3. Export the class file into the file system.
  4. Run the agent inside Notes to generate an AgentContext document in the AgentRunner.nsf. The AgentContext document is what allows you to build, debug and run without having to switch between the IDE and Notes.
  5. Debug your agent in the IDE using VisualAge for Java's debugger.
  6. Create the Production agent.

Each of these steps is described in more detail below.

Set up the AgentRunner

First you have to set up your Notes environment to access the AgentRunner classes, and then you have to set up the VisualAge for Java environment to access Domino Java classes and Notes AgentContext documents.

To set up your Notes 4.6 environment to support the AgentRunner, follow these steps:

  1. Add the IVJAgentRunner.jar file to the JavaUserClasses statement in your notes.ini file. If you do not have a JavaUserClasses statement in your notes.ini file already, you can cut and paste the following statement to the end of your notes.ini file so that your JavaUserClasses points to the IVJAgentRunner.jar file.

    JavaUserClasses=X:\VAJava\ide\runtime\IVJAgentRunner.jar

    where X:\VAJava is the path where VisualAge for Java is installed. After you have edited the notes.ini file, you must shut down Notes and restart it so that your changes take effect.

  2. Set your path to point to your Notes directory by entering

    set path=%path%X:/path/Notes

    on a command line. X is the drive on which Notes is installed. path is the path to your Notes directory. Your Notes directory will be temporarily added to your path. When you close your command window, this setting will be erased. Do not close the command window in which you set your path until you have finished using the AgentRunner. (If you want to permanently add this pointer, set the path to Notes in your computer's systems settings.)

  3. Copy the AgentRunner.nsf file from X:\VAjava\ide\runtime (where X:\VAjava is the path where VisualAge for Java is installed) to your notes\data directory.

Your Notes environment is now set up to support the AgentRunner. Next, you have to set up your VisualAge for Java Environment.

Add the Domino Java classes to the Workbench

To set up your VisualAge for Java IDE to use the AgentRunner, add the Domino Java class library from the repository to your workspace. (From the Workbench window's Selected menu, select Add > Project. The Add Project SmartGuide will open.)

You now should see the Domino Java class library on the Projects page of the Workbench window. This project contains a package called lotus.notes, with all the Java classes for Notes Object Interface/Domino 4.6 and additional Debug classes that support the AgentRunner tool. You can now use these classes when running or debugging an agent in the IDE.

Import an agent from Notes

In the Workbench, create a project called Domino Agents.

Next, use the Import SmartGuide to import your agent from Notes into this new project. The imported Java code is compiled and any unresolved problems are added to the All Problems page. Your .java file appears as in a package in your Domino Agents project in the Workbench.

Create a new agent in VisualAge for Java:

Use the Create Class SmartGuide to create a class in your new package, in your Domino Agents project. Click on the class with mouse button 1. In the Source pane of the Workbench, write the code for your agent. (For instructions, see the Java Programmer's Guide for Lotus Notes).

Export the class file

When you have finished writing your agent, use the Export SmartGuide to save it and export the .class file from the IDE to the file system, so it can be read by Notes.

You can now generate your AgentContext document in a Notes Database.

Run the agent in Notes to generate an AgentContext document

Create a Java agent in a Notes database. See the Notes help for more information on creating an agent.

  1. Open Lotus Notes 4.6.
  2. Create your agent in the appropriate database.
  3. Fill in the details for your agent. Select the Java radio button for What should this agent run
  4. Click Import class files and select the file that you exported from VisualAge for Java.
  5. Run the agent.

The AgentContext document is automatically generated in the AgentRunner.nsf when you run your agent in Notes from an agent class that extends DebugAgentBase. A call to getSession() will, after generating an AgentContext document, return null. So any use of the returned session will result in a thrown exception. But, since the purpose of running the agent is only to generate the context document (and not to run any of the agent code), you can ignore the exception.

Debug your agent

When you have generated an AgentContext document, you are ready to debug it in VisualAge for Java.

  1. Set one or more breakpoints in the NotesMain() method of your agent.
  2. Select your agent with mouse button 2.
  3. Select Tools - Domino AgentRunner.

You have two options:

or

Create the production agent

When your development of the agent is complete, you can move your agent to Notes. First, in the IDE, you have to change your agent's base class to extend lotus.notes.AgentBase instead of DebugAgentBase.

Export the .class file to the file system. and reimport it in your agent in Notes.

You can now run your agent in Notes.