Skip to main content

Domino AppDev Pack meets Kotlin and Spring Boot

Domino AppDev Pack Java API is still quite fresh for me, but I always try to push the limits, so I've decided to add Kotlin  to the mix. If you've never heard of Kotlin, please go and check it. It's a pretty cool language that can run on JVM and allows you to write more readable code more easily. I'll build a simple CRUD REST API, running on Spring Boot, that works with Domino data.

Domino AppDev Pack series:
3. Kotlin REST API (this)

My original plan was to just try other APIs directly from Java, but Heiko Voigt has already done that in his presentation at CollabSphere 2020. The presentation is available here . If you want to know more about AppDev Pack, please watch it. You can also find the code in his github repo. I knew that C3UG had prepared a course about AppDev Pack, but I somehow missed their recent videos about Java APIs and 1.0.6 . It would have saved me a lot of time when I started to play with the Java domino-db API.

Few more words of warning. I've never used Kotlin before and I have not worked with Spring in the last 4 years. Actually, in the last year, I've written more C# code than Java, which will make my brain even more confused, so please use the code as an example, not a best practice - production-ready recommendation. I asked Martin Jinoch, who is a big fan of Kotlin, to do a quick review - he didn't tell me that the code is all wrong, so it should be ok. And it works too ...


The main goal of this post is to create a CRUD REST API that works with simple employee data - first name, last name, social security number. Since we are on Domino, we'll make the SSN encrypted. The API will have OpenAPI specification and we'll also serve Swagger UI.


When working with Kotlin, Intellij Idea is the best IDE you can choose. There are plugins/extensions for Eclipse and VS Code, but these can't match Idea. One of the reasons is that Kotlin and Idea are primarily developed by the same company - Jetbrains, so they try to make the experience as pleasant as possible. I've used Android Studio, which is based on Idea,  in past, so I knew a bit how to work with the IDE, but I was still surprised how easy it is to use. I use the Ultimate version that has excellent Spring support too.

 Getting started

If you are starting with a new Spring Boot project, the best way is to open spring initialize. It's also integrated into Idea, so you can launch it directly from the new project wizard too. You then just configure your environment - language, build tool, version, and Spring dependencies.

Then you can download the package, or if running directly in the IDE, get the project ready.


We will need few more dependencies


As I've mentioned in my previous posts, domino-db is not available in public Maven repositories, so you'll either need to add it to yours or load it directly from the file system. I'm serving it from my Nexus server, so I just need to add


springdoc-openapi java library helps automating the generation of API documentation using spring boot projects. springdoc-openapi works by examining an application at runtime to infer API semantics based on spring configurations, class structure and various annotations.

That should be all we need for now.

domino-db infrastructure

In a normal Spring project, you'd probably use Spring Data project for your data-source. We don't have this luxury with Domino, so we need to manage the connection and queries manually. I've decided to create 2 beans - one for the executor service and one for the database.

You can see the details here . In Kotin, it's encouraged to have multiple declarations, e.g. classes, in one file as long as they are closely related. I always struggled with this in C#, but I guess I'll get used to it here. This file contains full definition of structure in application properties and creations of these beans.
My configuration is:


Repositories are responsible for direct data manipulation in your data source. In my case it wraps the CRUD methods that are implemented using domino-db apis. For example the findAll method runs a simple DQL.

Usually, the most annoying part of data manipulation is mapping between raw data and data models or DTOs. I did it here using brute-force, but at least I've used a simple extension function that allowed me to create getItemValueString method that's not available in domino-db Document. It's a nice Koltin feature (and also in C#). 

That's basically all code that's needed for the read operation. 


Creating a REST API is super easy in Spring, so there is not much to write about.

Now we have a REST API and we can try to use it.

Other operations

Create, delete, and update operations are pretty straightforward too. Check the source code for the details

Overall, I've written less than 200 lines of code (maybe even less than 100 as I don' have to count imports and fragments that were generated for me) and I have a working API. I like it. 


The SSN item is being saved as encrypted. I'm not providing an encryption key, so it's just encrypted for the current technical user. It would be easy to add PublicEncryptionKeys field to the document and encrypt it using it. 

Error handling

One tricky part of domino-db module is error handling as usually all you get is 'Request failed' message. In many cases, you can dive deeper into the nested exceptions and in BulkOperationException find details for individual documents. In this code, I'm doing this on REST API level

During testing, I've seen that some operations don't return the unid, but it helps a lot with troubleshooting. E.g. if I don't provide password for my Notes ID - and I can't use encryption - during creation I get a nice message:


As always, the code is available in my github repo -

In the future, you may be able to use something like Project Keep to build APIs on top of Domino data, but it's not available yet.

I really like Kotlin. With my sloppy fingers, every character I type in my code is a potential typo and a bug, so when I can write less, I make fewer bugs. Working with IntelliJ Idea was also a nice experience, so I will continue to use it in the future.

Domino-db API so far works just fine, but I should also test the performance with some production-level load, not just single calls.


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