Understanding the Notes Object Interface

The Notes Object Interface is a class library first introduced in Notes 4.0 with LotusScript. Under the hood, the NOI is really a bunch of C++ classes contained in dynamic link libraries. Both LotusScript and Java use the LSX (LotusScript eXtensions) architecture to bind to the same underlying C++ code.

There are other implications of the underlying native nature of Java NOI objects. First, you can't use the new operator to create Domino objects in Java. Instead, you use methods such as NotesFactory.createSession() and Session.getDatabase() that create native Notes objects and return them wrapped as Java objects. Second, you must make sure that the Notes system is initialized for each thread of your program. This is done automatically for the first thread in agents and applets, but you must use the NotesThread class to initialize servlets, applications, and extra threads in agents or applets. Details of NotesThread are presented later in this chapter.

The NOI describes a containment hierarchy. At the top of the hierarchy is the Session object, which contains all other objects. The Session object contains DbDirectory objects, which contain Database objects, which contain DocumentCollection objects, which contain Document objects, and so forth. You usually must start from the top and work your way through the hierarchy to find objects you want to use.

Keep in mind that an object can't exist without its containing parent object. When a parent object is destroyed in memory, its children are also destroyed . Because Java objects are automatically garbage-collected when they go out of scope, you might run into problems with code like this:

public Document getBugEntry() throws NotesException 
{
 Session l_nsCurrent = NotesFactory.createSession();
 DbDirectory l_dbDirCurrent = l_nsCurrent .getDbDirectory( "" );
 Database l_ndbContacts = l_dbDirCurrent.openDatabase( "contacts.nsf" );
 DocumentCollection l_ndcAll = l_ndbContacts.getAllDocuments();

 return l_ndcAll.getFirstDocument();
}

This method first creates a Session object and then winds its way through the containment hierarchy to get the first document in the contacts.nsf database. The problem lies in the fact that these variables are local to the method and go out of scope when it's over. Java will eventually garbage-collect these objects, so they might be destroyed before you're done with your document. Because children objects are destroyed with their parents, this is a problem. One solution is to reference container objects as fields of your class rather than as local variables . You can then use them throughout your class without worrying about the garbage collector ruining your day.

Unfortunately, the Java API lacks the front-end UI classes in the LotusScript API, such as NotesUIWorkspace . These NOI classes haven't yet been exposed in the Java binding. Likewise, both Java and LotusScript lack functionality found in the C++ API. If you really have to get at this hidden NOI functionality, you can write C++ code and wire it to your Java classes using JNI. This is a tricky business, though, and is beyond the scope of this book.