Homepage API Documentation Download Open Source Code

Domino

Do you need to write an add-in for IBM Domino server in Java?

The JAddin framework is a very thin and convenient layer between the Domino RunJava task and your Java application code. It greatly helps you to create Java server tasks by freeing you to learn all the Domino add-in specifics such as message queue handling, thread creation, communicating with the console, resource cleanup, etc. It is written entirely in Java to support all Domino versions and platforms.

Prerequisites

Example

public class HelloWorld extends JAddinThread {

	// This is the main entry point. When this method returns, the add-in terminates.
	public void addinStart() {
		
		logMessage("Started with parameters " + getAddinParameters());
		
		try {
			logMessage("Running on " + dbGetSession().getNotesVersion());
		} catch (Exception e) {
			logMessage("Unable to get Domino version: " + e.getMessage());
		}

		// Main add-in loop ...
		while (true) {
			logMessage("User code is executing ...");
			waitMilliSeconds(15000L);
		}
	}

	// This method is called asynchronously by the JAddin framework when the
	// command 'Quit' or 'Exit' is entered or at Domino server shutdown. Here
	// you may signal the addinStart() method to terminate and to perform any cleanup.
	public void addinStop() {
		logMessage("Termination in progress");
	}
	
	// This method is called asynchronously by the JAddin framework for any
	// console command entered. It should be executed as quickly as possible
	// to avoid any main Domino message queue delays.
	public void addinCommand(String command) {
		logMessage("You have entered the command " + command);
	}
}

Framework Architecture

JAddin.class

The JAddin class is loaded by the Domino RunJava as the main Java thread. It shares the Java Virtual Machine (JVM) with RunJava.

JAddinThread.class

This abstract class must be implemented by the user add-in class. It runs as a separate thread to minimize any delays on the normal processing of the Domino server.

AddinName.class

The user code runs in this class and does all the processing of the application. Several methods are called from the framework and can be implemented by the user class. When the user class terminates, the framework will perform its cleanup and terminates the JAddin main thread.

Application Development

To be able to use this framework, you must add the JAddin.class, JAddinThread.class and the notes.jar file from your IBM Notes or IBM Domino installation to your development environment.

Application Testing and Distribution

To distribute and install your add-in, you must include a valid MANIFEST.MF, the framework files JAddin.class and JAddinThread.class together with your application code.

Create MANIFEST.MF file

Make sure that the file includes an empty line at the bottom.

Manifest-Version: 1.0
Class-Path: .
Main-Class: AddinName

Create JAR container

There are many tools available to create JAR containers, but the easiest way is to use the command line.

jar cvmf MANIFEST.MF AddinName.jar AddinName.class JAddin.class JAddinThread.class

Install Application

Copy this JAR container to the domino/ndext directory. This directory is automatically searched by the RunJava task for any Java class to load.

Run application

There are several ways to start the application:

Program Document

Console Commands

The framework supports a number of special commands:

> Tell HelloWorld Help!
12.01.2019 18:18:02   JAddin: The following JAddin commands are available:
12.01.2019 18:18:02   JAddin: Quit!       Terminate the add-in thru the JAddin framework
12.01.2019 18:18:02   JAddin: GC!         Executes the Java virtual machine garbage collector
12.01.2019 18:18:02   JAddin: Debug!      Enable the debug logging to the console
12.01.2019 18:18:02   JAddin: NoDebug!    Disable the debug logging to the console
12.01.2019 18:18:02   JAddin: Heartbeat!  Manually start heartbeat processing (automatically done every 15 seconds)
12.01.2019 18:18:02   JAddin: Help!       Displays this help text

Domino Statistics

The JAddin framework periodically sets a number of Domino statistic values which are shown with the Show Stat AddinName command.

> Show Stat HelloWorld
  HelloWorld.Domino.Version = Release 10.0.1|November 29, 2018
  HelloWorld.JAddin.Date = 14-Jan-2019
  HelloWorld.JAddin.StartTime = Mon Jan 14 10:22:04 CET 2019
  HelloWorld.JAddin.Version = 2.0.0
  HelloWorld.JVM.GCCount = 1
  HelloWorld.JVM.HeapDefinedKB = 131'072
  HelloWorld.JVM.HeapUsedKB = 20'781
  HelloWorld.JVM.Version = 1.8.0_181 (IBM Corporation)
  HelloWorld.OS.Version = 6.2 (Windows 8)

Debugging

For problem determination, you may enable debugging with the special parameter Debug!. To stop the debugging, use the parameter NoDebug!. While active debugging adds a significant amount of data to the console log and to the log.nsf database, it can be helpful in finding the root of a problem.

Load RunJava AddinName Squirrel Debug! Start your add-in in debug mode
Tell AddinName Debug! Start the debug mode while the add-in is running
Tell AddinName NoDebug! Stop the debug mode while the add-in is running

The debug output is written to the Domino console and includes the name of the Java method with the source line number issuing the message.

> Load RunJava JAddin HelloWorld Debug!
12.01.2019 11:27:48   JVM: Java Virtual Machine initialized.
12.01.2019 11:27:48   RunJava: Started JAddin Java task.
12.01.2019 11:27:48   JAddin: Debug logging enabled - Enter 'Tell HelloWorld NoDebug!' to disable
12.01.2019 11:27:48   DEBUG: JAddin.runNotes(111)                JAddin framework version 2.0.0
12.01.2019 11:27:48   DEBUG: JAddin.runNotes(112)                Addin HelloWorld will be called with parameters null
12.01.2019 11:27:48   DEBUG: JAddin.runNotes(115)                Creating the Domino message queue
12.01.2019 11:27:48   DEBUG: JAddin.runNotes(133)                Opening the Domino message queue
12.01.2019 11:27:48   DEBUG: JAddin.runNotes(151)                Loading the user Java class HelloWorld
12.01.2019 11:27:48   DEBUG: JAddin.runNotes(163)                User Java class HelloWorld successfully loaded
12.01.2019 11:27:48   DEBUG: JAddin.runNotes(175)                => HelloWorld.addinInitialize()
12.01.2019 11:27:48   DEBUG: HelloWorld.addinInitialize(75)      -- Method addinInitialize()
12.01.2019 11:27:48   DEBUG: HelloWorld.addinInitialize(89)      Creating the Domino session
12.01.2019 11:27:48   DEBUG: JAddin.runNotes(177)                <= HelloWorld.addinInitialize()
12.01.2019 11:27:48   DEBUG: JAddin.runNotes(188)                => HelloWorld.start()
12.01.2019 11:27:48   DEBUG: JAddin.runNotes(190)                <= HelloWorld.start()
12.01.2019 11:27:48   DEBUG: HelloWorld.runNotes(114)            -- Method runNotes()
12.01.2019 11:27:48   DEBUG: HelloWorld.runNotes(127)            => HelloWorld.addinStart()
12.01.2019 11:27:48   HelloWorld: Started with parameters null
12.01.2019 11:27:48   HelloWorld: Running on Release 10.0.1 November 29, 2018
12.01.2019 11:27:48   HelloWorld: User code is executing ...
> Tell HelloWorld q

Frequently Asked Questions

Author

This framework was created to help implementing projects which required the use of Domino server add-ins. If you encounter any issue or if you have a suggestion, please let me know. If you want to share some details of your projects based on JAddin, I will be glad to publish them here. You may contact me thru my email address andy.brunner@abdata.ch.

Unlicense (see unlicense.org)

This software shall be used for Good, not Evil.


Created with love and passion in the beautiful country of Switzerland. As far as I know, no animal was harmed in the making of this program.