Month: June 2006

Suppose we have this new AgentBase implementation – what we really like is for it to revert back to the lotus.domino.AgentBase functionality whenever the agent is run inside Notes/Domino and only use our new AgentBase look-a-like whenever we run inside Eclipse. Part 2 discussed how to detect where the code is running so by now we have a member variable called pIsNotes that is true if inside Notes/Domino and false otherwise.

To “fool” the agent when running inside Eclipse we need to override the getSession() and the getPrintWriter() methods of the AgentBase class with an implementation that works in Eclise. If we don’t the agent will fail with a NullPointerException whenever the agent is run.

Using our pIsNotes member variable it is almost trivial to create a java.io.PrintWriter that maps to System.out and create a lotus.domino.Session using lotus.domino.NotesFactory whenever we are outside Notes/Domino. When inside Notes/Domino we simply call the super-implementation that is the code of the AgentBase class supplied by IBM:

public abstract class EclipseAgentBase extends AgentBase {
   // declarations
   private boolean pIsNotes = false;
   private Session pSession = null;

   {
      try {
         Class.forName("lotus.domino.servlet.DominoSessionContext");
         this.pIsNotes = true;
      } catch (ClassNotFoundException e) {
         // ignore - we're not in Notes/Domino
      }
   }

   public abstract void NotesMain();

   protected boolean isNotes() {
      return this.pIsNotes;
   }

   public PrintWriter getAgentOutput() {
      try {
         if (this.pIsNotes) {
            return super.getAgentOutput();
         } else {
            return new PrintWriter(new OutputStreamWriter(System.out, "ISO-8859-1"));
         }
      } catch (Exception e) {
         throw new RuntimeException("Unable to convert System.out to PrintWriter", e);
      }
   }

   public Session getSession() {
      try {
         if (this.pIsNotes) {
            return super.getSession();
         } else {
            if (null == this.pSession) {
               this.pSession = NotesFactory.createSession();
            }
            return this.pSession;
         }
      } catch (NotesException e) {
         throw new RuntimeException("Unable to create session", e);
      }
   }
   ...
   ...
}

In the next part we’ll dive a little deeper by looking at a crucial part we are missing – the AgentContext returned by the Session object. At present it simply returns null which won’t work when testing agents.

Stay tuned.

Part 1 discussed the need for a new base class for “Imported Java”-agents by extending the lotus.domino.AgentBase class to allow writing, testing and debugging agents from within Eclipse. Suppose we have this new AgentBase implementation – what we really like is for it to revert back to the lotus.domino.AgentBase functionality whenever the agent is run inside Notes/Domino and only use our new AgentBase look-a-like whenever we run inside Eclipse. To do this we need to detect where the code is running.

There are really not that many ways to detect whether the code is running inside Notes/Domino or Eclipse for that matter. My first choice was to look for a System property and found a property called package.restrict.definition.lotus.notes that would allow me to detect whether the code was running inside Notes/Domino. Using this property I could set a flag in the base class that I could query later on:

public abstract class EclipseAgentBase extends AgentBase {
   // declarations
   private boolean pIsNotes = false;

   {
      String prop_name = "package.restrict.definition.lotus.notes";
      this.pIsNotes = (null != System.getProperty(prop_name));
   }
   ...
   ...
}

The “strange” construct I use to initialize this pIsNotes member variable is called an initializer. If you would like to learn more about initializers I can recommend an article at Javaworld.com.

There is a problem with using System properties in Notes/Domino since you are only allowed to query a subset of them without having access to restricted operations. Strange but true… This meant I had to scratch that approach since I would really like an approach viable for all agents without requiring restricted access.

I finally settled on using the availability of a class for my detection. Since the Domino Servlet Container classes are only available inside Notes/Domino I could use a class from there. I settled on the DominoSessionContext class from the lotus.domino.servlet-package. The Domino Servlet Container classes are also available in agents since the dservlet.jar is placed in jvm/lib/ext. The detection is now as simple as trying to load the class:

public abstract class EclipseAgentBase extends AgentBase {
   // declarations
   private boolean pIsNotes = false;

   {
      try {
         Class.forName("lotus.domino.servlet.DominoSessionContext");
         this.pIsNotes = true;
      } catch (ClassNotFoundException e) {
         // ignore - we're not in Notes/Domino
      }
   }
   ...
   ...
}

In this case a java.lang.ClassNotFoundException simply means that the classloader cannot find the class hence we are outside Notes/Domino. Simple but it works.

This post way sparked by a post in the Notes/Domino forum on developerWorks.

Let me start by saying that you could probably use the AgentRunner if you can figure it out and if it still works. I haven’t used it for a LONG time and I doubt that it still works with the changes made to the Java API in Notes/Domino 6.x and 7.x. The Using Document of the AgentRunner database hasn’t been updated since 1999!! Anyways – there are other options.

Write the code in a separate class hierarchy

The first one is to write the agent functionality in separate classes and then have the agent code call these classes to do its job. This is a viable approach though it means you have to maintain the actual business code and the agent code in separate places (the business code in Eclipse and the agent code in Notes/Domino).

Extend lotus.domino.AgentBase

Another option is to extend the AgentBase class and implement some of the intializing functionality yourself for testing. The approach isn’t optimal and still makes you implement some boilerplate code but it’s a start and a viable option for writing and testing your agents in Eclipse. The new AgentBase class can be made to detect whether it runs inside Eclipse or inside Notes/Domino so it’s easy to move the code into Notes/Domino once it works.

The boilerplate code has to do with initializing a thread to Notes in a main() method before calling the NotesMain() method of your agent class. The below example shows the required boilerplate code for the ExampleAgent1 class:

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

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

The new AgentBase class (called EclipseAgentBase) means you can write agents in Eclipse. The only change is that you extend EclipseAgentBase instead of AgentBase:

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();
         System.out.println("Username: " + session.getUserName());
      } catch (Exception e) {
         e.printStackTrace();
      }
   }
}

In the next part of the post I’ll dive into how do build the EclipseAgentBase class.