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)

2. Certificates

3. Kotlin REST API

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 - https://github.com/mpradny/appdevpack-java-helloworld

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

<dependency>
<groupId>com.hcl.domino</groupId>
<artifactId>domino-db</artifactId>
<version>1.0.0</version>
<scope>system</scope>
<systemPath>C:\\lib/domino-db-1.0.0.jar</systemPath>
</dependency>

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.

 Coool.

Conclusion

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. 

Fell free to grab my sample from https://github.com/mpradny/appdevpack-java-helloworld

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.