Skip to main content

Getting started with Domino AppDev Pack Java API - Part 1

 The newest Domino AppDev Pack release 1.0.6 added support for Java API. In past, we've seen many projects that tried to decouple Java APIs from Domino server, but except for the built-in DIIOP, all were community-driven and required some sort of bridge or fake Domino binaries package. This time we're getting brand new, officially supported API. 

Domino AppDev Pack series:
1. First Java API (this)

I've never worked with Node.js based domino-db module, but I've seen several demos and I was well aware of the architecture. Even with all this knowledge, when I've checked the official documentation, I was pretty terrified. It looked like I need to be an experienced Domino admin, security specialist, and who knows what to just try to see how the new Java API. Luckily, if you just try to read between the lines, it's not that bad. HCL just documented the full pretty complex setup, which is not what you are looking for if you what to write your first HelloWorld program using this new API.

I hoped that there will be someone who will show me all the new APIs during our upcoming SUTOL conference. We have an AppDev Pack expert between us - Jan Krejcárek, but he currently doesn't have enough free time to prepare the session, so I've offered my help (To be fully honest, I originally suggested that he will do it when he had to leave our planning call for few minutes, which wasn't nice from me, but if you know how such calls work, usually the people not attending the calls get all the tasks ... ).

Many Domino developers are familiar with Java, so the learning curve should be much easier for them, compared to getting into the full Node.js ecosystem. Recently I also see a bit of decline in the Node.js hype that started several years ago, primarily because all other languages, including Java and C# have enhanced and include native support for async and non-blocking apis. 

Initial goal

My initial goal was to just call run a command-line Java program that connects to a test Domino server, creates a document. That's it. Should not be rocket science. Compared to the setup documented by HCL I don't need:
  • CAs and certificates - I can now play with anonymous access
  • IAM - I don't need to access the app as a user
  • ID vault - I'll be running as anonymous, so I won't be able to do any idfile-based encryption anyway.
Getting rid of the most complicated parts of the setup reduced the installation procedure to basically 3 steps.

Server setup

Because many of the steps in the official HCL documentation contains Windows-based samples, I decided to run my server on Windows this time, so no Docker, but I guess I'll get back to this later. The steps are super easy, so you can do this on Linux too.

I'm running everything on 11.0.1 server, it's currently the only supported server version.

1. Install Domino server

Ok, I guess everyone knows how to do that - click, click, finish. You'll also need a Notes client (and probably Designer and Administrator later on) - click, click, finish one more time.

2. Install the AppDev Pack binaries and configuration database

Super easy too, just extract the files and create the adpconfig.nsf from the provided template. See the documentation for details.

3. Create a minimal Proton config document

In the adpconfig.nsf that you've created in the previous step, create a new configuration document for your server. In the configuration document
  • adjust the Listen Address (if you want to allow connection for different machine)
  • uncheck the "Enable SSL/TLS connection"
  • Save and click Start Task

This will force you to use Proton only with anonymous access (so nothing you'd like to see in production, but we are just playing with it, right?).

You are done with the server setup.

4. Create a test database

My plan was to call the new API and create a document, so just create an empty Notes database on the server and adjust the ACL, so anonymous can create new documents in the database.

Now we are ready to use the API.

First Java program

I haven't found much information in the documentation about how to actually use the provided jar or what are the required dependencies. Luckily, there is a Maven pom.xml file inside, which helps with the setup.

Normally, you would install the provided jar into your shared or local Maven repository and use that. For sake of simplicity I've decided to skip this step in this demo, but as there are many dependencies I'm still using Maven to run the program. You can get the code here -

1. domino-db dependency

Our life would be much easier if HCL was able to push the domino-db.jar to e.g. Maven central, but I guess they can't do that because of the license restrictions. In the future, I hope they will be able to host (or open their existing) Maven repository, so customers could use their Flexnet login to pull the dependency.

For now, I've just copied it to a local folder, C:\lib in my case, and added this directly in the pom.xml


This method is currently being deprecated in Maven but still works. It's pretty easy to use for now ... .

2. Additional dependencies

Maven is not able to able to extract dependencies from the jar if we include it using the previous method. Originally, I've tried to add only those reported as missing during execution, but after the third, I gave up and just copied all dependencies listed in pom.xml of domino-db.jar. All are now included in pom.xml of my sample.

3. Sample program

All samples in the documentation use authentication using certificates, but you can just ignore these. Another missing part in the documentation is how to work with so call EXECUTOR_SERVICE, so I just went for some simple default.

Here is the full sample:

Pretty simple, right?

4. Test run

Now the final part, verification that it all just works. And it does! After running the program I get a new document in my test db.



I know that the AppDev Pack Java API is currently in preview, but I think if HCL added a similar dead-simple sample in the documentation, more people would try it. I have seen many scenarios where the new Java API can be used for system-to-system integration, so there is a potential for pretty fast user adoption. This setup should be doable in 10 minutes, less time than you probably need to download the installers. 

The next part of the series will secure the communication using certificates, but I'll try to make it a bit more simple than the official doc. Stay tuned.


Popular posts from this blog

Microsoft Word black box in numbering issue

This is awkward post, primarily to save the solution for future me. I have seen many people mentioning this problem over years and as I've struggled with it several times, I needed to find final and permanent solution. All editions of Microsoft Word from time to time suffer from bug in numbering. Instead of a number, black box is displayed. Sometimes it happens right after document is opened, sometimes during editing. Probably some internal structure of document gets corrupted, so based on level of corruption, different fixes could help. Many of them are listed at I took different approach. Since docx is just standard zip package with xml files, I decided to try if I can fix it manually. And it worked. When I extracted the docx, there was file called numbering.xml in word folder. When I examined that file, I found strange se

HCL Domino SSO with Microsoft Teams

 Microsoft Teams is probably one of the most used tools this year, it was already quite popular before the pandemic started to spread across the world this spring, but now most of the businesses I work with use it. After using it just like a chat/conferencing tool, many start to explore further capabilities of the platform. When working with Domino data in apps that are web-enabled, it can be quite easy - just add a web tab anywhere you want. The problem is, that you need to deal with user authentication. 

Domino CI build with Jenkins and Docker

 I wanted to make this work for a very long time, but there were always some parts missing, so I could not get the full process running. Finally, the wait is over. The following paragraphs describe a way to build Notes/Domino apps automatically on a Jenkins server, allowing parallel builds and all "normal" continuous-integration behavior, without having to think too much about Domino specifics. The Problem Until now, I was running my automated builds of Domino apps using Jenkins in two ways: The official headless-designer way, where you need to pass special commands to Domino Designer and hope for the best as the Designer sometimes gets stuck. I have this wrapped inside a Jenkins pipeline, so I have some control and can e.g. avoid parallel builds by using locks on Jenkins, but still, sometimes it just dies. Some of my headless builds run for more than 30 minutes, so it's really hard to quickly spot an issue without actually connecting to the machi