wir bloggen über software_

Performance Testing with k6: A Field Report

2025-07-18T00:00:00-05:00

Project context

GA-Lotse is a modular web application for health authorities which is intended to simplify internal documentation and external communication with citizens. Different departments are mapped in modules, which then can be configured by the health authorities. To ensure that the application meets highest security standards, the data is stored separately for each module. This and other security features – such as the Zero Trust principle – lead to intrinsic performance losses, which is why performance testing was an important part of the project.

Selecting the load testing tool

It is often the case that you don’t have to implement everything yourself, so we looked for a tool which supports performance testing. Since we want to test a web application, the tool must allow browser testing. Our additional requirements were as follows:

The ability to write the test code in TypeScript, as we also use TypeScript for the frontend of the application and the end-to-end tests
Open-source availability of the tool
Executability on a self-hosted server (not a pure cloud solution)
Good reporting to visualize the results of the tests for us and the developers.

After evaluating several tools, we decided on k6. k6 supports browser tests, enables development in TypeScript and, in combination with Grafana and through individually definable metrics, offers comprehensive reporting.

Our setup

k6 runs the performance tests and generates some metrics, such as TTFB or the duration of the individual requests. However, in order to visualize these and other test results, we needed even more tools. We chose InfluxDB as the database, as it is optimized for storing data in a time-resolved manner. To visualize the results, we used Grafana-Dashboards because k6 belongs to Grafana and it provides an interface to InfluxDB. To query the data from the InfluxDB, we used the proprietary database query language Flux. However, this is not a long-term solution as Flux will probably no longer be supported – or only supported to a limited extent – in the next major version. We decided to use the tools locally and package them in Docker containers in order to be able to run the tests hardware-independently and not be dependent on cloud providers. Alternatively, there is the option of using Grafana Cloud k6 to avoid installing the tools locally.

Performance testing with k6

A test with k6 can be executed with a Javascript or TypeScript file (see example script).

import { Options, Scenario } from "k6/options";
import { schoolEntryBrowserTest } from "@/modules/browser/schoolEntryBrowserTest";
import { schoolEntryApiTest } from "@/modules/api/schoolEntryApiTest";

const scenarios: Record<string, Scenario> = {
  schoolEntryBrowser: {
    exec: 'schoolEntryBrowserTestFunction',
    executor: 'constant-vus',
    vus: 3,
    duration: '15m',
    options: {
      browser: {
        type: 'chromium',
      }
    }
  },
  schoolEntryApi: {
    exec: 'schoolEntryApiTestFunction',
    executor: 'ramping-vus',
    startVUs: 1,
    stages: [
      { target: 3, duration: '5m' },
      { target: 5, duration: '5m' },
      { target: 3, duration: '5m' },
    ]
  }
};

export const options: Options = {
  discardResponseBodies: true,
  scenarios: scenarios,
  systemTags: ['status', 'url', 'check', 'scenario'],
  setupTimeout: '5m',
};

export async function schoolEntryBrowserTestFunction() {
  await schoolEntryBrowserTest();
}

export async function schoolEntryApiTestFunction() {
  await schoolEntryApiTest();
}

This script defines options for the test and the test functions to be executed. The options are defined as JSON. An important option which determines the course of the test is scenarios. This is where executable scenarios can be defined, thus mapping the actual test.

To define a scenario one must define a function to be executed, as well as the number of executing parallel users, which in k6 are called Virtual Users (VU). The total duration of the scenario can be determined by specifying time periods. In addition, ramps can be defined to increase or decrease the number of parallel users during the test. Another way to influence the course of the test is to set a time interval in which a specific number of VUs should go through the scenario.

Several such scenarios can be defined for a test, which are then run using different configurations. To make this definition of the scenarios easier and faster than editing a long JSON file, we have developed a builder that dynamically creates the scenario configuration and makes it available on GitHub: https://github.com/cronn/k6-scenario-builder.

Our findings

During testing, we noticed a few things which need to be taken into account. First of all, it makes sense to have a dedicated machine available to run the tests. Since performance is not only affected by the load of many simultaneous users, but also by the amount of data in the database, we created both short spike tests as well as test scenarios that have a runtime of several hours in order to constantly increase the amount of data and simulate a kind of time-lapse of the actual use of the application. These tests can be carried out much more comfortably by an external machine than on your own laptop.

In addition, the execution of a test requires sufficient resources on the executing machine. Therefore, care should be taken to ensure that there are always free resources available during the execution of a test so as not to unintentionally influence the results. We noticed this when running browser tests with some VUs. Too many browsers open at the same time turned the machine into a bottleneck. Our solution to this is to define both scenarios and browser tests which depict the same user journey, but send the necessary requests directly to the backend in order to increase the load on the backend without accessing the browser. Such API scenarios are also well suited to quickly assemble a scenario and thus get an overview of the backend’s performance.

Another insight we gained was to test in an environment which was as close to production as possible. After all, the configuration of an environment, especially a complex microservice cluster, can have significant impact on performance. In addition to running the tests from another machine and testing on a production-like environment, it was still important for us to enable testing entirely on our own laptop. This allows developers to independently develop new scenarios and provide easy access to databases and logs.

It also occurred that we had exceeded professional limits by configuring our scenarios, especially during long tests. For example, we created an unrealistic number of appointments for one day or user, or even had too many users with the same permissions. Many different parameters can influence performance and should therefore be defined as early as possible, allowing us to avoid unnecessary test runs. Nevertheless, it was also important for us to deliberately exceed the known limits to test the limits of the application and then improve it where necessary. After all, the customer may not know their professional limits, or their limits might be reached through technical errors. The application should not become unusable because the user booked one appointment too many. One lesson learned was therefore to clarify professional limits at an early stage and to observe them in the tests.

Pros and Cons of k6

We ran into problems from time to time during testing with k6. A significant limitation of developing performance tests with k6 is a lack of a debugger. k6 uses its own JavaScript engine to execute the test code, and there is no built-in debugger. The Javascript engine also has other weaknesses which you should be aware of, such as that it does not support the popular fetch API. In the context of browser tests, methods such as goto() are a weakness, as they do not always work reliably in combination with Chromium, which occasionally leads to timing problems. In addition, locators must be identified via XPaths, which is very susceptible to regression, as well as often unsightly and long. Finally, the documentation of k6 is often relatively short.

However, k6 also has many advantages. The reporting in combination with InfluxDB and Grafana works very well. Meaningful plots can be quickly created in such a setup without much prior knowledge and then be displayed in a dashboard so that the test results can be analyzed and communicated. In addition, the parallel execution of different scenarios, each of which is also executed with parallel virtual users, works very well. It allows you to create complex scenarios which map different types of performance tests, such as load tests, spike tests, and soak tests. The fact that the test options (and especially the scenarios) are described in JSON is an advantage as it provides a smooth transition to the Typescript code. You also have the option of running the browser tests in headful mode, so that problems can be detected and fixed during execution.

Summary

Since we had constantly developed both our tests and setup during the test phase, an iterative approach paid off for us. We started with two simple scenarios for application-critical modules. In these initial scenarios, we realized that we needed more metrics and plots in our reports to analyze the results. Iteratively, we then added metrics to our tests and visualized them in the Grafana board. These metrics included information such as the duration of requests, the loading times of certain pages, or even the CPU and RAM usage of the executing machine. The duration of individual requests was particularly important for us, but which information is relevant depends on the application. Metric types built into k6 allow the collection of information to be flexibly designed. Working with k6 has shown us both strengths and weaknesses of the tool. Whether k6 is the best choice certainly depends on the use case, but for us it was a suitable tool despite some significant weaknesses.

Performance-Testing mit k6: Ein Erfahrungsbericht

2025-07-18T00:00:00-05:00

Projektkontext

GA-Lotse (Gesundheitsamt-Lotse) ist eine modular aufgebaute Webanwendung für Gesundheitsämter, die die interne Dokumentation und externe Kommunikation mit Bürgerinnen und Bürgern vereinfachen soll. Verschiedene Abteilungen eines Gesundheitsamtes sind in Modulen abgebildet, die für Gesundheitsämter konfiguriert werden können. Damit die Anwendung höchsten Sicherheitsstandards genügt, werden die Daten für jedes Modul separat gespeichert. Dies und weitere Sicherheitsfeatures wie das Zero-Trust-Prinzip führen zu intrinsischen Einbußen der Performance, weshalb das Testen der Performance ein wichtiger Teil des Projektes war.

Auswahl des Lasttesttools

Wie so häufig muss man nicht alles selbst implementieren, daher haben wir uns nach einem Tool umgesehen, das Performance-Testing unterstützt. Da wir eine Webanwendung testen wollen, sollte es Browsertests ermöglichen. Zudem waren unsere Hauptanforderungen folgende:

Die Möglichkeit den Testcode in TypeScript zu schreiben, da wir TypeScript auch für das Frontend der Anwendung und die Ende-zu-Ende-Tests verwenden
Open-Source-Verfügbarkeit des Tools
Ausführbarkeit auf einem selbstgehosteten Server (keine reine Cloud-Lösung)
Ein gutes Reporting, um die Ergebnisse der Tests für uns und die Entwickler zu visualisieren.

Nach der Evaluation mehrerer Tools haben wir uns für k6 entschieden. k6 unterstützt Browsertests, ermöglicht die Entwicklung in TypeScript und bietet in Kombination mit Grafana sowie durch individuell definierbare Metriken ein umfassendes Reporting.

Unser Setup

k6 führt die Performance-Tests aus und erzeugt dabei bereits einige Metriken, wie z.B. TTFB oder die Dauer der einzelnen Requests. Um diese und weitere Testergebnisse persistieren und visualisieren zu können, benötigten wir noch weitere Tools.

Als Datenbank haben wir uns für InfluxDB entschieden, da diese dafür optimiert ist, Daten zeitaufgelöst zu speichern. Zur Visualisierung der Ergebnisse haben wir Grafana-Dashboards genutzt, unter anderem da k6 zu Grafana gehört und es eine Schnittstelle zur InfluxDB bietet. Zur Abfrage der Daten aus der InfluxDB haben wir die proprietäre Datenbankabfragesprache Flux genutzt. Diese wird jedoch vermutlich in der nächsten Major-Version v3 nicht mehr oder nur noch eingeschränkt unterstützt.

Wir haben uns entschieden, die Tools lokal zu nutzen und sie in Docker-Container zu verpacken, um die Tests hardwareunabhängig ausführen zu können und nicht von Cloud-Anbietern abhängig zu sein. Alternativ besteht die Möglichkeit, Grafana Cloud k6 zu verwenden, um die lokale Installation der Tools zu vermeiden.

Performance-Tests mit k6

Ein Test mit k6 lässt sich mit einem Javascript oder TypeScript-File ausführen (s. Beispielskript).

import { Options, Scenario } from "k6/options";
import { schoolEntryBrowserTest } from "@/modules/browser/schoolEntryBrowserTest";
import { schoolEntryApiTest } from "@/modules/api/schoolEntryApiTest";

const scenarios: Record<string, Scenario> = {
  schoolEntryBrowser: {
    exec: 'schoolEntryBrowserTestFunction',
    executor: 'constant-vus',
    vus: 3,
    duration: '15m',
    options: {
      browser: {
        type: 'chromium',
      }
    }
  },
  schoolEntryApi: {
    exec: 'schoolEntryApiTestFunction',
    executor: 'ramping-vus',
    startVUs: 1,
    stages: [
      { target: 3, duration: '5m' },
      { target: 5, duration: '5m' },
      { target: 3, duration: '5m' },
    ]
  }
};

export const options: Options = {
  discardResponseBodies: true,
  scenarios: scenarios,
  systemTags: ['status', 'url', 'check', 'scenario'],
  setupTimeout: '5m',
};

export async function schoolEntryBrowserTestFunction() {
  await schoolEntryBrowserTest();
}

export async function schoolEntryApiTestFunction() {
  await schoolEntryApiTest();
}

In diesem Skript werden Optionen für den Test sowie die auszuführenden Testfunktionen definiert. Die Optionen werden als JSON definiert. Eine wichtige Option, die den Testverlauf bestimmt, ist scenarios. Dort können Szenarien definiert werden, die ausgeführt werden und somit den eigentlichen Test abbilden.

Für ein solches Szenario wird eine auszuführende Funktion, sowie die Anzahl an ausführenden parallelen Nutzern, die in k6 Virtual User (VU) genannt werden, definiert. Mit der Angabe von Zeiträumen kann die Gesamtdauer des Szenarios bestimmt werden. Außerdem können Rampen definiert werden, um die Anzahl der parallelen User während des Tests zu erhöhen oder zu verringern. Eine andere Möglichkeit den Testverlauf zu beeinflussen, ist, ein Zeitintervall festzulegen, in dem eine konkrete Anzahl an VUs das Szenario durchlaufen sollen.

Für einen Test können mehrere solcher Szenarien definiert werden, die mit unterschiedlichen Konfigurationen durchlaufen werden. Um diese Definition der Szenarien einfacher und schneller zu gestalten als ein langes JSON-File zu editieren, haben wir einen Builder entwickelt, der die Szenario-Konfiguration dynamisch erstellt und diesen auf GitHub zur Verfügung gestellt: https://github.com/cronn/k6-scenario-builder.

Unsere Erkenntnisse

Während des Testens sind uns einige Dinge aufgefallen, die es aus unserer Sicht zu berücksichtigen gilt. Zunächst ist es sinnvoll, eine dedizierte Maschine zur Verfügung zu haben, die die Tests ausführt. Da die Performance nicht nur durch Last vieler gleichzeitiger User beeinträchtigt wird, sondern auch von der Menge der Daten in der Datenbank, haben wir neben kurzen Spike-Tests auch Testszenarien erstellt, die eine Laufzeit über mehrere Stunden haben, um so die Datenmenge stetig zu erhöhen und eine Art Zeitraffer der tatsächlichen Nutzung der Anwendung zu simulieren. Diese Tests sind von einer externen Maschine deutlich komfortabler auszuführen als von dem eigenen Laptop.

Zudem benötigt die Ausführung eines Tests ausreichend Ressourcen auf der ausführenden Maschine. Daher sollte darauf geachtet werden, dass während der Ausführung eines Tests stets noch freie Ressourcen vorhanden sind, um nicht die Ergebnisse ungewollt zu beeinflussen. Dies haben wir bei der Ausführung von Browsertests mit einigen VUs bemerkt. Eine zu große Anzahl an gleichzeitig geöffneten Browsern hat die auszuführende Maschine zum Bottleneck gemacht. Unsere Lösung dafür ist, neben Browsertests gleichzeitig Szenarien zu definieren, die eine möglichst gleiche User-Journey abbilden, jedoch die nötigen Requests direkt ans Backend schicken, um somit die Last aufs Backend browserunabhängig zu erhöhen. Solche API-Szenarien eignen sich auch gut, um schnell ein Szenario zusammenzubauen und somit browserunabhängig einen Überblick über die Performance des Backends zu bekommen.

Eine weitere Erkenntnis von uns war, auf einer möglichst produktionsnahen Umgebung zu testen. Denn auch die Konfiguration einer Umgebung, gerade ein komplexer Microservice-Cluster, kann die Performance erheblich beeinflussen. Neben dem Ausführen der Tests von einer anderen Maschine und dem Testen auf einer produktionsähnlichen Umgebung war es für uns dennoch wichtig, auch das Testen vollständig auf dem eigenen Laptop zu ermöglichen. Dies ermöglicht die unabhängige Entwicklung neuer Szenarien durch die Entwickler und einen einfachen Zugang zu Datenbanken und Logs.

Es ist vorgekommen, dass wir durch die Konfiguration unserer Szenarios, vor allem bei langen Tests, fachliche Limits überschritten haben. Zum Beispiel haben wir unrealistisch viele Termine für einen Tag oder User angelegt, oder sogar zu viele User mit den gleichen Berechtigungen gehabt. Viele Größen können die Performance beeinflussen und sollten deshalb möglichst frühzeitig abgesteckt werden. Dadurch können wenig aussagekräftige Testläufe vermieden werden. Trotzdem war es uns auch wichtig, die bekannten Limits bewusst zu überschreiten, um die Reaktion der Anwendung zu testen und dort dann gegebenenfalls nachzubessern. Denn es ist ja nicht gesagt, dass der Kunde seine fachlichen Limits kennt oder diese durch technische Fehler nicht überschritten werden. Bei einem Termin zu viel sollte die Anwendung nicht unbedienbar werden. Ein Learning war für uns daher, fachliche Limits früh abzuklären und in den Tests zu beachten.

Vor- und Nachteile von k6

Während des Testens mit k6 sind wir immer mal wieder auf Probleme gestoßen. Eine erhebliche Einschränkung beim Entwickeln von Performance-Tests mit k6 ist ein fehlender Debugger. k6 nutzt eine eigene JavaScript-Engine, um den Testcode auszuführen, für die es keinen Debugger gibt. Die Javascript-Engine hat auch weitere Schwächen, denen man sich bewusst sein sollte. Beispielsweise unterstützt sie die verbreitete Fetch API nicht. Im Zusammenhang mit Browsertests sind Schwächen von k6, dass Methoden wie goto(), die darauf warten sollen, dass eine Seite geladen ist, im Zusammenspiel mit Chromium nicht immer zuverlässig funktionieren, was hin und wieder zu Timing-Problemen führt. Darüber hinaus müssen Locator über XPaths identifiziert werden, was sehr regressionsanfällig ist, sowie häufig unschön und lang. Zuletzt ist auch die Dokumentation von k6 häufig relativ knapp.

Einige andere Dinge haben sich als Vorteile von k6 herausgestellt. Das Reporting im Zusammenspiel mit der InfluxDB und Grafana hat wie erhofft sehr gut funktioniert. Über dieses Setup lassen sich ohne große Vorkenntnisse schnell aussagekräftige Plots erstellen und in einem Dashboard anzeigen, sodass die Testergebnisse analysiert und kommuniziert werden können. Außerdem funktioniert das parallele Ausführen von verschiedenen Szenarien, die jeweils ebenfalls mit parallelen virtuellen Usern ausgeführt werden, sehr gut. Dadurch lassen sich komplexe Szenarien erstellen, die verschiedene Arten von Performance-Tests wie Load-Tests, Spike-Tests und Soak-Tests abbilden. Dass die Testoptionen und insbesondere die Szenarien als JSON beschrieben werden ist sehr angenehm, da es einen fließenden Übergang zum Typescript-Code bietet. Außerdem hat man die Möglichkeit, die Browsertests in einem Headful Mode laufen zu lassen, sodass sich Probleme während der Ausführung erkennen lassen und behoben werden können.

Zusammenfassung

Da wir während der Testphase unsere Tests und unser Setup stetig weiterentwickelt haben, hat sich für uns ein iterativer Ansatz ausgezahlt. Wir sind mit zwei einfachen Szenarien für Module gestartet, die zu den wichtigsten in der Anwendung gehören. Bei diesen ersten Szenarien haben wir festgestellt, dass wir weitere Metriken und Plots in unseren Reports benötigen, um die Ergebnisse analysieren zu können. Iterativ haben wir dann Metriken zu unseren Tests hinzugefügt und im Grafana-Board visualisiert. Dies waren Informationen wie die Dauer von Requests, die Ladezeiten von bestimmten Seiten oder auch die CPU- und RAM-Auslastung der ausführenden Maschine. Für uns war vor allem die Dauer einzelner Requests von Bedeutung, welche Informationen relevant sind, hängt jedoch von der Anwendung ab. Durch in k6 eingebaute Metrik-Typen lässt sich die Erhebung von Informationen flexibel gestalten.

Die Arbeit mit k6 hat uns sowohl Stärken als auch Schwächen des Tools gezeigt. Ob k6 passend ist, hängt sicher vom Anwendungsfall ab, für uns war es aber trotz einiger signifikanter Schwächen ein passendes Tool.

Analyzing Business Reports with LLMs – Part 2

2025-06-24T00:00:00-05:00

Welcome back to our series on analysing annual reports with AI. In Part One we showed how the extraction of key figures from annual reports with LLMs (such as ChatGPT) works. Now we are going deeper and showing the final working solution, which we are using in cooperation with North Data.

We have already demonstrated how relevant information can be filtered out of the dense text of annual reports in a structured way. But if you want to scale this process in practice, you quickly reach its limits – be it in terms of accuracy across many different documents, the robust processing of complex layouts and tables, or the cost-effectiveness of large-scale analysis.

This is exactly where there have been many exciting developments. With Gemini Flash from Google, a model is available which reshuffles the cards for automated document analysis in terms of speed, contextual understanding, and the delivery of structured data.¹ In this second part, we will ask: what makes Gemini Flash so more powerful for this specific task than previous approaches or the classic OCR pipelines? How does it make the step from feasibility study to productive tool? Let us look under the hood.

Gemini extracts structured JSON code from PDFs.

The classic approach: OCR as the basis, but not the whole solution

Before we dive into Gemini’s capabilities, it is worth looking at the traditional way of extracting data from PDFs. This most commonly starts with Optical Character Recognition (OCR). OCR tools generate text from scanned documents or image-only PDFs by converting pixels into letters. The result is not only the raw text content, but often also its position on the page, usually in the form of coordinates or so-called bounding boxes for each recognized word or line.

OCR Bounding Boxes from Azure Document Intelligence.

However, for a meaningful analysis we need structured data, not continuous text. This is where the challenges begin.

The first hurdle lays in the structure in the pure text output being recognized. How do you automatically identify tables, related key-value pairs (such as “revenue: €10 million”) or semantically meaningful blocks? This often requires complex, downstream steps – whether purpose-built parsers, rule-based systems that look for specific patterns, or even separate machine learning models trained on tasks such as table recognition.

However, these downstream systems are often susceptible to layout changes. Small adjustments in the design of a report from one year to the next or the format differing between companies can throw off painstakingly created rules or parsers and make them unusable.

In addition, there is a lack of contextual understanding. OCR provides the text but does not understand its meaning. Recognizing that the term “Total Assets” on page 10 refers to the same metric as a detailed breakdown in a table on page 45 is beyond the capabilities of pure text recognition.

All these factors create complexity and thus lead to a high development and maintenance effort. It can be said that OCR is a valuable tool, but for the extraction of structured data it is usually only the first step in a complex and often fragile processing chain.

Our path to productive use: evaluation, model selection and integration

The leap from successful demonstration (as shown in Part 1²) to a reliable, scalable production system required a systematic approach and further developments in several areas.

Firstly, a solid evaluation was essential. To this end we manually curated a dataset of 100 representative English annual reports. For the most important key figures, the correct values (ground truth) were annotated by hand and collected in a table. Only with such a reliable basis can the quality of different models and approaches be objectively measured and tracked over time.

Secondly, we significantly expanded the scope of extraction. Instead of just a few key figures, the goal was now to reliably extract a wide range of over 20 relevant values per report. This includes, among other things, the wage costs, information on profit and loss, cash flow, but also data such as the average number of employees or the name of the auditor.

These more demanding goals led us to test different models. In the end, the choice fell on Gemini 2.0 Flash Lite: This model optimally combined all the decisive factors for our application.

LLM comparison based on the parameters "intelligence" and "price", via artificialanalysis.ai.

Quality & Speed: In our tests, Gemini 2.0 Flash Lite showed high accuracy for most of the targeted metrics, often keeping up with that of larger, more expensive models. Google itself positions the Flash models as optimized for tasks where it is important to maintain high speed and efficiency while maintaining high quality ³. Our experience confirms that the model lives up to its “flash” in its name in terms of processing speed.

Cost: A decisive factor for large-scale deployment is cost. Gemini 2.0 Flash Lite is significantly cheaper than the larger Pro models. Compared to older models like gpt-3.5-turbo-16k, which still cost about $3 per million input tokens in July 2023 ⁴, the Gemini Flash variant we used is cheaper by a factor of 40 ⁵! This makes the processing of thousands of reports economically viable.

Multimodality & Context: A significant advantage over plain text models or classic OCR pipelines is Gemini’s multimodality. Put simply, instead of just delivering the raw text and its coordinates (like traditional OCR), Gemini Flash can “read” the text and “see” the page layout at the same time. It “understands” how text is arranged in columns or tables, recognizes headings, and can interpret images or charts in the document. As a result, it is better at capturing context which the pure text order often does not convey. This is a great advantage, especially with the complex and varied layouts of annual reports. Coupled with the long context window, which allows the analysis of large document sections in one go, this is a decisive step forward.

This combination of good quality, high speed, low cost, and the ability to understand documents holistically made Gemini 2.0 Flash Lite a viable choice for our productive deployment in collaboration with North Data.

Gemini Flash in Action: The Workflow with Structured Outputs

The core of our approach combines the strengths of Gemini with pragmatic solutions to deal with the peculiarities of large documents.

A central problem with annual reports is that they often comprise hundreds of pages. While handing over the entire document to Gemini would be ideal for context, it is too expensive for mass use. To get around this problem, we have developed a multi-step approach: First, we still rely on proven OCR technology to extract the plain text of the entire document. This raw text then serves as the basis for a quick preliminary analysis using keywords. We look for terms and phrases that typically indicate relevant sections, such as “Consolidated Balance Sheet”, “Income Statement” or “Notes to the Financial Statements”.

Based on this analysis we then select the up to 100 pages that are most likely to contain the financial ratios we are looking for. Only this selection is then passed on to Gemini Flash Lite as a PDF context. This trick not only significantly reduces processing costs but also helps to focus the model on the important parts of the document and minimize the “noise” of irrelevant pages.

After isolating the relevant pages, we commission Gemini to extract them into a predefined format. Another building block for precise results is the use of so-called structured outputs. Gemini can not only generate text but also provides directly structured JSON data which follows a predetermined scheme.

To do this, we define a clear target scheme in advance, which in turn defines exactly which data fields we expect and in which format (such as “number”, “text”, “currency symbol”). In Python, we like to use Pydantic for easy definition and validation. We explicitly give this structure to the model as an instruction. This is not only practical for automated further processing, but also demonstrably improves quality: In our tests, this step alone led to an improvement in the evaluation result of around 4%.

Here is a simplified Python example to illustrate the principle with the google-genai library and structured outputs:

from google import genai
from google.genai import types
from pydantic import BaseModel, Field


client = genai.Client(api_key="GEMINI_API_KEY")


# Define the desired output structure using Pydantic
class FinancialData(BaseModel):
    revenue: float | None = Field(
        description="Total revenue reported for the fiscal year."
    )
    net_income: float | None = Field(description="Net income or profit after tax.")
    total_assets: float | None = Field(description="Total assets value.")
    fiscal_year: int | None = Field(description="The ending year of the fiscal period.")
    currency_symbol: str | None = Field(
        description="Currency symbol used for major values (e.g., $, £, €)."
    )


# Upload the relevant PDF pages (assuming 'selected_report_pages.pdf' was created by pre-filtering)
pdf_file = client.files.upload(file="'selected_report_pages.pdf")

prompt = """
Please analyze the provided pages from the annual report PDF.
Extract the following financial figures for the main consolidated entity reported:
- Total Revenue
- Net Income (Profit after tax)
- Total Assets
- The Fiscal Year End
- The primary Currency Symbol used for the main financial figures (£, $, € etc.)

Return the data strictly adhering to the provided 'FinancialData' schema.
If a value cannot be found or determined confidently, leave the corresponding field null.
Pay close attention to units (e.g., thousands, millions).
"""

try:
    response = client.models.generate_content(
        model="gemini-2.0-flash-lite-001",
        contents=[prompt, pdf_file],
        config=types.GenerateContentConfig(
            response_mime_type="application/json",
            response_schema=FinancialData,
        ),
    )
    extracted_data = FinancialData.model_validate_json(response.text)
    print(extracted_data)

except Exception as e:
    print(f"\nAn error occurred: {e}")

finally:
    client.files.delete(name=pdf_file.name)

A look at the numbers: How well does it really work?

To objectively assess the actual performance of our approach with Gemini Flash, we created a dataset of 100 manually annotated business reports. This serves as ground truth against which we check the extraction results of the model.

The overall accuracy across all metrics and reports for our approach was 83.5%. These were the first feasibility values for the solution we integrated at North Data. This is a solid basis which demonstrates that the approach works. However, it gets more interesting when you look at the accuracy for individual metrics:

Key figure (parameters)	Accuracy
Overall	83.5%
capital	96.0%
cash	95.0%
employees	95.0%
revenue	95.0%
equity	98.0%
currencySymbol	99.0%
auditorName	89.0%
materials	89.0%
…	…
liabilities (creditors)	75.0%
currentAssets	64.0%
realEstate	60.0%
receivables	52.0%
tax	41.0%

What does this table tell us and what are the current hurdles?

The results paint a clear picture: The model achieves remarkably high accuracy values for clearly defined master data or values, which are often prominently and relatively uniformly shown in annual reports. These include, for example, capital, equity, employees, cash or the currency symbol. Fortunately, hallucinations – for example inventing numbers that do not exist in the document – were not a significant problem in our tests. If errors occurred, it was usually due to misinterpretations of existing figures and not to their free invention.

It becomes more difficult for the model with more complex key figures. This is where the limitations of the current approach become apparent, especially when it comes to semantic fuzziness and varying levels of detail. Many balance sheet items can be defined, named, or broken down differently in reports. Terms such as “total assets” are not always clear – does it mean the balance sheet total before or after deduction of certain items such as goodwill, for example the intangible value?

The exact definition of current assets, receivables or liabilities varies between companies and reporting standards. This is where the model sometimes reaches its limits in deducing the exact definition valid in the respective report from the immediate context alone.

The dependence on layouts and the placement of information also plays a role. Some assets, such as realEstate (real estate assets), are often not prominently found on the main pages of the balance sheet but are hidden in detail in the “Notes to the Financial Statements” (Appendix). The model’s ability to correctly map such information across different pages and layouts is heavily challenged and results in lower accuracy scores.

Finally, some metrics require more complex interpretations or implicit calculations. The extraction of values such as tax is a good example of this. Different types of taxes (income taxes, sales taxes, etc.) and deferred taxes can often be spread over several sections. The correct aggregation and interpretation of this information is challenging, which explains the current accuracy of only 41% for this metric.

These quantitative results confirm our qualitative observations: the model is excellent at finding clearly labelled information. However, it reaches its limits when dealing with issues such as ambiguities in wording, widely varying or complex layouts, and the need to understand implicit knowledge or contexts across multiple text passages.

Another important aspect is the varying accuracy between different companies. The standard deviation of accuracy per company is about 9.2%. It is particularly striking that the accuracy of the large, individually designed reports from listed companies (PLCs) such as AstraZeneca (50%), Barclays (65%), HSBC (50%), Shell (70%) or Unilever (55%) tends to be significantly lower than average. Tests with excerpts of different lengths showed that the length of the context to be mastered is not a major difficulty for Gemini, we therefore assume that the uniqueness of the reporting structures of these groups is particularly challenging for the model. While Gemini Flash Lite handles layouts that are often created by smaller companies using off-the-shelf software, these complex cases are a bigger hurdle. One explanation could be that the reports that deviate from the standard rarely made it into Gemini’s training data.

Another recurring problem is the correct capture of units and scales. Missing or misinterpreting information such as “in thousands of £” or “millions of USD” will result in extracted values that are wrong by factors of 1,000 or 1,000,000. Here, robust downstream validation rules and targeted prompting are necessary to sensitize the model to these details.

The representation of negative numbers, which is often done by parentheses in annual reports (e.g. “(1.234)” instead of “-1.234”), also requires an explicit note in the prompt so that the model interprets this convention correctly and extracts the numbers with the correct sign. As already mentioned, hallucinations do not pose any major problems here (as it was with older models), it is the interpretation of the numbers that does not always succeed.

Finally, we are also faced with the classic trade-off between costs and performance in particularly complex cases. More sophisticated reasoning approaches such as Chain-of-Thought (CoT), in which the model makes its “thought steps” explicit, or the use of even larger and more powerful models (for example Gemini 2.5 Pro) could remedy the problems mentioned, especially when analysing the more complex reports.

However, these are currently often much more expensive. For example, Gemini 2.5 Pro is currently 16 to 32 times more expensive than the Gemini 2.0 Flash Lite we used. The common GPT-4.1, which is used in ChatGPT, also costs $2 per 1 million input tokens – about 27 times as much as Gemini 2.0 Flash Lite. Using our solution to process an average report from our 30-page test dataset costs only about $0.0007!

Conclusion: Gemini Flash as a powerful addition to the toolbox

Gemini Flash has proven to be a useful building block for us to take the extraction of structured data from annual reports to a new level and bring it into productive use at North Data. It does not necessarily replace the entire classic pipeline (as our OCR pre-filtering shows), but it does provide a powerful, integrated alternative to the core process of intelligent data extraction and structuring.

The ability to understand layouts, work within a larger context, and deliver structured outputs significantly reduces complexity and maintenance compared to traditional, multi-tiered approaches. The challenges remain, but the progress is clear and opens new opportunities for automated financial data analysis.

We are excited to see how this technology will develop further and what new solutions will emerge. Have you had similar experiences or developed different strategies? Share your thoughts with us!

This blog post was written with the support of Gemini 2.5 Pro.

OmniAI OCR Benchmark, retrieved 17/06/25 ↩
cronn Blog: Analyzing Business Reports with ChatGPT – Part I ↩
Documentation Google Gemini 2.0 Flash-Lite, retrieved 17/06/25 ↩
Web Archive: OpenAI-Preise vom 14. Juni 2023, retrieved 17/06/25 ↩
Prices for Gemini Developer API, retrieved 17/06/25 ↩

Analyse von Geschäftsberichten mit LLMs – Teil 2

2025-06-24T00:00:00-05:00

Willkommen zurück zu unserer Serie über die Analyse von Geschäftsberichten mit KI! Im ersten Teil haben wir anhand eines Beispiels gezeigt, wie die Extraktion von Kennzahlen aus Geschäftsberichten mit LLMs wie ChatGPT grundsätzlich funktioniert. Jetzt gehen wir weiter in die Tiefe und zeigen dafür eine Lösung, die wir in Zusammenarbeit mit North Data produktiv einsetzen.

Wir konnten damals demonstrieren, wie sich relevante Informationen aus den dichten Textwüsten von Geschäftsberichten strukturiert herausfiltern lassen. Doch wer das in der Praxis skalieren will, stößt schnell an Grenzen – sei es bei der Genauigkeit über viele verschiedene Dokumente hinweg, der robusten Verarbeitung komplexer Layouts und Tabellen oder der Wirtschaftlichkeit, die für eine großflächige Analyse nötig ist.

Genau hier hat sich in der Zwischenzeit aber einiges getan. Mit Gemini Flash von Google steht ein Modell bereit, das die Karten für die automatisierte Dokumentenanalyse in Sachen Geschwindigkeit, Kontextverständnis und dem Ausliefern strukturierter Daten neu mischt.¹ In diesem zweiten Teil wollen wir daher tief eintauchen: Was macht Gemini Flash so viel leistungsfähiger für diese spezifische Aufgabe als frühere Ansätze oder die klassischen OCR-Pipelines? Wie ermöglicht es den Schritt von der Machbarkeitsstudie zum produktiven Werkzeug? Werfen wir einen Blick unter die Haube.

Gemini extrahiert strukturierten JSON-Code aus PDFs.

Der klassische Ansatz: OCR als Basis, aber nicht die ganze Lösung

Bevor wir uns den Fähigkeiten von Gemini widmen, lohnt sich ein kurzer Blick auf den traditionellen Weg zur Datenextraktion aus PDFs. Dieser beginnt fast immer mit Optical Character Recognition (OCR). OCR-Tools helfen uns, wenn es darum geht, Text aus gescannten Dokumenten oder reinen Bild-PDFs lesbar zu machen. Sie wandeln Pixel in Buchstaben um. Das Ergebnis ist nicht nur der „rohe“ Textinhalt, sondern oft auch dessen Position auf der Seite, meist in Form von Koordinaten oder sogenannten Bounding Boxes für jedes erkannte Wort oder jede Zeile.

Bounding Boxes bei OCR durch Azure Document Intelligence.

Nach diesem rohen Text samt Koordinaten fängt die eigentliche Arbeit oft erst an, denn für eine sinnvolle Analyse brauchen wir strukturierte Daten, keinen Fließtext. Hier beginnen die Herausforderungen:

Zuerst muss die Struktur im reinen Text-Output erkannt werden. Wie identifiziert man automatisch Tabellen, zusammengehörige Key-Value-Paare (wie „Umsatz: 10 Mio. €“) oder semantisch sinnvolle Blöcke? Dafür sind häufig komplexe, nachgelagerte Schritte notwendig – seien es speziell entwickelte Parser, regelbasierte Systeme, die auf bestimmte Muster achten, oder sogar separate Machine-Learning-Modelle, die auf Aufgaben wie Tabellenerkennung trainiert wurden.

Diese nachgelagerten Systeme sind allerdings oft anfällig für Layout-Änderungen. Kleine Anpassungen im Design eines Berichts von einem Jahr zum nächsten, oder die unterschiedlichen Formate verschiedener Unternehmen, können mühsam erstellte Regeln oder Parser aus dem Tritt bringen und unbrauchbar machen.

Hinzu kommt das fehlende Kontextverständnis. OCR liefert zwar den Text, versteht aber dessen Bedeutung nicht. Zu erkennen, dass sich der Begriff „Total Assets“ auf Seite 10 auf dieselbe Kennzahl bezieht wie eine detaillierte Aufschlüsselung in einer Tabelle auf Seite 45, übersteigt die Fähigkeiten reiner Texterkennung.

All diese Faktoren führen zu Komplexität und somit zu einem hohen Entwicklungs- und Wartungsaufwand. Es lässt sich feststellen: OCR ist ein wichtiges Werkzeug im Kasten. Aber für das Ziel der End-to-End-Extraktion strukturierter Daten ist es meist nur der erste Schritt in einer komplexen und oft fragilen Verarbeitungskette.

Unser Weg zum Produktiveinsatz: Evaluation, Modellwahl und Integration

Der Sprung von einer erfolgreichen Demonstration (wie in Teil 1 gezeigt²) zu einem zuverlässigen, skalierbaren Produktivsystem erforderte einen systematischen Ansatz und Weiterentwicklungen in mehreren Bereichen.

Zunächst war eine solide Evaluation unerlässlich. Wir haben also manuell einen Datensatz aus 100 repräsentativen englischen Geschäftsberichten kuratiert. Für die wichtigsten Kennzahlen wurden die korrekten Werte (Ground Truth) von Hand annotiert und in einer Tabelle gesammelt. Nur mit einer solchen verlässlichen Basis lässt sich die Qualität verschiedener Modelle und Ansätze objektiv messen und über die Zeit verfolgen.

Parallel dazu erweiterten wir den Umfang der Extraktion im Vergleich zur alten Lösung deutlich. Statt nur einiger weniger Kennzahlen war das Ziel nun, eine breite Palette von über 20 relevanten Werten pro Bericht zuverlässig zu extrahieren. Dazu gehören unter anderem die vom Unternehmen ausgewiesenen Lohnkosten, Angaben zu Gewinn und Verlust, Barmittel, aber auch Daten wie die durchschnittliche Mitarbeiterzahl oder der Name des Wirtschaftsprüfers.

Diese anspruchsvolleren Ziele führten uns zu Tests verschiedener Modelle. Die Wahl fiel schließlich auf Gemini 2.0 Flash Lite: Dieses Modell vereinte für unseren Anwendungsfall alle entscheidenden Faktoren optimal.

LLM-Vergleich anhand der Parameter „Intelligenz“ und „Preis“, via artificialanalysis.ai.

Qualität & Geschwindigkeit: In unseren Tests zeigte Gemini 2.0 Flash Lite eine überraschend hohe Genauigkeit für die meisten der anvisierten Kennzahlen, die oft mit der von größeren, teureren Modellen mithalten konnte. Google selbst positioniert die Flash-Modelle als optimiert für Aufgaben, bei denen es auf hohe Geschwindigkeit und Effizienz bei gleichzeitig guter Qualität ankommt³. Unsere Erfahrungen bestätigen, dass das Modell seinem „Flash“ im Namen in puncto Verarbeitungsgeschwindigkeit gerecht wird.

Kosten: Ein entscheidender Faktor für den Einsatz im großen Maßstab sind die Kosten. Gemini 2.0 Flash Lite ist deutlich günstiger als die größeren Pro-Modelle. Im Vergleich zu älteren Modellen wie gpt-3.5-turbo-16k aus dem ersten Teil, das im Juli 2023 noch etwa 3 US-Dollar pro Million Input-Token kostete⁴, ist die von uns genutzte Gemini-Flash-Variante um den Faktor 40 günstiger⁵! Das macht die Verarbeitung tausender Berichte wirtschaftlich tragbar.

Multimodalität & Kontext: Ein wesentlicher Vorteil gegenüber reinen Textmodellen oder klassischen OCR-Pipelines ist die Multimodalität von Gemini. Vereinfacht gesagt bedeutet das: Statt nur den rohen Text und dessen Koordinaten zu liefern (wie traditionelle OCR), kann Gemini Flash gleichzeitig den Text „lesen“ und das Seitenlayout „sehen“. Es „versteht“, wie Text in Spalten oder Tabellen angeordnet ist, erkennt Überschriften und kann Bilder oder Diagramme im Dokument interpretieren. Dadurch erfasst es den Kontext, den die reine Textreihenfolge oft nicht vermittelt, wesentlich besser. Dies ist gerade bei den komplexen und variantenreichen Layouts von Geschäftsberichten ein großer Vorteil. Gepaart mit dem langen Kontextfenster, das die Analyse umfangreicher Dokumentabschnitte am Stück erlaubt, ist dies ein entscheidender Fortschritt.

Diese Kombination aus guter Qualität, hoher Geschwindigkeit, niedrigen Kosten und der Fähigkeit, Dokumente ganzheitlich zu verstehen, machte Gemini 2.0 Flash Lite zur guten Wahl für unseren produktiven Einsatz in Zusammenarbeit mit North Data.

Gemini Flash in Aktion: Der Workflow mit Structured Outputs

Der Kern unseres Ansatzes kombiniert die Stärken von Gemini mit pragmatischen Lösungen, um auch mit den Eigenheiten sehr umfangreicher Dokumente umzugehen.

Ein zentrales Problem stellen lange Geschäftsberichte dar, die oft hunderte von Seiten umfassen. Das gesamte Dokument an Gemini zu übergeben, wäre zwar ideal für den Kontext, ist aber zu teuer für den Masseneinsatz. Um dieses Problem zu umgehen, haben wir einen mehrstufigen Ansatz entwickelt: Zuerst setzen wir nach wie vor auf bewährte OCR-Technologie, um den reinen Text des gesamten Dokuments zu extrahieren. Dieser Rohtext dient uns dann als Basis für eine schnelle Voranalyse mittels Schlüsselwörtern. Wir suchen nach Begriffen und Phrasen, die typischerweise auf relevante Abschnitte hindeuten, wie zum Beispiel „Consolidated Balance Sheet“, „Income Statement“ oder „Notes to the Financial Statements“.

Basierend auf dieser Analyse wählen wir die bis zu 100 Seiten aus, die am wahrscheinlichsten die gesuchten Finanzkennzahlen enthalten. Nur dieser Auszug des Berichts wird dann als PDF-Kontext an Gemini Flash Lite übergeben. Dieser Kniff reduziert nicht nur die Verarbeitungskosten erheblich, sondern hilft auch, das Modell auf die wirklich wichtigen Teile des Dokuments zu konzentrieren und das „Rauschen“ irrelevanter Seiten zu minimieren.

Nachdem wir die relevanten Seiten isoliert haben, beauftragen wir Gemini mit der gezielten Extraktion in ein vordefiniertes Format. Ein weiterer Baustein für präzise Ergebnisse ist hierbei die Nutzung von sogenannten Structured Outputs. Gemini besitzt die Fähigkeit, nicht nur Text zu generieren, sondern direkt strukturierte JSON-Daten zu liefern, die einem vorgegebenen Schema folgen.

Wir definieren dazu im Vorfeld ein klares Zielschema, das genau festlegt, welche Datenfelder wir erwarten und in welchem Format (wie etwa „Zahl“, „Text“, „Währungssymbol“). In Python nutzen wir dafür gerne Pydantic zur einfachen Definition und Validierung. Diese Struktur geben wir dem Modell explizit als Anweisung mit. Das ist nicht nur praktisch für die automatisierte Weiterverarbeitung, sondern verbessert auch nachweislich die Qualität: In unseren Tests führte allein dieser Schritt zu einer Verbesserung des Evaluations-Ergebnisses um rund 4 %.

Hier ein vereinfachtes Python-Beispiel zur Illustration des Prinzips mit der google-genai -Bibliothek und Structured Outputs:

from google import genai
from google.genai import types
from pydantic import BaseModel, Field


client = genai.Client(api_key="GEMINI_API_KEY")


# Define the desired output structure using Pydantic
class FinancialData(BaseModel):
    revenue: float | None = Field(
        description="Total revenue reported for the fiscal year."
    )
    net_income: float | None = Field(description="Net income or profit after tax.")
    total_assets: float | None = Field(description="Total assets value.")
    fiscal_year: int | None = Field(description="The ending year of the fiscal period.")
    currency_symbol: str | None = Field(
        description="Currency symbol used for major values (e.g., $, £, €)."
    )


# Upload the relevant PDF pages (assuming 'selected_report_pages.pdf' was created by pre-filtering)
pdf_file = client.files.upload(file="'selected_report_pages.pdf")

prompt = """
Please analyze the provided pages from the annual report PDF.
Extract the following financial figures for the main consolidated entity reported:
- Total Revenue
- Net Income (Profit after tax)
- Total Assets
- The Fiscal Year End
- The primary Currency Symbol used for the main financial figures (£, $, € etc.)

Return the data strictly adhering to the provided 'FinancialData' schema.
If a value cannot be found or determined confidently, leave the corresponding field null.
Pay close attention to units (e.g., thousands, millions).
"""

try:
    response = client.models.generate_content(
        model="gemini-2.0-flash-lite-001",
        contents=[prompt, pdf_file],
        config=types.GenerateContentConfig(
            response_mime_type="application/json",
            response_schema=FinancialData,
        ),
    )
    extracted_data = FinancialData.model_validate_json(response.text)
    print(extracted_data)

except Exception as e:
    print(f"\nAn error occurred: {e}")

finally:
    client.files.delete(name=pdf_file.name)

Ein Blick auf die Zahlen: Wie gut funktioniert es wirklich?

Um die tatsächliche Leistung unseres Ansatzes mit Gemini Flash objektiv zu bewerten, haben wir, wie erwähnt, einen Datensatz aus 100 manuell annotierten Geschäftsberichten erstellt. Dieser dient als Ground Truth, gegen den wir die Extraktionsergebnisse des Modells prüfen.

Die Gesamtgenauigkeit über alle Kennzahlen und Berichte hinweg für unseren Ansatz lag bei 83,5 %. Dies waren die ersten Machbarkeitswerte für die Lösung, die wir bei North Data integriert haben. Das ist eine solide Basis und zeigt, dass der Ansatz grundsätzlich funktioniert. Interessanter wird es jedoch, wenn man sich die Genauigkeit für einzelne Kennzahlen ansieht:

Kennzahlen (Parameter)	Genauigkeit
Gesamt (Overall)	83.5%
capital	96.0%
cash	95.0%
employees	95.0%
revenue	95.0%
equity	98.0%
currencySymbol	99.0%
auditorName	89.0%
materials	89.0%
…	…
liabilities (creditors)	75.0%
currentAssets	64.0%
realEstate	60.0%
receivables	52.0%
tax	41.0%

Was verrät uns diese Tabelle und wo liegen die aktuellen Hürden?

Die Evaluationsergebnisse zeichnen ein klares Bild: Bei klar definierten Stammdaten oder Werten, die in Geschäftsberichten oft prominent und relativ einheitlich ausgewiesen werden, erzielt das Modell sehr hohe Genauigkeitswerte. Dazu zählen beispielsweise capital (Eigenkapital), equity (Reinvermögen), die employees (Anzahl der Mitarbeiter), cash (Barmittel) oder das currencySymbol (Währungssymbol). Erfreulicherweise sind Halluzinationen – also das Erfinden von Zahlen, die im Dokument nicht existieren – in unseren Tests kein signifikantes Problem gewesen. Wenn Fehler auftraten, dann meist durch Fehlinterpretationen vorhandener Zahlen, nicht durch deren freie Erfindung.

Schwieriger wird es für das Modell bei komplexeren Kennzahlen. Hier zeigen sich die Grenzen des aktuellen Ansatzes, insbesondere wenn es um semantische Unschärfe und variierende Detailgrade geht. Viele Bilanzposten können in Berichten unterschiedlich definiert, benannt oder aufgeschlüsselt sein. Begriffe wie „Total Assets“ sind nicht immer absolut eindeutig – meint es die Bilanzsumme vor oder nach Abzug bestimmter Posten wie Goodwill, also den immateriellen Firmenwert?

Die genaue Abgrenzung von currentAssets (kurzfristige Vermögenswerte), receivables (Forderungen) oder liabilities (Verbindlichkeiten) variiert zwischen Unternehmen und Berichtsstandards. Hier stößt das Modell manchmal an seine Grenzen, die exakte, im jeweiligen Bericht gültige Definition allein aus dem unmittelbaren Kontext zu erschließen.

Ebenso spielt die Abhängigkeit von Layouts und der Platzierung von Informationen eine Rolle. Einige Werte, wie beispielsweise realEstate (Immobilienvermögen), sind oft nicht prominent auf den Hauptseiten der Bilanz zu finden, sondern detailliert in den „Notes to the Financial Statements“ (Anhang) versteckt. Die Fähigkeit des Modells, solche Informationen über verschiedene Seiten und Layouts hinweg korrekt zuzuordnen, ist stark gefordert und führt zu niedrigeren Genauigkeitswerten.

Schließlich erfordern manche Kennzahlen komplexere Interpretationen oder implizite Berechnungen. Die Extraktion von Werten wie tax (Steuern) ist hierfür ein gutes Beispiel. Oft spielen verschiedene Steuerarten (Ertragssteuern, Umsatzsteuern etc.) und latente Steuern eine Rolle, die über mehrere Abschnitte verteilt sein können. Die korrekte Zusammenführung und Interpretation dieser Informationen sind anspruchsvoll, was die aktuelle Genauigkeit von nur 41 % für diese Kennzahl erklärt.

Diese quantitativen Ergebnisse bestätigen unsere qualitativen Beobachtungen: Das Modell ist hervorragend darin, klar benannte Informationen zu finden. Bei Mehrdeutigkeiten, stark variierenden oder komplexen Layouts und der Notwendigkeit, implizites Wissen oder Zusammenhänge über mehrere Textstellen hinweg zu verstehen, stößt es jedoch an Grenzen.

Ein weiterer wichtiger Aspekt ist die variierende Genauigkeit zwischen verschiedenen Unternehmen. Die Standardabweichung der Genauigkeit pro Unternehmen liegt bei etwa 9,2 %. Besonders auffällig ist, dass die Genauigkeit bei den sehr großen, oft hunderte Seiten umfassenden und individuell gestalteten Berichten von börsennotierten Unternehmen (PLCs) wie AstraZeneca (50 %), Barclays (65 %), HSBC (50 %), Shell (70 %) oder Unilever (55 %) teilweise deutlich abfällt.

Tests mit unterschiedlich langen Ausschnitten aus den Berichten zeigten, dass die Länge des zu bewältigenden Kontextes für Gemini keine größere Schwierigkeit darstellt. Wir gehen daher davon aus, dass vor allem die Einzigartigkeit der Berichtsstrukturen dieser Konzerne für das Modell herausfordernd sind. Während Gemini Flash Lite gut mit Layouts zurechtkommt, die oft von kleineren Unternehmen mit Standardsoftware erstellt werden, sind diese komplexen Fälle eine größere Hürde. Eine Erklärung könnte sein, dass es die vom Standard abweichenden Berichte seltener in Geminis Trainingsdaten geschafft haben.

Ein weiteres wiederkehrendes Problem ist die korrekte Erfassung von Einheiten und Skalierungen. Das Übersehen oder die Fehlinterpretation von Angaben wie „in Tausend £“ oder „Millions USD“ führt zu extrahierten Werten, die um Faktoren von 1.000 oder 1.000.000 falsch sind. Hier sind robuste nachgelagerte Validierungsregeln und gezieltes Prompting notwendig, um das Modell für diese Details zu sensibilisieren.

Auch die Darstellung negativer Zahlen, die in Geschäftsberichten oft durch Klammern erfolgt (z.B. „(1.234)“ statt „-1.234“), erfordert einen expliziten Hinweis im Prompt, damit das Modell diese Konvention korrekt interpretiert und die Zahlen mit dem richtigen Vorzeichen extrahiert. Wie bereits gesagt stellen Halluzinationen (im Gegensatz zu älteren Modellen) hier keine großen Probleme dar, bloß die Interpretation der Zahlen gelingt nicht immer.

Zu guter Letzt stehen wir auch vor dem klassischen Trade-off zwischen Kosten und Leistung bei besonders komplexen Fällen. Anspruchsvollere Reasoning-Ansätze wie Chain-of-Thought (CoT), bei denen das Modell seine „Gedankenschritte“ explizit macht, oder der Einsatz noch größerer und leistungsfähigerer Modelle (z.B. Gemini 2.5 Pro) könnten bei den genannten Problemen, insbesondere bei den komplexen Berichten, Abhilfe schaffen.

Diese sind jedoch aktuell oft noch deutlich teurer. So ist beispielsweise Gemini 2.5 Pro derzeit 16- bis 32-mal so teuer wie das von uns genutzte Gemini 2.0 Flash Lite. Auch das sehr gängige GPT-4.1, welches in ChatGPT zum Einsatz kommt, kostet mit 2 $ pro 1 Million Input Tokens ca. 27-mal so viel wie Gemini 2.0 Flash Lite. Die Verarbeitung eines durchschnittlichen Berichts aus unserem Testdatensatz mit 30 Seiten kostet mit unserer Lösung daher nur ca. 0,0007 $!

Fazit: Gemini Flash als leistungsstarke Ergänzung im Werkzeugkasten

Gemini Flash hat sich für uns als nützlicher Baustein erwiesen, um die Extraktion strukturierter Daten aus Geschäftsberichten auf ein neues Level zu heben und in den produktiven Einsatz bei North Data zu bringen. Es ersetzt nicht zwangsläufig die gesamte klassische Pipeline (wie unsere OCR-Vorfilterung zeigt), aber es bietet eine enorm leistungsfähige, integrierte Alternative für den Kernprozess der intelligenten Datenextraktion und -strukturierung.

Die Fähigkeit, Layouts zu verstehen, über einen größeren Kontext zu arbeiten und direkt strukturierte Outputs zu liefern, reduziert die Komplexität und den Wartungsaufwand im Vergleich zu traditionellen, mehrstufigen Ansätzen erheblich. Die Herausforderungen bleiben, aber der Fortschritt ist deutlich und eröffnet neue Möglichkeiten für die automatisierte Finanzdatenanalyse.

Wir sind gespannt, wie sich diese Technologie weiterentwickelt und welche neuen Lösungsansätze sich ergeben. Habt ihr ähnliche Erfahrungen gemacht oder andere Strategien entwickelt? Teilt eure Gedanken mit uns!

Dieser Blogpost wurde mit Unterstützung von Gemini-2.5-Pro geschrieben.

OmniAI OCR Benchmark, abgerufen am 17.06.25 ↩
cronn Blog: Analyse von Geschäftsberichten mit ChatGPT – Teil 1 ↩
Dokumentation Google Gemini 2.0 Flash-Lite, abgerufen am 17.06.25 ↩
Web Archive: OpenAI-Preise vom 14. Juni 2023, abgerufen am 17.06.25 ↩
Preise für die Gemini Developer API, abgerufen am 17.06.25 ↩

Code Generation using Java Annotation Processing

2025-05-21T00:00:00-05:00

Introduction to code generation

Developers often find themselves confronted with writing the same type of simple code over and over again. Over time, some options were designed to reduce the time needed for writing trivial code. IDEs can automatically generate getters and setters or even apply custom templates that can be used for code generation. Elaborate tools like the OpenAPI Generator ¹ are able to create the groundwork for client and server code in REST-based communication by using the interface specification as input, and even more recently elaborate AIs have been launched with this purpose in mind. In general, there are two different types of generating code: one time generation, like the getter and setter creation from IDE, and continuous generation, like the OpenAPI generator. In the latter, a change of interface specification directly results in changes in the generated code, and thus specification and code remain in sync.

Java annotation processing, which was introduced in Java 1.6, is another example of continuous generation. The main idea is that a code generator operates on specific parts of the code which is marked by annotations. These annotations are then processed in the generator, where new code is generated based on the annotated code and the annotations themselves. One of the most prominent frameworks that incorporates annotation processing is Project Lombok ² which, among other features, has the option of generating getters and setters via annotation processing. The advantage of annotation processing is that the new methods are only created in the generated code and are not present in the actual versioned code, which in turn is more precise and contains less trivial boilerplate code. Furthermore, the generated code does not become obsolete and thus requires no maintenance.

Using an existing annotation processor

An annotation processor is in most cases already present if one is using third party libraries. The process of using it as code generator is easily described through the following example: suppose you want to map an object of type Company to its DTO CompanyDto. MapStruct ³ enables simple mapping of different types through generated classes which are described by annotations on an interface used as base.

Let us look at a Definition of a MapStruct mapper for a Company object to CompanyDto:

// File: CompanyMapper.java
@Mapper
public interface CompanyMapper {
	CompanyMapper INSTANCE = Mappers.getMapper(CompanyMapper.class);

	@Mapping(target = "companyName", source = "name")
	@Mapping(target = "companyAge", source = "age")
	CompanyDto map(Company company);
}

The actual usage of the mapper from above looks like this:

// File: CompanyMapperTest.java
@Test
void mapCompanyToDto() throws Exception {
    Company source = new Company("cronn GmbH", 10);

    CompanyDto destination = CompanyMapper.INSTANCE.map(source);

    assertThat(destination.getCompanyName()).isEqualTo("cronn GmbH");
    assertThat(destination.getCompanyAge()).isEqualTo(10);
}

In order to use an annotation processor (in this case MapStruct) it is necessary to inform the build tool that such a processor is present and should be used. Gradle, for example, employs the keyword “annotationProcessor” for this, as is shown below.

// File: build.gradle
dependencies {
    annotationProcessor("org.mapstruct:mapstruct-processor:${mapstructVersion}")
    ...
}

Using the above definition MapStruct then creates an implementation for the interface using the information given through the annotations. The output for this is shown below.

// Generated File: CompanyMapperImpl.java
public class CompanyMapperImpl implements CompanyMapper {

    @Override
    public CompanyDto map(Company company) {
        if ( company == null ) {
            return null;
        }

        String companyName = null;
        int companyAge = 0;

        companyName = company.getName();
        companyAge = company.getAge();

        CompanyDto companyDto = new CompanyDto( companyName, companyAge );

        return companyDto;
    }
}

Through annotation processing, an interesting aspect of the Java compilation step becomes visible. Normally, the compilation to bytecode starts with the parsing step, continues with an analyzing step and ends with the bytecode generation (note that this is an oversimplification for the needs of this article). Annotation processing is directly incorporated into this process. After the parsing step, all relevant annotations are processed by processors and if new code has been generate the parsing step is restarted. By repeating these steps in multiple rounds it is possible to generate code in one annotation processor which itself contains annotations which may trigger further processors in following rounds. This is nicely illustrated in the OpenJDK article on Compilation Overview ⁴.

The compilation process contains a repetition in case annotation processors generate new source material.

Custom code generator for annotation processing

The usage of existing annotation processors from third party libraries is already a big improvement for typical situations. However, the more interesting application is the development and use of custom generators. For this purpose, Java offers the javax.annotation.processing.Processor interface ⁵, which is already implemented in the abstract class javax.annotation.processing.AbstractProcessor. When creating a custom annotation processor either this interface has to be implemented, or the abstract class has to be extended in order to inform the compilation unit to use it. Through this, the custom processor inherits, among others, the methods getSupportedAnnotationTypes and process.

One of the first steps in creating a custom annotation processor is to tell the compilation unit, which annotations are handled by this processor. When inheriting from AbstractProcessor, instead of implementing getSupportedAnnotationTypes with a custom implementation, the supported annotations can be configured with the annotation @SupportedAnnotationTypes, which is used on the processor itself. Here, it is possible to use existing annotations as well as custom annotations specifically created for use with this processor. It is even possible to use wildcards for this.

The following example shows a custom annotation and how this is used in a custom annotation processor.

// File: Builder.java
package org.example;

@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.TYPE)
public @interface Builder {
}

The custom annotation processor using the custom annotation from above looks like this:

// File: BuilderAnnotationProcessor.java
@SupportedAnnotationTypes("org.example.Builder")
public class BuilderAnnotationProcessor extends AbstractProcessor {

    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        ...

The process method is the one which is called by the compilation unit and where the actual generation happens. A set of all configured annotations and a RoundEnvironment for the current processing round are given as parameters. In order to get all elements that are currently annotated with the configured annotations, the round environment can be used by calling its method getElementsAnnotatedWith(…). Depending on the target, on which the annotation is specified, the returned elements may be of different element types like classes, fields or methods (e.g. in the upper example for @org.example.Builder the target ElementType.TYPE was used, which specifies classes, interfaces, enums and records).

// File: BuilderAnnotationProcessor.java
@Override
public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
    for (Element classElement : roundEnv.getElementsAnnotatedWith(Builder.class)) {
        String className = classElement.getSimpleName().toString();
        process(className);
    }
}

For the actual Java file creation, a Filer ⁶ instance can be used, which already has information about the build location for newly created files. Additionally, to the RoundEnvironment mentioned above, when inheriting from AbstractProcessor, a ProcessingEnvironment also exists, which can be accessed from child classes and be used in order to get such a Filer instance for creating new source files.

// File: BuilderAnnotationProcessor.java
private void process(String className) {
    ...
    try {
        JavaFileObject sourceFile = processingEnv
            .getFiler()
            .createSourceFile(getSourceFileName(className));

        try (Writer writer = new BufferedWriter(sourceFile.openWriter())) {
            writer.write(generateSourceCode(...));
        }
    } catch (IOException e) {
        // handle exception
        ...
    }
}

The final code that is generated by the processor, is just text that is written with the file writer of the filer instance. Therefore, it can be created in different well-known ways, e.g. by using string concatenation, StringBuilders or multi-line strings with formatters. However, if its content gets too complex, dedicated frameworks like ⁷ or more elaborate techniques like StringTemplates ⁸ are advised. The custom code generator in our example code ⁹ builds up on StringTemplates and shows some of the capabilities there. As mentioned previously, the generation process repeats itself in the case of newly created files also containing annotations for which annotation processors exist.

As described above, it is important to note that the complete annotation processing happens during the compilation step. If debugging is desired it is therefore necessary to add debug information to this, for example in the case of Gradle, by adding the -Dorg.gradle.debug=true flag to the current Gradle task. Through this, it is possible to use typical debugging tools, which make the development of such a code generator as simple as regular code.

In order to use the custom annotation processor during compilation of the target code, the compiler has to be informed about the existence of a processor to be used. There are different ways to achieve this, ranging from specific javac options like javac -processor …, to maven plugins. It is also possible to register it in the meta information of the build jar file in a file typically named META-INF/services/javax.annotation.processing.Processor, where each annotation processor is listed line by line. This is also the solution used in our example code. To make this process even easier, Google AutoService library ¹⁰ automatically creates such a file (interestingly enough, by using annotations and generating the file through annotation processing).

// File: META-INF/services/javax.annotation.processing.Processor
org.example.BuilderAnnotationProcessor

Conclusion

Many possibilities exist for automatic generation of simple code in Java. This article presented Annotation Processing, which is easy to use and deeply integrated in the Java environment. Potential applications range from builder classes, object mappers between different domain models, (fluent) setters and getters, automatic generation of constructors and boilerplate methods such as toString() and hashCode(). All of which can be used by adding a single annotation to the target code. Our example code ⁹ demonstrates the usage of existing third party libraries as well as the creation of custom annotations and generators. Due to the mentioned versatility and ease-of-use annotation processing is a powerful tool in the Java ecosystem.

OpenAPI Generator ↩
Project Lombok Note: unlike typical annotation processors, in order to fulfill all its goals, Project Lombok directly manipulates the .class files instead of creating new .java files first ↩
MapStruct ↩
OpenJDK compilation overview ↩
Java Processor interface documentation ↩
Java Filer documentation ↩
JavaPoet ↩
StringTemplate ↩
Example code ↩ ↩²
Google AutoService ↩

Handling of the ‘this-escape’ warning in JDK 21

2024-08-13T00:00:00-05:00

JDK version 21 introduced a new rule to the Java linter. According to this rule it is not permitted to call an overridable method within the constructor of a class ¹. If this rule is disregarded and the Java code compiled using the -Xlint:all or -Xlint:this-escape flag, this leads to the following this-escape warning:

warning: [this-escape] possible `this` escape before subclass is fully initialized

You can jump to the three approaches here:

Using the keywords final, private or static
Usage of the annotation @PostConstruct
Revise the class design

Background

The addition of the new rule to the Java linter in JDK 21 is a good improvement as it helps prevent code smell. It has long been recommended to avoid calling overridable methods from the constructor ² ³. However, as an analysis ⁴ of some well-known open source projects shows, there are still places in the code where the recommendation is forgotten or ignored. Even in our own projects the upgraded Java linter was also able to find a few places that did not follow the recommendation.

In this article, we will briefly look at why no overridable methods should be called in the constructor. The following three sections show approaches that were used to resolve the warning in our projects.

In the following, it is assumed that the code shown is always compiled with the flag -Xlint:all, even if this was not explicitly specified. The complete code is available in this GitHub repository.

Origin Story

The rationale for the this-escape warning is explained below. Using an example, let’s take a look at the class Person. The class has an instance variable name and a public non-final method greet(). The greet() method is called in the constructor of the class. The code compiles fine with JDK 17, but when compiling with JDK 21, the Java linter issues a this-escape warning.

public class Person {

    private final String name;

    public Person(String name) {
        this.name = Objects.requireNonNullElse(name, "stranger");
        greet(); // Calls overrideable method, causes this-escape warning
    }

    public void greet() {
        System.out.println("Hello " + name + "!");
    }
}

The Person class itself is unproblematic, but as soon as the class is extended, it can lead to errors that are difficult to find. The Java linter warns of this with the this-escape warning. To be able to provoke an error, we also create the class Musician as an extension of the class Person. The class Musician adds another instance variable, instrument, and overrides the method greet().

public class Musician extends Person {

    private final String instrument;

    public Musician(String name, String instrument) {
        super(name);
        this.instrument = Objects.requireNonNullElse(instrument, "triangle");
    }

    @Override
    public void greet() {
        super.greet();
        System.out.println("I heard you play " + instrument + ". Awesome!");
    }
}

What is now being output when a new Musician object is created with the new Musician("Jimi", "guitar") statement? When an instance of Musician is created, the constructor of Person is called in the constructor of Musician. In the constructor of Person, the instance variable name is initialized and then the method greet() is called. The variable instrument is then initialized within the constructor of the class Musician. The statement results in the following output:

Hello Jimi!
I heard you play null. Awesome!

The overridden method greet() is called from Person even before Musician has been fully instantiated. This results in the value null being output for instrument, although instrument can never have the value null after instantiation of the object Musician. The reason for the incorrect output is quickly apparent in the example. Nevertheless, it shows that a class should not call any overridable methods of its own class in the constructor, as the class cannot ensure that it is in a consistent state when the method is called. It follows that the greet() method should not be both overridable and called by the constructor at the same time.

It should be noted that the error in this example seems obvious as we have looked at a simple example to explain the situation. In practice, the error in an extensive class within a complex class hierarchy with further inheritance and nesting in connection with concurrency can be considerably more difficult to locate.

Three approaches

The following three sections present ways of preventing or circumventing the calling of an overridable method from the constructor.

Using the keywords `final`, `private` or `static`

The most direct way to prevent the this-escape warning is to prohibit the overwriting of all methods called by the constructor. This can be achieved in Java with the keywords final, private, and static. If a class is declared as final, it is no longer possible to extend it. Accordingly, none of its methods can be overwritten. The declaration of a method as final, private or static ensures that it is the method alone which cannot be overwritten.

We can use these keywords to fix the incorrect output of the Person and Musician classes from the last section in various ways. In the following, we first declare the greet() method of Person as final to satisfy the Java linter.

public class Person {

    private final String name;

    public Person(String name) {
        this.name = Objects.requireNonNullElse(name, "stranger");
        greet();
    }

    public final void greet() { // Method is now final
        System.out.println("Hello " + name + "!");
    }
}

This makes it so that the Musician class can no longer overwrite the greet() method. Instead, a separate method printInstrument() is defined in the Musician class, which is now responsible for the output of the instrument. For this approach to work, we must define that the class Musician should not be extended by any other class, so we add the keyword final to the declaration of the class – otherwise, the Java linter would give us a this-escape warning here too.

public final class Musician extends Person { // Class is now final

    private final String instrument;

    public Musician(String name, String instrument) {
        super(name);
        this.instrument = Objects.requireNonNullElse(instrument, "triangle");
        printInstrument();
    }

    public void printInstrument() {
        System.out.println("I heard you play " + instrument + ". Awesome!");
    }
}

After the changes, the statement new Musician("Jimi", "guitar") leads to the following output:

Hello Jimi!
I heard you play guitar! Awesome!

However, it is not always possible to declare a class as final or method as final, private, or static. If the class is managed by a dependency injection framework, such as Spring or Quarkus, the call of overridable methods from the constructor can usually be bypassed in another way. We will look at these in the next section.

Usage of the annotation `@PostConstruct`

Although we will be using Spring in the following examples, the approach can also be used for other dependency injection frameworks that implement the Jakarta Contexts and Dependency Injection specification or the Jakarta Annotations specification. Part of the Jakarta Annotations specification is the annotation @PostContruct, which is essential for the approach presented here. Using the annotation, we can link into the life cycle of a bean managed by Spring. In the case of @PostConstruct this happens, as the name suggests, after the constructor has been executed and the bean has been fully initialized. This makes it possible to move the call of an overridable method from the constructor to a safe place. Spring offers other ways to insert custom code into the lifecycle of a bean, but the use of @PostConstruct is the recommended ⁵, so only this will be discussed here.

In order to illustrate the use of @PostConstruct, let us extend our earlier example. In the previous example, the instrument triangle was assigned to each musician if no instrument was specified. We want to optimize this a little by making it possible to connect an external resource. This should provide a mapping between known musicians, represented by their name, and their instrument. The mapping should be saved in a cache for faster access. The use of the cache is shown schematically in the following listing:

String name = getName(); // Get name of a musician from somewhere
String instrument = getInstrument(); // Get instrument from somewhere
if (instrument == null) {
    /*
         musicianInstrumentCache contains a mapping of the form:
         Jimi -> guitar
         Miles -> trumpet
         Ludwig -> piano
         ...
    */
    instrument = musicianInstrumentCache.getInstrumentFor(name);
}
Musician musician = new Musician(name, instrument);

We create two classes for the implementation. The abstract class MusicianInstrumentCache contains a simple cache, which was realized as a Map with the mapping musician name ⟼ instrument, and calls the method updateCache() in the constructor. The updateCache() method is to be used by the specializations of MusicianInstrumentCache (see below) to read in an external resource and update the cache. The following applies to the updateCache() method:

Calling the method should enable other classes to update the cache at runtime . The method should therefore be public.
For different types of resources, such as external files, databases, etc., it should be possible to create different specializations of MusicianInstrumentCache, which override the updateCache() method in line with the resource used. Therefore, the method should be abstract and cannot be declared as private, final, or static.

The implementation of the abstract class MusicianInstrumentCache is given below. The linter issues a this-escape warning when the class is compiled, as the abstract method updateCache() is called in the constructor.

public abstract class MusicianInstrumentCache {

    protected static final Map<String, String> cache =
            new ConcurrentHashMap<>();

    public MusicianInstrumentCache() {
        System.out.println("MusicianInstrumentCache.init()");
        updateCache(); // Calls overrideable method, causes this-escape warning
    }

    public abstract void updateCache(); // Should be public and abstract

    public String getInstrumentFor(String name) {
        return cache.get(name);
    }
}

Before we address the problem, let’s look at a specialization of the class MusicianInstrumentCache. The class FileBasedMusicianInstrumentCache shows a possible specialization of MusicianInstrumentCache. The class should read the mapping from a file via the Spring-injected ResourceLoader, then proceed to write it to the cache. To keep the example short, the reading of the file and the writing to the cache is only implied in the code.

@Component
public class FileBasedMusicianInstrumentCache extends MusicianInstrumentCache {

    private final ResourceLoader resourceLoader;
    private String mappingResource = "classpath:mapping.csv";

    public FileBasedMusicianInstrumentCache(ResourceLoader resourceLoader) {
        System.out.println("FileBasedMusicianInstrumentCache.init()");
        this.resourceLoader = resourceLoader;
    }

    @Override
    public void updateCache() {
        System.out.println("FileBasedMusicianInstrumentCache.updateCache()");
        // Logic for importing mapping and adding it to the cache. Briefly,
        // represented by the following lines without exception handling:
        Resource resource = resourceLoader.getResource(mappingResource);
        String content = resource.getContentAsString(StandardCharsets.UTF_8);
        Arrays.stream(content.split("\n"))
                .map(line -> line.split(","))
                .forEach(mapping -> cache.put(mapping[0], mapping[1]));
    }

    // getter and setter
}

It should be noted that if the updateCache() method of the FileBasedMusicianInstrumentCache class is called in the constructor of the MusicianInstrumentCache class, then the resourceLoader has not yet been set. This is because, as described in the section Origin Story, the constructor of the extending class FileBasedMusicianInstrumentCache calls the constructor of the class MusicianInstrumentCache as the first statement, even if the call via super() was not explicitly specified in the Java code. This can also be seen in the output, where FileBasedMusicianInstrumentCache.updateCache() is written to the console before FileBasedMusicianInstrumentCache.init():

MusicianInstrumentCache.init()
FileBasedMusicianInstrumentCache.updateCache()
FileBasedMusicianInstrumentCache.init()

Fortunately, the error and the this-escape warning can be fixed with the annotation @PostConstruct without major adjustments, so that the overridable method updateCache() is no longer called before the object has been completely initialized. It is sufficient to annotate the updateCache() method in the MusicianInstrumentCache class with @PostConstruct. The call of the method updateCache() can be removed from the constructor, as Spring is now responsible for the call. The class FileBasedMusicianInstrumentCache can remain unchanged, as Spring checks whether a method with @PostConstruct is annotated in a superclass and adopts the behaviour for the subclasses.

public abstract class MusicianInstrumentCache {

    protected static final Map<String, String> cache =
            new ConcurrentHashMap<>();

    public MusicianInstrumentCache() {
        System.out.println("MusicianInstrumentCache.init()");
        // Remove importMapping() method call here
    }

    @PostConstruct // Add annotation
    public abstract void updateCache();

    public String getInstrumentFor(String name) {
        return cache.get(name);
    }
}

When the application is started, the constructor MusicianInstrumentCache is still called when the class FileBasedMusicianInstrumentCache is initialized, but the method updateCache() is no longer called in the constructor; instead, the constructor of FileBasedMusicianInstrumentCache is completed first. Only after FileBasedMusicianInstrumentCache has been completely constructed does Spring call the updateCache() method annotated with @PostConstruct. This results in the following output:

MusicianInstrumentCache.init()
FileBasedMusicianInstrumentCache.init()
FileBasedMusicianInstrumentCache.updateCache()

The procedure with @PostConstruct makes it possible to link the use of overridable methods to the creation of the object without the problems that may result when calling from the constructor. However, this requires the use of a dependency injection framework that supports the annotation @PostConstruct.

The previous two sections described two small tweaks to satisfy the linter. In the next section we will look at another way of dealing with the warning.

Revise the class design

Sometimes the this-escape warning can also serve as a suggestion to re-evaluate the class design. Depending on the result of the evaluation, the necessary changes may have a greater impact on the structure of the code than was the case with the other two methods. We once again take up the example from the previous section to show what an adaptation of the class design could look like.

In the last section, the two classes MusicianInstrumentCache and FileBasedMusicianInstrumentCache were created, with the latter extending the former. Due to inheritance, the method updateCache() had to be public and overridable, which ultimately led to the this-escape warning. In the following, the class design should use composition instead of inheritance.

The functionality of the class MusicianInstrumentCache is split for this purpose. The management of the cache will remain the task of the class MusicianInstrumentCache. The import of an external resource is outsourced to the class FileBasedMusicianInstrumentImporter. The class FileBasedMusicianInstrumentImporter also receives a reference to an instance of the class MusicianInstrumentCache. Below, the old, inheritance-based class design is compared to the new class design in a UML class diagram.

Inheritance                           Composition
=========                             ===========
┌────────────────────────────────┐   ┌────────────────────────────────────────┐
│           <abstract>           │   │                                        │
│    MusicianInstrumentCache     │   │        MusicianInstrumentCache         │
├────────────────────────────────┤   ├────────────────────────────────────────┤
│#cache:Map<String,String>       │   │-cache:Map<String,String>               │
├────────────────────────────────┤   ├────────────────────────────────────────┤
│+importMapping():void <abstract>│   │~put(name:String,instrument:String):void│
│+getInstrumentFor(String):String│   │+getInstrumentFor(String):String        │
└────────────────────────────────┘   └────────────────────────────────────────┘
                 ▲                                       ^
                 │                                       │
                 │                                       │ -cache
                 │                                       │
┌────────────────┴───────────────┐   ┌───────────────────┴────────────────────┐
│FileBasedMusicianInstrumentCache│   │  FileBasedMusicianInstrumentImporter   │
├────────────────────────────────┤   ├────────────────────────────────────────┤
│-resourceLoader:ResourceLoader  │   │-resourceLoader:ResourceLoader          │
├────────────────────────────────┤   ├────────────────────────────────────────┤
│+importMapping():void           │   │+importMapping():void                   │
└────────────────────────────────┘   └────────────────────────────────────────┘

The following listing shows the code of the new class MusicianInstrumentCache. The class has two methods, one for reading and one for writing the cache. MusicianInstrumentCache was annotated with @Component, as it is managed by the Dependency Injection Framework, and is to be injected into FileBasedMusicianInstrumentImporter.

@Component
public class MusicianInstrumentCache {

    private final Map<String, String> cache = new ConcurrentHashMap<>();

    void put(String name, String instrument) {
        cache.put(name, instrument);
    }

    public String getInstrumentFor(String name) {
        return cache.get(name);
    }
}

The code of the class FileBasedMusicianInstrumentImporter is shown in the following listing. The annotation @PostConstruct is no longer required as it is now sufficient to declare the class as final.

@Component
public final class FileBasedMusicianInstrumentImporter {

    private final MusicianInstrumentCache cache;
    private final ResourceLoader resourceLoader;
    private String mappingResource = "classpath:mapping.csv";

    public FileBasedMusicianInstrumentImporter(MusicianInstrumentCache cache,
                                               ResourceLoader resourceLoader) {
        this.cache = cache;
        this.resourceLoader = resourceLoader;
        importMapping();
    }

    public void importMapping() {
        // Logic for importing mapping and adding it to the cache. Briefly,
        // represented by the following lines without exception handling:
        Resource resource = resourceLoader.getResource(mappingResource);
        String content = resource.getContentAsString(StandardCharsets.UTF_8);
        Arrays.stream(content.split("\n"))
                .map(line -> line.split(","))
                .forEach(mapping -> cache.put(mapping[0], mapping[1]));
    }

    // getter and setter
}

The example is intended to provide an impression of what a revision of the class design could look like. However, this does not always have to involve a switch from inheritance to composition. It could also involve extracting/moving methods, or using a creational pattern to resolve the call of an overridable method from the constructor.

At this point, we have looked at all the approaches that were used to upgrade our project. The next section summarizes the main points of this article.

Summary

In this post, we described the motivation behind the Java linter’s this-escape warning and showed three ways to prevent said warnings. The possibilities are listed below:

Use of the keywords final, private, or static;
Use of the annotation @PostConstruct;
Revision of the class design

It is not always the case that all three approaches are applicable. Sometimes a combination of multiple approaches is necessary to resolve the warning. The best way to deal with the warning must be decided on a case-by-case basis. In most cases the first or second approach should be sufficient; however, the use of the second approach requires that the affected class is managed by a dependency injection framework such as Spring or Quarkus. Reworking the class design should always lead to success, but is also the most time-consuming.

References

Add lint check for calling overridable methods from a constructor ↩
Joshua Bloch. 2001. Effective Java programming language guide. Sun Microsystems, Inc., USA. ↩
Writing Final Classes and Methods ↩
Calling Methods from a Constructor ↩
Customizing the Nature of a Bean ↩

Behandlung der this-escape-Warnung in JDK 21

2024-07-11T00:00:00-05:00

In der JDK Version 21 wurde der Java Linter um eine neue Regel erweitert. Nach der ist es nicht erlaubt, im Konstruktor einer Klasse eine überschreibbare Methode aufzurufen¹. Wird die Regel missachtet und der Java Code mit dem Flag -Xlint:all oder -Xlint:this-escape kompiliert, führt dies zur folgenden this-escape Warnung:

warning: [this-escape] possible 'this' escape before subclass is fully initialized

In diesem Beitrag wollen wir kurz betrachten, wieso im Konstruktor keine überschreibbaren Methoden aufgerufen werden sollten. Die darauffolgenden drei Abschnitte zeigen Verfahren, die für das Auflösen der Warnung in unseren Projekten angewandt wurden.

Hier kommt ihr gleich zu den drei Lösungswegen:

Verwendung der Schlüsselwörter final, private oder static
Verwendung der Annotation @PostConstruct
Überarbeiten des Klassendesigns

Hintergrund

Die Erweiterung des Java Linters in JDK 21 um die neue Regel ist eine gute Verbesserung, da sie hilft, Code-Smell zu verhindern. Keine überschreibbaren Methoden aus dem Konstruktor aufzurufen, wird seit Langem empfohlen² ³. Wie aber eine Analyse⁴ einiger bekannter Open-Source-Projekte zeigt, gibt es im Code dennoch immer wieder Stellen, an denen die Empfehlung missachtet oder vergessen wurde. Auch bei unseren Projekten konnte der Java Linter nach dem Upgrade auf JDK 21 vereinzelt Stellen finden, die nicht der Empfehlung folgten.

Es wird im Folgenden vorausgesetzt, dass der abgebildete Code immer mit dem Flag -Xlint:all kompiliert wird, auch wenn dies nicht extra angegeben wurde. Abrufbar ist der vollständige Code im dafür bereitgestellten GitHub-Repository.

Origin Story

Nachfolgend soll die Rationale für die this-escape-Warnung anhand eines Beispiels erläutert werden. Dazu schauen wir uns als Beispiel die Klasse Person an, siehe unten. Die Klasse hat eine Instanzvariable name und eine öffentliche nicht finale Methode greet(). Im Konstruktor der Klasse wird die Methode greet() aufgerufen. Der Code lässt sich mit JDK 17 problemlos kompilieren, aber beim Kompilieren mit JDK 21 gibt der Java Linter eine this-escape-Warnung aus.

public class Person {

    private final String name;

    public Person(String name) {
        this.name = Objects.requireNonNullElse(name, "stranger");
        greet(); // Calls overrideable method, causes this-escape warning
    }

    public void greet() {
        System.out.println("Hello " + name + "!");
    }
}

Die Klasse Person für sich ist unproblematisch, aber sobald die Klasse erweitert wird, kann es zu schwer auffindbaren Fehlern führen. Davor warnt der Java Linter mit der this-escape-Warnung. Um einen Fehler provozieren zu können, erstellen wir zusätzlich die Klasse Musician, die die Klasse Person erweitert. Die Klasse Musician fügt eine weitere Instanzvariable instrument hinzu und überschreibt die Methode greet().

public class Musician extends Person {

    private final String instrument;

    public Musician(String name, String instrument) {
        super(name);
        this.instrument = Objects.requireNonNullElse(instrument, "triangle");
    }

    @Override
    public void greet() {
        super.greet();
        System.out.println("I heard you play " + instrument + ". Awesome!");
    }
}

Was wird nun ausgegeben, wenn ein neues Objekt Musician mit der Anweisung new Musician("Jimi", "guitar") erstellt wird? Beim Erstellen einer Instanz von Musician wird im Konstruktor von Musician der Konstruktor von Person aufgerufen. Im Konstruktor von Person erfolgt die Initialisierung der Instanzvariable name und dann der Aufruf der Methode greet(). Anschließend wird im Konstruktor der Klasse Musician die Variable instrument initialisiert. Die Anweisung führt entsprechend zu der folgenden Ausgabe:

Hello Jimi!
I heard you play null. Awesome!

Die überschriebene Methode greet() wird aus Person aufgerufen, noch bevor Musician vollständig instanziiert wurde. Dies führt dazu, dass für instrument der Wert null ausgegeben wird, obwohl instrument nach Instanziierung des Objekts Musician nie den Wert null haben kann. Die Ursache für die fehlerhafte Ausgabe ist in dem Beispiel schnell ersichtlich. Dennoch zeigt es, dass eine Klasse keine überschreibbaren Methoden der eigenen Klasse im Konstruktor aufrufen sollte, da die Klasse nicht sicherstellen kann, dass sie sich beim Aufrufen der Methode in einem konsistenten Zustand befindet. Demnach sollte die Methode greet() also nicht gleichzeitig überschreibbar sein und vom Konstruktor aufgerufen werden.

Zu beachten ist, dass der Fehler in diesem Beispiel offensichtlich sein mag. Wir haben hier ein einfaches Beispiel betrachtet, um den Sachverhalt zu erläutern. In der Praxis kann der Fehler in einer umfangreichen Klasse innerhalb einer komplexen Klassenhierarchie mit weiteren Vererbungen und Verschachtelungen in Zusammenhang mit Nebenläufigkeit erheblich schwieriger zu lokalisieren sein.

Drei Lösungswege

In den folgenden drei Abschnitten werden Möglichkeiten vorgestellt, wie das Aufrufen einer überschreibbaren Methode aus dem Konstruktor verhindert oder umgangen werden kann.

Verwendung der Schlüsselwörter `final`, `private` oder `static`

Die direkteste Möglichkeit, die this-escape-Warnung zu verhindern, ist das Überschreiben aller vom Konstruktor aufgerufenen Methoden zu verbieten. Dies ist in Java mit den Schlüsselwörtern final, private und static erreichbar. Wird eine Klasse als final deklariert, ist es nicht mehr möglich, diese zu erweitern. Dementsprechend ist auch keiner ihrer Methoden überschreibbar. Die Deklaration einer Methode als final, private oder static sorgt dafür, dass nur die Methode nicht überschrieben werden kann.

Die fehlerhafte Ausgabe der Klasse Person und Musician aus dem letzten Abschnitt können wir mithilfe der Schlüsselwörter auf unterschiedliche Weise beheben. Im Folgenden wird zunächst die Methode greet() von Person als final deklariert, um den Java Linter zufriedenzustellen.

public class Person {

    private final String name;

    public Person(String name) {
        this.name = Objects.requireNonNullElse(name, "stranger");
        greet();
    }

    public final void greet() { // Method is now final
        System.out.println("Hello " + name + "!");
    }
}

Die Klasse Musician kann nun nicht mehr die Methode greet() überschreiben. Stattdessen wird in der Klasse Musician eine eigene Methode printInstrument() definiert, die für die Ausgabe des Instruments verantwortlich ist. In dem Beispiel wird davon ausgegangen, dass Klasse Musician von keiner anderen Klasse erweitert werden soll, daher fügen wir das Schlüsselwort final zu der Deklaration der Klasse hinzu. Andernfalls würde uns der Java Linter auch hier eine this-escape- Warnung ausgeben.

public final class Musician extends Person { // Class is now final

    private final String instrument;

    public Musician(String name, String instrument) {
        super(name);
        this.instrument = Objects.requireNonNullElse(instrument, "triangle");
        printInstrument();
    }

    public void printInstrument() {
        System.out.println("I heard you play " + instrument + ". Awesome!");
    }
}

Nach den Änderungen führt die Anweisung new Musician("Jimi", "guitar") zu der folgenden Ausgabe:

Hello Jimi!
I heard you play guitar! Awesome!

Nicht immer ist es möglich, eine Klasse als final oder eine Methode als final, private oder static zu deklarieren. Falls die Klasse von einem Dependency Injection Framework, wie Spring oder Quarkus, verwaltet wird, kann der Aufruf von überschreibbaren Methoden aus dem Konstruktor meist auch auf eine andere Weise umgangen werden. Diese schauen wir uns im nächsten Abschnitt an.

Verwendung der Annotation `@PostConstruct`

In den nachfolgenden Beispielen verwenden wir Spring. Das Verfahren ist aber genauso für andere Dependency Injection Frameworks anwendbar, welche die Jakarta Contexts and Dependency Injection Spezifikation bzw. die Jakarta Annotations Spezifikation implementieren. Teil der Jakarta Annotations Spezifikation ist die Annotation @PostContruct, welche wesentlich für das hier vorgestellte Verfahren ist. Mithilfe der Annotation können wir uns in den Lebenszyklus einer von Spring verwalteten Bean einklinken. Wie es der Name bereits vermuten lässt, ist es in dem Fall von @PostConstruct der Zeitpunkt, nachdem der Konstruktor ausgeführt und die Bean vollständig initialisiert wurde. Dies ermöglicht es, den Aufruf einer überschreibbaren Methode aus dem Konstruktor heraus an eine sichere Stelle zu verschieben. Spring bietet noch andere Möglichkeiten, eigenen Code in den Lebenszyklus einer Bean einzufügen, aber die Verwendung von @PostConstruct ist die empfohlene⁵, weshalb hier nur auf diese eingegangen wird.

Wir erweitern das Beispiel aus dem vorherigen Abschnitt, um die Verwendung von @PostConstruct veranschaulichen zu können. In dem vorherigen Beispiel wurde jedem Musiker das Instrument triangle zugeordnet, wenn kein Instrument angegeben wurde. Das wollen wir nachfolgend ein wenig optimieren, indem wir ermöglichen, eine externe Ressource anzubinden. Diese soll ein Mapping zwischen bekannten Musikern, repräsentiert durch ihren Namen, und ihrem Instrument bereitstellen. Für einen schnelleren Zugriff ist das Mapping in einem Cache zu speichern. Die Verwendung des Caches ist im folgenden Listing schematisch dargestellt:

String name = getName(); // Get name of a musician from somewhere
String instrument = getInstrument(); // Get instrument from somewhere
if (instrument == null) {
    /*
         musicianInstrumentCache contains a mapping of the form:
         Jimi -> guitar
         Miles -> trumpet
         Ludwig -> piano
         ...
    */
    instrument = musicianInstrumentCache.getInstrumentFor(name);
}
Musician musician = new Musician(name, instrument);

Für die Umsetzung erstellen wir zwei Klassen. Die abstrakte Klasse MusicianInstrumentCache beinhaltet einen einfachen Cache, der als eine Map mit der Abbildung Musikername ⟼ Instrument realisiert wurde, und ruft im Konstruktor die Methode updateCache() auf. Die Methode updateCache() soll von den Spezialisierungen von MusicianInstrumentCache (s.u.) dazu verwendet werden, eine externe Ressource einzulesen und den Cache zu aktualisieren. Für die Methode updateCache() gilt:

Der Aufruf der Methode soll es anderen Klassen ermöglichen, den Cache zur Laufzeit zu aktualisieren. Daher soll die Methode öffentlich sein.
Für unterschiedliche Typen von Ressourcen, wie externe Dateien, Datenbanken usw., sollen verschiedene Spezialisierungen von MusicianInstrumentCache erstellt werden können, welche die Methode updateCache() entsprechend der eingesetzten Ressource überschreiben. Daher soll die Methode abstrakt sein und kann nicht als private, final oder static deklariert werden.

Die Implementierung der abstrakten Klasse MusicianInstrumentCache ist nachfolgend angegeben. Der Linter gibt eine this-escape-Warnung beim Kompilieren der Klasse aus, da im Konstruktor die abstrakte Methode updateCache() aufgerufen wird.

public abstract class MusicianInstrumentCache {

    protected static final Map<String, String> cache =
            new ConcurrentHashMap<>();

    public MusicianInstrumentCache() {
        System.out.println("MusicianInstrumentCache.init()");
        updateCache(); // Calls overrideable method, causes this-escape warning
    }

    public abstract void updateCache(); // Should be public and abstract

    public String getInstrumentFor(String name) {
        return cache.get(name);
    }
}

Bevor wir uns dem Problem widmen, betrachten wir eine Spezialisierung der Klasse MusicianInstrumentCache. Die Klasse FileBasedMusicianInstrumentCache zeigt eine mögliche Spezialisierung von MusicianInstrumentCache. Die Klasse soll das Mapping über den von Spring injizierten ResourceLoader aus einer Datei einlesen und anschließend in den Cache schreiben. Um das Beispiel kurzzuhalten, wurde das Einlesen der Datei und das Schreiben in den Cache in dem Code nur angedeutet.

@Component
public class FileBasedMusicianInstrumentCache extends MusicianInstrumentCache {

    private final ResourceLoader resourceLoader;
    private String mappingResource = "classpath:mapping.csv";

    public FileBasedMusicianInstrumentCache(ResourceLoader resourceLoader) {
        System.out.println("FileBasedMusicianInstrumentCache.init()");
        this.resourceLoader = resourceLoader;
    }

    @Override
    public void updateCache() {
        System.out.println("FileBasedMusicianInstrumentCache.updateCache()");
        // Logic for importing mapping and adding it to the cache. Briefly,
        // represented by the following lines without exception handling:
        Resource resource = resourceLoader.getResource(mappingResource);
        String content = resource.getContentAsString(StandardCharsets.UTF_8);
        Arrays.stream(content.split("\n"))
                .map(line -> line.split(","))
                .forEach(mapping -> cache.put(mapping[0], mapping[1]));
    }

    // getter and setter
}

Zu beachten ist, dass der resourceLoader noch nicht gesetzt wurde, wenn im Konstruktor der Klasse MusicianInstrumentCache die Methode updateCache() der Klasse FileBasedMusicianInstrumentCache aufgerufen wird. Das liegt daran, dass wie im Abschnitt Origin Story beschrieben im Konstruktor der erweiternden Klasse FileBasedMusicianInstrumentCache als erste Anweisung der Konstruktor der Klasse MusicianInstrumentCache aufgerufen wird, selbst wenn der Aufruf über super() nicht explizit im Java Code angegeben wurde. Dies ist auch in der Ausgabe ersichtlich, bei der FileBasedMusicianInstrumentCache.updateCache() vor FileBasedMusicianInstrumentCache.init() in die Konsole geschrieben wird:

MusicianInstrumentCache.init()
FileBasedMusicianInstrumentCache.updateCache()
FileBasedMusicianInstrumentCache.init()

Glücklicherweise lässt sich der Fehler und die this-escape-Warnung mit der Annotation @PostConstruct ohne größere Anpassungen beheben, sodass nicht mehr die überschreibbare Methode updateCache() aufgerufen wird, bevor das Objekt vollständig initialisiert wurde. Es genügt, die Methode updateCache() in der Klasse MusicianInstrumentCache mit @PostConstruct zu annotieren. Der Aufruf der Methode updateCache() kann aus dem Konstruktor entfernt werden, da Spring jetzt für den Aufruf verantwortlich ist. Die Klasse FileBasedMusicianInstrumentCache kann unverändert bleiben, da Spring prüft, ob in einer Superklasse eine Methode mit @PostConstruct annotiert ist und das Verhalten für die Unterklassen übernimmt.

public abstract class MusicianInstrumentCache {

    protected static final Map<String, String> cache =
            new ConcurrentHashMap<>();

    public MusicianInstrumentCache() {
        System.out.println("MusicianInstrumentCache.init()");
        // Remove importMapping() method call here
    }

    @PostConstruct // Add annotation
    public abstract void updateCache();

    public String getInstrumentFor(String name) {
        return cache.get(name);
    }
}

Beim Starten der Anwendung wird nun zunächst beim Initialisieren der Klasse FileBasedMusicianInstrumentCache wie bisher der Konstruktor MusicianInstrumentCache aufgerufen, aber in dem Konstruktor wird nicht mehr die Methode updateCache() aufgerufen, sondern stattdessen zunächst der Konstruktor von FileBasedMusicianInstrumentCache abgeschlossen. Erst nachdem FileBasedMusicianInstrumentCache vollständig konstruiert wurde, ruft Spring die mit @PostConstruct annotierte Methode updateCache() auf. Dies führt zu der folgenden Ausgabe:

MusicianInstrumentCache.init()
FileBasedMusicianInstrumentCache.init()
FileBasedMusicianInstrumentCache.updateCache()

Das Vorgehen mit @PostConstruct ermöglicht die Verwendung von überschreibbarer Methode an die Erstellung des Objekts zu koppeln, ohne die Probleme, die beim Aufruf aus dem Konstruktor heraus resultieren können. Dies setzt allerdings voraus, dass ein Dependency Injection Framework verwendet wird, welches die Annotation @PostConstruct oder vergleichbares unterstützt.

In den vorherigen beiden Abschnitten wurden Vorgehen beschrieben, um den Linter durch kleine Kniffe wieder zufriedenzustellen. In dem nächsten Abschnitt betrachten wir noch eine andere Möglichkeit, mit der Warnung umzugehen.

Überarbeiten des Klassendesigns

Manchmal kann die this-escape-Warnung auch als Anregung dienen, das Klassendesign erneut zu evaluieren. Je nach Ergebnis der Evaluation können die durchzuführenden Änderungen einen größeren Einfluss auf die Struktur des Codes haben, als es bei den beiden anderen Verfahren der Fall war. Wir greifen das Beispiel aus dem vorherigen Abschnitt auf, um aufzuzeigen, wie eine Anpassung des Klassendesigns aussehen könnte.

In dem letzten Abschnitt wurden die beiden Klassen MusicianInstrumentCache und FileBasedMusicianInstrumentCache erstellt, wobei letztere die erstere erweiterte. Durch die Vererbung musste die Methode updateCache() öffentlich und überschreibbar sein, was schließlich zu der this-escape-Warnung geführt hat. Das Klassendesign soll im Folgenden eine Komposition statt einer Vererbung verwenden.

Die Funktionalität der Klasse MusicianInstrumentCache wird dazu aufgeteilt. Das Verwalten des Cache wird weiterhin Aufgabe der Klasse MusicianInstrumentCache bleiben. Das Einlesen einer externen Ressource wird in die Klasse FileBasedMusicianInstrumentImporter ausgelagert. Die Klasse FileBasedMusicianInstrumentImporter erhält außerdem eine Referenz auf eine Instanz der Klasse MusicianInstrumentCache. Unten ist das alte, auf Vererbung basierende Klassendesign, dem neuen Klassendesign in einem UML-Klassendiagramm gegenübergestellt.

Vererbung                             Komposition
=========                             ===========
┌────────────────────────────────┐   ┌────────────────────────────────────────┐
│           <abstract>           │   │                                        │
│    MusicianInstrumentCache     │   │        MusicianInstrumentCache         │
├────────────────────────────────┤   ├────────────────────────────────────────┤
│#cache:Map<String,String>       │   │-cache:Map<String,String>               │
├────────────────────────────────┤   ├────────────────────────────────────────┤
│+importMapping():void <abstract>│   │~put(name:String,instrument:String):void│
│+getInstrumentFor(String):String│   │+getInstrumentFor(String):String        │
└────────────────────────────────┘   └────────────────────────────────────────┘
                 ▲                                       ^
                 │                                       │
                 │                                       │ -cache
                 │                                       │
┌────────────────┴───────────────┐   ┌───────────────────┴────────────────────┐
│FileBasedMusicianInstrumentCache│   │  FileBasedMusicianInstrumentImporter   │
├────────────────────────────────┤   ├────────────────────────────────────────┤
│-resourceLoader:ResourceLoader  │   │-resourceLoader:ResourceLoader          │
├────────────────────────────────┤   ├────────────────────────────────────────┤
│+importMapping():void           │   │+importMapping():void                   │
└────────────────────────────────┘   └────────────────────────────────────────┘

Das nachfolgende Listing zeigt den Code der neuen Klasse MusicianInstrumentCache. Die Klasse besitzt zwei Methoden, jeweils eine für das Auslesen und Schreiben des Cache. MusicianInstrumentCache wurde mit @Component annotiert, da es vom Dependency Injection Framework verwaltet und in FileBasedMusicianInstrumentImporter injiziert werden soll.

@Component
public class MusicianInstrumentCache {

    private final Map<String, String> cache = new ConcurrentHashMap<>();

    void put(String name, String instrument) {
        cache.put(name, instrument);
    }

    public String getInstrumentFor(String name) {
        return cache.get(name);
    }
}

Der Code der Klasse FileBasedMusicianInstrumentImporter ist im folgenden Listing dargestellt. Die Annotation @PostConstruct wird nicht mehr benötigt. Es reicht nun aus, die Klassen als final zu deklarieren.

@Component
public final class FileBasedMusicianInstrumentImporter {

    private final MusicianInstrumentCache cache;
    private final ResourceLoader resourceLoader;
    private String mappingResource = "classpath:mapping.csv";

    public FileBasedMusicianInstrumentImporter(MusicianInstrumentCache cache,
                                               ResourceLoader resourceLoader) {
        this.cache = cache;
        this.resourceLoader = resourceLoader;
        importMapping();
    }

    public void importMapping() {
        // Logic for importing mapping and adding it to the cache. Briefly,
        // represented by the following lines without exception handling:
        Resource resource = resourceLoader.getResource(mappingResource);
        String content = resource.getContentAsString(StandardCharsets.UTF_8);
        Arrays.stream(content.split("\n"))
                .map(line -> line.split(","))
                .forEach(mapping -> cache.put(mapping[0], mapping[1]));
    }

    // getter and setter
}

Das Beispiel soll einen Eindruck liefern, wie eine Überarbeitung des Klassendesigns aussehen könnte. Dies muss jedoch nicht immer eine Umstellung von Vererbung nach Komposition beinhalten. Möglich wäre etwa auch das Extrahieren/Verschieben von Methoden oder die Anwendung eines Erzeugermusters, um den Aufruf einer überschreibbaren Methode aus dem Konstruktor aufzulösen.

An dieser Stelle haben wir alle Verfahren betrachtet, die beim Upgrade unseres Projekts angewendet wurden. Der nächste Abschnitt fasst noch mal die wesentlichen Punkte dieses Beitrags zusammen.

Zusammenfassung

In diesem Beitrag wurde die Motivation hinter der this-escape-Warnung des Java Linters beschrieben und drei Möglichkeiten gezeigt, die Warnungen zu verhindern. Die Möglichkeiten sind nachfolgend aufgelistet:

Verwendung der Schlüsselwörter final, private oder static
Verwendung der Annotation @PostConstruct
Überarbeitung des Klassendesigns

Nicht immer ist jedes Verfahren anwendbar. Manchmal ist auch eine Kombination verschiedener Verfahren nötig, um die Warnung zu beheben. Welcher Umgang mit der Warnung am besten geeignet ist, muss von Fall zu Fall entschieden werden. Meistens sollte das erste oder zweite Verfahren jedoch ausreichen. Die Anwendung des zweiten Verfahrens setzt allerdings voraus, dass die betroffene Klasse durch ein Dependency Injection Framework wie Spring oder Quarkus verwaltet wird. Das Überarbeiten des Klassendesigns sollte immer zum Erfolg führen, kann allerdings auch am meisten Zeit in Anspruch nehmen.

Referenzen

Add lint check for calling overridable methods from a constructor ↩
Joshua Bloch. 2001. Effective Java programming language guide. Sun Microsystems, Inc., USA. ↩
Writing Final Classes and Methods ↩
Calling Methods from a Constructor ↩
Customizing the Nature of a Bean ↩

Time-Travelling through Data Realms with Auditing

2024-03-26T00:00:00-05:00

Guardian of data history

Auditing plays a significant role in the realm of data management. It serves as the guardian of data history, ensuring that every alteration to data is not only tracked, but also logged comprehensively. Essentially, auditing offers us a unique time-traveling mechanism, allowing us to traverse the history of our data, discover who made which changes, and understand the when and why behind those alterations. As developers, it is vital to consider efficient auditing methods for specific applications and use-cases. In this article, I will lay out the differences between the Java-based auditing tools Hibernate Envers, JPA Data and database trigger-based auditing. Using a simple Java application with Spring Boot, Spring Security, JPA Data and Hibernate ORM as an example, we will explore which approach is most suitable for various situations and requirements.

First, the basics: Change Data Capture

Change Data Capture (CDC) describes a process in which changes made to data in a database are propagated in real-time to a downstream system. This builds the basis for any auditing system. Any auditing process needs to be alerted that the audited data has been changed. This change could be a database insert, or a modify or delete operation. The existence of this change is then either preserved in some way, or a trigger event could be initiated.

Stay in the Java world: Hibernate Envers

Hibernate Envers presents a CDC solution that simplifies auditing within Java applications. What sets it apart is its seamless integration with Hibernate ORM, ensuring that you can stay firmly within the Java ecosystem. It works with one global REVINFO table as well as a table for each entity. To audit an entity, it is sufficient to annotate it with the @Audited annotation. While Envers uses a deny-listing instead of an allow-listing approach, keep in mind that each property is then automatically audited if not explicitly excluded. You will remember this once your database runs out of space because you forgot to explicitly exclude big files from auditing. Let us look at a simple example: imagine we have an Entity called dog with a few simple properties like name and height, and we mark it to be audited.

@Audited
@Entity
public class Dog {

	@Id
	private Long id;

	private String name;

	private Integer height;

	//Getters and setters

}

From this, hibernate will generate three tables: the known entity table, the REVINFO table, and the entity audit table (see picture). The REVINFO table consists of a revision ID and a timestamp. The revision ID included in the REVINFO table is pointing to the revision ID in the entity audit table. The audit table additionally includes the entity properties and a REVTYPE column that states the type of the occurred modification. That means that the auditing table has a history of every revision of an entity. That comes in handy if one wants to fetch the state of an entity at any given point in time, for example to diff it with the current state. Envers provides numerous ways to fulfill your auditing desires by offering a ton of configuration possibilities: from excluding single properties from being audited, to customizing the auditing tables itself. Read more about that in its documentation.

To retrieve the audit data, Envers offers a AuditReaderFactory which queries all entity state snapshots. For our example dog entity with an object instance with ID 1, this would look like this:

List<Dog> snapshots = AuditReaderFactory.get(entityManager)
.createQuery()
.forRevisionsOfEntity( Dog.class, true, true)
.add(AuditEntity.id().eq(1L))
.getResultList();

Pros:

Stays in the Java World: Hibernate Envers offers a smooth transition into the auditing world, keeping your entire process within the Java ecosystem. This is particularly advantageous if your application primarily revolves around Java.
Automatic Table Generation: Envers streamlines the auditing setup by automatically generating auditing tables, even for databases like PostgreSQL. Tools like LiquiBase can further simplify this process, making it a breeze to configure.
Database-Agnostic: One of the standout features of Envers is its database-agnostic nature. It doesn’t confine you to a particular type of database, ensuring flexibility across various database systems, whether you are working with e.g., PostgreSQL or MariaDB.
Revision at Point in Time: Envers empowers you to access data as it existed at a specific revision, offering granular insights for historical data analysis or diffing.

Cons:

Performance Overhead: Envers introduces an additional layer of SQL operations for each transaction, including insertions, updates, and deletions. While these operations are essential for comprehensive auditing, they may potentially impact the overall performance due to their synchronous nature.
Limited Data Source: Envers primarily captures changes initiated within your application. This means that changes made through SQL consoles or other external applications might go unnoticed.
Lack of Bulk Support: Envers does not provide support for bulk updates or deletions, which can be a limitation in use cases where such operations are a common occurrence.

Break out of your java comfort zone: Database triggers

If you are not afraid of leaving the cozy safety provided by Java abstraction layers, want to improve the performance of your auditing solution, or desire more customization, trigger-based auditing could be the right choice for you. Let’s look at how we can transform our dog example to use trigger-based auditing. In a first step, we want to record any type of change in a separate dog_audit_log table which contains a new_value and old_value column with type jsonb. We use jsonb as the column type here for simplicity and durability reasons: if a column is added or removed from the dog entity, it will not affect our audit log table.

In order to achieve this, we need to implement a function in PostgreSQL database which will transfer the committed changes. Additionally, we need to also implement a trigger which will execute this function if a INSERT, UPDATE or DELETE statement is committed.

CREATE TRIGGER dog_audit_trigger
AFTER INSERT OR UPDATE OR DELETE ON dog
FOR EACH ROW EXECUTE FUNCTION dog_audit_trigger_func()

There are also more automated solutions available that use database triggers, e.g., Debezium. It is Kafka based and extracts the CDC events from the binary log of the database.

To retrieve the audit data, one must “manually” query the dog_audit_log and join it with the dog table.

Pros:

Decoupled Architecture: One of the most significant advantages of trigger-based auditing is its decoupled architecture. It operates independently of your application, providing a non-intrusive auditing solution.
Comprehensive Auditing: It captures all changes, not just those initiated within your application. This breadth makes it suitable for auditing data from various sources, ensuring that no change goes unnoticed.

Cons:

Not Coupled with Hibernate: Trigger-based auditing is not tightly integrated with Hibernate, which may make it a less convenient choice if your application heavily relies on Hibernate for data management.
Cascading Trigger Hell: Be aware of possible side effects of other database operations that could initiate cascading triggers.
Metadata Retrieval Challenges: Extracting metadata can be more challenging. This may require additional effort and customization to achieve the desired results.

Keep it simple: JPA Data

For basic auditing requirements, JPA Data offers a straightforward solution. It enables you to track when an entity was created or modified, providing basic auditing capabilities without the intricacies associated with Hibernate Envers or database triggers. To achieve this, we can use simple annotation provided by JPA Data. Additionally, we need to add the @EnableJpaAuditing annotation to our configuration class. Let’s look at our example dog entity again:

@Entity
@EntityListeners(AuditingEntityListener.class)
public class Dog {

	@Id
	private Long id;

	private String name;

	private Integer height;

	@CreatedDate
	private Instant createdAt;

	@CreatedBy
	private String createdBy;

	@LastModifiedDate
	private Instant modifiedAt;

	@LastModifiedBy
	private String modifiedBy;

	//Getters and setters

}

We simply implement four more attributes in our entity which track when and by whom it was created or modified. In contrast to Envers and trigger-based solutions, these attributes are not saved in a separate table and do not include a snapshot of the previous state. That means that JPA Data does not keep a history of revisions of your entity anywhere, only when and by whom the current version was created or last edited. While this solution does not offer the level of customization provided by hibernate, it is possible to extend or modify its capabilities by, e.g., modifying the used EntityListener. Since we do not save snapshots of an entity, we can only query the current entity object, including when and by whom it was modified last or created.

Pros:

Simplicity: JPA Data shines in its simplicity. It’s easy to set up and use, making it an excellent fit for projects with basic auditing requirements.
Performance: Due to its lightweight nature, JPA Data introduces minimal performance overhead, ensuring that your application’s performance remains largely unaffected.

Cons:

Limited Auditing Features: JPA Data, while simple and lightweight, offers only basic auditing capabilities. It is suitable for straightforward use cases but falls short when it comes to more advanced auditing requirements.
Inability to Capture Delete Operations: JPA Data does not capture delete operations, limiting its effectiveness in comprehensive auditing scenarios where tracking deletions is essential.

Conclusion

In conclusion, selecting the right auditing approach depends, as always, on your project’s specific requirements and priorities.

Hibernate Envers offers seamless integration, keeping you firmly in the Java world, but it comes with potential performance overhead.

Trigger-based auditing is the go-to-choice for capturing changes from various sources, but its setup may be more complex, and it lacks tight integration with Hibernate.

JPA Data is ideal for basic auditing needs, prioritizing simplicity and minimal performance impact. However, it may not suffice for advanced auditing scenarios.

Zeitreisen durch Datenwelten mit Auditing

2024-03-26T00:00:00-05:00

Hüter der Datenhistorie

Audit-Verfahren sind im Bereich des Datenmanagements unverzichtbar. Sie fungieren als Hüter der Datenhistorie und gewährleisten, dass jede Änderung an Daten nicht nur nachverfolgt, sondern auch detailliert festgehalten wird. Audit-Methoden ermöglichen uns eine Art Zeitreise durch die Datenhistorie, um zu verstehen, wer, wann und welche Änderungen vorgenommen hat.

Für Entwickler ist es daher wichtig, effektive Audit-Techniken für spezifischen Anwendungen und Anforderungen zu kennen. In diesem Artikel stelle ich die Unterschiede zwischen den Java-basierten Tools Hibernate Envers, JPA Data und dem Einsatz von Datenbank-Triggern für das Auditing vor. Anhand einer Beispielanwendung mit Spring Boot, Spring Security, JPA Data und Hibernate ORM untersuchen wir, welcher Ansatz für verschiedene Szenarien am besten geeignet ist.

Ein Blick auf die Grundlagen: Change Data Capture

Change Data Capture (CDC) ist ein Verfahren, das Datenänderungen in einer Datenbank in Echtzeit an ein nachgelagertes System übermittelt. Diese Technik ist das Fundament jedes Audit-Systems, denn jeder Audit-Prozess muss über Änderungen an den überwachten Daten informiert werden. Solche Änderungen können Einfüge-, Update- oder Löschoperationen in der Datenbank sein. Das Erkennen dieser Änderungen erfolgt entweder durch Aufzeichnung oder durch Auslösen eines Trigger-Ereignisses.

In der Java-Welt: Hibernate Envers

Hibernate Envers bietet eine CDC-Lösung speziell für Java-Anwendungen, die das Auditing vereinfacht. Die nahtlose Integration mit Hibernate ORM ermöglicht es, innerhalb des Java-Ökosystems zu bleiben. Das System nutzt eine zentrale REVINFO-Tabelle sowie spezifische Tabellen für jede Entität. Um eine Entität zu auditieren, genügt es, diese mit der Annotation @Audited zu versehen.

Envers setzt auf einen Deny-Listing-Ansatz. Eigenschaften werden also standardmäßig auditiert – es sei denn, sie werden explizit ausgenommen. Das wird besonders dann deutlich, wenn die Datenbank an ihre Grenzen stößt, weil man vergessen hat, große Dateien vom Audit auszunehmen. Betrachten wir dazu ein einfaches Beispiel: Eine Entität namens Dog mit Eigenschaften wie Name und Größe wird für das Auditing annotiert.

@Audited
@Entity
public class Dog {

	@Id
	private Long id;
	private String name;
	private Integer height;
	//Getters and setters

}

Daraus erzeugt Hibernate drei spezifische Tabellen, wie in der folgenden Abbildung dargestellt. Zu diesen Tabellen zählen die Übersicht der auditierten Entitäten, die REVINFO-Tabelle und die Tabelle für die Überprüfung der Entitäten selbst. Die REVINFO-Tabelle setzt sich aus der Revisions-ID und einem Zeitstempel zusammen. Diese Revisions-ID korrespondiert mit der in der Tabelle für die Entitätsprüfung, die neben der Revisions-ID und den Entitätseigenschaften auch eine Spalte REVTYPE enthält. Diese Spalte kennzeichnet den Typ der durchgeführten Änderung, was bedeutet, dass die Audittabelle eine vollständige Historie jeder Revision einer Entität bewahrt. Das ist besonders nützlich, wenn man den Zustand einer Entität zu einem bestimmten Zeitpunkt rekonstruieren möchte, etwa um ihn mit dem aktuellen Zustand zu vergleichen.

Envers bietet umfangreiche Konfigurationsmöglichkeiten, um sämtlichen Anforderungen an das Auditing gerecht zu werden. Das reicht vom Ausschluss bestimmter Eigenschaften von der Auditierung bis hin zur individuellen Anpassung der Auditing-Tabellen. Weitere Informationen dazu findet man in der offiziellen Dokumentation.

Um Audit-Daten abzurufen, bietet Envers die AuditReaderFactory an, die es ermöglicht, alle Zustandsschnappschüsse einer Entität zu ermitteln. Für unser Beispiel mit der Entität Dog und der Objektinstanz-ID „1“ würde das folgendermaßen aussehen:

List<Dog> snapshots = AuditReaderFactory.get(entityManager).createQuery()
    .forRevisionsOfEntity( Dog.class, true, true)
    .add(AuditEntity.id().eq(1L))
    .getResultList();

Vorteile:

In der Java-Welt: Hibernate Envers ermöglicht einen reibungslosen Übergang zu Auditing-Systemen, alles innerhalb des Java-Ökosystems.
Automatische Tabellengenerierung: Envers erleichtert die Einrichtung von Auditing-Tabellen durch automatische Generierung, auch für Datenbanken wie PostgreSQL. Werkzeuge wie LiquiBase können diesen Prozess noch weiter vereinfachen.
Datenbank-agnostisch: Ein besonderer Vorteil von Envers ist seine Datenbank-Unabhängigkeit. Dadurch ist man ist nicht auf einen bestimmten Datenbanktyp festgelegt und kann flexibel mit verschiedenen Datenbanksystemen arbeiten, sei es PostgreSQL, MariaDB oder andere.
Revision zu einem bestimmten Zeitpunkt: Mit Envers kann man auf Daten zugreifen, wie sie zu einem bestimmten Zeitpunkt vorlagen, und so detaillierte Einblicke in historische Daten oder für Vergleichsanalysen gewinnen.

Nachteile:

Performance Overhead: Envers fügt jeder Transaktion zusätzliche SQL-Operationen hinzu, einschließlich Einfügungen, Aktualisierungen und Löschvorgänge. Diese notwendigen Operationen können aufgrund ihrer synchronen Natur die Gesamtperformance beeinträchtigen.
Beschränkte Datenquelle: Envers konzentriert sich hauptsächlich auf Änderungen, die innerhalb der Anwendung durchgeführt werden. Änderungen, die über SQL-Konsolen oder durch andere externe Anwendungen erfolgen, könnten daher übersehen werden.
Fehlende Unterstützung für Bulkoperationen: Envers bietet keine spezielle Unterstützung für Bulkaktualisierungen oder -löschungen – in Szenarien, in denen solche Operationen regelmäßig anfallen, kann das eine Einschränkung darstellen.

Raus aus der Java-Komfortzone: Datenbank-Trigger

Wenn ihr bereit seid, die Komfortzone der Java-Abstraktionsebenen zu verlassen und die Performanz eurer Auditing-Lösung verbessern wollt oder wenn ihr nach den umfangreichsten Anpassungsmöglichkeiten sucht, könnte triggerbasiertes Auditing die richtige Wahl für euch sein.

Schauen wir uns an, wie wir unser Beispiel in ein triggerbasiertes Auditing-System umwandeln können. Im ersten Schritt zeichnen wir jede Änderungsart in einer separaten Tabelle dog_audit_log auf, die eine Spalte für new_value und eine für old_value, jeweils vom Typ jsonb, beinhaltet. Wir verwenden jsonb für eine einfache Handhabung und um Anpassungen flexibel zu gestalten. Änderungen in der Struktur der Entität Dog, wie das Hinzufügen oder Entfernen von Spalten, beeinflussen unsere Audit-Log-Tabelle nicht.

Damit wir das erreichen, setzen wir eine Funktion in der PostgreSQL-Datenbank um, die die vorgenommenen Änderungen verarbeitet. Zudem müssen wir einen Trigger einrichten, der diese Funktion aktiviert, sobald eine INSERT-, UPDATE- oder DELETE-Operation durchgeführt wird.

CREATE TRIGGER dog_audit_trigger
AFTER INSERT OR UPDATE OR DELETE ON dog
FOR EACH ROW EXECUTE FUNCTION dog_audit_trigger_func()

Es gibt auch automatisierte Lösungen, die Datenbank-Trigger nutzen, wie zum Beispiel Debezium. Dieses Tool basiert auf Kafka und extrahiert CDC-Events aus dem binären Log der Datenbank. Um an die Audit-Daten zu kommen, müsst ihr die dog_audit_log-Tabelle „manuell“ abfragen und sie mit der Dog-Tabelle verknüpfen.

Vorteile:

Entkoppelte Architektur: Ein Hauptvorteil der triggerbasierten Überwachung ist ihre Unabhängigkeit von der Anwendung. Sie bietet eine nicht-intrusive Auditing-Lösung, die im Hintergrund läuft.
Umfassendes Auditing: Diese Methode erfasst alle Änderungen – nicht nur die, die innerhalb der Anwendung erfolgen. Das macht sie ideal, um Daten aus verschiedenen Quellen zu prüfen und sicherzustellen, dass keine Änderungen übersehen werden.

Nachteile:

Nicht mit Hibernate gekoppelt: Da die triggerbasierte Überwachung nicht direkt in Hibernate integriert ist, könnte sie für Anwendungen, die stark auf Hibernate für die Datenverwaltung setzen, weniger geeignet sein.
Kaskadierende Trigger-Hölle: Seid euch der möglichen Nebenwirkungen bewusst, die durch andere Datenbankoperationen ausgelöste kaskadierende Trigger haben könnten.
Herausforderungen beim Abrufen von Metadaten: Das Herausziehen von Metadaten kann schwieriger sein und erfordert womöglich zusätzlichen Aufwand sowie Anpassungen, um die gewünschten Informationen zu erhalten.

Simples Auditing: JPA Data

Um das Auditing einfach zu gestalten, bietet JPA Data eine simple Lösung für grundlegende Audit-Anforderungen. Es ermöglicht uns, den Zeitpunkt der Erstellung oder Änderung einer Entität nachzuverfolgen, und stellt grundlegende Audit-Funktionen bereit. Und das ganz ohne die Komplexität, die mit Hibernate Envers oder Datenbank-Trigger verbunden ist. Dafür können wir eine einfache Annotation nutzen, die von JPA Data zur Verfügung gestellt wird. Zusätzlich ist es notwendig, die Annotation @EnableJpaAuditing in der Konfigurationsklasse zu deklarieren. Werfen wir einen Blick auf unsere Beispiel-Entität Dog:

@Entity
@EntityListeners(AuditingEntityListener.class)
public class Dog {

	@Id
	private Long id;

	private String name;

	private Integer height;

	@CreatedDate
	private Instant createdAt;

	@CreatedBy
	private String createdBy;

	@LastModifiedDate
	private Instant modifiedAt;

	@LastModifiedBy
	private String modifiedBy;

	//Getters and setters

}

Indem wir einfach vier weitere Attribute in unsere Entität einfügen, können wir verfolgen, wann und von wem sie erstellt oder geändert wurde. Im Unterschied zu Envers und triggerbasierten Lösungen werden diese Informationen jedoch nicht in einer separaten Tabelle gespeichert und bieten keinen Schnappschuss des vorherigen Zustands. Das bedeutet, JPA Data speichert nicht die Historie der Revisionen einer Entität, sondern lediglich, wann und von wem die aktuelle Version erstellt oder zuletzt bearbeitet wurde.

Obwohl diese Lösung nicht die umfassenden Anpassungsmöglichkeiten von Hibernate bietet, lässt sich der Funktionsumfang durch Anpassungen erweitern oder ändern, beispielsweise durch Modifizieren des verwendeten EntityListener.

Da keine Snapshots einer Entität gespeichert werden, ist es lediglich möglich, das aktuelle Entitätsobjekt abzufragen; einschließlich der Informationen, wann und von wem es zuletzt geändert oder erstellt wurde.

Vorteile:

Einfachheit: JPA Data besticht durch seine Einfachheit. Die Einrichtung und Handhabung sind kinderleicht, was es besonders für Projekte mit grundlegenden Audit-Anforderungen attraktiv macht.
Leistung: Dank seiner einfachen Beschaffenheit hat JPA Data nur minimale Auswirkungen auf die Performance, sodass die Anwendungsleistung größtenteils unberührt bleibt.

Nachteile:

Begrenzte Audit-Möglichkeiten: Obwohl JPA Data für seine Einfachheit geschätzt wird, beschränkt es sich auf elementare Audit-Funktionen.
Keine Erfassung von Löschvorgängen: Ein wesentlicher Nachteil von JPA Data ist, dass es keine Löschaktionen aufzeichnet. Das macht es für umfangreichere Audit-Szenarien, in denen die Verfolgung von Löschungen entscheidend ist, weniger geeignet.

Schlussfolgerung

Zusammenfassend hängt die Entscheidung für die passende Auditing-Lösung, wie so oft, von den spezifischen Bedürfnissen und Prioritäten des Projekts ab.

Hibernate Envers punktet mit nahtloser Integration, sodass man tief in der Java-Welt verwurzelt bleibt. Allerdings kann das zu einem erhöhten Leistungsaufwand führen.

Triggerbasiertes Auditing ist optimal, um Änderungen aus verschiedenen Quellen zu erfassen, kann aber in der Einrichtung komplizierter sein und eine enge Anbindung an Hibernate vermissen lassen.

JPA Data ist ideal für gewöhnliche Audit-Anforderungen, in denen Einfachheit und geringe Auswirkungen auf die Performance im Vordergrund stehen. Für fortgeschrittene Auditing-Szenarien könnte es jedoch nicht ausreichen.

Web Accessibility: A Necessity for All

2024-02-29T00:00:00-06:00

Web Accessibility: A Necessity for Everyone

Internet accessibility is a fundamental requirement which affects not only people with disabilities, but all of us. It provides seamless access to online content for seniors, children and people with visual impairments, but also for those with temporary limitations, such as a broken arm.

Surprisingly, most disabilities are not congenital, but are caused by illness or accidents.¹ This means that every one of us could be in need of accessible websites at some point. Therefore, it is imperative that websites facilitate the participation of people with disabilities in daily life. From 28 June 2025, accessible products and services will become mandatory for most online shops and e-book providers. This is when the EU Accessibility Act (EAA) comes into force. Accessibility will then become compulsory for many website operators. This can be difficult to implement without automated accessibility testing.

Automated Accessibility Testing with Axe

To ensure that a website is accessible, regular checks for potential barriers are essential – ideally automated, as even minor changes can exclude some users by affecting the user experience.

In this article, I’m going to share two ways to run frontend accessibility testing using Axe, a tool from Deque. Not only is Axe free, but it’s also well-suited for automated testing and is one of the leading tools in the field. It is important to note that in creating this example, we expect errors to showcase the functionality of Axe. It’s important to note that Axe alone may not fully detect all barriers, but it does provide an easy entry point to identify and fix errors. Axe has a JavaScript library that easily integrates with Java and Selenium.

Axe’s integration into automated tests

The integration of Axe into automated testing is a powerful accessibility testing tool that is easy to install and use. In the following section, I’ll show how Axe can be used in conjunction with Selenium and Cucumber.

In the first example, I’m using Java, but you can also use Axe in other programming languages and testing frameworks, such as Playwright (I’ll explain this in the second example below). Of course, all the necessary dependencies must be present in the project, including Axe-Selenium integration or the Axe-Playwright package.

To illustrate the structure of the project, here are examples of the directory structure for both Java/Selenium and TypeScript/Playwright: Here for Java with Selenium:

└───a11y-minimal-selenium
    │
    ├───axeReports
    │ AccessibilityViolations_XYZ.txt
    │
    └───src
        ├───main
        │   ├───java
        │   └───resources
        │
        └───test
            ├───java
            │ AccessibilityTestSteps.java
            │ TestRunner.java
            │
            └───resources
                    a11y.feature

And here for TypeScript with Playwright:

└───a11y-minimal-playwright
    │
    ├───axeReports
    │   └───artifacts
    │           accessibility-scan-results-XYZ.html
    │
    ├───test
    │   ├───features
    │   │       a11y.feature
    │   │
    │   └───steps
    │           a11y.steps.ts
    │
    └───test-results
            cucumber-report.html

In both cases, I use Cucumber to describe our requirement in a specific scenario. In our case, this scenario is that our website is to be barrier-free.

#  a11y.feature
Feature: Accessibility Testing

  Scenario: Verify accessibility of a web page
    Given I open the web page "www.cronn.de/"
    When I check the accessibility of the page
    Then accessibility violations should be found
    And a report is generated

Now we will take a closer look at the individual steps in both variants: Java/Selenium and TypeScript/Playwright.

Accessibility testing with Java/Selenium

After the webpage has been opened and the axeBuilder has been defined as new AxeBuilder(), the accessibility analysis is performed in the When I check the accessibility of the page step. This can look like this:

AccessibilityTestSteps.java

@When("I check the accessibility of the page")
public void i_check_the_accessibility_of_the_page() {
    axeResults = axeBuilder.analyze(driver);
}

Of course, it is also possible to check only for certain options or check only for specific rules or tags, which can be found on the Axe Rules page. You can also include and exclude certain elements and combine everything as you wish. It might look like this (where the individual options, rules, etc. have been defined beforehand):

var axeResults = axeBuilder.withOptions(options)
                .withRules(axeRules)
                .withTags(axeTags)
                .disableRules(disabledRules)
                .exclude("#excludedElement")
                .analyze(driver);

Then we check to see if we can find accessibility issues in our instance of Results called axeResults. This is also very convenient with:

AccessibilityTestSteps.java

@Then("accessibility violations should be found")
public void accessibility_violations_should_be_found() {
    assertFalse("Accessibility violations found", axeResults.getViolations().isEmpty());
}

We can then write the accessibility problems we find in our report. This can be designed completely according to your own requirements and the following is only a minimal example of a text file with an output during the test:

AccessibilityTestSteps.java

@And("a report is generated")
public void a_report_is_generated() {
    List<Rule> violations = axeResults.getViolations();
    if (!violations.isEmpty()) {
        logger.info(() -> "Violations: " + violations);
        String AxeReportPath = System.getProperty("user.dir") + File.separator + "axeReports" + File.separator;
        String timeStamp = new SimpleDateFormat("yyyy_MM_dd_HH_mm_ss").format(new java.util.Date());
        String AxeViolationReportPath = AxeReportPath + "AccessibilityViolations_" + timeStamp;

        assertTrue(getReadableAxeResults(ResultType.Violations.getKey(), driver, violations));
        AxeReporter.writeResultsToTextFile(AxeViolationReportPath, AxeReporter.getAxeResultString());
    } else {
        logger.warn(() -> "No Accessibility violations found");
    }
}

This accessibility test uses the webdriver setup of this test project along with Axe-webdriverjs and calls AxeBuilder to then parse the page with Axe-core. As soon as the test results are returned, they can be output directly in the console or via generated reports. There is also a direct explanation of what the problem is and where it is located. In addition, reference is made directly to the appropriate rule for further explanations:

ACCESSIBILITY CHECK
VIOLATIONS check for: www.cronn.de/
Found 1 items

1: Heading levels should only increase by one
Description: Ensures the order of headings is semantically correct
Help URL: https://dequeuniversity.com/rules/axe/4.7/heading-order?application=axeAPI
Impact: moderate
Tags: cat.semantics, best-practice
        HTML element: <h4 class="title text-center">agile</h4>
        Selector: [.col-md-3.col-lg-2.col-6:nth-child(2) > .title]

Accessibility testing with TypeScript/Playwright and Cucumber

Firstly, the necessary packages need to be installed. Secondly, the accessibility tests can then be implemented. Here is a simple example using TypeScript and Playwright.

After the website has opened and the axeBuilder has been defined in our class as the new AxeBuilder(), we want to perform the accessibility analysis in the When I check the accessibility of the page step. This is done easily with:

// a11y.steps.ts

When("I check the accessibility of the page", async function () {
  accessibilityScanResults = await new AxeBuilder({ page }).analyze();
});

Of course, it is also possible to include and exclude certain elements in this way, as already shown above.

In the last step, it is checked if we find any problems, in other words: if our checklist is complete.

// a11y.steps.ts

Then("accessibility violations should be found", async function () {
  expect(accessibilityScanResults.violations.length).toBeGreaterThan(0);
});

Here, too, we generate reports from the accessibility problems found, this time as an HTML report, and check that it is complete.

// a11y.steps.ts

Then("a report is generated", async function () {
  const now = new Date().toISOString().replace(/[-T:]/g, "_").slice(0, -5);
  const filename = `accessibility-scan-results-${now}.html`;
  const axeReportPath = "axeReports";
  createHtmlReport({
    results: accessibilityScanResults,
    options: {
      outputDirPath: axeReportPath,
      reportFileName: filename,
    },
  });

  expect(
    accessibilityScanResults.violations.map((v) => v.help),
    `A11y report in ${filename}`
  ).not.toEqual([]);
});

Here, you can view the clear, HTML-formatted report:

Summary

Ensuring the accessibility of websites for people of different abilities is of fundamental importance. Using Axe simplifies the process of performing automated accessibility testing and provides an excellent starting point for identifying and resolving issues.

Axe’s integration into automated testing enables effective accessibility monitoring, regardless of whether Java/Selenium or TypeScript/Playwright is being used. Clear reporting and customization options make it easier to identify accessibility violations, which is particularly important in the context of societal obligations and ever-increasing legal requirements.

Further information on disabilities in Germany can be found in the press release from the federal statistical office ↩

wir bloggen über software_

Performance Testing with k6: A Field Report

Project context

Selecting the load testing tool

Our setup

Performance testing with k6

Our findings

Pros and Cons of k6

Summary

Performance-Testing mit k6: Ein Erfahrungsbericht

Projektkontext

Auswahl des Lasttesttools

Unser Setup

Performance-Tests mit k6

Unsere Erkenntnisse

Vor- und Nachteile von k6

Zusammenfassung

Analyzing Business Reports with LLMs – Part 2

The classic approach: OCR as the basis, but not the whole solution

Our path to productive use: evaluation, model selection and integration

Gemini Flash in Action: The Workflow with Structured Outputs

A look at the numbers: How well does it really work?

What does this table tell us and what are the current hurdles?

Conclusion: Gemini Flash as a powerful addition to the toolbox

Analyse von Geschäftsberichten mit LLMs – Teil 2

Der klassische Ansatz: OCR als Basis, aber nicht die ganze Lösung

Unser Weg zum Produktiveinsatz: Evaluation, Modellwahl und Integration

Gemini Flash in Aktion: Der Workflow mit Structured Outputs

Ein Blick auf die Zahlen: Wie gut funktioniert es wirklich?

Was verrät uns diese Tabelle und wo liegen die aktuellen Hürden?

Fazit: Gemini Flash als leistungsstarke Ergänzung im Werkzeugkasten

Code Generation using Java Annotation Processing

Introduction to code generation

Using an existing annotation processor

Custom code generator for annotation processing

Conclusion

Handling of the ‘this-escape’ warning in JDK 21

Background

Origin Story

Three approaches

Using the keywords final, private or static

Usage of the annotation @PostConstruct

Revise the class design

Summary

References

Behandlung der this-escape-Warnung in JDK 21

Hintergrund

Origin Story

Drei Lösungswege

Verwendung der Schlüsselwörter final, private oder static

Verwendung der Annotation @PostConstruct

Überarbeiten des Klassendesigns

Zusammenfassung

Referenzen

Time-Travelling through Data Realms with Auditing

Guardian of data history

First, the basics: Change Data Capture

Stay in the Java world: Hibernate Envers

Pros:

Cons:

Break out of your java comfort zone: Database triggers

Pros:

Cons:

Keep it simple: JPA Data

Pros:

Cons:

Conclusion

Zeitreisen durch Datenwelten mit Auditing

Hüter der Datenhistorie

Ein Blick auf die Grundlagen: Change Data Capture

In der Java-Welt: Hibernate Envers

Vorteile:

Nachteile:

Raus aus der Java-Komfortzone: Datenbank-Trigger

Vorteile:

Nachteile:

Simples Auditing: JPA Data

Vorteile:

Nachteile:

Schlussfolgerung

Using the keywords `final`, `private` or `static`

Usage of the annotation `@PostConstruct`

Verwendung der Schlüsselwörter `final`, `private` oder `static`

Verwendung der Annotation `@PostConstruct`