Getting database activity in a Java agent - Part 1

So you have a requirement to access the user activity log for a database through a Java agent?  The first thing you will discover is that there is no way to access this information through the standard Domino object model.  However, all is not lost - this information can be accessed using the Domino C API.  You just need to code a link between your Java agent and the C API.  This article is the first in a series describing the steps required to create this link.

The easiest way to call a native shared library in a Java agent is using JNA (https://jna.dev.java.net/).  JNA is a Java library that allows Java programs to easily access native shared libraries (DLLs on Windows machines).  The only drawback to its use is that JNA requires a JAR file to be present on the machine on which you wish to run the Java agent (ie. the client for a client side agent or the server for a server side agent).  For the purposes of this article, I will assume that you are creating a server-side Java agent.  In addition, I have assumed that you are running a Windows based server - those running other operating systems will need to translate folder structures/syntax as required.

To install JNA on the server, you will need to download the latest release JAR file from the JNA homepage.  You will need the jna.jar file.  Download this file.  It will need to be copied to the folder <Domino Path>/jvm/lib/ext on your server where <Domino Path> is the path to the Domino installation.  Domino automatically searches this folder for JAR files to include when running Java agents - you will need to restart the HTTP task on the server to load the new JAR file.

You will also need to copy a version of the file to your local machine. You will reference this version of the file when compiling your Java agents in the Domino designer - ensuring you do not get any nasty compile messages when you reference the JNA objects.  Place the JAR file in the <Domino Path>/jvm/lib/ext on your machine where <Domino Path> is the path to the Domino installation.

You are now ready to begin the development of your new agent.  In the Domino designer, create a new Java agent.  From the Project menu, select the Properties option.  In the properties window, click the Java Build Path option.  This opens the Java Build Path window shown in Figure 1 below.

Figure 1 - The Java Build Path window

Select the Libraries tab, then click the Add External JARS... button.  Browse to and select the jna.jar file you copied to your development machine.  Click the OK button to save your change to the build path.

The key to JNA is to define a Java interface that converts the native library call signatures to Java interface methods.  The JNA library provides some helpful classes for defining these interfaces.  If you are interested in the process of defining the interface, the JNA documentation has a good overview here.  The key to the interface definition is that it inherits from the JNA StdCallLibrary class - this will be vital for linking the interface to the Windows API. 

The interface that defines all of the C structures and methods you will require to retrieve a database's user activity log is this:

import com.sun.jna.*;
import com.sun.jna.ptr.*;
import com.sun.jna.win32.*;

public interface NNotes extends StdCallLibrary {

public class TimeDate extends Structure {

public int innards1;
public int innards2;

}

public class DBActivity extends Structure {

public static class ByReference extends DBActivity implements Structure.ByReference {}

public TimeDate First;
public TimeDate Last;
public int Uses;
public int Reads;
public int Writes;
public int PrevDayUses;
public int PrevDayReads;
public int PrevDayWrites;
public int PrevWeekUses;
public int PrevWeekReads;
public int PrevWeekWrites;
public int PrevMonthUses;
public int PrevMonthReads;
public int PrevMonthWrites;

}

public class DBActivity_Entry extends Structure {

public TimeDate Time;
public short Reads;
public short Writes;
public int UserNameOffset;

public DBActivity_Entry() {}

public DBActivity_Entry(Pointer pointer) {

super(pointer);

// Read the values
read();

}

}

short ConvertTIMEDATEToText(IntByReference IntlFormat, IntByReference TextFormat, Pointer InputTime, Pointer retTextBuffer, short TextBufferLength, ShortByReference retTextLength);
short NSFDbOpen(String dbName, IntByReference dbHhandle);
short NSFDbClose(IntByReference dbHandle);
short NSFDbGetUserActivity(int dbHandle, int Flags, DBActivity.ByReference retDbActivity, IntByReference rethUserInfo, ShortByReference retUserCount);
Pointer OSLockObject(int Handle);
short OSUnlockObject(int Handle);

}

Once you have defined the interface, you can begin writing the agent.  In part 2 of this article, I will describe the steps required to retrieve the database activity.