Using Domino AgentRunner

Domino AgentRunner can be used to build, run, and debug Domino agents in VisualAge for Java. AgentRunner uses a set of debug classes that access Notes context information so that you can run an agent in the IDE.

To use AgentRunner, follow these steps:

  1. Set up your Domino environment to access AgentRunner classes.
  2. Add Domino classes to your VisualAge for Java environment.
  3. Create an agent in the IDE with a class that extends DebugAgentBase and export the class file to the file system.
  4. Import and run the agent in Domino to generate an AgentContext document in the file AgentRunner.nsf. The AgentContext document is what allows you to build, debug and run without having to switch between the IDE and Domino.
  5. Debug your agent in the IDE using VisualAge for Java's debugger.
  6. Create the production agent.

Setting up AgentRunner in Domino

To set up your Domino 5.0 environment to support AgentRunner, set the PATH environment variable to point to the Domino directory.

To set up your Domino 4.6 environment to support 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, you can cut and paste the following statement to the end of your notes.ini file:
    JavaUserClasses=X:\IBMVJava\eab\runtime30\domino\ar\IVJAgentRunner.jar
    

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

  2. Set the PATH environment variable to point to your Domino directory.
  3. Copy the AgentRunner.nsf file from the X:\IBMVJava\eab\runtime30\domino\ar directory to your Domino data directory.

Your Domino environment is now set up to support AgentRunner. Next, set up your VisualAge for Java environment.

Adding Domino Java classes to the Workbench

To set up your VisualAge for Java IDE to use AgentRunner, add the Domino Java class library from the repository to your workspace:

  1. From the Workbench, select File and then Quick Start.
  2. From the list of categories on the left, select Features.
  3. From the list of tasks on the right, select Add Feature. Click OK.
  4. In the Selection Required window, select the version of Java library that corresponds to the level of Domino that you have installed. Click OK.

You now should see the Domino Java class library on the All Projects view of the Workbench window. This project contains a package of Java classes (called lotus.notes) for the appropriate version of Notes Object Interface/Domino, plus additional debug classes that support AgentRunner.

You can now use these classes when running or debugging an agent in the IDE. Next, import from Domino or create an agent in VisualAge for Java.

Importing or creating an agent in VisualAge for Java

In the Workbench, create a project called Domino Agents.

Importing an agent from Domino

  1. Use the Import SmartGuide to import your agent (a .java file) from Domino 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.

  2. In the newly imported Java source code, change the class declaration from
    public class ... extends AgentBase
    

    to

    public class ... extends DebugAgentBase
    
  3. Save your code.

Creating a new agent

  1. From the Workbench, create a class in the Domino Agents project, using DebugAgentBase as the superclass.
  2. Left-click on the class name. In the Source pane of the Workbench, write the code for your agent.

    For Domino 5.0, see Domino 5 Designer Help. For Domino 4.6, see the Java Programmer's Guide for Lotus Notes.

  3. When you have finished writing your agent, use the Export SmartGuide to export it as a .class file to the file system.

Next, generate your AgentContext document in a Notes database.

Generating an AgentContext document

For Domino 5.0, perform these steps:

  1. Open Lotus Domino.
  2. Create your agent in the appropriate database.
  3. Fill in the details for your agent.
  4. From the Run list, select Imported Java.
  5. Click Import class files.
  6. Select the .class file that you exported from VisualAge for Java and click OK.
  7. Save and run the agent.

For Domino 4.6, perform these steps:

  1. Open Lotus Domino.
  2. Create your agent in the appropriate database.
  3. Fill in the details for your agent.
  4. For What should this agent run, select the Java radio button.
  5. Click Import class files.
  6. Select the .class file that you exported from VisualAge for Java and click OK.
  7. Save and run the agent.

The AgentContext document is automatically generated in AgentRunner.nsf when you run your agent from a class that extends DebugAgentBase. A call to getSession() will, after generating an AgentContext document, return null.

You are now ready to debug your agent.

Debugging 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. Right-click on the agent name.
  3. Select Tools and then Domino AgentRunner.

You have two options:

Creating the production agent

When development of the agent is complete, you can move your agent to Notes.

  1. In the IDE, change the agent's superclass to AgentBase.
  2. Export the agent's .class file to the file system.
  3. Import the .class file into Notes.

You can now run your agent in Notes.