This last couple of weeks I've made what I hope to be a brief return to developing for the Notes client. One of the requirements I had was to "add a form" to an existing Notes database, which allowed the user to input a few parameters and do a simple search of a remote SQL database, present the results to the user for their review before letting them import the resulting data in to the Notes database.

It goes without saying that I'd forgotten how to program in the Notes client. Having had such a long absence from Notes I came at it assuming that I could use Java code in the client (maybe you can and I missed something?).

For example, I'd assumed that, by now, I'd be able to write Java code in the Click event of a Button. As you can see below, this isn't an option.

I'm sure there's good reasons why we can't (is there?) but it left me a bit stuck. Was LotusScript my only option? I didn't relish the idea of fudging my way through getting LotusScript to do what I needed to do. It's not that I don't think it could. I'm sure it can, but it was a problem that really needed Java as the solution.

Not wanting to learn client development all over again or struggle trying to get LotusScript to do it I opted to write a Java Swing-based interface.

You can see an example below:

In the above example the user has clicked the Action button on the view and up popped the interface you can see. After entering some data and clicking a button the results table is populated from the SQL data. Then, when the Import button is pressed the data is saved in Notes -- a new document for each row of the table.

How does it work?

It's quite simple. The View's Action button looks like this:

This runs a Java Agent called "Import". Inside this agent the Java code simply creates an instance of a JFrame, adds all the components to it and then displays it. As far as the user's concerned it's just a part of Notes - when in fact it's a "standalone" Java application running inside Notes' JVM.

Powerful

The more I got in to this approach the more powerful I realised it was. Not only because the Java code is all self-contained in an Agent; meaning there are no installers or separate executable files to mange or distribute. But also because the app gets updated at the same time as the database design. Even the icons used in the buttons are stored as Resource files in the Agent itself. It's win win.

And because it's written in pure Java it's uses true OO patterns and a rich GUI. There are endless possibilities and pretty much no limit as to what you can do inside that popup window. I even managed to use a Thread to add and update a progress bar during the import process, which made me feel all geeky going multi-threaded (easier than it may sound!).

It also used a Data Access Layer (DAL) and data-modelling classes to abstract away from the SQL database. I had to do this as it's schema is subject to change. Also, at some point, the system will be moved off of Notes. At that point it will be easier to migrate this pure OO Java-based solution than it would be a Notes one.

It's worth noting that it runs inside the Notes JVM as the current user, meaning there's no need to store or ask for their password.

Gotchas

The one thing I don't like about using these Java windows is there's no way to open them as modal to the Notes client. It's all to easy for them to slip under the Notes client and the user to lose track of where it's gone.

However, they can be made to run (and stay) on top of all other windows, but that's a bit annoying. To do that would involve editing the java.policy file (found in <Notes Folder>\JVM\lib\security) on the user's machine and adding this permission:

Then in the code itself you can set the Swing frame to stay on top, like so:

try{
  frame.setAlwaysOnTop(true);
} catch (SecurityException sex){ }

Also, I've I've yet to work out how to limit it to only showing one window at a time. If the windows pops below others and the user presses the View Action button again they end up with two of them. I'd rather it brought the first back in to focus.

The other gotcha I found was that any button click (or other event) handlers in the popup window had no access to the Agent's Session object. That's because the Agent itself has completed running and all the session-based object have been recycled. If you want the Java code to interact with Notes then you need to create a new session.

To do this I wrote the basis of the Agent like this:

public class JavaAgent extends AgentBase {

 private static String databaseServer;
 private static String databasePath;

 public void NotesMain() {
  try {
   Session session = getSession();
   
   //So that later any session/threads can access this database
   databaseServer = session.getCurrentDatabase().getServer();
   databasePath = session.getCurrentDatabase().getFilePath();
   
   //Launch the dialog/form for user input
   //initializeUI();

 } catch(Exception e) {
   e.printStackTrace();
 }
}


 private static void calledFromSwingUIAfterAgentIsDone(){
  try{
   NotesThread.sinitThread();
   Session session = NotesFactory.createSession();

   Database db = session.getDatabase(databaseServer, databasePath);
   Document doc = dc.createDocument();

   //etc

  } catch (Exception e){
   //report error
  } finally {
   NotesThread.stermThread();
  }
 }
}

Note that I stored the database's server name and file path in two Strings that we can refer to later when we create our own Session object and re-open the database.

Summary

All in all it's an approach I'm happy with and it's got the job done. Some of you may think it's crazy overkill but, for me, it was the best (if not only) solution.

If there's any interest I can package up a downloadable example?