Java in Notes/Domino Explained: Classloading

When doing Java development you write your code in classes and hence deal with classes. Each Java class in your source code is compiled into a binary class file.

JavaAgent.java (text) -(compile)-> JavaAgent.class (binary)

The compilation is done automatically for you when you write Java in Notes/Domino or if programming in Eclipse. It does however still help to be aware of what actually goes on under the covers when your agent is run.

“The process of finding the binary classes and loading them into memory is called classloading…”

The fact that each class is compiled into a separate file means that a Java agent consisting of 4 classes will contain 4 compiled classes. Since all the code isn’t combined into a separate file (like an EXE-file on Windows) the Java Virtual Machine (JVM) needs to locate these compiled classes at runtime and load them into memory so it can use them hence the word classloading.

The default classloader in Notes/Domino (lotus.domino.AgentLoader) is capable of loading classes from the classpath of the current agent which consists of:

• Classes that are part of the agent itself.
• Classes and JAR-files added to the agent using the “Edit Project”-button.
• Java Script libraries added to the agent using the “Edit Project”-button.
• Classes present on the Notes/Domino system classpath.

See the post “Managing external Java dependencies in Domino Designer” for more information on the Notes/Domino system classpath.

The exceptions

There are three exceptional situations that can and do occur frequently when working with Java in relation to classloading. These are the java.lang.ClassNotFoundException, the java.lang.NoClassDefFoundError and the java.lang.UnsupportedClassVersionError. Below are short excerpts from their explanation in the JDK. When programming in Notes/Domino you will probably encounter the first two at some point. The third I do not wish upon you… 🙂

The ClassNotFoundException exception is encountered when you try to dynamically instantiate a class using a string name (java.lang.Class.forName()) and the class cannot be found in the classpath. This is a checked exception you must catch when doing a Class.forName() call.

The NoClassDefFoundError is raised if you use a class in your agent which in turn uses another class that cannot be loaded at runtime. The most common scenario for this is when using third-party library consisting of multiple JAR-files. In this case you may only have included one of the JAR-files in your agent to make it compile. The agent may compile but if classes in the included JAR-file uses classes in a second JAR-file, that wasn’t included in the agent, this error will occur.

The UnsupportedClassVersionError is less likely to occur if you are on Notes/Domino 6.x or 7.x but does occur quite a lot if you are using third-party libraries on older Notes/Domino versions. The binary Java class format changes slightly over time (much like the On-Disk-Structure of Notes databases) and since the JVM cannot be forward compatible it needs a way to tell you that you are trying to load a class into the JVM it doesn’t know how to handle (the version of the class format is wrong). The way around this is to try and compile the classes using a Java 1.1.8 compiler or using “classic” mode with newer compilers.

So why is this important?

To really appreciate the concept of classloading you need to realize that:

1. Java classes are not loaded into memory before actually used.
2. Java supports dynamic classloading.
3. You can write your own classloader.
4. Classloaders in Java are hierarchical and thus can delegate classloading to other classes.

You don’t have to worry too much about item 1. I’ll explain item 2 and 3 in detail in subsequent posts to avoid making this post too long. Item 4 deals with delegation of classloading in case a specific classloader cannot find a given class. Suffice it to say that these four concepts allows the JVM to conserve memory and you to write very powerful and highly dynamic agents/classes.

All this fuss about classloading might seem overly complex but consider the fact that many of the classes that you use in your Java agent aren’t some you have written. They are part of the Java Development Kit (the java.lang packages) or part of third-party libraries that you program and execute your agents against.

If there were no classloaders you could not have dynamic classloading and all classes would need to be loaded into memory before starting an agent. This could/would take up a lot of memory and be highly inefficient.