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

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. 

Quick Tip - SSJS Error line numbers

 Recently, I had to work on an app with a pretty huge server-side JavaScript codebase. Several developers with different levels of XPages knowledge worked on that project in the past, to the code is quite hard to follow. My suggestion to rewrite all the code to Java was not accepted, so we have to deal with SSJS for now. One of the most annoying things, when you work with SSJS, is that in many cases you don't know where an error is happening. If you keep things simple and allow redirection to an error page (default or custom), you get a lot of information, and usually, you don't want to scare users with that or you may even want to do something useful in a catch block to recover from the problem. If the problem is thrown directly in the XPages JS engine, it's usually an InterpretException, which contains the context information, but if you have to deal with standard Java exceptions, you don't have it. Imagine a simple scenario with a function in a ssjs lib. When you run