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

XPages EL/class-loader memory leak (now with solution)

 We have recently experienced OutOfMemory crashes of XPages app server. The server was recently upgraded to 12.0.1FP1, but we were getting some panic crashes in HTTP even before the upgrade (it was 9.0.1FP10). Our hopes were that the upgrade would stabilize the server, but it's not the case. At least now I start to see what's the problem.  update 8.12.2022 There were actually 3 different leaks. I have rewritten the article to be a bit more clear. I also re-run some of the tests on 9.0.1FP10, so I assume the problems are also in earlier versions. Problem 1 The server is hosting over 1000 NSF sharing the same design + some other custom apps. Not all NSFs are used via web as the app still has classic Notes UI in parallel, so it's a bit tricky to estimate the load. By using tell http xsp show modules I usually see around 350 NSFs active. We kept the default application timeout that should provide reasonable application recycling if it's not used continuously.  We started to

HCL Domino 12.0.2, Engage 2022 and HCL Factory tour Milan

 I haven't published my recap after Engage this year and the recent HCL Factory tour in Milan is a great opportunity to write a summary about what's happening in HCL (mostly Domino) space. It's a mix of news about 12.0.2, future directions, and my impressions, so it can be a bit chaotic, but I got the impression that many people see it similarly.  Engage 2022 Engage 2022 was great (as always). I love the atmosphere in Brudges. I visited it once after Engage a few years ago and I was happy to come back. This was also the first time I had the opportunity to speak at Engage, which obviously made it a bit more stressful, but also more fun. Together with Domino Jams, HCL continued conversations with customers and partners about the future of their products at Engage. Many of these ideas were now discussed in greater detail in Milan, some of them were even demoed.  My main takeaways from Engage were: Nomad (web and mobile) are a great addition to Notes family Restyle is a great g

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.