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 ...

Goal

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.



IDE

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.

Dependencies

We will need few more dependencies

domino-db

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
        <dependency>
            <groupId>com.hcl.domino</groupId>
            <artifactId>domino-db</artifactId>
            <version>1.0.0</version>
        </dependency>

springdoc-openapi-ui

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.
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.4.8</version>
        </dependency>

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 https://github.com/mpradny/appdevpack-kotlin-rest/blob/master/src/main/kotlin/net/pristo/kotlin/proton/config/Domino.kt . 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:

Repository

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. 

REST API

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. 

Encryption

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:


Conclusion

As always, the code is available in my github repo - https://github.com/mpradny/appdevpack-kotlin-rest

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.

Comments

Popular posts from this blog

XPages Date Field Issue: Solving the One-Day Jump on Every Save

 A user reported a very strange issue - when a document with a date field is saved, it changes the value one day to the past. With every save. But only for some dates, not all. It turned out to be a mystery that goes deep into XPages and Notes/Java APIs. I've posted a sample on OpenNTF Discord and Serdar tried it on his server - no issue. But he uses the GMT zone and I have CET (Windows set to UTC+1 - Amsterdam, Berlin... to be precise). To cut it short, the issue is caused by daylight saving interpretation between Notes and Java. The date fields (because XPages have no notion of real date-only fields) are stored with 00:00 time component and for some dates the conversion back to Java Date resulted in 23:00 on the previous day. XPages that get the date component as String for the input field, which is then saved back as a previous day during document save. The app is full of date fields and I couldn't add custom logic to every save operation, so I tried to fix it at XPages conv

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

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