Wednesday, October 14, 2020

JavaServerAddin in Domino - introduction

I will show how to build, register and load simple JavaAddin for Domino. I'm not entirely sure if lotus.notes.addins.JavaServerAddin is supported by HCL, so use that for your own sake.

1) Java class

import lotus.notes.addins.JavaServerAddin;

public class DemoAddin extends JavaServerAddin {
	public void runNotes() {
		AddInLogMessageText("Hello world", 0);
	}
}

2) JAR - from project

Export/build JAR file from the DemoAddin project (we are going to put jar file in the Domino folder).

3) Register JavaAddin

Place JAR file under Domino, f.x. path could be (DemoAddin is a folder and it could be just any name, DemoAddin-1.jar is our JAR file we built earlier)

C:\IBM\Domino\DemoAddin\DemoAddin-1.jar

and then register it in server's notes.ini using variable JAVAUSERCLASSES. In case if there are other addin registered there use semicolon as a separator for Windows and a colon for Linux

JAVAUSERCLASSES=addin-1;.\DemoAddin\DemoAddin-1.jar;addin-2

Alternatively simply put JAR file into the folder \jvm\lib\ext, but personally I prefer to keep customization separately instead of mixing core JAR files with customization. Additionally I'm not sure what happens to custom JAR file when is upgradet.

4) Load JavaAddin

It's time to run our DemoAddin. From console run following command

load runjava DemoAddin

Take into account if your include your class into a package, f.x. package org.demo; than you should add that into run command

load runjava org.demo.DemoAddin

If everything went fine you should see 3 lines

RunJava: Started DemoAddin Java task.
Hello world
RunJava: Finalized DemoAddin Java task.

Possible error

If you registered JAR file incorrectly, the error could be like this. In such case just make sure you followed steps properly.

RunJava: Can't find class DemoAddin1 or lotus/notes/addins/demoaddin1/DemoAddin1 in the classpath.  Class names are case-sensitive.

If I find time, I will make few more posts about this topic. It's really just a tip of the iceberg.

All articles in series
  1. JavaServerAddin in Domino - introduction
  2. JavaServerAddin in Domino - constructor and schedule

6 comments :

Paul Withers said...

If you add the JAR under the Domino classpath, so on Windows that’s \jvm\lib\ext, you don’t need to add the notes.ini variable. It’s worth highlighting that the Java class cannot be in a package, it needs to be at the top level. RunJava expects it to be there, I guess dating from Java 5 days.

John D. said...

I would be interested in reading more about this process, in particular how to build addins for Linux and Windows.

Dmytro said...

@Paus got points (I will update post)

> It’s worth highlighting that the Java class cannot be in a package, it needs to be at the top level.

In such cases you have to load it using full path, f.x.

load runjava org.demo.DemoAddin

> If you add the JAR under the Domino classpath, so on Windows that’s \jvm\lib\ext

Do you know if EXT is not fully reset after Domino upgrade? I found that using custom folder (within notes.ini) gives me better overview of what is going on.

Dmytro said...

@John as I mentioned in my post if I find time I will make more posts about this topic and thus also cover what you asked. Stay tuned!

Ulrich Krause said...

You can place the .jar in the ndext folder in the DominoPrgmDir. THis location is not modified during server updates.

Anonymous said...

Lordy, please stop using the \ext directory. I think just because "everyone does it" in Domino land doesn't make it correct.

https://docs.oracle.com/javase/tutorial/ext/basics/load.html

It overrides the classpath for ALL Java programs running under the Domino JVM. You might ask, "Well, who cares?" You will if you create a new jar and bundle a dependency jar that you require. If you then go and put another version of that jar you depend on in the \ext directory, suddenly your code stops using the bundled dependency and starts using the version in \ext whether you like it or not, and you have a bit of a debugging nightmare.

https://stackoverflow.com/questions/2068961/is-putting-external-jars-in-the-java-home-lib-ext-directory-a-bad-thing