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

WSL, HCL Volt and some Docker

My list of new technologies to try was growing fast in past months, but now I finally can try to catch up with all the cool improvements that can be used to enhance my/your dev experience. Microsoft has enhanced the Windows Subsystem for Linux this year and Docker completely changed the way Docker Desktop for Windows is integrated into the operating system. The most important change for me was that I can finally run Docker Desktop and VMWare Workstation on my machine in parallel. When I was looking for some good use cases to try how it works, HCL Domino was a logical choice. HCL started to even publish official Docker images for every release and some pre-releases are only available as Docker images. I have many test Domino machines running in VMs, but I had no HCL Volt. If you don't know that HCL Volt is - it's a new low-code platform that brings HCL Form Builder experience, now know as HCL Leap, to HCL Domino, which then serves as a data store and application server. Whe

XPages ${} risk of code injection

While working on app optimization I experimented a bit more with 'Compute on page load' vs. 'Compute dynamically' behavior. There have been several discussions in past about possible combination of ${} and #{}, for example posts from  Marky Roden ,  Sven Hasselbach  and  Paul Withers  . What struck me today was risk of code injection. In this app many elements are read from configuration documents that are loaded into beans and later used using ${} binding. This is recommended way as it is static information, so it's efficient. It works nicely until you insert expressions into your data. This way I realized that a lot of code is prone to code injection that can be contained either in configuration documents or any string that is stored and later read this way. To simulate the issue I created simple page with one field, one button and one text: All it does is saving entered value into applicationScope and then displaying it. Since the text uses ${} Compute o