Java in Notes/Domino Explained: Test agents in Eclipse by extending AgentBase (part 5)

By now (I assume you read part 1, part 2, part 3 and part 4) we have a working AgentBase extension called EclipseAgentBase. In this part I’ll show how to use the new and improved AgentBase class to easily write, test and debug Notes/Domino Java agents in Eclipse.

Please bear in mind that setting up the runtime environment for each agent below can seem like a chore and unnecessarily complex and cumbersome. It does however have the advantage that you can test the agent code and not worry about whether the database is a known state etc. It is my experience that most times when agents fail in test it is because some required document or profile document is missing. You can stub out these requirements with the new EclipseAgentBase class so you can focus on the agent code.

Enough explaining – let’s look at some code.

Simple agents, no objects from AgentContext

In the most simple agents, which is normally never the case,me where you do not use any objects from the AgentContext you only need to override the NotesMain method and implement the main()-method boilerplate code. As you can see from the example you can use the isNotes() method if you need to know whether the code is running in Notes/Domino or in Eclipse. Notice how the code runs perfectly no matter if you run the code in Notes/Domino or in Eclipse.

import lotus.domino.NotesThread;
import lotus.domino.Session;

public class ExampleAgent1 extends EclipseAgentBase {

   public static void main(String[] args) {
      try {
         NotesThread.sinitThread();
         new ExampleAgent1().NotesMain();

      } catch (Exception e) {
         e.printStackTrace();
      } finally {
         NotesThread.stermThread();
      }
   }

   public void NotesMain() {
      try {
         Session session = this.getSession();
         if (this.isNotes()) {
            System.out.println("We're in Notes...");
         } else {
            System.out.println("We're outside Notes...");
         }
         System.out.println("Username: " + session.getUserName());
      } catch (Exception e) {
         e.printStackTrace();
      }
   }
}

“Normal” agents, using AgentContext.getCurrentDatabase()

In what I call “normal” agents you will probably at least use some information about the current database. To do this we have to override the callbackGetCurrentDatabase() method of the agent (in bold below). This overridden method will only be used when running outside Notes/Domino. If your agent does a lot of calls to the method you might want to store the database instance and return the same instance if called multiple times.

import lotus.domino.Database;
import lotus.domino.NotesException;
import lotus.domino.NotesThread;
import lotus.domino.Session;

public class ExampleAgent2 extends EclipseAgentBase {

   public static void main(String[] args) {
      try {
         NotesThread.sinitThread();
         new ExampleAgent2().NotesMain();

      } catch (Exception e) {
         e.printStackTrace();
      } finally {
         NotesThread.stermThread();
      }
   }

   protected Database callbackGetCurrentDatabase() throws NotesException {
      return this.getSession().getDatabase(null,"names.nsf");
   }

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

Document agents, using AgentContext.getUnprocessedDocuments()

Many agents is built to process the unprocessed documents of the database. This poses some problems when configuring the runtime environment for testing. This is purpose I have written a couple of utility classes to help set this up.

Stay tuned.