New on Github: Domino JNA - Cross-platform access to IBM Notes/Domino C API methods from Java
Karsten Lehmann 8 April 2016 19:11:37
I would like to introduce you to a pet project that I have been working on for the last months:Domino JNA -
Cross-platform access to IBM Notes/Domino C API methods from Java
Cross-platform access to IBM Notes/Domino C API methods from Java
As you might have already read in this blog in the past, we have been playing with the Domino C API for some time now and found out that you can speed up view reading dramatically when you talk directly to the C API instead of using IBM's Java classes.
The C API also provides lots of other functionality for which no Java or LotusScript methods exist yet.
It has always been possible to build your own DLL with C code calling Domino methods and use it via Java's Native Interface (JNI). We did this in applications developed for customers and partners, e.g. to render Richtext to HTML format, directly stream attachments (IBM's API first stores files temporarily to disk, not a good idea) or replicate databases with a progress callback.
But the problem has always been that the native code has to be compiled for each platform.
JNA to the rescue
Java Native Access is a project that gives Java developers access to native shared libraries without creating their own DLL or library file.
You simply call Java methods and make sure that your method arguments match those on the C side.
So I created my first small sample application months ago calling some Domino code, found out that it worked in Windows 32 bit, found out that I had to change something for Windows 64 bit to get more than just crashes, found out that the whole stuff did nothing than crashing in Linux systems, read lots of Domino C API documentation, build testcases, documented the API methods....
...and months later I uploaded the whole stuff to Github. :-)
Here it is:
An API is nothing without documentation and sample code. And I am working on that, but this takes time. There are already a few testcases available for the view functions.
Since talking to low level functions is not what everybody likes, I am also creating helper functions that make working with the API easier. I rename stuff, I add stuff and hide stuff. So please be aware that this project is definitely not finish and will change, but I want to share the code today because it already creates value and works quite well for us.
What does it do already?
Here are some of the things you can do with the first version:
- view lookups using different key formats (e.g. strings, numbers, dates, date ranges) and equality/inequality searches (e.g. find less or greater than a search key)
- decodes all available types of view column data types (string, string list, number, number list, datetime, datetime list) and row data (e.g. just note id, UNID, counts, unread flag etc.)
- read view data as another Notes user
- separation of Notes views and their data into multiple databases (like programmatically creating private views and keeping them up-to-date incrementally)
- special optimized functions for local databases (e.g. when API is running on the server and databases are on the server as well):
- dynamic filtering of view rows based on a Note id list with paging support (this really rocks!)
- reading categorized views with expanded/collapsed entries and min/max level
by reading noteid lists of modified and deleted documents (IBM's Java API does not return ids of deleted docs)
License
The Github repository contains a Maven project with the API code and setup instructions. All is available under Apache 2.0 license.
As next step, I want to add the code to an XPages Extension Library plugin to make it easier to use from XPages code.
Please provide feedback if the project is working for you.
- Comments [7]