Running OpenNTF Domino API code directly from Eclipse

I’ve seen some requests in the last few days for the OpenNTF Domino API to support DIIOP sessions because people want to run their code directly from Eclipse. I’m afraid I have some bad news: it would be literally twice as much work for us to support DIIOP sessions at this point, because they are based on an entirely separate package from what we have worked on. Because we see so little DIIOP use in real world scenarios, we really aren’t motivated at this point to go through all that trouble.

Fortunately, what I can do is show you how to run your code directly from Eclipse using the normal local executable approach. It’s quite simple to do, it’s much faster, and it more closely mirrors what your code is likely to do in real world deployments. This is how I do all my scratch testing of the API, and it’s cumulatively saved me weeks of setup and teardown time for tests over the last couple of years.

First, start with a class that implements Runnable and has a static main(). I’ve attached a very simple example below…

import lotus.domino.NotesFactory;
import org.openntf.domino.Database;
import org.openntf.domino.Session;
import org.openntf.domino.thread.DominoThread;
import org.openntf.domino.utils.Factory;
public class DominoRunnable implements Runnable {
public static void main(String[] args) {
DominoThread thread = new DominoThread(new DominoRunnable(), "My thread");
public DominoRunnable() {
// whatever you might want to do in your constructor, but stay away from Domino objects
public void run() {
try {
Session session = Factory.fromLotus(NotesFactory.createSession(), Session.class, null);
Database db = session.getDatabase("", "names.nsf");
// whatever you're gonna do, do it fast!
} catch (Throwable t) {

Once you’ve created your class, you need an Eclipse run configuration to execute it. Start by selecting the Run menu…
When you get the Run Configurations dialog, you can click on the new icon in the upper left. Give your configuration a name, and select the Project and class file…
On the Arguments tab, you can add JVM arguments. This is a great place to try out stuff like alternative GC strategies or set other system properties.

Notice on the bottom you want to set a working directory. I have an environment variable defined for my Domino program directory, but you can also put in an explicit path…

Next you’ll need to set your JRE. If you have a typical Eclipse set up, this will be the key part because you *don’t* want to run with the Oracle JVM. You want to run your test class with the IBM J9 JVM from a local Notes or Domino installation. Whichever one you point to, make sure you’ve put the org.openntf.domino.jar into the jvm/lib/ext folder so that it will auto-load the library.

If you haven’t already defined a J9 JRE in Eclipse, you can do so directly from here. Just add a new JRE and point it to the correct install path. Or you can use the XPages SDK for Eclipse to automatically configure it for you.

Finally, just click “Run” and let your code rip!

Please note that if the Notes or Domino instance you point to is actually running at the time, then although your process will launch, you won’t be able to access any of the Databases in that local system. And you’ll be running with the credentials of the default ID on that system.

Posted in Uncategorized
5 comments on “Running OpenNTF Domino API code directly from Eclipse
  1. mathew says:

    What do you mean by “an entirely separate package”? Once you get a Session object, everything else is the same.

    I use DIIOP all the time for periodic data transfer and maintenance tasks.

    • thentf says:

      Nope, sorry. The INTERFACE is the same. They’re both lotus.domino.Session. But the implementation is different: lotus.domino.local.Session vs. lotus.domino.cso.Session

      The OpenNTF Domino API is based on the lotus.domino.local implementation. The cso objects work completely differently internally. And we’re very sensitive to the internal functions of the API.

      Incidentally, I really don’t know why IBM created .recycle() in the DIIOP implementation. It acts like pseudo-garbagecollection by dereferencing member values in the objects, but this kind of defeats the whole purpose of using Java. Since there aren’t any C++ handles, there’s nothing that actually has to be released.

      • Mikkel says:

        Most probably they added recycle to keep the API the same for the two approaches. What’s interesting would be to see if calling recycle on a remote object actually triggers a network call back to the server over IIOP. If so they may need it to handle recycle on the server side.

        But yes – one wonders… 🙂

      • thentf says:

        Mikkel, yes, it seems quite likely that implementing .recycle in the DIIOP version was simply to maintain consistency. But if so, then isn’t that a particularly crazy idea? I mean, .recycle is considered one of the worst aspects of the original API, and so they duplicated something universally reviled for the sake of consistency. But instead of just putting in a NOOP method, .recycle actually schedules the clearance of member fields on a separate thread! Why not just set them to null and let garbage collection do the work that it will still have to do anyway!?!??!

        It’s a bizarre decision that probably had to do with some notion of Windows memory restrictions, but the fact that it’s carried forward all this time is just… I don’t even have the words. I have to quote Nietzsche: “The irrationality of a thing is no argument against its existence, rather a condition of it.”

  2. […] perfect but i got the documents again on the lotuskb.nsf Thanks to Nathan Freeman for the article about running Domino API on eclipse The eclipse project is […]

Take the red pill.

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: