DEV Community: Jan Mewes

Practicing programming with sandbox projects

Jan Mewes — Sat, 06 Dec 2025 10:56:24 +0000

This blog post describes an approach for experimenting with programming languages and frameworks by using minimal starter projects that cannot do much more than outputting "Hello, World!". Those projects can then be used to experiment with the respective technology.

The Angular framework is used as an example, but the idea for this approach is to be applicable to other technologies as well.

Infrastructure

The Bash snippets below have been tested on a basic Ubuntu Droplet from the DigitalOcean cloud service provider. Besides the Linux operating system, the Droplet has the Version Control System git preinstalled.

Since the example uses Angular, additionally Node.js and the Angular CLI need to be installed:

# Install Node.js as described here: https://nodejs.org/en/download
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 24

# Install Angular CLI as described here: https://angular.dev/installation#install-angular-cli
npm install -g @angular/cli

Also, configuring the git user data may be necessary, and setting the default branch to main might be useful for consistency with other projects:

git config --global user.email "you@example.com"
git config --global user.name "Your Name"

git config --global init.defaultBranch main

Create new project

The Angular CLI provides the ng program, which can be used to create a new Angular project.

# Create project using the Angular CLI tool
ng new angular_sandbox --defaults

# Change directory into the project directory
cd angular_sandbox

# Check git repository
git log

The expected output from git log is an initial commit for the sandbox project like this:

Author: Your Name <you@example.com>
Date:   Fri Dec 5 06:37:07 2025 +0000

    initial commit

Create experiment branch

By using a separate branch for the experiments, it is possible to keep track of the lessons learned and still start the subsequent experiments with the simplest possible project setup.

# Switch back to the main branch, if necessary
git switch main

# Create new branch
git switch --create 2025-12-03/example-experiment

# Apply changes in a text editor

# Commit all changes
git add .
git commit -m "Try out something"

✏️ Tip
If a remote git repository is used, the branch can be pushed to the remote repository. The used text editor may be able to generate a link to the file on the remote repository with the current commit (see e.g. jetbrains.com).

Update main branch

If it turns out that a certain change is done again and again for all experiments, then it may be useful to include it in the main branch.

# Switch back to the main branch
git switch main

# Install commonly used dependencies
ng add @angular-eslint/schematics --defaults
npm install prettier \
  prettier-eslint \
  eslint-config-prettier \
  eslint-plugin-prettier \
  eslint-plugin-simple-import-sort \
  --save-dev

# Commit changes
git add .
git commit -m "Add eslint and prettier dependencies"

Cover image created by Johan Eklund and licensed under CC BY 2.0

Getting started with Spring RestClient

Jan Mewes — Sun, 15 Sep 2024 18:49:41 +0000

With Spring Framework v6.1 and Spring Boot v3.2 the RestClient class was introduced as alternative to RestTemplate. It can be used for creating synchronous outbound HTTP requests with a fluent API. This blog post provides examples of how the RestClient can be used in a Spring Boot project.

Getting started

The first step in creating an HTTP request is to create an instance of the RestClient class. Using the RestClient.Builder, a common base URL can be used for all requests.

The RestClient then provides e.g. the methods post(), put(), get() and delete() for starting to build a request. The request can then be provided with a specific resource path, request headers, etc. Finally, by calling retrieve().toEntity(String.class) the request is executed and the response payload is mapped to a String.

import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestClient;

@Component
class ExampleRestClient {

    private final RestClient restClient;

    ExampleRestClient() {
        restClient = RestClient.builder()
            .baseUrl("https://example.com")
            .build();
    }

    ResponseEntity<String> getExample() {
        return restClient.get()
            .uri("/example")
            .header("X-Foo", "bar")
            .retrieve()
            .toEntity(String.class);
    }
}

Query parameters

For URLs with query parameters (aka. URL Search Params), the UriBuilder can be used.

@Component
class ExampleRestClient {

    // ...

    ResponseEntity<String> getExample() {
        return restClient.get()
            .uri(uriBuilder -> uriBuilder.path("/example").queryParam("foo", "bar").build())
            .retrieve()
            .toEntity(String.class);
    }
}

Logbook

Sometimes it may be useful to log the details of the outgoing requests and incoming responses. For this purpose, the Logbook library may be used in combination with the Apache HTTP client.

To make it work, an Apache HTTP client needs to be created, with a Logbook instance registered as interceptor. Then the Apache HTTP client needs to be provided to the RestClient.Builder as the client request factory to be used.

import org.apache.hc.client5.http.impl.classic.CloseableHttpClient;
import org.apache.hc.client5.http.impl.classic.HttpClientBuilder;
import org.springframework.http.ResponseEntity;
import org.springframework.http.client.HttpComponentsClientHttpRequestFactory;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestClient;
import org.zalando.logbook.Logbook;
import org.zalando.logbook.core.WithoutBodyStrategy;
import org.zalando.logbook.httpclient5.LogbookHttpExecHandler;

@Component
class ExampleRestClient {

    private final RestClient restClient;

    ExampleRestClient() {
        final Logbook logbook = Logbook.builder()
            .strategy(new WithoutBodyStrategy())
            .build();
        final CloseableHttpClient client = HttpClientBuilder.create()
            .addExecInterceptorFirst("Logbook", new LogbookHttpExecHandler(logbook))
            .build();

        restClient = RestClient.builder()
            .requestFactory(new HttpComponentsClientHttpRequestFactory(client))
            .baseUrl("https://example.com")
            .build();
    }

    ResponseEntity<String> getExample() {
        return restClient.get()
            .uri("/")
            .retrieve()
            .toEntity(String.class);
    }
}

The following dependencies are required for this:

<dependency>
    <groupId>org.apache.httpcomponents.client5</groupId>
    <artifactId>httpclient5</artifactId>
    <version>5.3.1</version>
</dependency>

<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>logbook-core</artifactId>
    <version>3.9.0</version>
    <scope>test</scope>
</dependency>

<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>logbook-httpclient5</artifactId>
    <version>3.9.0</version>
    <scope>test</scope>
</dependency>

After enabling the TRACE level for the org.zalando.logbook Logger in the application.properties, the outbound HTTP requests from the ExampleRestClient will be logged.

logging.level.org.zalando.logbook: TRACE

Here is an example of the log messages created for the example request:

2024-09-15T20:34:24.013+02:00 TRACE 1892 --- [hello-spring] [nio-8080-exec-1] org.zalando.logbook.Logbook              : Outgoing Request: b7259e7febeb49f5
Remote: localhost
GET https://example.com/ HTTP/1.1
2024-09-15T20:34:24.570+02:00 TRACE 1892 --- [hello-spring] [nio-8080-exec-1] org.zalando.logbook.Logbook              : Incoming Response: b7259e7febeb49f5
Duration: 564 ms
HTTP/1.1 200 OK
Accept-Ranges: bytes
Age: 476506
Cache-Control: max-age=604800
Content-Type: text/html; charset=UTF-8
Date: Sun, 15 Sep 2024 18:34:24 GMT
Etag: "3147526947+gzip"
Expires: Sun, 22 Sep 2024 18:34:24 GMT
Last-Modified: Thu, 17 Oct 2019 07:18:26 GMT
Server: ECAcc (mid/8751)
Vary: Accept-Encoding
X-Cache: HIT

References

Create UML Class Diagrams for Java projects with IntelliJ IDEA and PlantUML

Jan Mewes — Sat, 02 Mar 2024 13:52:49 +0000

Introduction

UML Class diagrams can be useful for understanding complex code or for designing major new features. However, hand-drawing those diagrams may require too much time and effort. To reduce those costs, the Ultimate edition of IntelliJ IDEA has the bundled "Diagrams" plugin which can generate UML Class diagrams for Java and Kotlin code.

For the examples used below, the source code of the Apache Kafka project is being used (see github.com).

Create diagram

Given that the project is already set up in IntelliJ, select the files to be included in the diagram in the Project window. Then right-click the files and select "Diagrams > Show diagram" from the context menu.

More classes can be added later on to the diagram by pressing "Space" from within the diagram and then typing in the class name. Or by dragging and dropping the file file into the diagram.

Configure diagram

To include the class relationships, activate the "Show Dependencies" options. Sometimes it may also be useful to activate the options next left to it.

Export

The diagram can be exported as a PlantUML file with the help of the "Export Diagram" icon and the "Export to file > PlantUML" context menu.

Normalize generated code

PlantUML offers plenty of configuration options. The options that were used by the Diagrams plugin may be changed by running a custom Python script which is performing string-replacements in the generated file.

python3 normalize.py example.puml

Here is how the normalize.py script may look like:

#!/usr/bin/env python3

#
# normalize.py by janux_de is marked with CC0 1.0 
#
# https://creativecommons.org/publicdomain/zero/1.0/
#

import argparse
import re

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument('file', nargs=1)
    args = parser.parse_args()
    path = args.file[0]

    f = open(path, "r")
    original_lines = f.readlines()
    f.close()

    updated_lines = []
    for line in original_lines:
        # Replace theme configuration with "hiding empty members" flag
        line = line.replace("!theme plain", "hide empty members")

        # Remove cardinality indicators
        line = re.sub(r'"\d+"', "", line)

        # Remove variable names
        line = re.sub(r'-> ".*?"', "-> ", line)

        # Remove text on edges
        line = re.sub(r' : .*', "", line)

        # Simplify dashed lines
        line = re.sub(r'-\[.*?dashed\]-', "..", line)

        # Simplify plain lines
        line = re.sub(r'-\[.*?plain\]-', "--", line)

        # Replace composition symbol with directed association
        line = line.replace("*-->", "-->")

        # Use a more intuitive flavor for inheritance symbols
        line = line.replace("--^", "--|>")
        line = line.replace("..^", "..|>")

        updated_lines.append(line)

    f = open(path, "w")
    f.writelines(updated_lines)
    f.close()

Further processing

The diagram may then be manually edited, e.g. with the help of the PlantUML plugin for VS Code.

Finally, the PlantUML file may be compiled to a PNG with the help of this Docker command:

cat example.puml | docker run --rm -i \
    dstockhammer/plantuml:1.2023.13 \
    -pipe -tpng > example.png

(see github.com for the source code of the Docker image from the snippet above)

References

Spring: Adding OpenAPI validation to MockMVC tests

Jan Mewes — Sat, 13 May 2023 13:54:30 +0000

Motivation

Creating the OpenAPI specification (OAS) before the implementation of the API might lead to a better API design than the generation of the OAS from the implementation, the generations of the OAS from the tests, or not using OAS altogether.

However, this raises the need to validate that the implementation complies with the OAS. This may be done with Atlassian's open-source project swagger-request-validator as described below.

Also see

Overview

swagger-request-validator has a core component and allows integration with different testing approaches with a handful of sub-components. One of those sub-components is swagger-request-validator-mockmvc which integrates with Spring Mock MVC coming from spring-test that it used in the tests of the ksch.patientmanagment.impl project.

swagger-request-validator-core leverages jackson, io.swagger.core and io.swagger.parser to parse the test data and OAS. Then it matches them with the help of java-json-tools and reports violations if they don't match.

Those dependencies are visualized in the following UML Component diagram:

Implementation details

The swagger-request-validator library can be included by declaring the following dependencies in the build.gradle file:

dependencies {
  testImplementation('com.atlassian.oai:swagger-request-validator-core:2.34.1')
  testImplementation('com.atlassian.oai:swagger-request-validator-mockmvc:2.34.1')
}

To allow the usage of the allOf feature of OAS, the withResolveCombinators option of OpenApiInteractionValidator needs to be set to true (see swagger-request-validator#315) and additional properties need to be ignored.

public static OpenApiInteractionValidator createValidator(String specificationUrl) {
    LevelResolver levelResolver = LevelResolver.create()
        .withLevel("validation.schema.additionalProperties", ValidationReport.Level.IGNORE)
        .build();
    ParseOptions parseOptions = new ParseOptions();

    parseOptions.setResolve(true);
    parseOptions.setResolveFully(false);
    parseOptions.setResolveCombinators(true);

    return OpenApiInteractionValidator
        .createForSpecificationUrl(specificationUrl)
        .withLevelResolver(levelResolver)
        .withParseOptions(parseOptions)
        .build();
}

Then the openApi() validation can be added to the MockMVC expectations in the test.

OpenApiInteractionValidator validator = OasValidatorFactory.createValidator(
        "../../docs/openapi.yml"
);

mockMvc.perform(post("/api/patients").accept(APPLICATION_JSON))
        .andDo(print())
        .andExpect(status().isOk())
        .andExpect(jsonPath("_id", is(notNullValue())))
        .andExpect(openApi().isValid(validator))
;

References

Create WebJar with Gradle and GitHub Packages

Jan Mewes — Mon, 31 Oct 2022 17:04:23 +0000

A WebJar is a JAR file that contains HTML/CSS/JavaScript resources. Those resources are then served by a Java-based web server. This blog post shows how WebJars can be created from scratch, using Gradle as build system and GitHub Packages as repository.

Introduction
Example WebJar project
Create GitHub repository
Publish to GitHub Packages
Example App project

Introduction

Overview

The "example-webjar" project hosts an HTML file called "greeting.html" that contains the text "Hello, World!". That file is packaged in a WebJar and then published to GitHub packages (1). The "example-app" project downloads the WebJar from there (2) and serves the "greeting.html" when it is started (3).

Dependencies

To follow along with the steps described below, the following tools need to be installed on the computer:

Further, it is necessary to have a GitHub account.

Example WebJar project

First, create a new directory for the WebJar project. In this directory create a file called settings.gradle that specifies the project name:

rootProject.name = 'example-webjar'

Then create a file called build.gradle with the declaration of the WebJar identifiers:

apply plugin: 'java'
apply plugin: 'maven-publish'

publishing {
  publications {
    mavenJava(MavenPublication) {
      groupId = 'com.github.experimental-software'
      artifactId = 'example-webjar'
      version = '0.0.1'

      from components.java
    }
  }
}

Now create the sub-directory src/main/resources/META-INF/resources. And in this directory, create an HTML file called greeting.html:

<html>
  <body>
    <h1>Hello, World!</h1>
  </body>
</html>

Create GitHub repository

Next, create a new GitHub repository for the Example WebJar as explained at docs.github.com.

Then add the code created above to that repository:

git init
git add .
git commit -m "Initial commit"
git remote add origin git@github.com:experimental-software/example-webjar.git
git push

Publish to GitHub Packages

The repository where the release should be published has to be registered in the build.gradle file created above:

publishing {
  // publications { ...

  repositories {
    maven {
      name = "GitHubPackages"
      url = "https://maven.pkg.github.com/experimental-software/example-webjar"
      credentials {
        username = System.getenv("GITHUB_ACTOR")
        password = System.getenv("GITHUB_TOKEN")
      }
    }
  }
}

With the help of GitHub Actions certain scripts can automatically be executed when certain events happen in the repository. If the following file gets added, GitHub will automatically build and publish a new package after the creation of a release:

.github/workflows/release.yml:

name: Publish WebJar to GitHub Packages
on:
  release:
    types: [created]
jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-java@v1
        with:
          distribution: "temurin"
          java-version: 17
      - uses: gradle/gradle-build-action@v2
        with:
          gradle-version: current
      - run: gradle publish
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Those changes need to be committed and pushed into the repository.

git add .
git commit -m "Add publish workflow"
git push

To trigger the workflow, create a release in the GitHub user interface, as described at docs.github.com.

After a few moments, the workflow will start to run and can be observed in the "Actions" tab.

Example App project

The WebJar is now ready to be used. To try it out, create a new directory "example-app" for a new Java project.

In this directory, create a settings.gradle file that declares the project name:

rootProject.name = 'example-app'

Then create a file called build.gradle that declares a dependency on Spring Boot in the Maven Central repository and the example webjar in the GitHub Packages repository:

plugins {
  id 'org.springframework.boot' version '2.7.5'
  id 'io.spring.dependency-management' version '1.0.15.RELEASE'
  id 'java'
}

repositories {
  mavenCentral()

  maven {
    url = uri('https://maven.pkg.github.com/experimental-software/example-webjar')
    credentials {
      username = project.findProperty('gpr.user')
      password = project.findProperty('gpr.key')
    }
  }
}

dependencies {
  implementation 'com.github.experimental-software:example-webjar:0.0.1'
  implementation 'org.springframework.boot:spring-boot-starter-web'
}

Then create a file called DemoApplication.java in the directory src/main/java/com/example/demo that contains the "main" method of the app:

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

Before starting the app, it is necessary to create an access token with the "read:packages" scope, as described at docs.github.com.

This access token should be registered in the global Gradle properties, e.g.:

~/.gradle/gradle.properties:

gpr.user=jdoe
gpr.key=ghp_**********************************

Eventually, start the app by calling the bootRun Gradle task:

$ gradle bootRun

> Task :bootRun

...

2022-10-30 20:35:56.825  INFO 2386 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8080 (http) with context path ''

When the URL http://localhost:8080/greeting.html is opened in a web browser, the HTML file created above should be shown:

Java: Finding out the root cause of an unexpected log message

Jan Mewes — Sat, 02 Apr 2022 10:06:31 +0000

Imagine, you are developing a Java/Spring app. You are correctly following a tutorial for configuring a database. But it doesn't work as expected. There is a log message which gives a hint about the root cause, but you don't know from where exactly it is coming. This blog post explores how the hint in this error message can be leveraged to fix the underlying problem.

Example

Even though the datasource configuration has been configured with the URL jdbc:h2:mem:ksch, still the default URL jdbc:h2:mem:testdb is being used.

2022-04-02 09:53:26.037  INFO 27600 --- [           main] o.s.j.d.e.EmbeddedDatabaseFactory        :
Starting embedded database: url='jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=false', username='sa'

JAR search

It would be great if there would be a tool to search for the log message over all the JAR files in the Maven caches. And it turns out there is a tool that can do that:

https://github.com/Genivia/ugrep

Installation

ugrep can be used across a wide range of operating systems. However, there is no Ubuntu package available. But the project's Dockerfile is based on Ubuntu. So, from there we can get the steps required to compile the tool manually:

sudo apt-get install -y \
  nmake \
  vim \
  git \
  clang \
  wget \
  unzip \
  libpcre2-dev \
  libz-dev \
  libbz2-dev \
  liblzma-dev \
  liblz4-dev \
  libzstd-dev \
git clone https://github.com/Genivia/ugrep
cd ugrep/
./build.sh
sudo make install

Search query

Now we can search for the suspicious log message in the Maven caches which contain all of the project's dependencies.

$ cd ~/.m2/repository/
$ ugrep -z "Starting embedded database"
Binary file org/springframework/spring-jdbc/5.2.7.RELEASE/spring-jdbc-5.2.7.RELEASE.jar{org/springframework/jdbc/datasource/embedded/EmbeddedDatabaseFactory.class} matches

So, it is coming from the "spring-jdbc" project and we can search there for the file and line from where the log message originates:

https://github.dev/spring-projects/spring-framework/tree/971f665eb1e8cd9e8a0c788a8f5612f815894082/spring-jdbc

Disclaimer: If you look closely at the name of the logger in the original log message, you might be faster to find the right source file to introspect. But that is too easy, isn't it?

Debug

After having found the log message in the source code, we can set a breakpoint and start the app in debug mode. By following the data flow with further browsing in the IDE, we can logically deduce the root cause of the problem.

Solution

In this case, it turned out that the root cause was a custom datasource which canceled out the auto-configuration:

@Configuration
class BffConfig {

    @Bean
    public EmbeddedDatabase dataSource() {
        return new EmbeddedDatabaseBuilder()
            .setType(EmbeddedDatabaseType.H2).addScript("org/springframework/session/jdbc/schema-h2.sql").build();
    }
}

The solution was delete the custom datasource builder and move the init script into the profile configuration:

spring:
  datasource:
    data: classpath:org/springframework/session/jdbc/schema-h2.sql

References

Run a Bash command after file changes [Linux/macOS]

Jan Mewes — Sat, 12 Feb 2022 09:43:38 +0000

This blog post shows how to run a Bash command every time a file changes on a UNIX system. To achieve this goal, we can use the entr project. The snippets in this post have been tested on Ubuntu and macOS.

Setup

Ubuntu

On Ubuntu, entr can be installed with APT:

sudo apt-get update
sudo apt-get install entr

See https://howtoinstall.co/en/entr for further details.

macOS

On macOS, entr can be installed with Homebrew:

brew install entr

See https://formulae.brew.sh/formula/entr for further details.

Usage

To execute a Bash command every time a file changes, we first need to create a file, e.g. with the help of the touch program:

touch /tmp/example.txt

Now we can pipe the name of the file into the entr program and declare a Bash command which should be executed every time the file changes:

echo "/tmp/example.txt" | entr bash -c "echo 'File changed.'"

If you now open the file /tmp/example.txt in a text editor, you will see "File changed." printed to the terminal, every time you save the file.

For further information, refer to the homepage or the source code of the entr project:

Built-in Flutter Widget Finders

Jan Mewes — Tue, 07 Dec 2021 14:33:13 +0000

This blog post provides an overview of the options for querying widgets in widget tests which are available by default in the flutter_test library.

Identifier
- Find by key
Text
- Find by text
- Find by rich text
- Find by partial text
- Find by matching text
Type
- Find by class name
- Find by icon
- Find by element type
Hierarchy
- Find by descendant
- Find by ancestor
Miscellaneous
- Find by semantics label
- Find by image
- Find by tooltip
- Find by widget predicate
- Find by element predicate
References
Credits

Identifier

Find by key

find.byKey(const ValueKey('continue'))

Text

Find by text

find.text('Back')

Find by rich text

find.text('Close', findRichText: true)

Find by partial text

find.textContain('Back')

Find by matching text

find.textContain(RegExp(r'(\w+)'))

Type

Find by class name

find.byType(IconButton)

Find by icon

find.byIcon(Icons.inbox)

Find by element type

find.byElementType(SingleChildRenderObjectElement)

Hierarchy

Find by descendant

find.descendant(
  of: find.byType(TextField),
  matching: find.text('Key 1'),
)

Find by ancestor

find.ancestor(
  of: find.text('faded'),
  matching: find.byType('Opacity'),
)

Miscellaneous

Find by semantics label

find.bySemanticsLabel('Back')

Find by image

find.image(FileImage(File(filePath)))

Find by tooltip

find.byTooltip('Back')

Find by widget predicate

find.byWidgetPredicate(
 (Widget widget) => widget is Tooltip && widget.message == 'Back',
 description: 'widget with tooltip "Back"',
)

Find by element predicate

find.byElementPredicate(
  // finds elements of type SingleChildRenderObjectElement, including
  // those that are actually subclasses of that type.
  // (contrast with byElementType, which only returns exact matches)
 (Element element) => element is SingleChildRenderObjectElement,
 description: '$SingleChildRenderObjectElement element',
)

References

Credits

The source code snippets are adapted from the examples in the Flutter source code which is licensed under the BSD-3-Clause License.

Calling REST APIs from Dart and Flutter

Jan Mewes — Sat, 02 Oct 2021 10:27:29 +0000

When using API-based services, they often bring an SDK for some of the most popular languages, to facilitate the creation of apps using their API (e.g. Supabase or Google Ads). This blog post describes a concept for building your own SDK for consumption of any REST API, using the Dart programming language for use in an app using the Flutter framework.

Table of contents

Terminology
Context
Usage
- Package dependency declaration
- Instantiate API entry point
- Collection resources
- Singleton resources
- Error handling
- Usage in Flutter project
Testing
- Service tests
- Widget tests
Implementation details
- Overview
- Payload representations
- Tests

Terminology

The following table gives an overview of the abbreviations and technical terms used in the blog post.

Term	Description
API	Application Programming Interface; an interface of a software system that allows other software systems to use it.
SDK	Software Development Kit; a library that provides access to a third-party service for the respective programming language.
REST API	Short form for RESTful API which denotes a software architecture style based "representational state transfer".
KSCH	Kirpal Sagar Charitable Hospital; the target domain of the app to be built.
Workflow	A semi-automated business process.

Context

The backend service of the KSCH Workflows system provides a REST API for all the queries and commands which are needed for the apps in the KSCH workflows. The KSCH Dart Client facilitates it for all apps which use the Dart programming language to use that API by wrapping the low-level REST API with a high-level Dart API. The apps - e.g. the Registration desk, Pharmacy desk, and Administration app - can then use the KSCH Dart Client like any other Dart package.

In the text below, the KSCH Dart Client will also be referred to as "the SDK".

Usage

Before the discussion of the internal structure of the KSCH Dart Client, it will be shown how to use it.

Package dependency declaration

The KSCH Dart Client is a project-specific library that is of no use for the general Dart community. That's why the package is not published to the Dart package repository but is leveraging Dart's capability to declare dependencies directly on GitHub repositories.

dependencies:
  ksch_dart_client:
    git:
      url: https://github.com/ksch-workflows/ksch_dart_client
      ref: a85c7f0cb83087d13e207b1331bcf6f64676e995

Once the system is in production use, semantic versioning tags should be used instead of specific commit IDs.

Instantiate API entry point

The next step in using the SDK is to create an instance of the KschApi class. This class has a parameter for the base URL of the backend service so that it can be configured to be executed against the testing or production system.

KschApi api = KschApi('http://localhost:8080');

Collection resources

The first request to be done with the API is listing all patients with a GET request on the /patients collection resource.

http GET /patients

The basic idea of the SDK is that it provides a property in the api object for every supported resource. So, in the case of this example, there is a patients property. On its value is a method available for each operation that can be done on that resource. By calling this method, the HTTP call is triggered and delivers its response wrapped in a Future.

await api.patients.list();

Since collection resources are usually paged, the list method can take the index of the page to be requested as an optional parameter.

late PatientsResponsePayload response;
var page = 0;
do {
  response = await api.patients.list(page: page++);
  for (var patient in response.patients) {
    print(patient.id);
  }
} while (response.hasNextPage);

Singleton resources

For working with individual patients, the singleton resource can be used.

http GET /patients/${PATIENT_ID}

With the help of Dart's call method convention it is possible to invoke an object as a function. With this tool, a parameter can be passed to a collection resource for fluent access on a singleton resource below.

var response = await api.patients(patientId).get();
print(response.id);
print(response.name);
print(response.residentialAddress);

Each resource may also have sub-resources. All resource path elements act as a builder and the HTTP call is triggered only in the final method call.

await api.patients(patientId).visits.startVisit(VisitType.OPD);

Error handling

When there is an error response from the API, i.e. a status code >= 400, then an exception will be raised.

Usage in Flutter project

To avoid any HTTP-related ideas and too much business logic within the frontend widgets, the SDK is wrapped in a service layer. For every service, there is an interface which is widgets uses. During application start the main.dart file decides which service implementation should be used. Only that service implementation knows about the SDK and how to use it.

The SDK can now be used in any Dart project. To spare the Flutter code of dealing with the request details, the SDK can be wrapped into service classes.

class PatientServiceImpl implements PatientService {
  final KschApi _api;

  PatientServiceImpl(KschApi api) : _api = api;

  @override
  Future<Patient> get(String patientId) async {
    var response = await _api.patients(patientId).get();
    return Patient.from(response);
  }
}

The service can then be injected into the widget using e.g. get_it package.

class _RegisterPatientPageState extends State<RegisterPatientPage> {
  final PatientService patientService = GetIt.I<PatientService>();

  @override
  Widget build(BuildContext context) {
    return WebScaffold(
      title: 'Register patient',
      // ...
      floatingActionButton: FloatingActionButton(
        onPressed: () async {
          // ...
          final RegisterPatientResult? result = await showDialog(
              //...
              );
          if (result != null) {
            final createdPatient = await patientService.create(result.patient);
            // ...
          }
        },
        // ...
      ),
    );
  }
}

Testing

Service tests

The service classes can be tested with the help of the nock package.

void main() {
  late PatientServiceImpl patientService;

  setUpAll(nock.init);

  setUp(() {
    nock.cleanAll();

    patientService = PatientServiceImpl('http://localhost');
  });

  test('Should create patient in case of emergency', () async {
    var patientId = const Uuid().v4();
    givenCreatePatientResponse(MinimalPatientResponse(patientId).toJson());

    var result = await patientService.create(null);

    expect(result.id, equals(patientId));
  });
}

void givenCreatePatientResponse(dynamic body) {
  nock('http://localhost').post('/api/patients')..reply(200, body);
}

Widget tests

For the unit tests of the Flutter widgets, it should be fairly simple to create mocks for the used services.

Implementation details

Next comes a description of how the SDK is working internally.

Overview

The KSCH Dart Client as a small core with the KschApi class and model classes to be able to interpret pagination and links in the response payloads. The KschApi API provides an API for basic HTTP operations which can then be used by the resources. Further, it provides properties to the root resources.

The resources themselves are a tree structure, i.e. every resource can have subresources. Further, they know about their respective path element. Just before the actual HTTP called on the absolutePath, all the path elements of all ancestors are joined together.

The bases classes for the collection resources and identity resources are almost the same, with the difference that
identity resources know about their identification number.

Payload representations

The KSCH API uses JSON as the data format for request and response payloads. The code which does the mapping between JSON strings and Dart data types is generated with the help of the json_annotation library.

The Dart data types are a model of the JSON data structures. By default, the JSON properties are mapped with the Dart properties. If this is not possible, e.g. because a property in the JSON data starts with an underscore, then the mapping can be configured with custom annotation.

@JsonSerializable()
class VisitResponsePayload {
  @JsonKey(name: '_id')
  final String id;

  final VisitType type;

  final String opdNumber;

  final DateTime timeStart;

  VisitResponsePayload({
    required this.id,
    required this.type,
    required this.opdNumber,
    required this.timeStart,
  });

  factory VisitResponsePayload.fromJson(Map<String, dynamic> json) =>
      _$VisitResponsePayloadFromJson(json);

  Map<String, dynamic> toJson() => _$VisitResponsePayloadToJson(this);
}

The details of the fromJson and toJson methods are then generated from the Dart build runner.

dart run build_runner build

Tests

The unit tests for the SDK act also as API tests for the backend API. The expectation is that the backend has been locally started on port 8080. Then they are using the real API to make sure that all requests can be successfully executed and all responses successfully parsed. Later on, this test suite will also be included in the build process of the backend to make sure that no unintended breaking API changes are made.

Configure Flutter Web apps

Jan Mewes — Sun, 26 Sep 2021 17:25:59 +0000

When you are building a Flutter Web application that accesses a REST API, then the base URL of that API should be configurable, so that you can use a different API during development than the one which is used for the production system.

Dart Define

The simplest way to do that is to provide key-value declarations to the flutter run or flutter build web command, with the help of their --dart-define parameter.

flutter run -d chrome --dart-define="apiBaseUrl=https://example.com"

Here is the help text for that parameter:

Additional key-value pairs that will be available as constants from the String.fromEnvironment, bool.fromEnvironment, int.fromEnvironment, and double.fromEnvironment constructors. Multiple defines can be passed by repeating "--dart-define" multiple times.

Those declarations can then be used in the Flutter app with the methods String.fromEnvironment, bool.fromEnvironment, int.fromEnvironment, and double.fromEnvironment. If the app was called without the key-value declaration of the respective name, then a default value will be used. So, when building the app for the production system you can define the key-value pair. And when during development you can use the default value.

void main() {
  var apiBaseUrl = const String.fromEnvironment(
    'apiBaseUrl',
    defaultValue: 'http://localhost:8080',
  );
  initialiseContext(apiBaseUrl);

  runApp(RegistrationDeskApp());
}

GitHub Action

If you are using GitHub Pages as production system and the flutter-gh-pages action to update them, then the API base URL for the production API can be configured like this:

- uses: bluefireteam/flutter-gh-pages@v7
  with:
    customArgs: --dart-define="apiBaseUrl=https://example.com"

To avoid committing the API base URL to the Git repository, it should be provided as a GitHub repository secret.

Here are some pointers on how this can be set up in the repository settings:

And here is how the secret can be used:

- uses: bluefireteam/flutter-gh-pages@v7
  with:
    customArgs: --dart-define="apiBaseUrl=${{ secrets.API_BASE_URL }}"

Alternatives

As usual, there are other possibilities for how the problem under discussion could have been solved.

Main profiles

You might want to define different versions of the main.dart file for the respective environment. An example of this approach can be found in the Flutter template from Web Factory.

dotenv

The configuration could also have been done with a .env file and the flutter_dotenv plugin.

References

Adding links to a REST resource without the resource's notice

Jan Mewes — Tue, 03 Aug 2021 04:33:41 +0000

This blog post describes a concept for adding a link to a REST resource provided by a module A to a REST resource provided by module B without a dependency from A to B. The example implementation uses Spring Boot and Spring HATEOAS.

Context

The final goal is to render a screen with the patient's details. Besides editing the actual patient details like the patient's name and address, it should be possible to perform certain patient-related actions. Which actions can be performed is depending on the application state. For example, patients can only be discharged if they are currently admitted and have paid their bills.

REST API

When the app opens the patient details page, it executes the following HTTP request to receive the required data:

GET /patients/{patientId}

The actions which can be done on the patient details page depend on the application state. Following the HATEOAS concept for REST API design, the application state is indicated to the frontend applications with hyperlinks.

For example, it is only possible to start a new visit for a patient if there is no active visit, yet. So right after the creation of a new patient, the patient resource contains a "start-visit" in the "_links" section.

{
  "_id": "0a3949db-b2c4-4a8e-8ec4-5470f9a3e89e",
  "name": "John Doe",
  "address": "Guesthouse",
  "_links": {
    "self": {
      "href": "http://localhost:8080/api/patients/0a3949db-b2c4-4a8e-8ec4-5470f9a3e89e"
    },
    "start-visit": {
      "href": "http://localhost:8080/api/patients/0a3949db-b2c4-4a8e-8ec4-5470f9a3e89e/visits"
    }
  }
}

After the visit has been started, the "start-visit" link disappears from the patient resource. But if there are no open bills for the patient, the patient can be discharged via the "discharge" link.

{
  "_id": "0a3949db-b2c4-4a8e-8ec4-5470f9a3e89e",
  "name": "John Doe",
  "address": "Guesthouse",
  "_links": {
    "self": {
      "href": "http://localhost:8080/api/patients/0a3949db-b2c4-4a8e-8ec4-5470f9a3e89e"
    },
    "discharge": {
      "href": "http://localhost:8080/api/patients/0a3949db-b2c4-4a8e-8ec4-5470f9a3e89e/visits/4fc13f43-41db-494c-a265-aca01c3ae2a4/discharge"
    }
  }
}

Module structure

This scenario requires interaction between three modules of the hospital application: patient management, visit, and billing. The patient management module takes care of the patient's master data, the visit module takes care of the patient's journey through the hospital, and the billing module takes care of all payment-related things.

Circular dependencies between modules are not allowed to keep the system's complexity low. So to support the requirements described above, the visit module needs to know about the patient management module and the billing module. However, the patient management module must not know about the visit module and the billing module.

Dependency inversion

The way in which this can be achieved is that the class which takes care to create the patient resource, the PatientResourceAssembler, doesn't need to know which links need to be added to the patient resource, but it only needs to know that links need to be added.

So the PatientResourceAssembler requests from a central registry, the ResourceExtensionsRegistry, which links should be added to the REST resource representation of a Patient entity. Every module which has a dependency on the patient management module can add resource extensions for the patient resource to that central registry. To simplify that process, all the resource extensions need to be declared in a class derived from ResourceExtensions.

Implementation details

The following code snippet shows the part of VisitModuleResourceExtensions which registers a callback function for the Patient which is called whenever a REST resource for the Patient entity is requested. This is done with the help of the registerLink method provided by the base class ResourceExtensions.

@Component
public class VisitModuleResourceExtensions extends ResourceExtensions {

    // ...

    @Override
    public void init() {
        registerLink(Patient.class, patient -> createStartVisitLink(patient));
    }

    // ...
}

Within the method createStartVisitLink it is looked up whether there is already a patient with an active visit present. If yes, the "start-visit" link is not needed and the method returns an empty result. If no, then the "start-visit" link is generated with the help of Spring HATEOAS which can infer the resource path from the respective REST controller class and method.

private Optional<Link> createStartVisitLink(Patient patient) {
    if (visitRepository.hasActiveVisit(patient.getId())) {
        return Optional.empty();
    } else {
        var link = linkTo(methodOn(VisitController.class).startVisit(patient.getId())).withRel("start-visit");
        return Optional.of(link);
    }
}

The ResourceExtensions class then delegates the link registration to the ResourceExtensionsRegistry. And it takes care to execute the registration process at the time of the application startup, with the help of Spring's @PostConstruct annotation which marks a method that is executed right after a Spring Bean has been created.

@RequiredArgsConstructor
public abstract class ResourceExtensions {

    private final ResourceExtensionsRegistry resourceExtensionsRegistry;

    @PostConstruct
    protected abstract void init();

    protected final <T> void registerLink(Class<T> cls, Function<T, Optional<Link>> linkProvider) {
        resourceExtensionsRegistry.registerLink(cls, linkProvider);
    }
}

Finally, when the patient resource gets created, the required links are pulled from the extensions registry. By providing the patient entity to the getLinks method, the callback function described above can be called to generate the links dynamically.

@Component
@RequiredArgsConstructor
class PatientResourceAssembler implements RepresentationModelAssembler<Patient, PatientResource> {

    private final ResourceExtensionsRegistry resourceExtensionsRegistry;

    @Override
    public PatientResource toModel(Patient patient) {
        var result = PatientResource.from(patient);
        // ...
        result.add(resourceExtensionsRegistry.getLinks(Patient.class, patient));
        return result;
    }
}

Automatically publish a Flutter Web App on GitHub Pages

Jan Mewes — Fri, 14 May 2021 09:14:58 +0000

This blog post describes how to automatically publish a Flutter Web app to GitHub pages after every change in the repository.

It is assumed that you already know how to create and build a Flutter Web app. Further, it is assumed that your source Flutter source code is located in a Git repository hosted by GitHub. The GitHub Pages feature is available for free on public repositories but requires a paid plan for private repositories.

Publish to gh-pages branch

GitHub offers to run a script when there is a change on your branches or a tag was created. This feature is called GitHub Actions. In the spirit of the "Don't repeat yourself" principle, GitHub Actions can be grouped into modules. So, in this way, a group of steps can be grouped into one module.

There is already a GitHub Action available with which the goal of the blog post can be reached:

https://github.com/bluefireteam/flutter-gh-pages

You may refer to the action.yml of this GitHub Action to understand what it is doing.

What you need to do to apply this action is the following:

Create a directory ".github/workflows" in your repository
In the "workflows" directory, create a YAML file, e.g . "publish.yaml"

name: Publish to GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2
      - uses: subosito/flutter-action@v1
        with:
          channel: beta
      - run: flutter pub get
      - run: flutter test
      - uses: bluefireteam/flutter-gh-pages@v7
        with:
          baseHref: /registration-desk/

This tells GitHub to trigger this action whenever it sees a new change on the "main" branch. Then it creates a new Ubuntu VM on which the action will run. The first actual step will be the checkout of your repository. Then it installs Flutter on the VM. Finally, it builds the web app, creates a "gh-pages" branch in your repository, and commits the web app there.

Enable GitHub Pages

GitHub Pages is another feature of GitHub. It provides you a web server for static HTML files and a subdomain. The way to publish a website there is to enable the feature for a repository and then to tell it where to look for the files. Any branch can be the source of the website, and in this branch, you can choose whether you want to place the website in the repository root ("/") or in the "/docs" directory.

Go to the "Pages" settings, select the "gh-pages" branch as the source, keep the directory root, and then click on "Save".

The URL at which your website will be published is displayed in the banner above the source configuration. Mind that the initial rendering of the website may take a while. Afterwards, published updates will be available within 1-10 minutes.

Change base URL

If you are not using a custom domain for your GitHub Pages, then, by default, your URL will look like this:

https://ksch-workflows.github.io/registration-desk

The first part of the URL is the owner of the repository which can be an organization or a personal account. In this example, the owner is the organization "ksch-workflows". The domain of the URL is "github.io". Then after the domain is the resource path with the repository name. In this example, it is "registration-desk".

So, the "index.html" file of the website will be available under the following URL:

https://ksch-workflows.github.io/registration-desk/index.html

The problem with this is that the Flutter app, by default, assumes that it is located directly under the domain, not under a resource path. So, it assumes that the "index.html" file of the website will be available under a URL like this:

https://ksch-workflows.github.io/index.html

The result of this is that links to the root of the website will lead to "https://ksch-workflows.github.io/", not to "https://ksch-workflows.github.io/registration-desk". So, when the page tries to load the "main.dart.js" file which will render the page, then it tries to get it from "https://ksch-workflows.github.io/main.dart.js" which will yield a 404 Not Found error. The result of this is that you would see an empty page on the attempt to open "https://ksch-workflows.github.io/registration-desk" in a browser.

The solution for this is to change the base URL on the start page of the Flutter app:

diff --git a/web/index.html b/web/index.html
index fd7cfeb..7c588d9 100644
--- a/web/index.html
+++ b/web/index.html
@@ -11,7 +11,7 @@
     Fore more details:
     * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base
   -->
-  <base href="/">
+  <base href="$FLUTTER_BASE_HREF">

   <meta charset="UTF-8">
   <meta content="IE=Edge" http-equiv="X-UA-Compatible">

$FLUTTER_BASE_HREF will be filled with the --base-href parameter for the flutter build web command. If this is not provided, it will default to /.

flutter build web --release --base-href '/registration-desk/'

Credits

"Trans Canada Keystone Oil Pipeline" by shannonpatrick17 is licensed with CC BY 2.0. To view a copy of this license, visit https://creativecommons.org/licenses/by/2.0/