The Domino REST API not only provides secure access to "jsonified" Domino data,
but also comes with capabilities to ease integration. This enables one to quickly cater to the long tail of applications, giving them a home instead of loosing them to the shadow IT.

Once you know the steps, you can deploy new Single Purpose Applications (I modified the meaning of SPA a little) in no time.

No CORS, no headache

DRAPI allows to host static applications in the keepweb.d directory. "Static" might be a little misnomer (it only relates to the source files, not the interaction) since a JS file can make your experience quite interactive. Since you run on the same Domain and port as the API, you don't need to worry about CORS

Preparation

Your SPA will live in a sub directory of keepweb.d, so think about a name, we shall use demo42 here. Add a suitable icon (e.g. 72x72 px png), name it demo42.png and you are ready to roll. Let's assume our Domino API is running on https://api.demo.io

Work faster with vitejs

viteJS is one of the fronteand tools you want to learn. It features "hot module reload" to speed up development and, when done, packages your application nice and tidy.

It is easy to get started. You need a current version (22.x at time of writing) of nodeJS installed as development tooling.

npm create vite@latest demo42 -- --template vanilla
cd demo42
npm install

This will create the demo42 directory and scaffold the project for you. Before we get started with athe development, let's adjust the environment. In the root of the project create a file vite.config.js

import { defineConfig } from 'vite';

export default defineConfig({
  base: '/keepweb/demo42/',
  server: {
    proxy: {
      '/api': {
        target: 'https://api.demo.io',
        changeOrigin: true
      }
    }
  }
});

This allows you to develop in the comfort of your local machine's hot module reload which refreshes your app on svae automagically. It also fixes the path matching to its final destination. Next create in public the file manifest.json. This file defines the tile layout for the landing page.

{
  "short_name": "Demo 42",
  "name": "The final answer to all Demos",
  "start_url": ".",
  "display": "standalone",
  "theme_color": "#000000",
  "background_color": "#aacccc",
  "icon": "vite.svg"
}

You can play with colors and icons as you deem fit. Now we are ready to run the application:

npm run dev

Mainly as a note to self.

My default firewall setup

sudo ufw status
sudo ufw default allow outgoing
sudo ufw default deny incoming
grep IPV6 /etc/default/ufw
sudo ufw allow ssh
sudo ufw limit ssh/tcp comment 'Rate limit for openssh server'
sudo ufw allow 80/tcp comment 'Allow nginx HTTP'
sudo ufw limit 80 comment 'limit nginx HTTP'
sudo ufw allow 443/tcp comment 'Allow nginx HTTPS'
# For Domino mail
sudo ufw allow 1352/tcp comment 'Allow Notes replication'
sudo ufw allow 25/tcp comment 'Allow SMTP'
sudo ufw allow 587/tcp comment 'Allow SMTP'
sudo ufw allow 110/tcp comment 'Allow POP3'
sudo ufw allow 995/tcp comment 'Allow POP3s'
sudo ufw allow 143/tcp comment 'Allow IMAP'
sudo ufw allow 993/tcp comment 'Allow IMAPs'
sudo ufw allow from 1.2.3.4 'Allow the othe Domino'
sudo ufw enable

Java 14 (in a preview feature) introduced Records. In a nutshell: Records are (mostly) immutable objects with a greatly reduced amount of boilerplate code requirements. For a detailed introduction head over to Baeldung.

When records need update

The short answer: create a new record and use the existing as input. Let's look at an example:

public record Billionaire(String name, Long wealth, Temporal assessment) {

  public Billionaire cloneWithNewAssesment(Long newWealth, Temporal currentAssesment) {
    return new Billionaire(this.name, newWealth,currentAssesment);
  }
}

By itself this is a clean solution. You might add another function for unchanged assesment values. It gets messy when your records have a few more fields.

To address this, JEP 468 has neen proposed. Unfortunately it isn't seen anywhere in JDK 23 or JDK 24. Its syntax follows the spirit of boilerplate avoidance.

// Wealth changed
Billonaire theUpdated = oldBillionaire with { newWealth, newAssesment}

// Wealth unchanged
Billonaire anotherUpdated = oldBillionaire with { newAssesment}

Ultimately that's the way to go. Until then I needed a stopgap measure. It contains quite some boilerplate, following the builder pattern to make use easier

public record Billionaire(String name, Long wealth, Temporal assessment) {

  public BillionaireUpdater forCloning() {
    return new BillionaireUpdater(this);
  }
}

public class BillionaireUpdater {

  Long wealth = null;
  Temporal assessment = null;
  final Billionaire old;


  public BillionaireUpdater(Billionaire old) {
    this.old = old;
  }

  public BillionaireUpdater wealth(Long wealth) {
    this.wealth = wealth;
    return this;
  }

  public BillionaireUpdater assessment(Temporal assessment) {
    this.assessment = assessment;
    return this;
  }

  public Billionaire build() {
    return new Billionaire(
      old.name(),
      this.wealth == null ? old.wealth : this.wealth,
      this.assesment == null ? old.assesment : this.assesment
    );
  }
}

This approach keeps the "bulky" code outside the record, so once JEP 468 becomes available, updating should be managable leading to the ultimate removal of the Updater classes. The use is quite straight forward:

Billionaire theUpdated = oldBillionaire.forCloning()
                                    .wealth(insaneAmount)
                                    .assesment(dateOfAssesment)
                                    .build();

As usual YMMV

Getting your CI/CD pipeline right can be a daunting task. Here is one I had to address:

• Create a Quarkus Java application
• Compile it to a native executable
• Build a container for it
• Make the container available to both Linux and MacOS

The little irony, Docker on macOS or Windowsruns Linux under the hood.

The easy part - Quarkus

As I've written before it is easy to get started with Quarkus. It provides 5 ways to build containers, and detailed instructions to build a native image.

Building a native image looked daunting, with quite some prerequisites like GraalVM, CLI and C compiler. Luckily all this is available in a builder image, and a simple property settin in your pom.xml settles it:

I'm stronlgy in favour of Contract-First Development, when in comes to APIs. All invested parties, including your future self, agree on a neutral format, that both API providers and consumers will stick to. For REST APIs that is the OpenAPI spec

A popular critique of that approach is that it reeks of Big Design Upfront, happily skipping over the fact that nothing stops the teams to iterate over the specification too, one path, one schema at the time

The source of truth

The specification becomes the single authorative source for endpoints, security requirements, data formats and responses. While it is possible to generate the spec from source code, like. e.g. Spring or Quarkus, I see clear advantages to provide the specification standalone. Create it with a tool like Apicur.io, Stoplight or APIGit. Or use a plugin (or another) in your IDE or the other one

Once you have your first draft, you want to implement it server side. Eclipse vert.x offers the Vert.x OpenAPI Router for exactly that. You can get more details from my OpenAPI talk, or by peeking into the sample project (which used vert.x inside Quarkus).

When end-2-end testing applications that use an IdP, an IdP needs to be in a known state to make test repeatable.

Typically a container is used, with a configuration that needs to be reset before (and after) a run. Restoring the IdP configuration isn't ideal, since addring new test cases (e.g. adding a user with different properties to check application behavior). I propose a different approach: One-off IdP

Container without persistence

I start with an empty deployment of KeyCloak running in a docker container.

#!/bin/bash
#Run a clean KeyCloak
docker run --rm -p 8080:8080 \
       --name testcloak \
       -e KEYCLOAK_ADMIN=admin \
       -e KEYCLOAK_ADMIN_PASSWORD=password \
       quay.io/keycloak/keycloak:latest start-dev

The --rm parameter ensures that the container is discarded after use. There is no persistence flag (--mount), so when the container goes down, all data perishes (and that's intendet).

Configuration sequence

The empty KeyCloak only knows the realm master and the user admin. To turn it into a fully functional IdP we need to configure it. Since we want this process to be repeatable we shall use Keycloak's REST API. The documentation is complete, including an OpenAPI spec, but in a dictionary style, so all is good when you know what you are looking for. To learn what is needed the browser development tools while using the admin UI teach us the what.

The Domino REST API delivers collections using chunked transfer encoding. This has the advantage, that you can process results as they arrive. It produces the challenge that the usual client side code is designed to first wait for completion of the request. I wrote about the JavaScript solution a while ago, this is the Java edition.

Client choices

In JavaScript land the choice of client is simple: the Fetch API. In Java we have some choices:

• Since Java 11 there's a HttpClient in the JDK
• A very popular library is provided by the Apache HTTP components
• The SPRING framework, undisputed king of Java web frameworks, offers its own sset of clients
• The vert.x framework, which we used to build DRAPI, features its own client

There are probably more around. This article uses the JDK HttpClient. I'll skip the parts with Authentication and TLS handling, check the full example for details.

How it works

First we create an java.net.http.HttpClient. It takes care of the http version and the TLS context.

HttpClient getClient(SSLContext sslContext) {
  return HttpClient.newBuilder()
           .sslContext(sslContext)
           .build();
}

Then we build and execute the request. The magic is the BodySubscriber (more on that below).

Integer runGetRequest(HttpClient client, String url, String authHeader, BodySubscriber subscriber) throws Exception {
  HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Authorization", authHeader)
            .GET()
            .build();

  CompletableFuture<Integer> response =
          client.sendAsync(request, responseInfo -> subscriber)
          .whenComplete((r, t) -> System.out.println("Response: " + r.statusCode()))
          .thenApply(HttpResponse::body);

  return response.get();
}

You are developing a web application using Quarkus that consists of multiple (micro)services and a bunch of supporting libraries. Since maven modules provide sufficient isolation, you decide to use a parent project to keep dependency versions and parameters in sync and a Maven Reactor to build them together.

This blog post is for you. A special thanks to Alexey for helping out.

Moving parts

Our objective is to have a development setup where we can edit any of the services or libraries and then run them individually or all together. Ideally without the need to alter configurations between runs and the ability to deploy the setup using devcontainers (note: that's about the development setup, not about deploying the finished application). There are some moving parts:

• Quarkus CLI or Maven plugin
• Multi-Module Maven to keep libraries and services together and apart
• Maven profiles to conditionally modify maven runs
• Maven's <pluginManagement> and <dependencyManagement> to define configurations without activating them
• Your favourite Ide configured for Java and Quarkus
• Understand how VSCode's Tasks work
• Know how to setup DevContainers, especially when you need sidecars

That's a lot, let's dig in.

In the beginning was a test, that provided to be vital, but not sufficient. In modern application development we encounter:

• Unit Tests: testing a single function or a tuple of related functions
• Module Tests: testing bigger parts of your application, without actual external dependencies
• Integration or End-to-End tests: a.k.a life firing exercise

This entry isn't a discussion about the merits of how much and when test, but making tests easy to setup and distinguish

The manual way

We typically use Mockito, vert.x and REST-assured in our tests, so a typical test class would look like this:

@ExtendWith(VertxExtension.class, MockitoExtension.class, MyCustomExtension.class})
@Tag("UnitTest")
class SomethingTest {

  @Test
  does_it_blend() {
    // Test goes here
  }
}

It is just two lines, but everywhere. You can simplify it by creating your own annotation.

The custom annotation

@Target({TYPE, METHOD, ANNOTATION_TYPE})
@Retention(RUNTIME)
@ExtendWith({VertxExtension.class, MockitoExtension.class, MyCustomExtension.class})
@Tag("UnitTest")
public @interface UnitTest {
  // no action needed here, JUnit use only!
}

Now you simply use:

@UnitTest
class SomethingTest {

  @Test
  does_it_blend() {
    // Test goes here
  }
}

While this looks like minor cosmetic, it allows to control test extensions from a single place, your annotation source. Repeat that process for the other test types (ModuleTests, IntegrationTests, PerformanceTests etc.) you want to use.

In your pom.xml, in the build-plugins section you can use the tag to ensure all your unit test, but only them execute on mvn test and the others on mvn verify

<plugin>
  <!-- Run UNIT and MODULE tests, no backend calls -->
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-plugin</artifactId>
  <configuration>
    <groups>UnitTest,ModuleTest</groups>
  </configuration>
</plugin>

As usual YMMV

Know your patterns, so you don't re-invent the wheel. Patterns are like LEGO: You can combine them to larger patterns. One of those is the Hexagonal Achitecture officially called:

Ports and Adapters

proposed by Alistair Cockburn, one of the co-signers of the Agile Manifesto.

I've written about his work before and can highly recommend his latest book "Hexagonal Architecture Explained" (or for that matter any of his writings).

In a nushell, Ports and Adapters proposes an approach that leads to loosely coupled systems, that separates business logic from the software environment (think I/O, databses, API and UI) to facilitate clarity and ease of testing.

This post doesn't aim to explain it, for that you can refer to the Wikipedia article or, better, read the book but trying to describe how to apply it to Java in a Maven project.