Skip to content

13. Webservices

Voraussetzungen: Version 9 der Anwendung [Tax], die am Ende dieses Kapitels vorgestellt wird, verwendet die Module [tax-dao], [tax-business] und [tax-ui] aus Version 5 (Kapitel 6) wieder. Bevor Sie Ihre Projekte erstellen oder öffnen, müssen Sie Version 5 mit dem Befehl [mvn install] im lokalen Maven-Repository installiert haben, eingegeben im Ordner [06-architectures/TaxV5] (siehe Kapitel 6, Abschnitt zu [mvn install]).

13.1. Einführung

Im vorherigen Kapitel haben wir mehrere TCP/IP-Client-Server-Anwendungen vorgestellt. Da Clients und Server Textzeilen austauschen, können sie in jeder Sprache geschrieben werden. Der Client muss lediglich das vom Server erwartete Kommunikationsprotokoll kennen.

Webservices sind ebenfalls Serveranwendungen (TCP/IP). Sie haben die folgenden Merkmale:

  • Sie werden von Webservern gehostet, und das Austauschprotokoll zwischen Client und Server ist HTTP (HyperText Transfer Protocol), ein auf TCP/IP aufbauendes Protokoll, das wir im vorherigen Kapitel untersucht haben;
  • Der Webservice hat ein standardisiertes Kommunikationsprotokoll, unabhängig vom angebotenen Dienst. Ein Webservice bietet verschiedene Dienste an: S1, S2 …, Sn. Jeder dieser Dienste erwartet vom Client bereitgestellte Parameter und liefert dem Client ein Ergebnis. Für jeden Dienst muss der Client wissen:
    • wie der Dienst Si anzugeben ist;
    • die Liste der bereitzustellenden Parameter und ihre Typen;
    • den Typ des vom Dienst gelieferten Ergebnisses. Sobald diese Elemente bekannt sind, folgt der Dialog zwischen Client und Server demselben Schema, unabhängig davon, welcher Webservice abgefragt wird. Der Client-Code ist somit standardisiert;
  • Um sich vor Angriffen aus dem Internet zu schützen, öffnen viele Organisationen auf ihren Servern nur bestimmte Ports nach außen: vor allem die Ports 80 (HTTP) und 443 (HTTPS) für den Webservice. Alle anderen Ports sind gesperrt. Folglich sind Client-Server-Anwendungen wie die im vorherigen Kapitel beschriebenen im Allgemeinen auf das private Netzwerk (Intranet) der Organisation beschränkt. Das Hosten eines Dienstes auf einem Webserver macht ihn für die gesamte Internet-Gemeinschaft zugänglich;
  • Der Webservice lässt sich als entferntes Objekt betrachten: Die von ihm angebotenen Dienste werden dann zu Methoden dieses Objekts. Ein Client kann dieses entfernte Objekt über ein Zwischenobjekt, einen sogenannten Proxy, der die gesamte Netzwerkkommunikation verbirgt, so verwenden, als wäre es lokal. So lässt sich ein Client bauen, der von dieser Schicht unabhängig ist: Ändert sich die Schicht, muss der Rest des Clients nicht angepasst werden;
  • Wie bei den TCP/IP-Client-Server-Anwendungen aus dem vorherigen Kapitel können Client und Server in jeder Programmiersprache geschrieben werden. Sie tauschen Textzeilen aus, die aus zwei Teilen bestehen: den vom HTTP-Protokoll verlangten Headern und dem Nachrichtentext, dessen Format zwischen Client und Server vereinbart wird.

Die Architektur einer auf Webservices basierenden Client-Server-Anwendung sieht wie folgt aus:

Image

Dies ist eine Erweiterung der Schichtenarchitektur aus Kapitel 6, zu der spezialisierte Schichten für die Netzwerkkommunikation hinzukommen: der Webservice-Client auf Clientseite und der Webservice selbst auf Serverseite. Einer ähnlichen Architektur sind wir bereits beim TCP-Server zur Steuerberechnung (Version 8) aus dem vorherigen Kapitel begegnet.

13.1.1. Gestern: SOAP und WSDL

In den 2000er-Jahren folgten Webservices meist dem Standard SOAP (Simple Object Access Protocol). Der Client sendete eine HTTP-Anfrage per POST, deren Rumpf ein XML-Dokument war: ein „Umschlag“ mit dem Namen der aufgerufenen Methode und ihren Parametern. Der Server antwortete mit einem weiteren XML-Umschlag, der das Ergebnis enthielt. Jeder Dienst wurde durch ein XML-Dokument im Format WSDL (Web Services Description Language) beschrieben, das unter der URL des Dienstes gefolgt von [?wsdl] abrufbar war: Es listete die Methoden, ihre Parameter und ihre Typen auf. Anhand dieses Dokuments erzeugten Werkzeuge automatisch den Proxy des Dienstes.

In Java wurden diese Dienste mit der API JAX-WS geschrieben: Eine mit [@WebService] annotierte Klasse, deren öffentliche Methoden (die mit [@WebMethod] annotiert sein konnten) zu den Methoden des Dienstes wurden; das Werkzeug [wsimport] erzeugte den Client-Proxy aus der WSDL. JAX-WS war von Java 6 bis Java 10 Teil des JDK; in Java 11 wurde es entfernt (JEP 320) und existiert heute außerhalb des JDK unter dem Namen Jakarta XML Web Services. Es findet sich noch in Altanwendungen, doch neue Dienste verwenden es selten. Zu den Gründen für diese Ablösung zählen die Schwerfälligkeit von XML und SOAP-Umschlägen, die Komplexität der zugehörigen Standards (WS-Security, WS-Addressing usw.) und die Schwierigkeit, diese Dienste aus einem Browser aufzurufen.

13.1.2. Heute: REST und JSON

Die meisten aktuellen Webservices folgen dem Stil REST (REpresentational State Transfer) und tauschen JSON-Dokumente aus (JavaScript Object Notation, vorgestellt in Kapitel 5). Der REST-Stil beruht auf den folgenden Prinzipien:

  • Der Service stellt Ressourcen bereit, die jeweils durch eine URL bezeichnet werden: [/tax], [/clients/12], [/clients/12/orders];
  • Auf diese Ressourcen wird mit den Methoden (auch Verben genannt) des HTTP-Protokolls zugegriffen, von denen jede eine bestimmte Bedeutung hat;
  • Das Ergebnis der Aktion wird durch den HTTP-Statuscode in der Antwort angezeigt;
  • Der Rumpf von Anfragen und Antworten ist meist ein JSON-Dokument, das kompakter und einfacher als XML ist;
  • Der Service ist zustandslos: Jede Anfrage enthält alle für ihre Verarbeitung nötigen Informationen; der Server speichert von einer Anfrage zur nächsten keine Informationen über einen bestimmten Client.

Die am häufigsten verwendeten HTTP-Methoden sind die folgenden:

Methode
Verwendung
Beispiel
GET
Eine Ressource lesen; eventuelle Parameter stehen in der URL
GET /clients/12
POST
Eine Ressource anlegen oder eine Verarbeitung anfordern; die Daten stehen im Rumpf der Anfrage
POST /clients
PUT
Eine Ressource ersetzen
PUT /clients/12
PATCH
Einen Teil einer Ressource ändern
PATCH /clients/12
DELETE
Eine Ressource löschen
DELETE /clients/12

Die Statuscodes, die im vorherigen Kapitel eingeführt wurden, entfalten hier ihre volle Bedeutung:

Code
Bedeutung
200 OK
Die Anfrage war erfolgreich; der Rumpf der Antwort enthält das Ergebnis
201 Created
Die Ressource wurde angelegt; der Header [Location] gibt ihre URL an
204 No Content
Die Anfrage war erfolgreich; die Antwort hat keinen Rumpf
400 Bad Request
Die Anfrage ist ungültig (fehlender oder ungültiger Parameter usw.)
404 Not Found
Die angeforderte Ressource existiert nicht
415 Unsupported Media Type
Der Typ des gesendeten Dokuments (Header [Content-Type]) wird nicht akzeptiert
500 Internal Server Error
Auf dem Server ist ein unerwarteter Fehler aufgetreten

Ein REST-Service hat kein zwingend vorgeschriebenes Äquivalent zu WSDL. Üblich ist es jedoch, ihn mit einem OpenAPI-Dokument (früher Swagger) im JSON- oder YAML-Format zu beschreiben, aus dem Werkzeuge Dokumentation, Testseiten und Clients erzeugen können. Darauf kommen wir später zurück.

Erwähnen wir schließlich gRPC, von Google entworfen: Die Methoden des Dienstes und ihre Nachrichten werden in einer [.proto]-Datei beschrieben, aus der Werkzeuge Server und Client erzeugen, so wie zur Zeit von WSDL; die Nachrichten werden in einem kompakten Binärformat (Protocol Buffers) kodiert und über HTTP/2 übertragen. gRPC ist sehr effizient und beliebt für die Kommunikation zwischen Diensten innerhalb derselben Organisation, eignet sich aber schlecht für Browser. Es ist in Java mit der Bibliothek [grpc-java] verfügbar, die wir nicht verwenden werden.

13.1.3. Spring Boot und Spring MVC

Zum Schreiben unserer Webservices verwenden wir Spring Boot. In Kapitel 6 haben wir den Dependency-Injection-Container des Spring Frameworks verwendet. Dieses Framework enthält auch ein Webmodul, Spring MVC, das mithilfe von Annotationen eine URL und eine HTTP-Methode einer Java-Methode zuordnet: [@RestController] an der Klasse, [@GetMapping], [@PostMapping] … an ihren Methoden. Spring Boot (Version 1.0 im Jahr 2014, Version 4 im November 2025, mit Spring Framework 7) vereinfacht den Einsatz von Spring:

  • Es konfiguriert die Anwendung automatisch anhand der verfügbaren Bibliotheken: Sind Spring MVC und Jackson vorhanden, richtet es alles ein, was für einen JSON-Webservice nötig ist, ohne eine einzige Konfigurationszeile;
  • Es bettet den Webserver ein in die Anwendung: Der Server Tomcat (Version 11) ist einfach eine Bibliothek, die vom Hauptprogramm gestartet wird. Es ist daher nicht nötig, einen separaten Webserver oder Anwendungsserver (Tomcat, GlassFish, WildFly …) zu installieren, auf dem die Anwendung früher als [.war]-Archiv bereitgestellt wurde;
  • Es stellt Starter bereit – Maven-Abhängigkeiten, die alles bündeln, was für einen bestimmten Anwendungsfall nötig ist. Der Starter [spring-boot-starter-webmvc] enthält Spring MVC, Tomcat, Jackson 3 (Kapitel 5) und Logging (SLF4J und Logback);
  • Es stellt ein übergeordnetes Maven-Projekt bereit, [spring-boot-starter-parent], das die Versionen all dieser untereinander kompatiblen Bibliotheken festlegt, sowie ein Maven-Plugin, [spring-boot-maven-plugin], das die Anwendung startet ([mvn spring-boot:run]) und sie als einzelne ausführbare Datei, [.jar], paketiert.

Spring Boot ist nicht die einzige Lösung: Jakarta EE (früher Java EE) definiert den API-Standard JAX-RS (Jakarta RESTful Web Services), und auch Frameworks wie Quarkus, Micronaut und Helidon sind weit verbreitet. Spring Boot ist jedoch am weitesten verbreitet und baut ganz natürlich auf dem auf, was wir in Kapitel 6 behandelt haben.

13.2. Ein erster Webservice

Wir werden unsere erste Client-Server-Anwendung mit der folgenden vereinfachten Architektur bauen:

Image

Die Projekte dieses Kapitels sind Maven-Projekte, zusammengefasst im Ordner [13-web-services]:

13-web-services/
  pom.xml                   aggregation project of the six Maven projects
  WsHello/                  "Hello" web service
    pom.xml
    src/main/java/wshello/WsHelloApplication.java
    src/main/java/wshello/HelloController.java
    src/main/resources/application.properties
  ClientWsHello/            its console client
    pom.xml
    src/main/java/clientwshello/Main.java
  WsOperations/             web service of the four operations
    pom.xml
    src/main/java/wsoperations/WsOperationsApplication.java
    src/main/java/wsoperations/OperationsController.java
    src/main/resources/application.properties
  ClientWsOperations/       its console client
    pom.xml
    src/main/java/clientwsoperations/Main.java
  WsTax/                    tax calculation web service (version 9)
    pom.xml
    TaxData.json
    src/main/java/tax/ws/...
    src/main/resources/application.properties
    src/main/resources/static/index.html    the web client
  ClientWsTax/              its console client (version 9)
    pom.xml
    src/main/java/tax/client/TaxBusinessHttp.java
    src/main/java/tax/client/Main.java
  ClientNode/               a JavaScript client
    client-tax.mjs

Die Projekte sind in den Kursmaterialien bereits eingerichtet: Der Leser muss lediglich den Ordner [13-web-services] in seiner IDE (IntelliJ, IDEA oder VS Code) öffnen oder in einen Projektordner wechseln und den angegebenen Maven-Befehl eingeben. Services werden mit [mvn spring-boot:run] gestartet und Konsolenclients mit [mvn compile exec:java]. Die Datei [pom.xml] im Stammverzeichnis des Ordners ist kein übergeordnetes Projekt: Sie listet lediglich die sechs Projekte in einem [<modules>]-Tag auf, wodurch sich alle auf einmal bauen lassen (durch Eingabe von [mvn compile] im Ordner [13-web-services]).

Um selbst ein Spring-Boot-Projekt anzulegen, verwendet man am einfachsten die Website Spring Initializr: Dort wählen Sie Maven, Java, die Spring-Boot-Version, den Projektnamen und seine Abhängigkeiten (hier „Spring Web“) aus und laden dann eine ZIP-Datei mit einem sofort einsatzbereiten Projekt herunter: der Datei [pom.xml], der Hauptklasse und der Datei [application.properties]. IntelliJ, IDEA und VS Code (mit der Erweiterung „Spring Boot Extension Pack“) bieten denselben Assistenten.

13.2.1. Die Serverseite

Image

Die Datei [pom.xml] des Projekts [WsHello] sieht wie folgt aus:

<?xml version="1.0" encoding="UTF-8"?>
<!-- der Webdienst WsHello: eine Spring-Boot-Anwendung -->
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!-- das Spring-Boot-Elternprojekt: Bibliotheksversionen und Plugin-Konfiguration -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>4.1.1</version>
        <relativePath/>
    </parent>

    <groupId>examples.webservices</groupId>
    <artifactId>ws-hello</artifactId>
    <version>1.0</version>

    <properties>
        <java.version>25</java.version>
        <maven.compiler.release>25</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <!-- Spring MVC, der eingebettete Tomcat-Server und Jackson -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-webmvc</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.15.0</version>
                <configuration>
                    <parameters>true</parameters>
                    <compilerArgs>
                        <arg>-Xlint:all</arg>
                    </compilerArgs>
                </configuration>
            </plugin>
            <!-- mvn spring-boot:run startet die Anwendung; mvn package erstellt daraus ein ausführbares Jar -->
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

Erläuterungen:

  • Zeilen 9–14: Das Projekt erbt vom übergeordneten Spring-Boot-Projekt [spring-boot-starter-parent], das als Abhängigkeit von Maven Central heruntergeladen wird (das leere Tag [<relativePath/>] zeigt an, dass es nicht im übergeordneten Ordner gesucht werden soll). Dieses übergeordnete Projekt legt die Versionen mehrerer hundert Bibliotheken fest und konfiguriert die Maven-Plugins. Deshalb haben die Abhängigkeiten und das Plugin in den Zeilen 28–31 und 48–51 kein [<version>]-Tag: Ihre Version ist die von Spring Boot 4.1.1 gewählte;
  • Zeile 21: Die Eigenschaft [java.version] wird vom übergeordneten Projekt zur Konfiguration des Compilers verwendet; Zeile 22 dupliziert sie, in Übereinstimmung mit den anderen Projekten des Kurses;
  • Zeilen 28–31: Die einzige Abhängigkeit des Projekts ist der Web-Starter. Er stellt Spring MVC (Spring Framework 7.0), den eingebetteten Server Tomcat 11, Jackson 3 und Logging bereit;
  • Zeile 41: die Compiler-Option [-parameters], die die Namen der Methodenparameter in den [.class]-Dateien erhält. Spring benötigt dies, um einen Methodenparameter ([name]) dem gleichnamigen Parameter einer URL zuzuordnen. Das übergeordnete Projekt aktiviert diese Option bereits; wir führen sie hier auf, um sie sichtbar zu machen;
  • Zeilen 48–51: das Spring-Boot-Plugin. [mvn spring-boot:run] kompiliert die Anwendung und führt sie aus; [mvn package] erzeugt eine Datei [target/ws-hello-1.0.jar], die die Anwendung und alle ihre Abhängigkeiten enthält und anschließend mit [java -jar target/ws-hello-1.0.jar] ausgeführt wird.

Die Hauptklasse sieht wie folgt aus:

package wshello;

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

// die Spring-Boot-Anwendung WsHello
@SpringBootApplication
public class WsHelloApplication {

    public static void main(String[] args) {
        // startet Spring, dann den Tomcat-Server, der auf die Anfragen wartet
        SpringApplication.run(WsHelloApplication.class, args);
    }
}
  • Zeile 7: Die Annotation [@SpringBootApplication] vereint drei Annotationen: [@Configuration] (die Klasse kann Beans definieren, wie in Kapitel 6), [@EnableAutoConfiguration] (automatische Konfiguration anhand der verfügbaren Bibliotheken) und [@ComponentScan] (Spring sucht im Paket dieser Klasse und in dessen Unterpaketen nach annotierten Klassen – Controllern, Konfigurationen usw.);
  • Zeile 10: Hier behalten wir die Standardform der Methoden [main] und [public static] bei, nach der die Spring-Boot-Werkzeuge die Hauptklasse suchen;
  • Zeile 12: [SpringApplication.run] liest die Konfiguration (Datei [application.properties], Umgebungsvariablen, Kommandozeilenargumente), erzeugt den Spring-Container und seine Beans, startet den Tomcat-Server und gibt dann die Kontrolle zurück. Das Programm endet dort jedoch nicht: Die Tomcat-Threads warten auf Anfragen, bis die Anwendung beendet wird (Strg-C).

Die Konfiguration der Anwendung steht in der Datei [src/main/resources/application.properties]:

1
2
3
4
5
6
7
8
# der Name der Anwendung
spring.application.name=WsHello
# der Listening-Port des Tomcat-Servers
server.port=5100
# kein Banner beim Start
spring.main.banner-mode=off
# kürzere Logmeldungen: Zeit, Level, Thread, Klasse, Meldung
logging.pattern.console=%d{HH:mm:ss.SSS} %-5level [%thread] %logger{0} : %msg%n
  • Zeile 2: der Name der Anwendung;
  • Zeile 4: Der Server lauscht auf Port 5100 (standardmäßig 8080). Dieser Wert kann auch als Argument übergeben werden: [mvn spring-boot:run -Dspring-boot.run.arguments=--server.port=5100], oder über die Umgebungsvariable [SERVER_PORT];
  • Zeile 6: Standardmäßig zeigt Spring Boot beim Start ein großes Banner mit ASCII-Text an; wir entfernen es;
  • Zeile 8: das Format der Log-Meldungen. Das Standardformat ist sehr umfassend (Datum, Level, Prozess-ID, Anwendungsname, Thread, vollständiger Klassenname, Meldung), führt aber zu sehr langen Zeilen. Wir kürzen es auf die Uhrzeit, den Level der Meldung, den Namen des Threads, den Kurznamen der ausgebenden Klasse ([%logger{0}]) und die Meldung.

Der Webservice selbst ist die Klasse [HelloController]. Sie stellt eine Methode bereit, die die Zeichenkette [Hello Mrs xx] zurückgibt, wobei xx der empfangene Name ist:

package wshello;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

// der Webdienst WsHello: jede annotierte öffentliche Methode bearbeitet eine URL
@RestController
public class HelloController {

    // die Wurzel der Website: ein Begrüßungstext
    @GetMapping("/")
    public String home() {
        return "WsHello web service: try /hello/{name} or /greeting/{name}";
    }

    // eine zur URL gewordene "Webmethode": sie grüßt die Dame
    // das Segment {name} der URL wird an den Parameter [name] der Methode übergeben
    // eine Zeichenkette wird unverändert zurückgegeben (text/plain)
    @GetMapping("/hello/{name}")
    public String hello(@PathVariable String name) {
        return "Hello Mrs " + name;
    }

    // dasselbe mit einer JSON-Antwort: ein Objekt wird in JSON serialisiert (application/json)
    @GetMapping("/greeting/{name}")
    public Greeting greeting(@PathVariable String name) {
        return new Greeting(name, "Hello Mrs " + name);
    }

    // das Ergebnis der Methode /greeting
    public record Greeting(String name, String message) {
    }
}

Erläuterungen:

  • Zeile 8: Die Annotation [@RestController] kennzeichnet die Klasse als Controller: Spring erzeugt beim Start eine einzige Instanz davon (einen Singleton) und weist ihr die HTTP-Anfragen zu, bei denen die URL einer ihrer Methoden entspricht. Das Ergebnis jeder Methode wird unverändert im Rumpf der Antwort an den Client gesendet;
  • Zeilen 12–15: Die Annotation [@GetMapping("/")] ordnet die HTTP-Methode GET der URL [/] (dem Wurzelverzeichnis der Website) und der Methode [home] zu, die einen Text mit Erläuterungen zur Verwendung des Dienstes zurückgibt;
  • Zeilen 20–23: Die Template-URL (die sogenannte Route) [/hello/{name}] enthält eine Variable [{name}]: Sie entspricht jedem URL-Segment, das nach [/hello/] folgt. Somit weist die URL [/hello/Carla%20Bruni] den Wert [Carla Bruni] der Variablen [{name}] zu (der Code [%20] steht in einer URL für ein Leerzeichen). Die Annotation [@PathVariable] (Zeile 21) weist Spring an, diesen Wert an den gleichnamigen Methodenparameter zu übergeben: Das ist Datenbindung. Die Methode gibt eine Zeichenkette zurück: Diese wird unverändert als Textdokument (Typ [text/plain]) an den Client gesendet;
  • Zeilen 26–29: derselbe Ablauf, aber die Methode gibt ein Objekt vom Typ [Greeting] zurück. Spring serialisiert es mit Jackson (Kapitel 5) zu JSON und sendet es als Dokument vom Typ [application/json] an den Client. Dies ist das Standardformat für die Antwort eines REST-Webservice;
  • Zeilen 32–33: der Ergebnistyp, ein Record (Kapitel 4), der innerhalb des Controllers deklariert ist. Jackson kann Records serialisieren: Jede Komponente wird zu einer JSON-Eigenschaft mit demselben Namen.

Der Service wird mit dem Befehl [mvn spring-boot:run] gestartet, der im Projektordner eingegeben wird. Er gibt sein Log aus (im Kurs sind die Pfade in Zeile 2 durch [...] abgekürzt):

> mvn spring-boot:run
18:57:19.455 INFO  [main] WsHelloApplication : Starting WsHelloApplication using Java 25.0.4.1 with PID 6430 (... in .../13-web-services/WsHello)
18:57:19.911 INFO  [main] WsHelloApplication : No active profile set, falling back to 1 default profile: "default"
18:57:24.871 INFO  [main] TomcatWebServer : Tomcat initialized with port 5100 (http)
18:57:24.915 INFO  [main] StandardService : Starting service [Tomcat]
18:57:24.915 INFO  [main] StandardEngine : Starting Servlet engine: [Apache Tomcat/11.0.24]
18:57:25.041 INFO  [main] WebApplicationContextInitializer : Root WebApplicationContext: initialization completed in 4582 ms
18:57:27.317 INFO  [main] TomcatWebServer : Tomcat started on port 5100 (http) with context path '/'
18:57:27.394 INFO  [main] WsHelloApplication : Started WsHelloApplication in 10.545 seconds (process running for 11.704)
18:57:30.107 INFO  [http-nio-5100-exec-1] [/] : Initializing Spring DispatcherServlet 'dispatcherServlet'
18:57:30.108 INFO  [http-nio-5100-exec-1] DispatcherServlet : Initializing Servlet 'dispatcherServlet'
18:57:30.113 INFO  [http-nio-5100-exec-1] DispatcherServlet : Completed initialization in 5 ms
18:58:33.536 INFO  [SpringApplicationShutdownHook] GracefulShutdown : Commencing graceful shutdown. Waiting for active requests to complete
18:58:33.585 INFO  [tomcat-shutdown] GracefulShutdown : Graceful shutdown complete
  • Zeile 2: der Start der Anwendung, die Java-Version und das Ausführungsverzeichnis, das dem Projektverzeichnis entspricht;
  • Zeile 3: Mit Spring können Sie Profile (Entwicklung, Test, Produktion usw.) definieren, die unterschiedliche Konfigurationen aktivieren ([application-dev.properties]-Dateien usw.). Hier ist kein Profil aktiv;
  • Zeilen 4–6: Der eingebettete Tomcat-Server wird erstellt; er lauscht auf Port 5100;
  • Zeile 7: Der Spring-Container ist bereit: Er hat seine Beans erstellt, darunter unseren Controller;
  • Zeilen 8–9: Tomcat nimmt nun Verbindungen an; die Anwendung ist bereit. Der Start dauerte auf unserem Testrechner etwa zehn Sekunden, was recht langsam ist; üblicherweise dauert er zwei bis drei Sekunden;
  • Zeilen 10–12: Diese Meldungen erschienen bei der ersten Anfrage: Das Spring-Servlet [DispatcherServlet], das alle Anfragen entgegennimmt und auf die Controller-Methoden verteilt, wird erst an dieser Stelle initialisiert. Ein Servlet ist eine Java-Komponente, die Anfragen in einem Webserver wie Tomcat verarbeitet (Jakarta Servlet); Spring baut darauf auf. Der Thread-Name [http-nio-5100-exec-1] zeigt an, dass die Anfrage von einem der Threads des Tomcat-Servers verarbeitet wird;
  • Zeilen 13–14: Diese Meldungen erschienen, als der Server nach den in den folgenden Absätzen beschriebenen Tests mit Strg+C beendet wurde; das Herunterfahren erfolgte „geordnet“ (graceful): Tomcat schließt noch laufende Anfragen ab, bevor er sich beendet.

Jede Log-Meldung gibt ihren Zeitpunkt, ihre Stufe ([TRACE], [DEBUG], [INFO], [WARN], [ERROR]), den sendenden Thread und die sendende Klasse an. Meldungen der Stufe [INFO] und höher werden standardmäßig angezeigt; mit der Eigenschaft [logging.level.<package>=DEBUG] werden für ein bestimmtes Paket auch Meldungen niedrigerer Stufen angezeigt.

13.2.2. Den Service mit curl abfragen

Während der Service läuft, fragen wir ihn in einem zweiten Befehlsfenster mit dem im vorigen Kapitel vorgestellten Werkzeug [curl] ab. Die Option [-i] zeigt die Antwort-Header vor dem Body an, und die Option [-s] (silent) unterdrückt die Fortschrittsanzeige:

1
2
3
4
5
6
7
> curl -s -i http://localhost:5100/hello/Carla%20Bruni
HTTP/1.1 200 
Content-Type: text/plain;charset=UTF-8
Content-Length: 21
Date: Sat, 03 Oct 2026 16:57:30 GMT

Hello Mrs Carla Bruni
  • Zeile 2: Die Anfrage war erfolgreich. Tomcat sendet den Text nicht, der üblicherweise auf den Statuscode folgt ([OK]): Er ist seit HTTP/1.1 optional (und existiert in HTTP/2 nicht mehr); nur der Code zählt;
  • Zeile 3: Das Dokument ist Text (UTF-8);
  • Zeile 4: die Größe des Dokuments in Bytes;
  • Zeile 5: der Zeitpunkt der Antwort, der in den HTTP-Headern stets in koordinierter Weltzeit (GMT) angegeben wird, während das Server-Log die Ortszeit verwendet;
  • Zeile 7: das Ergebnis der Methode [hello].

Fragen wir nun die JSON-Version ab:

1
2
3
4
5
6
7
> curl -s -i http://localhost:5100/greeting/Carla%20Bruni
HTTP/1.1 200 
Content-Type: application/json
Content-Length: 56
Date: Sat, 03 Oct 2026 16:57:30 GMT

{"name":"Carla Bruni","message":"Hello Mrs Carla Bruni"}
  • Zeile 3: Das Dokument hat nun den Typ [application/json]. Die Angabe des Zeichensatzes ist nicht nötig: Ein über das Netzwerk ausgetauschtes JSON-Dokument ist immer UTF-8-codiert (RFC 8259);
  • Zeile 7: Das serialisierte Objekt [Greeting]. Die JSON-Eigenschaften [name] und [message] entsprechen den Namen der Komponenten des Records. Da die Java-Namen bereits im Format „camelCase“ vorliegen, das auch in JavaScript und JSON üblich ist, muss nichts umgewandelt werden.

Eine URL, die zu keiner Route passt, liefert eine 404-Antwort:

1
2
3
4
5
6
7
> curl -s -i http://localhost:5100/hello
HTTP/1.1 404 
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sat, 03 Oct 2026 16:57:31 GMT

{"timestamp":"2026-10-03T16:57:31.003Z","status":404,"error":"Not Found","path":"/hello"}
  • Zeile 4: Das Dokument wird in Blöcken gesendet, denen jeweils ihre Größe vorangestellt ist; der Server musste die Gesamtgröße des Dokuments nicht berechnen, bevor er mit dem Senden begann;
  • Zeile 7: das von Spring Boot erzeugte Fehlerdokument: das Datum, der Statuscode, sein Text und der angeforderte Pfad. Aus Sicherheitsgründen enthält es weder die Meldung einer eventuellen Exception noch den Aufrufstapel (Eigenschaften [server.error.include-message] und [server.error.include-stacktrace], standardmäßig deaktiviert). Im nächsten Service sehen wir, wie man ein standardisiertes Fehlerdokument erhält.

Sie können die URL [http://localhost:5100/hello/Carla Bruni] auch in die Adressleiste eines Browsers eingeben, der dann den empfangenen Text anzeigt: Ein per GET abgefragter Webservice lässt sich sehr einfach testen.

13.2.3. Ein Konsolen-Client

Image

Man kann den Client des Service mit einem einfachen TCP-Client schreiben, wie im vorigen Kapitel: Es genügt, die HTTP-Anfrage zu senden und die Antwort zu lesen. Wir verwenden jedoch die Klasse [java.net.http.HttpClient] (Java 11), die ebenfalls im vorigen Kapitel vorgestellt wurde, das HTTP-Protokoll für uns übernimmt und für die JSON-Dokumente Jackson verwendet. Das Projekt [ClientWsHello] ist ein gewöhnliches Maven-Projekt, dessen Datei [pom.xml] die Jackson-Abhängigkeit und die Hauptklasse deklariert:

    <dependencies>
        <!-- Jackson zum Lesen der JSON-Antworten -->
        <dependency>
            <groupId>tools.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>3.1.5</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.15.0</version>
                <configuration>
                    <parameters>true</parameters>
                    <compilerArgs>
                        <arg>-Xlint:all</arg>
                    </compilerArgs>
                </configuration>
            </plugin>
            <!-- mvn exec:java führt die Hauptklasse aus -->
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.5.1</version>
                <configuration>
                    <mainClass>clientwshello.Main</mainClass>
                </configuration>
            </plugin>

Sein Code lautet wie folgt:

package clientwshello;

import java.io.IOException;
import java.net.ConnectException;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import tools.jackson.databind.json.JsonMapper;

// Konsolenclient des Webdienstes WsHello
public class Main {

    // die JSON-Antwort des Dienstes: dieselben Komponentennamen wie auf der Serverseite
    record Greeting(String name, String message) {
    }

    public static void main(String[] args) throws InterruptedException {
        // die URL des Dienstes kann als Argument übergeben werden
        URI serviceUrl = URI.create(args.length > 0 ? args[0] : "http://localhost:5100/");
        // der Jackson-Konverter JSON <-> Objekte
        JsonMapper mapper = JsonMapper.builder().build();

        // ein einziger HTTP-Client für die gesamte Dauer des Programms
        try (HttpClient client = HttpClient.newHttpClient()) {
            while (true) {
                // der Name der Dame
                String input = IO.readln("Name of the lady (nothing to stop): ");
                String name = input == null ? "" : input.strip();
                if (name.isEmpty()) {
                    break;
                }
                try {
                    // der Name wird in den Pfad der URL eingefügt: er muss darin kodiert werden
                    String encodedName = URLEncoder.encode(name, StandardCharsets.UTF_8).replace("+", "%20");
                    // 1 - Textantwort
                    String text = get(client, serviceUrl.resolve("hello/" + encodedName));
                    IO.println("[text] " + text);
                    // 2 - JSON-Antwort, in ein Greeting-Objekt deserialisiert
                    String json = get(client, serviceUrl.resolve("greeting/" + encodedName));
                    Greeting greeting = mapper.readValue(json, Greeting.class);
                    IO.println("[JSON] " + greeting);
                } catch (ConnectException e) {
                    // unter dieser Adresse lauscht kein Dienst (die Exception hat keine Meldung)
                    IO.println("Error: ConnectException: connection refused (" + serviceUrl + ")");
                } catch (IOException e) {
                    // der Dienst hat mit einem Fehler geantwortet oder die Kommunikation ist fehlgeschlagen
                    IO.println("Error: " + e.getClass().getSimpleName() + " : " + e.getMessage());
                }
            }
        }
    }

    // eine GET-Anfrage, deren Antworttext als Zeichenkette zurückgegeben wird
    private static String get(HttpClient client, URI url) throws IOException, InterruptedException {
        HttpRequest request = HttpRequest.newBuilder(url).GET().build();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        // ein anderer Statuscode als 2xx ist ein Fehler
        if (response.statusCode() / 100 != 2) {
            throw new IOException("the service responded " + response.statusCode() + " for " + url);
        }
        return response.body();
    }
}

Erläuterungen:

  • Zeilen 16–18: Die JSON-Antwort des Service wird in ein Objekt vom Typ [Greeting] deserialisiert. Der Client hat keinen Zugriff auf den Typ [Greeting] des Servers; er deklariert einen eigenen mit denselben Komponentennamen. Ein Client teilt nicht den Code des Servers, sondern nur das Format der ausgetauschten Dokumente;
  • Zeile 22: Die URL des Service wird als Argument übergeben oder lautet ersatzweise standardmäßig [http://localhost:5100/]: Ändert sich die Adresse des Service, muss der Client nicht neu kompiliert werden;
  • Zeile 24: der JSON-Konverter von Jackson 3 (Kapitel 5);
  • Zeile 27: ein einziger [HttpClient] für das gesamte Programm. Er verwaltet eine Menge wiederverwendbarer Verbindungen und muss gemeinsam genutzt und nicht für jede Anfrage neu erstellt werden. Ab Java 21 implementiert [HttpClient] das Interface [AutoCloseable]: Die [try]-Anweisung mit Ressource schließt ihn am Ende des Programms;
  • Zeile 37: Der eingegebene Name wird zu einem URL-Segment: Dort nicht zulässige Zeichen müssen codiert werden. [URLEncoder.encode] codiert das „é“ als [%C3%A9], ist aber für Formularparameter gedacht, bei denen das Leerzeichen als [+] codiert wird. In einem URL-Pfad muss das Leerzeichen als [%20] codiert werden: Daher ersetzen wir das [+] (ein tatsächlich eingegebenes [+] wird als [%2B] codiert und ist davon nicht betroffen);
  • Zeile 39: Die Methode [resolve] der Klasse [URI] bildet aus der Basis-URL und einer relativen URL eine URL. Beachten Sie: Die Basis-URL muss auf [/] enden, damit [hello/...] an sie angehängt wird;
  • Zeilen 42–43: Die JSON-Antwort wird mit der Methode [Greeting]-Objekt [readValue] von Jackson deserialisiert;
  • Zeilen 45–47: Die Exception [ConnectException] wird ausgelöst, wenn keine Verbindung zum Service möglich ist, zum Beispiel wenn unter der angegebenen Adresse kein Service lauscht. Sie hat keine Meldung; wir erstellen selbst eine. Dieser [catch] -Block muss dem in Zeile 48 vorangehen, denn [ConnectException] ist von [IOException] abgeleitet;
  • Zeilen 48–50: andere Kommunikationsfehler und Fehlerantworten des Service (siehe Zeile 62);
  • Zeilen 57–65: eine GET-Anfrage, deren Antwort-Body als Zeichenkette geliefert wird;
  • Zeile 58: Die Anfrage wird mit einem Builder erstellt: URL, HTTP-Methode, dann [build];
  • Zeile 59: Die Methode [send] sendet die Anfrage und wartet auf die Antwort. Ihr zweiter Parameter, ein [BodyHandler], legt fest, was mit dem Antwort-Body geschehen soll: [ofString] liest den gesamten Body in eine Zeichenkette ein, die gemäß dem im Header [Content-Type] angegebenen Zeichensatz decodiert wird (standardmäßig UTF-8). [send] löst bei einem Kommunikationsfehler eine [IOException] und, wenn der Thread während des Wartens unterbrochen wird, eine [InterruptedException] aus; das Hauptprogramm lässt Letztere nach oben durchlaufen (Zeile 20);
  • Zeilen 61–63: Anders als andere Bibliotheken behandelt [HttpClient] einen Fehler-Statuscode (4xx, 5xx) nicht als Exception: Die Antwort wird normal zurückgegeben, und wir müssen ihren Code selbst prüfen. Hier lösen wir bei jedem Code außer 2xx eine [IOException] aus.

Ergebnisse bei laufendem Service:

1
2
3
4
5
6
7
8
> mvn -q compile exec:java
Name of the lady (nothing to stop): Carla Bruni
[text] Hello Mrs Carla Bruni
[JSON] Greeting[name=Carla Bruni, message=Hello Mrs Carla Bruni]
Name of the lady (nothing to stop): Marie Curie
[text] Hello Mrs Marie Curie
[JSON] Greeting[name=Marie Curie, message=Hello Mrs Marie Curie]
Name of the lady (nothing to stop): 

Zeile 4 zeigt das empfangene [Greeting]-Objekt im Format der für Records generierten Methode [toString]. Die Maven-Option [-q] (quiet) unterdrückt Mavens eigene Meldungen. Wenn Sie eine Adresse angeben, unter der kein Service lauscht, wird die Verbindung verweigert:

1
2
3
4
> mvn -q compile exec:java -Dexec.args="http://localhost:5199/"
Name of the lady (nothing to stop): Carla Bruni
Error: ConnectException: connection refused (http://localhost:5199/)
Name of the lady (nothing to stop): 

Und wenn die URL des Service falsch ist, liefert der Service eine 404-Antwort:

1
2
3
4
> mvn -q compile exec:java -Dexec.args="http://localhost:5100/hello/"
Name of the lady (nothing to stop): Carla Bruni
Error: IOException : the service responded 404 for http://localhost:5100/hello/hello/Carla%20Bruni
Name of the lady (nothing to stop): 

Bei einem SOAP-Service verwendete der Client einen aus der WSDL des Service generierten Proxy und rief die entfernte Methode wie eine lokale Methode auf. Hier rufen wir die URL des Service direkt auf. Für den Steuerberechnungs-Service schreiben wir einen richtigen Proxy.

13.2.4. Beschreibung des Service: OpenAPI

Die WSDL beschrieb einen SOAP-Service in einem standardisierten Format. Ihr heutiges Äquivalent ist das OpenAPI-Dokument. Für Spring Boot erzeugt die Bibliothek [springdoc-openapi] (Abhängigkeit [org.springdoc:springdoc-openapi-starter-webmvc-ui]) es ohne eine einzige Codezeile: Sie durchsucht beim Start die Controller und ihre Annotationen und veröffentlicht das Dokument unter der URL [/v3/api-docs] sowie eine interaktive Testseite, Swagger UI, unter der URL [/swagger-ui.html]. Das Dokument beschreibt jede Route: ihre URL, ihre HTTP-Methode, ihre Parameter und deren Typen sowie das JSON-Schema ihrer Antworten. Generatoren wie der OpenAPI Generator nutzen es, um einen typisierten Client in verschiedenen Sprachen zu erzeugen, so wie [wsimport] es bei der WSDL tat. Diese Bibliothek gehört nicht zu Spring Boot, und wir verwenden sie in diesem Kapitel nicht.

13.3. Ein Webservice für arithmetische Operationen

Der vorige Service bot nur eine einzige Methode. Wir betrachten nun einen Webservice, der die vier Grundrechenarten bereitstellt: add(a, b), subtract(a, b), multiply(a, b) und divide(a, b). Wir nutzen die Gelegenheit, um die beiden Möglichkeiten der Parameterübergabe an einen Webservice sowie die Fehlerbehandlung zu untersuchen.

13.3.1. Die Serverseite

Der Service [WsOperations] akzeptiert zwei Arten von Anfragen:

Anfrage
Parameter
GET /add?a=1.5&b=2
Die Operation im URL-Pfad, die Zahlen im Query-String
POST /calculation
ein JSON-Dokument im Anfrage-Body: [{"operation":"add","a":1.5,"b":2}]

In beiden Fällen ist die Antwort ein JSON-Dokument: [{"operation":"add","a":1.5,"b":2.0,"result":3.5}]. GET eignet sich für einfache Anfragen, die auf dem Server nichts verändern: Die URL kann in einen Browser eingegeben und als Lesezeichen gespeichert werden, und ihre Antwort kann zwischengespeichert werden. POST eignet sich für umfangreiche oder strukturierte Daten. Die Datei [pom.xml] des Projekts ist dieselbe wie bei [WsHello], abgesehen vom Projektnamen ([ws-operations]), und ihre Hauptklasse [WsOperationsApplication] ist identisch mit der von [WsHello]. Ihre Datei [application.properties] lautet wie folgt:

# der Name der Anwendung
spring.application.name=WsOperations
# der Listening-Port des Tomcat-Servers
server.port=5110
# die von Spring MVC erkannten Fehler werden im Format "Problem Details" (RFC 9457) gemeldet
spring.mvc.problemdetails.enabled=true
# kein Banner beim Start
spring.main.banner-mode=off
# kürzere Logmeldungen: Zeit, Level, Thread, Klasse, Meldung
logging.pattern.console=%d{HH:mm:ss.SSS} %-5level [%thread] %logger{0} : %msg%n
  • Zeile 4: Der Service lauscht auf Port 5110;
  • Zeile 6: Von Spring MVC selbst erkannte Fehler (unbekannte URL, ungültiges JSON-Dokument, nicht unterstützter Dokumenttyp usw.) werden über eine Antwort im Format Problem Details gemeldet. Dieses durch RFC 9457 standardisierte Format ist ein JSON-Dokument vom Typ [application/problem+json] , das einen Fehler beschreibt: seinen Typ, einen Titel, den Statuscode, ein Detail und gegebenenfalls zusätzliche Informationen. Dies ist der Standardweg für einen REST-Service, um mitzuteilen, was schiefgelaufen ist.

Der Controller lautet wie folgt:

package wsoperations;

import java.util.LinkedHashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.function.DoubleBinaryOperator;
import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

// der Webdienst WsOperations: die vier Grundrechenarten
@RestController
public class OperationsController {

    // GET /add?a=1.5&b=2 (ebenso für subtract, multiply, divide)
    // [operation] stammt aus dem Pfad der URL, [a] und [b] aus ihrem Query-String
    @GetMapping("/{operation}")
    public ResponseEntity<?> calculateGet(@PathVariable String operation,
            @RequestParam(required = false) String a, @RequestParam(required = false) String b) {
        return calculate(operation, readNumber(a), readNumber(b));
    }

    // POST /calculation mit einem JSON-Body: {"operation":"add","a":1.5,"b":2}
    // der JSON-Body wird in den Parameter [request] deserialisiert
    @PostMapping("/calculation")
    public ResponseEntity<?> calculatePost(@RequestBody CalculationRequest request) {
        return calculate(request.operation(), request.a(), request.b());
    }

    // eine mit Dezimalpunkt geschriebene Zahl, null, wenn sie fehlt oder fehlerhaft ist
    private static Double readNumber(String text) {
        if (text == null) {
            return null;
        }
        try {
            double number = Double.parseDouble(text);
            // NaN und Unendlich werden abgelehnt
            return Double.isFinite(number) ? number : null;
        } catch (NumberFormatException e) {
            return null;
        }
    }

    // die beiden HTTP-Methoden gemeinsame Berechnung
    private static ResponseEntity<?> calculate(String operation, Double a, Double b) {
        // die angeforderte Operation, null, wenn sie unbekannt ist
        String name = operation == null ? "" : operation.toLowerCase(Locale.ROOT);
        DoubleBinaryOperator calculation = switch (name) {
            case "add" -> (x, y) -> x + y;
            case "subtract" -> (x, y) -> x - y;
            case "multiply" -> (x, y) -> x * y;
            case "divide" -> (x, y) -> x / y;
            default -> null;
        };
        // Prüfung der Parameter: die Fehler werden gesammelt
        Map<String, List<String>> errors = new LinkedHashMap<>();
        if (calculation == null) {
            errors.put("operation", List.of("Unknown operation [" + name
                    + "]: use add, subtract, multiply or divide"));
        }
        if (a == null) {
            errors.put("a", List.of("The number a is missing or incorrect"));
        }
        if (b == null) {
            errors.put("b", List.of("The number b is missing or incorrect"));
        }
        if (!errors.isEmpty()) {
            // Antwort 400 mit der Liste der Fehler
            ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
            problem.setTitle("Incorrect parameters");
            problem.setProperty("errors", errors);
            return ResponseEntity.badRequest().body(problem);
        }
        // Division durch null wird abgelehnt: Antwort 400
        if (name.equals("divide") && b == 0) {
            ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST,
                    "The number b must be non-zero for a division");
            problem.setTitle("Division by zero");
            return ResponseEntity.badRequest().body(problem);
        }
        // Antwort 200 mit dem Ergebnis in JSON
        return ResponseEntity.ok(new CalculationResult(name, a, b, calculation.applyAsDouble(a, b)));
    }

    // die Berechnungsanfrage (Body der POST-Anfrage): die im JSON fehlenden Zahlen sind null
    public record CalculationRequest(String operation, Double a, Double b) {
    }

    // das Ergebnis einer Berechnung (Body der Antwort)
    public record CalculationResult(String operation, double a, double b, double result) {
    }
}

Erläuterungen:

  • Zeilen 24–28: Die GET-Anfrage. Der Parameter [operation] der Methode ist an die Routenvariable [{operation}] ([@PathVariable]) gebunden. Die Parameter [a] und [b], die mit [@RequestParam] annotiert sind, werden an die gleichnamigen Parameter im Query-String ([?a=1.5&b=2]) gebunden. Sie sind optional ([required = false]): Ein fehlender Parameter wird als [null] behandelt; andernfalls würde Spring eine Anfrage, in der einer von ihnen fehlt, mit einer 400-Antwort ablehnen;
  • Zeile 26: [a] und [b] sind als Typ [String] deklariert. Wir hätten sie auch als Typ [double] oder [Double] deklarieren können: Spring hätte dann die Konvertierung selbst durchgeführt und einen fehlerhaften Wert mit einer 400-Antwort mit einer generischen Fehlermeldung abgelehnt. Indem wir sie als Zeichenketten empfangen, behalten wir die Kontrolle über die Fehlermeldungen;
  • Zeilen 32–35: die POST-Anfrage. Der Parameter [request], der mit [@RequestBody] annotiert ist, wird von Jackson aus dem JSON-Body der Anfrage erstellt. Seine Komponenten haben den Typ [Double] (Zeile 93) und nicht [double]: Eine im JSON-Dokument fehlende Eigenschaft wird dann als [null] ausgewertet, wodurch sie erkannt werden kann;
  • Zeilen 38–49: Umwandlung einer Zeichenkette in eine Zahl; schlägt sie fehl, ist das Ergebnis [null]. Sowohl in der URL als auch in JSON werden Zahlen mit Dezimalpunkt geschrieben: [Double.parseDouble], das von der Systemsprache unabhängig ist, ist daher das richtige Werkzeug (und nicht [NumberFormat], das auf einem französischen Server ein Komma erwarten würde, siehe Kapitel 5). Es akzeptiert außerdem die Texte [NaN] und [Infinity], die wir ablehnen (Zeile 45);
  • Zeile 54: der Name der Operation in Kleinbuchstaben. [Locale.ROOT] führt die Umwandlung unabhängig von der Systemsprache durch;
  • Zeilen 55–61: Die angeforderte Operation wird durch ein funktionales Interface (Kapitel 7) dargestellt, [DoubleBinaryOperator], dessen Methode [applyAsDouble(double, double)] einen [double] zurückgibt. Ein [switch]-Ausdruck wählt das zur Operation passende Lambda aus; bei einer unbekannten Operation wählt er [null] aus;
  • Zeilen 63–73: Die drei Parameter werden validiert, indem die Fehler in einem Dictionary gesammelt werden, das jedem Parameter die Liste seiner Fehlermeldungen zuordnet. Eine [LinkedHashMap] behält die Einfügereihenfolge bei;
  • Zeilen 74–80: Wird ein Fehler gefunden, wird eine 400-Antwort zurückgegeben. Die Spring-Klasse [ProblemDetail] stellt ein „Problem Details“-Dokument dar: [forStatus] erstellt es mit einem Statuscode, [setTitle] legt seinen Titel fest, und [setProperty] fügt ihm eine Eigenschaft hinzu, hier [errors], die Liste der Fehler. Die Klasse [ResponseEntity] stellt eine vollständige HTTP-Antwort dar: Statuscode, Header und Body. [ResponseEntity.badRequest()] bereitet eine 400-Antwort vor, und [body] liefert ihren Body;
  • Zeilen 82–87: Eine Division durch null wird mit einer 400-Antwort abgelehnt, deren Dokument diesmal ein Detail enthält ([forStatusAndDetail]). Diese Ablehnung ist notwendig: In Java löst die Division eines [double] durch null keine Exception aus, sondern liefert unendlich ([Double.POSITIVE_INFINITY]), was ein JSON-Dokument nicht darstellen kann (Jackson würde es als Zeichenkette schreiben, ["Infinity"]). Der Test [b == 0] vergleicht den Wert des [Double]-Objekts mit null: Java „entpackt“ es automatisch (Unboxing);
  • Zeile 89: die 200-Antwort, deren Body das als JSON serialisierte Objekt [CalculationResult] ist;
  • Zeilen 93–98: die beiden mit den Clients ausgetauschten Typen. Diese Objekte, die ausschließlich dazu dienen, Daten zwischen zwei Anwendungen zu transportieren, heißen DTO (Data Transfer Object). Records eignen sich dafür ideal.

Beide Methoden des Controllers geben den Typ [ResponseEntity<?>] zurück: eine Antwort, deren Body von beliebigem Typ sein kann, hier ein [CalculationResult] oder ein [ProblemDetail]. Spring untersucht den tatsächlichen Typ des Bodys, um ihn zu serialisieren; es weist dem Dokument den Typ [application/json] oder, bei einem [application/problem+json] [ProblemDetail], den Typ zu.

13.3.2. Tests mit curl

Der Service wird mit [mvn spring-boot:run] im Ordner [WsOperations] gestartet. Eine Addition:

1
2
3
4
5
6
7
> curl -s -i "http://localhost:5110/add?a=1.5&b=2"
HTTP/1.1 200 
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sat, 03 Oct 2026 16:59:40 GMT

{"operation":"add","a":1.5,"b":2.0,"result":3.5}

Die Zahl 2 ist zu 2.0 geworden: Jackson schreibt einen [double] immer mit seinem Dezimalteil. Für einen Client, insbesondere für JavaScript, ist das dieselbe Zahl. Eine Division durch null:

1
2
3
4
5
6
7
8
> curl -s -i "http://localhost:5110/divide?a=1&b=0"
HTTP/1.1 400 
Content-Type: application/problem+json
Transfer-Encoding: chunked
Date: Sat, 03 Oct 2026 16:59:40 GMT
Connection: close

{"detail":"The number b must be non-zero for a division","instance":"/divide","status":400,"title":"Division by zero"}
  • Zeile 2: Die Anfrage wird abgelehnt;
  • Zeile 3: Der Body ist ein „Problem Details“-Dokument;
  • Zeile 6: Nach einer 400-Antwort schließt Tomcat vorsichtshalber die Verbindung: Eine ungültige Anfrage könnte unerwartete Daten in der Verbindung hinterlassen haben. Der Client öffnet für seine nächste Anfrage eine neue;
  • Zeile 8: Das Dokument enthält die Eigenschaften [title], [status] und [detail], die von unserem Code gesetzt wurden, sowie [instance], von Spring hinzugefügt: der Pfad der Anfrage, die den Fehler verursacht hat. Die Eigenschaft [type], eine URL, die den Fehlertyp dokumentiert, fehlt: RFC 9457 weist ihr dann den Wert [about:blank] zu, was bedeutet, dass der Statuscode zur Beschreibung des Problems ausreicht. Beachten Sie, dass die Eigenschaften alphabetisch sortiert sind: Dies ist das Standardverhalten von Jackson 3 für gewöhnliche Klassen wie [ProblemDetail]; Records behalten dagegen die Reihenfolge ihrer Komponenten bei.

Eine unbekannte Operation, eine mit Dezimalkomma geschriebene Zahl und eine fehlende Zahl:

1
2
3
4
5
6
7
8
> curl -s -i "http://localhost:5110/power?a=1,5"
HTTP/1.1 400 
Content-Type: application/problem+json
Transfer-Encoding: chunked
Date: Sat, 03 Oct 2026 16:59:40 GMT
Connection: close

{"instance":"/power","status":400,"title":"Incorrect parameters","errors":{"operation":["Unknown operation [power]: use add, subtract, multiply or divide"],"a":["The number a is missing or incorrect"],"b":["The number b is missing or incorrect"]}}

Die Eigenschaft [errors] des Dokuments enthält die Validierungsfehler, Parameter für Parameter; da sie mit [setProperty] hinzugefügt wurde, steht sie nach den standardisierten Eigenschaften. Nun eine POST-Anfrage. Die Option [-d] von [curl] sendet den darauf folgenden Text im Body einer POST-Anfrage, und die Option [-H] fügt der Anfrage einen Header hinzu, hier den Typ des gesendeten Dokuments:

1
2
3
4
5
6
7
> curl -s -i -H "Content-Type: application/json" -d '{"operation":"multiply","a":1.5,"b":-4}' http://localhost:5110/calculation
HTTP/1.1 200 
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sat, 03 Oct 2026 16:59:41 GMT

{"operation":"multiply","a":1.5,"b":-4.0,"result":-6.0}

Ist das gesendete JSON-Dokument ungültig, kann Jackson den Parameter [request] nicht erstellen: Spring antwortet von sich aus mit einem 400-Fehler, ohne unsere Methode auszuführen:

1
2
3
4
5
6
7
8
> curl -s -i -H "Content-Type: application/json" -d '{"operation":"multiply","a":1.5,' http://localhost:5110/calculation
HTTP/1.1 400 
Content-Type: application/problem+json
Transfer-Encoding: chunked
Date: Sat, 03 Oct 2026 16:59:41 GMT
Connection: close

{"detail":"Failed to read request","instance":"/calculation","status":400,"title":"Bad Request"}

Das „Problem Details“-Dokument in Zeile 8 wurde von Spring MVC dank der Eigenschaft [spring.mvc.problemdetails.enabled] erzeugt; ohne sie erhielten wir das bei [WsHello] gesehene Spring-Boot-Fehlerdokument. Dasselbe gilt, wenn der Header [Content-Type] weggelassen wird: [curl] sendet den Body dann als HTML-Formular, und Spring lehnt diesen Dokumenttyp ab:

1
2
3
4
5
6
7
8
> curl -s -i -d 'x' http://localhost:5110/calculation
HTTP/1.1 415 
Accept: application/json, application/*+json
Content-Type: application/problem+json
Transfer-Encoding: chunked
Date: Sat, 03 Oct 2026 16:59:41 GMT

{"detail":"Content-Type 'application/x-www-form-urlencoded;charset=UTF-8' is not supported.","instance":"/calculation","status":415,"title":"Unsupported Media Type"}

Der Code 415 (Unsupported Media Type) bedeutet, dass der Typ des gesendeten Dokuments nicht akzeptiert wird; der Header [Accept] in Zeile 3 teilt dem Client mit, welche Typen akzeptiert werden.

13.3.3. Die Clientseite

Image

Unser Konsolen-Client fragt die Operation und die beiden Zahlen in einer einzigen Zeile ab und ruft dann den Service zweimal auf: zuerst mit GET, dann mit POST, um beide Methoden zu demonstrieren. Seine Datei [pom.xml] ist identisch mit der von [ClientWsHello], abgesehen vom Projektnamen und der Hauptklasse. Sein Programm lautet wie folgt:

package clientwsoperations;

import java.io.IOException;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.nio.charset.StandardCharsets;
import java.text.NumberFormat;
import java.text.ParsePosition;
import java.util.List;
import java.util.Map;
import tools.jackson.databind.json.JsonMapper;

// Konsolenclient des Webdienstes WsOperations
public class Main {

    // die mit dem Dienst ausgetauschten Objekte (die Komponentennamen sind die des JSON)
    record CalculationRequest(String operation, double a, double b) {
    }

    record CalculationResult(String operation, double a, double b, double result) {
    }

    // eine Fehlerantwort im Format "Problem Details"
    record Problem(String title, String detail, Integer status, Map<String, List<String>> errors) {
    }

    // die Zahlen werden in der aktuellen Kultur eingegeben und angezeigt (fr-FR: Dezimalkomma, en-US: Dezimalpunkt)
    private static final NumberFormat FORMAT = NumberFormat.getInstance();

    public static void main(String[] args) throws InterruptedException {
        URI serviceUrl = URI.create(args.length > 0 ? args[0] : "http://localhost:5110/");
        // der JSON-Konverter; Jackson 3 ignoriert die unbekannten JSON-Eigenschaften (instance...)
        JsonMapper mapper = JsonMapper.builder().build();

        try (HttpClient client = HttpClient.newHttpClient()) {
            while (true) {
                // Eingabe der Operation und der beiden Zahlen (Dezimaltrennzeichen der aktuellen Kultur)
                String input = IO.readln("Operation a b (e.g.: add 1.5 2), nothing to stop: ");
                String[] fields = input == null ? new String[0] : input.strip().split("\\s+");
                if (fields.length == 0 || fields[0].isEmpty()) {
                    break;
                }
                if (fields.length != 3) {
                    IO.println("Three elements are needed: operation a b");
                    continue;
                }
                // lokale Prüfung der beiden Zahlen, vor jedem Aufruf des Dienstes
                String operation = fields[0];
                Double a = readNumber(fields[1]);
                if (a == null) {
                    IO.println("Incorrect number a...");
                }
                Double b = readNumber(fields[2]);
                if (b == null) {
                    IO.println("Incorrect number b...");
                }
                if (a == null || b == null) {
                    continue;
                }
                String calculation = operation + "(" + FORMAT.format(a) + " ; " + FORMAT.format(b) + ")";

                // 1 - GET-Anfrage: in der URL werden die Zahlen mit Dezimalpunkt geschrieben
                String url = URLEncoder.encode(operation, StandardCharsets.UTF_8) + "?a=" + a + "&b=" + b;
                try {
                    HttpRequest request = HttpRequest.newBuilder(serviceUrl.resolve(url)).GET().build();
                    HttpResponse<String> response = client.send(request, BodyHandlers.ofString());
                    if (response.statusCode() == 200) {
                        CalculationResult result = mapper.readValue(response.body(), CalculationResult.class);
                        IO.println("[GET " + url + "] " + calculation
                                + " = " + FORMAT.format(result.result()));
                    } else {
                        // Fehlschlag: der Statuscode und das empfangene Dokument werden unverändert angezeigt
                        IO.println("[GET " + url + "] error " + response.statusCode()
                                + " : " + response.body());
                    }
                } catch (IOException e) {
                    // der Dienst ist nicht erreichbar
                    IO.println("[GET " + url + "] error: " + e);
                }

                // 2 - POST-Anfrage: die Anfrage wird in JSON im Body der Anfrage gesendet
                try {
                    String json = mapper.writeValueAsString(new CalculationRequest(operation, a, b));
                    HttpRequest request = HttpRequest.newBuilder(serviceUrl.resolve("calculation"))
                            .header("Content-Type", "application/json")
                            .POST(HttpRequest.BodyPublishers.ofString(json))
                            .build();
                    HttpResponse<String> response = client.send(request, BodyHandlers.ofString());
                    if (response.statusCode() == 200) {
                        // Erfolg: der Body enthält das Ergebnis
                        CalculationResult result = mapper.readValue(response.body(), CalculationResult.class);
                        IO.println("[POST calculation] " + calculation + " = " + FORMAT.format(result.result()));
                    } else {
                        // Fehlschlag: der Body enthält die Beschreibung des Problems
                        Problem problem = mapper.readValue(response.body(), Problem.class);
                        IO.println("[POST calculation] error " + response.statusCode() + " : " + problem.title());
                        if (problem.detail() != null) {
                            IO.println("  " + problem.detail());
                        }
                        if (problem.errors() != null) {
                            problem.errors().forEach((parameter, messages) ->
                                    IO.println("  " + parameter + " : " + String.join(" ; ", messages)));
                        }
                    }
                } catch (IOException e) {
                    // der Dienst ist nicht erreichbar
                    IO.println("[POST calculation] error: " + e);
                }
            }
        }
    }

    // eine in der aktuellen Kultur eingegebene Zahl, null, wenn die Eingabe keine ist
    private static Double readNumber(String text) {
        ParsePosition position = new ParsePosition(0);
        Number number = FORMAT.parse(text, position);
        // die Eingabe muss vollständig gelesen worden sein: "2.5x" wird abgelehnt
        return number == null || position.getIndex() != text.length() ? null : number.doubleValue();
    }
}

Erläuterungen:

  • Zeilen 20–29: die DTOs des Clients. Sie werden hier erneut deklariert: Ein Client teilt nicht den Code des Servers, sondern nur das Format der ausgetauschten JSON-Dokumente. Die Spring-Klasse [ProblemDetail] gehört zum Web-Framework; für den Client genügt ein einfacher Record. Seine Komponenten sind Objekttypen ([String], [Integer], [Map]): Eine im Dokument fehlende Eigenschaft wie [detail] oder [errors] wird auf [null] gesetzt;
  • Zeile 32: Zahlen werden im Format der Systemsprache eingegeben und angezeigt, hier Englisch: Dezimalpunkt;
  • Zeile 37: Ab Jackson 3 werden im Record unbekannte Eigenschaften (hier [instance]) bei der Deserialisierung standardmäßig ignoriert;
  • Zeilen 51–63: Die Zahlen werden lokal geprüft, bevor der Service aufgerufen wird. Ein Service muss seine Parameter immer prüfen (da er nicht weiß, wer ihn aufruft), ein Client kann jedoch unnötigen Netzwerkverkehr vermeiden;
  • Zeile 64: der Text, der die Berechnung beschreibt, mit den Zahlen im Format der Systemsprache;
  • Zeile 67: die URL für die GET-Anfrage. Zahlen müssen mit einem Dezimalpunkt geschrieben werden: Das Verketten eines [Double] mit einer Zeichenkette verwendet dessen [toString]-Methode, die unabhängig von der Systemsprache ist. Die vom Benutzer eingegebene Operation wird mit [URLEncoder] kodiert;
  • Zeilen 69–70: die GET-Anfrage;
  • Zeilen 71–74: Bei Erfolg (Statuscode 200) wird das JSON der Antwort in ein Objekt vom Typ [CalculationResult] deserialisiert;
  • Zeilen 75–79: Schlägt die Anfrage fehl, werden der Statuscode und das empfangene Dokument unverändert angezeigt;
  • Zeilen 80–83: Die Ausnahme [IOException] zeigt einen Kommunikationsfehler an, etwa einen nicht erreichbaren Service;
  • Zeilen 87–92: die POST-Anfrage. Das Objekt vom Typ [CalculationRequest] wird von [writeValueAsString] in JSON serialisiert; die Anfrage erhält den Header [Content-Type] und anschließend ihren Body: [BodyPublishers.ofString] sendet eine als UTF-8 kodierte Zeichenkette;
  • Zeilen 97–107: Im Fehlerfall ist der Body ein „Problem Details“-Dokument, das in ein Objekt vom Typ [Problem] deserialisiert wird; dessen Titel, Details und Validierungsfehler werden angezeigt. Die Methode [forEach] einer [Map] erhält ein Lambda mit zwei Parametern: dem Schlüssel und dem Wert jedes Elements (Kapitel 7);
  • Zeilen 118–123: das Lesen einer Zahl im Format der Systemsprache. Die Methode [parse(String, ParsePosition)] von [NumberFormat] liest den Anfang der Zeichenkette und gibt im Objekt [ParsePosition] an, wo sie angehalten hat: Hat sie nicht am Ende angehalten, enthält die Eingabe überzählige Zeichen ([2.5x]).

Ergebnisse bei laufendem Service:

> mvn -q compile exec:java
Operation a b (e.g.: add 1.5 2), nothing to stop: add 1.5 2
[GET add?a=1.5&b=2.0] add(1.5 ; 2) = 3.5
[POST calculation] add(1.5 ; 2) = 3.5
Operation a b (e.g.: add 1.5 2), nothing to stop: divide 1 0
[GET divide?a=1.0&b=0.0] error 400 : {"detail":"The number b must be non-zero for a division","instance":"/divide","status":400,"title":"Division by zero"}
[POST calculation] error 400 : Division by zero
  The number b must be non-zero for a division
Operation a b (e.g.: add 1.5 2), nothing to stop: power 2 3
[GET power?a=2.0&b=3.0] error 400 : {"instance":"/power","status":400,"title":"Incorrect parameters","errors":{"operation":["Unknown operation [power]: use add, subtract, multiply or divide"]}}
[POST calculation] error 400 : Incorrect parameters
  operation : Unknown operation [power]: use add, subtract, multiply or divide
Operation a b (e.g.: add 1.5 2), nothing to stop: multiply 2.5 x
Incorrect number b...
Operation a b (e.g.: add 1.5 2), nothing to stop: 
  • Zeile 3: die URL der GET-Abfrage: Die dort eingegebenen Zahlen 1.5 und 2 werden als 1.5 und 2.0 geschrieben;
  • Zeilen 6–8: derselbe Fehler, bei beiden Anfragen beobachtet: das Rohdokument bei der GET-Anfrage und dessen Verarbeitung bei der POST-Anfrage;
  • Zeilen 10–12: Der Service hat eine unbekannte Operation erkannt;
  • Zeile 14: Die fehlerhafte Zahl wurde vom Client erkannt, der den Service nicht abgefragt hat.

13.4. Beispielanwendung – Version 9: ein Webservice zur Steuerberechnung

Wir greifen die Anwendung zur Steuerberechnung wieder auf. Im vorherigen Kapitel (Version 8) hatten wir einen TCP-Server erstellt, der mit einem eigenen Kommunikationsprotokoll aus der Ferne abgefragt werden konnte. Nun machen wir daraus einen REST-Webservice.

13.4.1. Die Architektur

Die Architektur von Version 9 sieht wie folgt aus:

Image

  • Auf der Serverseite empfängt der Webservice [WsTax] HTTP-Anfragen und lässt sie von den Schichten [business] und [dao] aus Version 5 (Kapitel 6) verarbeiten, die unverändert wiederverwendet werden;
  • auf der Clientseite wird die Schicht [ui] aus Version 5 ebenfalls unverändert wiederverwendet. Sie kommuniziert mit einer neuen [business]-Schicht, [TaxBusinessHttp], die die Schnittstelle [ITaxBusiness] implementiert, indem sie den Webservice abfragt: Sie fungiert als Proxy für den Service. Die Schicht [ui] weiß nicht, dass die Berechnung auf einem anderen Rechner erfolgt;
  • auf beiden Seiten übernimmt der Dependency-Injection-Container von Spring die Integration der Schichten, genau wie in Version 5.

13.4.2. Der Webservice

Der Vertrag des Service sieht wie folgt aus:

Anfrage
Antwort bei Erfolg
Antwort im Fehlerfall
GET /tax?married=y&children=2&salary=60000
200: [{"tax":4282}]
400: „Problem Details“-Dokument
POST /tax mit dem Body [{"married":true,"children":2,"salary":60000}]
200: [{"tax":4282}]
400: „Problem Details“-Dokument

Das Projekt [WsTax] hängt von den Modulen [tax-dao] and [tax-business] aus Version 5 ab. Damit Maven sie findet, müssen Sie sie zunächst im lokalen Maven-Repository des Rechners (dem Ordner [.m2/repository] im Home-Verzeichnis des Benutzers) installieren, indem Sie [mvn install] im Ordner [06-architectures/TaxV5] eingeben (Kapitel 6). Die Abhängigkeiten der Datei [pom.xml] von [WsTax] lauten dann wie folgt (der Rest der Datei entspricht dem von [WsHello], abgesehen vom Projektnamen: [examples.tax:ws-tax:9.0]):

    <dependencies>
        <!-- Spring MVC, der eingebettete Tomcat-Server und Jackson -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-webmvc</artifactId>
        </dependency>
        <!-- die [dao]- und [business]-Schicht aus Version 5, unverändert wiederverwendet -->
        <dependency>
            <groupId>examples.tax</groupId>
            <artifactId>tax-dao</artifactId>
            <version>5.0</version>
        </dependency>
        <dependency>
            <groupId>examples.tax</groupId>
            <artifactId>tax-business</artifactId>
            <version>5.0</version>
        </dependency>
    </dependencies>
  • Zeilen 7–17: die beiden Module aus Version 5, identifiziert über ihre Maven-Koordinaten. Das Modul [tax-dao] enthält außerdem die Klassen [TaxBracket] and [TaxException] aus der Schicht [entities]. Diese Module hängen von Jackson 3.1.5 ab, das der Web-Starter bereits mitbringt.

Die Konfigurationsdatei [application.properties] sieht wie folgt aus:

# der Name der Anwendung
spring.application.name=WsTax
# der Listening-Port des Tomcat-Servers
server.port=5120
# die von Spring MVC erkannten Fehler werden im Format "Problem Details" (RFC 9457) gemeldet
spring.mvc.problemdetails.enabled=true
# kein Banner beim Start
spring.main.banner-mode=off
# kürzere Logmeldungen: Zeit, Level, Thread, Klasse, Meldung
logging.pattern.console=%d{HH:mm:ss.SSS} %-5level [%thread] %logger{0} : %msg%n

# die [dao]-Schicht: ihre Implementierung und ihre Datendatei
dao.implementation=JsonTax
dao.file=TaxData.json
  • Zeile 4: Der Service lauscht auf Port 5120;
  • Zeilen 13–14: die Konfiguration der Schicht [dao] im selben Format wie in der Datei [tax.properties] aus Version 5: die zu verwendende Implementierung und ihre Datendatei. Dies sind keine Spring-Boot-Eigenschaften, sondern Eigenschaften, die spezifisch für unsere Anwendung sind: Eine Datei [application.properties] kann beliebig viele davon enthalten. Hier verwenden wir die JSON-Datei [TaxData.json], die im Projektordner liegt, der zusammen mit [mvn spring-boot:run] der Laufzeitordner des Service ist.

Die Schichten [dao] und [business] werden über eine Konfigurationsklasse in den Spring-Container integriert:

package tax.ws;

import tax.dao.FileTax;
import tax.dao.HardwiredTax;
import tax.dao.ITaxDao;
import tax.dao.JsonTax;
import tax.entities.TaxException;
import tax.business.ITaxBusiness;
import tax.business.TaxBusiness;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

// die Integration der [dao]- und [business]-Schicht aus Version 5 in den Spring-Container
@Configuration
public class TaxConfig {

    // die [dao]-Schicht: ihre Implementierung und ihre Datei stammen aus der Konfiguration
    @Bean
    public ITaxDao dao(@Value("${dao.implementation:HardwiredTax}") String implementation,
            @Value("${dao.file:}") String file) {
        return switch (implementation) {
            case "HardwiredTax" -> new HardwiredTax();
            case "FileTax" -> new FileTax(file);
            case "JsonTax" -> new JsonTax(file);
            default -> throw new TaxException(
                    "Unknown implementation [" + implementation + "] of the [dao] layer");
        };
    }

    // die [business]-Schicht: Spring übergibt ihr die [dao]-Schicht
    @Bean
    public ITaxBusiness business(ITaxDao dao) {
        return new TaxBusiness(dao);
    }
}

Kommentare:

  • Zeile 15: die Annotation [@Configuration] (Kapitel 6): Die Klasse definiert Beans. Spring findet sie, weil sie sich im selben Paket wie die Hauptklasse befindet ([@ComponentScan]);
  • Zeilen 19–29: Die annotierte Methode [@Bean] erstellt die Schicht [dao]. Ihre Parameter werden von Spring bereitgestellt: Die Annotation [@Value] injiziert den Wert einer Konfigurationseigenschaft. In [${dao.implementation:HardwiredTax}] ist der Text nach dem Zeichen [:] der Standardwert, der verwendet wird, wenn die Eigenschaft fehlt. Diese und die folgende Methode entsprechen denen der Klasse [TaxConfig] aus Version 5 (Kapitel 6), jedoch ohne die Annotation [@PropertySource]: Spring Boot liest die Datei [application.properties] selbst ein;
  • Zeilen 32–35: die Schicht [business]. Der Parameter [dao] der Methode erhält die Bean vom Typ [ITaxDao]: Spring erstellt also die Schicht [dao] vor der Schicht [business].

Diese Zeilen ersetzen die Integration der Schichten, die das Hauptprogramm in Version 5 vorgenommen hat: Der Spring-Container ist derselbe, aber nun erstellt Spring Boot ihn und findet die Konfigurationsklasse selbstständig. Die so definierten Beans sind Singletons, die beim Start der Anwendung erstellt werden, bevor Anfragen verarbeitet werden: Fehlt die Datendatei oder ist sie fehlerhaft, startet der Service nicht, anstatt auf alle Anfragen mit einem 500-Fehler zu antworten. Das überprüfen wir später.

Der Webservice ist der Controller [TaxController]:

package tax.ws;

import tax.business.ITaxBusiness;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

// der Webdienst für die Steuerberechnung (Version 9)
@RestController
public class TaxController {

    // das Log der Klasse
    private static final Logger log = LoggerFactory.getLogger(TaxController.class);

    // die [business]-Schicht, von Spring injiziert
    private final ITaxBusiness business;

    public TaxController(ITaxBusiness business) {
        this.business = business;
    }

    // GET /tax?married=y&children=2&salary=60000
    @GetMapping("/tax")
    public TaxResponse calculateGet(@RequestParam(required = false) String married,
            @RequestParam(required = false) String children, @RequestParam(required = false) String salary) {
        Boolean isMarried = switch (married == null ? "" : married.toLowerCase(Locale.ROOT)) {
            case "y" -> true;
            case "n" -> false;
            default -> null;
        };
        return calculate(isMarried, readInteger(children), readInteger(salary));
    }

    // POST /tax mit dem JSON-Body {"married":true,"children":2,"salary":60000}
    @PostMapping("/tax")
    public TaxResponse calculatePost(@RequestBody TaxRequest request) {
        return calculate(request.married(), request.children(), request.salary());
    }

    // die beiden HTTP-Methoden gemeinsame Verarbeitung: die Steuer oder eine Exception, wenn die Anfrage fehlerhaft ist
    private TaxResponse calculate(Boolean married, Integer children, Integer salary) {
        // korrekte Parameter: die Berechnung wird von der [business]-Schicht angefordert
        if (married != null && children != null && children >= 0 && salary != null && salary >= 0) {
            int tax = business.calculateTax(married, children, salary);
            log.info("Tax(married={}, children={}, salary={}) = {}", married, children, salary, tax);
            return new TaxResponse(tax);
        }
        // fehlerhafte Parameter: die Liste der Fehler
        Map<String, List<String>> errors = new LinkedHashMap<>();
        if (married == null) {
            errors.put("married",
                    List.of("Indicate whether the taxpayer is married: y/n (GET) or true/false (POST)"));
        }
        if (children == null || children < 0) {
            errors.put("children", List.of("The number of children must be a positive or zero integer"));
        }
        if (salary == null || salary < 0) {
            errors.put("salary", List.of("The salary must be a positive or zero integer"));
        }
        log.warn("Incorrect request: {}", String.join(", ", errors.keySet()));
        throw new BadRequestException(errors);
    }

    // eine ganze Zahl, null, wenn sie fehlt oder fehlerhaft ist
    private static Integer readInteger(String text) {
        try {
            return text == null ? null : Integer.valueOf(text);
        } catch (NumberFormatException e) {
            return null;
        }
    }

    // eine fehlerhafte Anfrage liefert eine Antwort 400 im Format "Problem Details"
    @ExceptionHandler
    public ProblemDetail badRequest(BadRequestException e) {
        ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
        problem.setTitle("Incorrect parameters");
        problem.setProperty("errors", e.getErrors());
        return problem;
    }

    // die Berechnungsanfrage (Body der POST-Anfrage): die im JSON fehlenden Eigenschaften sind null
    public record TaxRequest(Boolean married, Integer children, Integer salary) {
    }

    // die Antwort: der Betrag der Steuer
    public record TaxResponse(int tax) {
    }
}

Kommentare:

  • Zeile 24: das Log der Klasse. Spring Boot verwendet das Logging-API-Framework (Simple Logging Facade for Java), das hier mit Logback implementiert ist. [LoggerFactory.getLogger] erzeugt einen Log-Eintrag, dessen Kategorie der vollständige Name der Klasse ist;
  • Zeilen 27–31: Der Controller erhält die Schicht [business] über seinen Konstruktor. Spring, das den Controller erstellt, übergibt ihm die Bean vom Typ [ITaxBusiness] , die von [TaxConfig] definiert wird: Das ist die Konstruktorinjektion, wie in Kapitel 6 beschrieben. Ein Feld mit dem Modifizierer [final] stellt sicher, dass sich die Schicht nicht ändert;
  • Zeilen 34–43: die GET-Anfrage. Die drei Parameter des Query-Strings werden als Zeichenketten empfangen und umgewandelt: [y]/[n] to [married] (Zeilen 37–41, ein [switch]-Ausdruck vom Typ [Boolean]), Ganzzahlen für [children] and [salary] ([readInteger], Zeilen 76–82), [null] im Fehlerfall;
  • Zeilen 46–49: die POST-Anfrage: Das JSON im Body wird in ein Objekt [TaxRequest] (Zeile 94) deserialisiert, dessen Komponenten mit Objekttyp ([Boolean], [Integer]) zum Erkennen fehlender Werte dienen. Dieselbe URL [/tax] ist je nach HTTP-Methode der Anfrage zwei Methoden zugeordnet;
  • Zeilen 52–73: die beiden Anfragen gemeinsame Verarbeitung. Sie gibt bei Erfolg eine Antwort zurück und löst bei einem Fehler eine Ausnahme aus. Der Typ ihres Ergebnisses ist daher, wie der der Methoden in den Zeilen 35 und 47, einfach [TaxResponse]: Aus ihren Signaturen lässt sich ablesen, was der Service zurückgibt, wenn alles gut geht;
  • Zeile 54: Sind die drei Parameter korrekt? Die Vergleiche [children >= 0] and [salary >= 0] entpacken die Objekte vom Typ [Integer]: Sie werden nur ausgewertet, wenn diese nicht [null] sind, dank der Lazy Evaluation des Operators [&&];
  • Zeile 55: Die Berechnung wird an die Schicht [business] aus Version 5 delegiert;
  • Zeile 56: Jede Berechnung wird auf der Stufe [INFO] protokolliert. Der Nachrichtentext ist ein Template: Jedes Vorkommen von [{}] wird der Reihe nach durch das entsprechende Argument ersetzt. Anders als bei der Verkettung wird die Nachricht nur erzeugt, wenn sie angezeigt werden muss (abhängig vom Log-Level), und Logging-Werkzeuge können jeden Wert einzeln erfassen;
  • Zeilen 60–72: Im Fehlerfall wird die Fehlerliste erstellt, eine Warnung ([warn]) protokolliert und eine Ausnahme [BadRequestException] ausgelöst, die diese Liste mitführt;
  • Zeilen 85–91: Eine mit [@ExceptionHandler] annotierte Methode fungiert als Exception-Handler: Spring ruft sie auf, wenn eine Controller-Methode eine Ausnahme des Typs auslöst, den ihr Parameter angibt, hier [BadRequestException]. Was sie zurückgibt, wird zur HTTP-Antwort: ein [ProblemDetail], dessen Statuscode (400) zum Statuscode der Antwort wird;
  • Zeilen 94–99: die DTO-Antworten des Service.

Die Ausnahme [BadRequestException] sieht wie folgt aus:

package tax.ws;

import java.io.Serial;
import java.util.List;
import java.util.Map;

// die vom Controller geworfene Exception, wenn die Berechnungsparameter fehlerhaft sind
public class BadRequestException extends RuntimeException {

    @Serial
    private static final long serialVersionUID = 1L;

    // die Fehlermeldungen, Parameter für Parameter
    // (transient: eine Map ist nicht zwingend serialisierbar)
    private final transient Map<String, List<String>> errors;

    public BadRequestException(Map<String, List<String>> errors) {
        super("Incorrect parameters: " + String.join(", ", errors.keySet()));
        this.errors = errors;
    }

    public Map<String, List<String>> getErrors() {
        return errors;
    }
}
  • Zeile 8: eine ungeprüfte Ausnahme, die von den Methoden, die sie auslösen, nicht deklariert werden muss;
  • Zeilen 10–11: Eine Ausnahme ist serialisierbar (im Sinne der binären Java-Serialisierung): Der Compiler verlangt mit der Option [-Xlint:all], dass sie eine Versionsnummer deklariert;
  • Zeile 15: die Fehlerliste. Das Schlüsselwort [transient] schließt dieses Feld von der binären Serialisierung aus, da der Typ [Map] nicht zwangsläufig serialisierbar ist; ohne dieses Schlüsselwort würde der Compiler eine Warnung ausgeben. Das hat hier keine Folgen: Unsere Ausnahmen werden nie serialisiert.

Die Hauptklasse [WsTaxApplication] ist identisch mit der der beiden anderen Services. Der Ordner [src/main/resources/static] enthält den Webclient, der im folgenden Abschnitt behandelt wird.

Der Webservice ist zustandslos: Die Methoden des Controllers behalten keinen Zustand von einer Anfrage zur nächsten. Der Controller und die Schichten [business] und [dao] sind Singletons, die einmalig erstellt werden und so lange existieren, wie die Anwendung läuft; sie werden von allen Anfragen gemeinsam genutzt, die gleichzeitig von verschiedenen Threads des Tomcat-Servers verarbeitet werden können (Kapitel 8). Das ist hier unproblematisch, weil diese Objekte nach ihrer Erstellung nie verändert werden: Die Steuerstufen werden einmalig gelesen, und der Controller hat nur ein Feld [final]. Ein Controller sollte niemals anfragespezifische Daten in seinen Feldern speichern. Das Singleton ist der Standard-Scope für Spring-Beans; es gibt aber noch weitere: [prototype] (ein Objekt pro Anfrage an den Container), [request] (ein Objekt pro HTTP-Anfrage), [session] (ein Objekt pro HTTP-Sitzung). Beachten Sie schließlich, dass die Eigenschaft [spring.threads.virtual.enabled=true] bewirkt, dass jede Anfrage von einem virtuellen Thread (Java 21, Kapitel 8) statt von einem Thread aus dem Tomcat-Pool verarbeitet wird: Der Service kann dann eine sehr große Zahl gleichzeitiger Anfragen bewältigen, die auf I/O-Operationen warten.

13.4.3. Den Service ausführen

Beginnen wir mit einem Konfigurationsfehler. Kommandozeilenargumente der Form [--property=value] gehören zur Konfiguration der Anwendung und überschreiben die Werte aus [application.properties]. Bei [mvn spring-boot:run] werden sie über die Eigenschaft [spring-boot.run.arguments] übergeben. Geben wir eine nicht existierende Datendatei an (im Kurs wurden die Zeilen dieses Logs, die sehr lang sind, mit [...] abgekürzt):

> mvn spring-boot:run -Dspring-boot.run.arguments=--dao.file=missing.json
19:01:41.197 INFO  [main] WsTaxApplication : Starting WsTaxApplication using Java 25.0.4.1 with PID 22677 (...)
...
19:01:49.390 INFO  [main] TomcatWebServer : Tomcat initialized with port 5120 (http)
...
19:01:50.956 WARN  [main] AnnotationConfigServletWebServerApplicationContext : Exception encountered during context initialization - cancelling refresh attempt: org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'taxController' ... Error creating bean with name 'business' ... Error creating bean with name 'dao' ... Factory method 'dao' threw exception with message: Error while reading the file missing.json
19:01:50.991 INFO  [main] StandardService : Stopping service [Tomcat]
...
19:01:51.454 ERROR [main] LoggingFailureAnalysisReporter : 

***************************
APPLICATION FAILED TO START
***************************

Description:

The service cannot start: Error while reading the file missing.json (missing.json: The file [missing.json] does not exist)

Action:

Check the dao.implementation and dao.file properties of the configuration.
  • Zeile 4: Der Tomcat-Server wurde erstellt, hat seinen Port aber noch nicht geöffnet;
  • Zeile 6: Die Erstellung einer Bean ist fehlgeschlagen. Um den Controller zu erstellen, musste Spring die [business]-Schicht und damit die Schicht [dao] erstellen, deren Konstruktor eine [TaxException] instanziiert hat (Kapitel 6). Die Meldungen unserer Schichten sind, wie die von Spring, auf Englisch;
  • Zeile 7: Der Tomcat-Server wird angehalten; der Service hat keine Anfragen angenommen;
  • Zeilen 9–21: der Bericht zum Startfehler. Seine Beschreibung (Zeile 17) und die empfohlene Maßnahme (Zeile 21) werden von einer Klasse erzeugt, die wir eigens dafür geschrieben haben.

Tatsächlich zeigt Spring Boot bei einem Startfehler normalerweise die Ausnahme und den gesamten Aufrufstack an: Dutzende Zeilen, in denen die relevante Meldung schwer zu finden ist. Spring Boot kann die Ausnahme auch an Failure Analyzer weiterreichen, die sie in einen lesbaren Bericht übersetzen. Es liefert Analyzer für die häufigsten Fehler mit (Port bereits belegt, Bean nicht gefunden usw.), und wir können eigene hinzufügen:

package tax.ws;

import tax.entities.TaxException;
import org.springframework.boot.diagnostics.AbstractFailureAnalyzer;
import org.springframework.boot.diagnostics.FailureAnalysis;

// Spring Boot ruft diesen Analyzer auf, wenn der Start wegen einer TaxException fehlschlägt
// (fehlende oder fehlerhafte Datendatei, unbekannte Implementierung)
public class TaxFailureAnalyzer extends AbstractFailureAnalyzer<TaxException> {

    @Override
    protected FailureAnalysis analyze(Throwable rootFailure, TaxException cause) {
        // die Beschreibung des Fehlers: die Meldung der Exception und die ihrer Ursache
        String description = "The service cannot start: " + cause.getMessage()
                + (cause.getCause() == null ? "" : " (" + cause.getCause().getMessage() + ")");
        // was der Benutzer tun muss
        String action = "Check the dao.implementation and dao.file properties of the configuration.";
        return new FailureAnalysis(description, action, cause);
    }
}
  • Zeile 9: Die Klasse [AbstractFailureAnalyzer<T>] von Spring Boot sucht in der Kette der Ursachen, die zum Startfehler geführt haben, nach einer Ausnahme vom Typ [T] – hier [TaxException]. Findet sie eine, ruft sie die Methode [analyze] auf;
  • Zeile 12: Der Parameter [rootFailure] ist die ursprüngliche Ausnahme, und [cause] ist die in der Kette gefundene [TaxException] ;
  • Zeilen 14–18: Der Bericht ist ein Objekt vom Typ [FailureAnalysis], bestehend aus einer Beschreibung, einer empfohlenen Maßnahme und der analysierten Ausnahme.

Dieser Analyzer ist keine Bean (er muss auch funktionieren, wenn der Container nicht erstellt werden konnte): Spring Boot sucht ihn in den Dateien [META-INF/spring.factories] der Bibliotheken und der Anwendung. Unserer liegt in [src/main/resources/META-INF]:

# der Analyzer für die durch eine TaxException verursachten Startfehler
org.springframework.boot.diagnostics.FailureAnalyzer=tax.ws.TaxFailureAnalyzer
  • Zeile 2: Der Schlüssel ist der Name der Schnittstelle [FailureAnalyzer], und der Wert ist der Name unserer Klasse (mehrere Klassen würden durch Kommas getrennt).

Starten wir nun den Service wie gewohnt mit [mvn spring-boot:run] und fragen ihn dann mit [curl] ab:

1
2
3
4
5
6
7
> curl -s -i "http://localhost:5120/tax?married=y&children=2&salary=60000"
HTTP/1.1 200 
Content-Type: application/json
Content-Length: 12
Date: Sat, 03 Oct 2026 17:04:03 GMT

{"tax":4282}

Das ist das erwartete Testergebnis: Ein verheirateter Steuerpflichtiger mit zwei Kindern und einem Jahresgehalt von 60.000 Euro zahlt 4.282 Euro Steuern (beachten Sie, dass die verwendete Steuertabelle – die von 2004 – nur für dieses Steuerjahr beibehalten wird). Mit fehlerhaften Parametern:

1
2
3
4
5
6
7
8
> curl -s -i "http://localhost:5120/tax?married=x&children=-2"
HTTP/1.1 400 
Content-Type: application/problem+json
Transfer-Encoding: chunked
Date: Sat, 03 Oct 2026 17:04:03 GMT
Connection: close

{"instance":"/tax","status":400,"title":"Incorrect parameters","errors":{"married":["Indicate whether the taxpayer is married: y/n (GET) or true/false (POST)"],"children":["The number of children must be a positive or zero integer"],"salary":["The salary must be a positive or zero integer"]}}

Dann per POST, mit einem JSON-Dokument:

1
2
3
4
5
6
7
> curl -s -i -H "Content-Type: application/json" -d '{"married":true,"children":2,"salary":60000}' http://localhost:5120/tax
HTTP/1.1 200 
Content-Type: application/json
Content-Length: 12
Date: Sat, 03 Oct 2026 17:04:04 GMT

{"tax":4282}

Das Log des Service wird am Ende des Kapitels gezeigt: Es enthält eine Aufzeichnung aller angeforderten Berechnungen.

13.4.4. Die Konsolenausgabe: eine neue [business]-Schicht

Der Client von Version 9 verwendet die Schicht [ui] aus Version 5, ohne sie zu ändern: die Klasse [tax.ui.Dialog], deren statische Methode [run(ITaxBusiness business)] mit dem Benutzer interagiert und Berechnungen bei der Schicht [business] anfordert, die ihr übergeben wird. Man muss ihr lediglich eine Schicht namens [business] übergeben, die den Webservice abfragt. Die Abhängigkeiten des Projekts [ClientWsTax] lauten wie folgt (der Rest der Datei [pom.xml] entspricht dem von [ClientWsHello], abgesehen vom Projektnamen und von der Hauptklasse: [examples.tax:client-ws-tax:9.0], [tax.client.Main]):

    <dependencies>
        <!-- die Schnittstelle der [business]-Schicht und die [ui]-Schicht aus Version 5 -->
        <!-- (tax-ui bringt auch tax-dao und den Spring-Container mit) -->
        <dependency>
            <groupId>examples.tax</groupId>
            <artifactId>tax-business</artifactId>
            <version>5.0</version>
        </dependency>
        <dependency>
            <groupId>examples.tax</groupId>
            <artifactId>tax-ui</artifactId>
            <version>5.0</version>
        </dependency>
        <!-- Jackson für die mit dem Dienst ausgetauschten JSON-Dokumente -->
        <dependency>
            <groupId>tools.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>3.1.5</version>
        </dependency>
    </dependencies>
  • Zeilen 4–13: die Module aus Version 5: [tax-business] für die Schnittstelle [ITaxBusiness], [tax-ui] für die Klasse [Dialog]. Ein Projekt darf von einem Modul abhängen, das ein Hauptprogramm enthält: In diesem Fall nutzt es die öffentlichen Klassen des Moduls, ohne das Programm selbst auszuführen. Das Modul [tax-dao] ist eine indirekte (transitive) Abhängigkeit: Der Client verwendet daraus nur die Klasse [TaxException]. Ebenso stellt [tax-ui] den Spring-Container bereit ([spring-context]);
  • Zeilen 15–19: Jackson, für die JSON-Dokumente. Es wird ebenfalls von [tax-dao] bereitgestellt, doch der Client verwendet es direkt: Es ist besser, es zu deklarieren.

Die neue [business]-Schicht ist die Klasse [TaxBusinessHttp]:

package tax.client;

import tax.entities.TaxException;
import tax.business.ITaxBusiness;
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import tools.jackson.databind.json.JsonMapper;

// die [business]-Schicht auf der Clientseite: ein Proxy des Webdienstes für die Steuerberechnung
// sie implementiert dieselbe Schnittstelle wie die lokale [business]-Schicht aus Version 5
public class TaxBusinessHttp implements ITaxBusiness {

    // die mit dem Webdienst ausgetauschten Objekte
    private record TaxRequest(boolean married, int children, int salary) {
    }

    private record TaxResponse(int tax) {
    }

    // der HTTP-Client, die URL der Methode POST /tax, der JSON-Konverter
    private final HttpClient client;
    private final URI taxUrl;
    private final JsonMapper mapper = JsonMapper.builder().build();

    public TaxBusinessHttp(HttpClient client, URI serviceUrl) {
        this.client = client;
        this.taxUrl = serviceUrl.resolve("tax");
    }

    @Override
    public int calculateTax(boolean married, int nbChildren, int salary) {
        // die Anfrage POST /tax, mit der Anfrage in JSON in ihrem Body
        String json = mapper.writeValueAsString(new TaxRequest(married, nbChildren, salary));
        HttpRequest request = HttpRequest.newBuilder(taxUrl)
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(json))
                .build();
        HttpResponse<String> response;
        try {
            // synchrones Senden: die Methode wartet auf die Antwort
            response = client.send(request, HttpResponse.BodyHandlers.ofString());
        } catch (IOException e) {
            // der Dienst ist nicht erreichbar
            throw new TaxException("The web service " + taxUrl + " is unreachable", e);
        } catch (InterruptedException e) {
            // der Thread wurde während des Wartens unterbrochen: dies wird erneut signalisiert
            Thread.currentThread().interrupt();
            throw new TaxException("The tax calculation was interrupted", e);
        }
        // hat der Dienst die Anfrage akzeptiert?
        if (response.statusCode() != 200) {
            throw new TaxException("The web service responded " + response.statusCode()
                    + " : " + response.body(), response.statusCode());
        }
        // die JSON-Antwort {"tax":4282}
        return mapper.readValue(response.body(), TaxResponse.class).tax();
    }
}

Kommentare:

  • Zeile 14: Die Klasse implementiert die Schnittstelle [ITaxBusiness] aus Version 5;
  • Zeilen 17–21: Die DTO-Variablen werden innerhalb der Klasse deklariert ([private]), da sie sonst niemand verwendet;
  • Zeilen 28–31: Die Klasse erhält über ihren Konstruktor den HTTP-Client und die URL des Service, aus denen sie die URL für die Methode [POST /tax] berechnet;
  • Zeilen 36–40: die Anfrage [POST tax], wobei die Anfrage als JSON in ihrem Body serialisiert wird;
  • Zeile 44: Die Anfrage wird synchron gesendet: Die Methode [send] wartet auf die Antwort, was zur Methode [calculateTax] der Schnittstelle passt, die selbst synchron ist (sie gibt einen [int] zurück);
  • Zeilen 45–47: [send] löst eine [IOException] aus, wenn der Service nicht erreichbar ist. Das ist eine geprüfte Ausnahme, die die Methode [calculateTax] der Schnittstelle nicht deklariert: Sie wird in eine [TaxException] gekapselt, die ungeprüfte Ausnahme der Anwendung [Tax];
  • Zeilen 48–52: Dasselbe gilt für [InterruptedException], die ausgelöst wird, wenn der Thread beim Warten unterbrochen wird. Das Abfangen der Ausnahme löscht das Unterbrechungsflag des Threads: Bewährte Praxis (Kapitel 8) ist es, es mit [Thread.currentThread().interrupt()] zurückzusetzen, damit der aufrufende Code weiß, dass der Thread unterbrochen wurde;
  • Zeilen 54–57: Eine Fehlerantwort wird in eine [TaxException] umgewandelt, deren Code der HTTP-Statuscode ist;
  • Zeile 59: Das JSON der Antwort [{"tax":4282}] wird deserialisiert, und der Steuerbetrag wird zurückgegeben.

Bei einem SOAP-Service erzeugte das Werkzeug [wsimport] einen Proxy, und eine dieser ähnliche Klasse implementierte [ITaxBusiness] , indem sie die Berechnung an ihn delegierte: Heute schreiben wir die paar Dutzend Zeilen des Proxys selbst.

Da die Methode [calculateTax] der Schnittstelle [ITaxBusiness] synchron ist, haben wir die synchrone Methode [send] von [HttpClient] verwendet. Diese Schnittstelle bietet auch eine asynchrone Methode, [sendAsync], die sofort ein [CompletableFuture<HttpResponse<T>>] zurückgibt (Kapitel 9). Um davon zu profitieren, müssten wir die Schnittstelle asynchron machen: [CompletableFuture<Integer> calculateTaxAsync(boolean married, int nbChildren, int salary)], was eine Änderung der Schnittstelle [ITaxBusiness], ihrer Implementierungen und der Schicht [ui] erfordern würde. Wir haben darauf verzichtet, um die Schichten aus Version 5 unangetastet zu lassen. Mit virtuellen Threads (Java 21) ist synchroner Code wieder die empfohlene Art geworden, Programme mit viel I/O zu schreiben: Ein virtueller Thread, der durch [send] blockiert ist, blockiert keine Systemthreads.

Das Hauptprogramm des Clients integriert die Schichten:

package tax.client;

import tax.business.ITaxBusiness;
import tax.ui.Dialog;
import java.net.URI;
import java.net.http.HttpClient;
import org.springframework.context.support.GenericApplicationContext;

public class Main {

    public static void main(String[] args) {
        // die URL des Webdienstes: die als Argument übergebene oder die Standard-URL
        URI serviceUrl = URI.create(args.length > 0 ? args[0] : "http://localhost:5120/");

        // der Exit-Code des Programms
        int code = 0;
        // Integration der Schichten: die [business]-Schicht ist nun ein Client des Webdienstes
        try (GenericApplicationContext context = new GenericApplicationContext()) {
            // die URL des Dienstes und der HTTP-Client, die Spring an den Konstruktor von TaxBusinessHttp übergibt
            context.registerBean(URI.class, () -> serviceUrl);
            context.registerBean(HttpClient.class, HttpClient::newHttpClient);
            context.registerBean(TaxBusinessHttp.class);
            context.refresh();
            ITaxBusiness business = context.getBean(ITaxBusiness.class);

            // der Dialog aus Version 5, ohne jede Änderung
            try {
                Dialog.run(business);
            } catch (RuntimeException e) {
                // der Dienst ist nicht erreichbar oder hat die Anfrage abgelehnt
                Dialog.displayError(e);
                code = 1;
            }
        }
        if (code != 0) {
            System.exit(code);
        }
    }
}

Kommentare:

  • Zeile 13: die URL des Service, als Argument übergeben oder standardmäßig [http://localhost:5120/];
  • Zeile 18: der Spring-Container, wie in Version 5. Er wird am Ende des [try]-Blocks geschlossen;
  • Zeilen 20–22: Drei Beans werden registriert: die Bean URL des Service und die Bean HTTP des Clients, die durch Lambdas (vom Typ [Supplier]) bereitgestellt werden, gefolgt von der Klasse [TaxBusinessHttp]. Um diese Klasse zu erstellen, untersucht Spring ihren Konstruktor und übergibt ihr die Beans der Typen [HttpClient] und [URI];
  • Zeile 23: Der Container erstellt die Beans;
  • Zeile 24: Beim Container wird eine Bean vom Typ [ITaxBusiness] angefordert; er gibt das Objekt [TaxBusinessHttp] zurück, das diese Schnittstelle implementiert. Der Rest des Programms kennt die Implementierung nicht;
  • Zeile 28: der Dialog aus Version 5, ohne jede Änderung;
  • Zeilen 29–33: Ist der Service nicht erreichbar, wird die Ausnahme von der [business]-Schicht durch die Schicht [ui] weitergereicht, die sie nicht behandelt: Sie wird mit der Methode [Dialog.displayError] aus Version 5 angezeigt;
  • Zeilen 35–37: Im Fehlerfall beendet sich das Programm nach dem Schließen des Containers mit dem Code 1.

Ergebnisse bei laufendem Service:

> mvn -q compile exec:java
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 2 60000
Tax=4282 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 3 60000
Tax=2959 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: n 0 60000
Tax=11519 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y -2 60000
syntax: Married NbChildren Salary
Married: y for married, n for not married
NbChildren: number of children
Salary: annual salary in euros
Incorrect NbChildren argument: type a positive or zero integer
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: 

Die Kontrollwerte der Steuerberechnung werden angezeigt: 4.282, 2.959 und 11.519 Euro. Die fehlerhafte Eingabe in Zeile 8 wurde von der Schicht [ui] erkannt, die die Schicht [business] nicht aufgerufen hat: Der Service hat nur gültige Anfragen erhalten. Wenn der Service angehalten wird:

> mvn -q compile exec:java
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 2 60000
Exception chain:
----------------------------------------
tax.entities.TaxException: The web service http://localhost:5120/tax is unreachable
----------------------------------------
java.net.ConnectException: null
----------------------------------------
java.net.ConnectException: null
----------------------------------------
java.nio.channels.ClosedChannelException: null
----------------------------------------

Die [TaxException] unseres Proxys kapselt die Ausnahme [ConnectException], die von [send] ausgelöst wird und ihrerseits die Ausnahmen der Netzwerkschicht kapselt (Kapitel 12). Keine davon hat eine Meldung: [getMessage()] gibt [null] zurück.

13.5. Ein Webclient für den Steuerberechnungsservice

Eine „traditionelle“ Webanwendung erzeugt ihre Seiten (HTML) auf dem Server: Bei jedem Klick auf eine Schaltfläche wird das Formular an den Server gesendet, der dem Browser eine neue, vollständige Seite zurückgibt. Heute fragt der Browser meist selbst in JavaScript einen Webservice ab und aktualisiert nur den Teil der Seite, der sich geändert hat. Genau das werden wir tun. Die Architektur sieht wie folgt aus:

Image

  • 1: Der Browser fordert die Seite [/] an; der Server [WsTax] sendet ihm die statische Datei [index.html];
  • 2: Bei jedem Klick auf die Schaltfläche [Calculate] sendet der JavaScript-Code der Seite die Anfrage [POST /tax] an den Webservice und zeigt den empfangenen Steuerbetrag auf der Seite an, ohne sie neu zu laden.

Der Webservice wurde nicht verändert: Er stellt lediglich eine zusätzliche Datei bereit. Spring Boot stellt Dateien, die im Ordner [static] innerhalb der Ressourcen der Anwendung ([src/main/resources/static]) liegen, automatisch als statische Dateien bereit: HTML-Seiten, Bilder, Skripte, Stylesheets usw. Die Datei [static/index.html] wird auch für die URL [/] ausgeliefert: Das ist die Startseite. Ein einzelner Server kann somit sowohl eine Website als auch einen Webservice hosten. Die Seite [index.html] sieht wie folgt aus:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Calculate your tax</title>
  <style>
    body { font-family: sans-serif; background: #ffffe0; margin: 2em; }
    td { padding: 4px 8px; white-space: nowrap; }
    .error { color: #cc2200; }
    #tax:not(:empty) { background: #99ccff; padding: 2px 8px; font-weight: bold; }
  </style>
</head>
<body>
  <h2>Calculate your tax</h2>
  <form id="form">
    <table>
      <tr>
        <td>Are you married</td>
        <td>
          <label><input type="radio" name="married" value="yes"> Yes</label>
          <label><input type="radio" name="married" value="no" checked> No</label>
        </td>
      </tr>
      <tr>
        <td>Number of children</td>
        <td><input type="text" id="children" size="3"></td>
        <td class="error" id="childrenError"></td>
      </tr>
      <tr>
        <td>Annual salary</td>
        <td><input type="text" id="salary" size="8"></td>
        <td class="error" id="salaryError"></td>
      </tr>
      <tr>
        <td>Tax to pay</td>
        <td><span id="tax"></span></td>
      </tr>
    </table>
    <p class="error" id="message"></p>
    <p>
      <button type="submit">Calculate</button>
      <button type="button" id="clear">Clear</button>
    </p>
  </form>

  <script>
    // die Elemente der Seite
    const form = document.getElementById("form");
    const children = document.getElementById("children");
    const salary = document.getElementById("salary");
    const tax = document.getElementById("tax");
    const childrenError = document.getElementById("childrenError");
    const salaryError = document.getElementById("salaryError");
    const message = document.getElementById("message");

    // eine eingegebene ganze Zahl oder null, wenn die Eingabe keine ganze Zahl ist
    function readInteger(text) {
      return /^\s*-?\d+\s*$/.test(text) ? parseInt(text, 10) : null;
    }

    // löscht das Ergebnis und die Fehlermeldungen
    function clearMessages() {
      tax.textContent = "";
      childrenError.textContent = "";
      salaryError.textContent = "";
      message.textContent = "";
    }

    // Schaltfläche [Calculate]: wir fragen den Webdienst ab, ohne die Seite neu zu laden
    form.addEventListener("submit", async (event) => {
      event.preventDefault();
      clearMessages();
      // die Anfrage, im von POST /tax erwarteten Format
      const request = {
        married: form.married.value === "yes",
        children: readInteger(children.value),
        salary: readInteger(salary.value)
      };
      try {
        const response = await fetch("tax", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify(request)
        });
        const body = await response.json();
        if (response.ok) {
          // 200: {"tax": 4282}
          tax.textContent = `${body.tax} euros`;
        } else {
          // 400: ein Dokument "Problem Details" mit den Fehlern pro Parameter
          const errors = body.errors ?? {};
          childrenError.textContent = errors.children?.join(" ") ?? "";
          salaryError.textContent = errors.salary?.join(" ") ?? "";
          message.textContent = body.title;
        }
      } catch (e) {
        // der Dienst ist nicht erreichbar
        message.textContent = `Error communicating with the service: ${e.message}`;
      }
    });

    // Schaltfläche [Clear]: Zurücksetzen des Formulars
    document.getElementById("clear").addEventListener("click", () => {
      children.value = "";
      salary.value = "";
      clearMessages();
    });
  </script>
</body>
</html>

Kommentare:

  • Zeilen 15–44: das Formular: zwei Optionsfelder für den Familienstand, zwei Eingabefelder für die Anzahl der Kinder und das Gehalt – jeweils gefolgt von einer Zelle, in der eine eventuelle Fehlermeldung angezeigt wird –, ein Feld für die Steuer, ein Absatz für eine allgemeine Meldung und zwei Schaltflächen;
  • Zeilen 46–108: der Code der Seite, JavaScript, der vom Browser ausgeführt wird. Der Kurs behandelt JavaScript nicht; dieser Code ist Java jedoch ähnlich genug, um ihn ohne Mühe lesen zu können;
  • Zeile 57: Eine Eingabe, die keine Ganzzahl ist, ergibt [null]; es ist Sache des Service, den Fehler zu melden;
  • Zeile 70: der Click-Handler der Schaltfläche [Calculate] (Formular absenden). Dies ist eine asynchrone Funktion ([async]): Wie [CompletableFuture] (Kapitel 9) blockiert sie den Browser beim Warten auf eine Antwort nicht;
  • Zeile 71: Wir verhindern, dass der Browser das Formular selbst absendet, was das Laden einer neuen Seite auslösen würde;
  • Zeilen 74–77: die Anfrage, ein JavaScript-Objekt im von [POST /tax] erwarteten Format;
  • Zeilen 80–83: Die Funktion [fetch] des Browsers sendet die HTTP-Anfrage: die Methode [POST], den Header [Content-Type] und den Body – die von [JSON.stringify] in JSON serialisierte Anfrage. Die URL [tax] ist relativ zur Seite: Die Anfrage wird an den Server gesendet, der die Seite geliefert hat. [await] wartet auf die Antwort, ohne den Browser zu blockieren;
  • Zeile 85: Der Body der Antwort wird in ein Objekt deserialisiert;
  • Zeilen 86–88: Bei Erfolg (Code 2xx) wird der Steuerbetrag angezeigt;
  • Zeilen 91–94: Tritt ein Fehler auf, werden der Titel des Dokuments „Problem Details“ sowie Fehlermeldungen zur Anzahl der Kinder und zum Gehalt angezeigt, jeweils neben dem zugehörigen Eingabefeld. Der Operator [?.] gibt [undefined] zurück, wenn das Objekt links davon nicht existiert, statt einen Fehler zu verursachen; der Operator [??] ersetzt einen fehlenden Wert durch den Wert, der ihm folgt. Java kennt für diese Operatoren keine direkte Entsprechung: In Java verwendet man [null]-Prüfungen oder ein [Optional];
  • Zeilen 103–106: Die Schaltfläche [Clear] setzt das Formular lokal zurück, ohne den Service abzufragen.

Da der Service nun läuft, rufen wir die URL [http://localhost:5120/] in einem Browser auf:

Image

Nach der Eingabe einer Berechnung und dem Klick auf die Schaltfläche [Calculate]:

Image

Ist die Eingabe fehlerhaft, stammen die Fehlermeldungen vom Webservice:

Image

Diese Screenshots wurden mit dem Browser Chromium aufgenommen, der über die Bibliothek Playwright von einem Programm gesteuert wird: So automatisiert man das Testen einer Weboberfläche.

Hier haben die Seite und der Service denselben Origin (dasselbe Protokoll, derselbe Rechner, derselbe Port: [http://localhost:5120]). Würde die Seite von einer anderen Site ausgeliefert, zum Beispiel [http://localhost:5000], würde der Browser die Same-Origin-Policy durchsetzen: Er würde dem JavaScript-Code das Lesen der Antwort des Service nur erlauben, wenn der Service dies über den Header [Access-Control-Allow-Origin] gestattet. Bei einer Anfrage wie unserer (POST mit einem JSON-Body) würde der Browser diese Erlaubnis sogar vor dem Senden der Anfrage einholen, und zwar über eine vorgeschaltete Anfrage mit der Methode OPTIONS (Preflight). Das ist der CORS-Mechanismus (Cross-Origin Resource Sharing), der den Benutzer vor bösartigen Seiten schützt, die versuchen könnten, ohne sein Wissen Services zu nutzen, bei denen er angemeldet ist. Um andere Origins zuzulassen, kann ein Spring-Controller mit [@CrossOrigin(origins = "http://localhost:5000")] annotiert werden; eine globale Konfiguration ist ebenfalls möglich (die Methode [addCorsMappings] der Schnittstelle [WebMvcConfigurer]). Clients, die keine Browser sind ([curl], unsere Konsolenclients), sind von CORS nicht betroffen.

Für umfangreichere, vom Server generierte Weboberflächen bietet Spring MVC außerdem Controller, die aus Templates (etwa Thymeleaf) erzeugte HTML-Seiten zurückgeben; dies geht über den Rahmen dieses Kurses hinaus.

13.6. Ein Webservice ist unabhängig von der Programmiersprache seines Clients

Bei einem SOAP-Service benötigte der Client ein Werkzeug, das die WSDL lesen und den Proxy erzeugen konnte, und Unterschiede in der Auslegung der Standards auf den verschiedenen Plattformen führten oft zu Interoperabilitätsproblemen. Bei einem REST/JSON-Service kann jede Sprache, die über einen HTTP-Client und eine JSON-Bibliothek verfügt, also alle aktuellen Sprachen, den Service ohne besondere Werkzeuge abfragen. Das haben wir bereits mit [curl] gesehen, das nicht in Java geschrieben ist, und mit dem JavaScript im Browser. Hier ist ein Client für Node.js, die Laufzeitumgebung für JavaScript außerhalb des Browsers:

// ein JavaScript-Client (Node.js) des Webdienstes für die Steuerberechnung
// Aufruf: node client-tax.mjs [service url]
const serviceUrl = process.argv[2] ?? "http://localhost:5120/";

// die zu sendenden Anfragen: die letzte ist fehlerhaft
const requests = [
  { married: true, children: 2, salary: 60000 },
  { married: false, children: 0, salary: 60000 },
  { married: true, children: -1, salary: 60000 },
];

for (const request of requests) {
  // POST /tax mit der Anfrage in JSON
  const response = await fetch(new URL("tax", serviceUrl), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(request),
  });
  const body = await response.json();
  if (response.ok) {
    console.log(`${JSON.stringify(request)} -> tax = ${body.tax} euros`);
  } else {
    console.log(`${JSON.stringify(request)} -> error ${response.status}: ${JSON.stringify(body.errors)}`);
  }
}
  • Zeile 3: die URL des Service, als Argument übergeben oder standardmäßig festgelegt;
  • Zeilen 6–9: drei Berechnungsanfragen, von denen die letzte fehlerhaft ist;
  • Zeilen 14–17: dieselbe Funktion [fetch] wie im Browser;
  • Zeilen 20–23: Anzeige des Steuerbetrags oder der Fehler.

Sobald der Service läuft:

1
2
3
4
> node client-tax.mjs
{"married":true,"children":2,"salary":60000} -> tax = 4282 euros
{"married":false,"children":0,"salary":60000} -> tax = 11519 euros
{"married":true,"children":-1,"salary":60000} -> error 400: {"children":["The number of children must be a positive or zero integer"]}

In Python würde man entsprechend das Modul [requests] oder [httpx] verwenden, in C# die Klasse [HttpClient]. Hier schließlich das Log des Service [WsTax] während aller Tests dieses Kapitels ([curl], Konsolenclient, Browser, Node.js-Client), bis zu seiner Beendigung mit Strg+C (im Kurs wurden die Pfade in Zeile 2 mit [...] abgekürzt):

> mvn spring-boot:run
19:03:44.598 INFO  [main] WsTaxApplication : Starting WsTaxApplication using Java 25.0.4.1 with PID 25879 (... in .../13-web-services/WsTax)
19:03:44.621 INFO  [main] WsTaxApplication : No active profile set, falling back to 1 default profile: "default"
19:03:50.050 INFO  [main] TomcatWebServer : Tomcat initialized with port 5120 (http)
19:03:50.140 INFO  [main] StandardService : Starting service [Tomcat]
19:03:50.166 INFO  [main] StandardEngine : Starting Servlet engine: [Apache Tomcat/11.0.24]
19:03:50.314 INFO  [main] WebApplicationContextInitializer : Root WebApplicationContext: initialization completed in 4921 ms
19:03:51.065 INFO  [main] WelcomePageHandlerMapping : Adding welcome page: class path resource [static/index.html]
19:03:53.070 INFO  [main] TomcatWebServer : Tomcat started on port 5120 (http) with context path '/'
19:03:53.142 INFO  [main] WsTaxApplication : Started WsTaxApplication in 10.178 seconds (process running for 11.043)
19:04:03.287 INFO  [http-nio-5120-exec-1] [/] : Initializing Spring DispatcherServlet 'dispatcherServlet'
19:04:03.287 INFO  [http-nio-5120-exec-1] DispatcherServlet : Initializing Servlet 'dispatcherServlet'
19:04:03.336 INFO  [http-nio-5120-exec-1] DispatcherServlet : Completed initialization in 49 ms
19:04:03.533 INFO  [http-nio-5120-exec-1] TaxController : Tax(married=true, children=2, salary=60000) = 4282
19:04:03.813 WARN  [http-nio-5120-exec-3] TaxController : Incorrect request: married, children, salary
19:04:04.116 INFO  [http-nio-5120-exec-4] TaxController : Tax(married=true, children=2, salary=60000) = 4282
19:04:09.345 INFO  [http-nio-5120-exec-6] TaxController : Tax(married=true, children=2, salary=60000) = 4282
19:04:09.875 INFO  [http-nio-5120-exec-8] TaxController : Tax(married=true, children=3, salary=60000) = 2959
19:04:09.890 INFO  [http-nio-5120-exec-10] TaxController : Tax(married=false, children=0, salary=60000) = 11519
19:04:13.159 INFO  [http-nio-5120-exec-2] TaxController : Tax(married=true, children=2, salary=60000) = 4282
19:04:13.319 WARN  [http-nio-5120-exec-3] TaxController : Incorrect request: children, salary
19:04:13.811 INFO  [http-nio-5120-exec-4] TaxController : Tax(married=true, children=2, salary=60000) = 4282
19:04:13.828 INFO  [http-nio-5120-exec-5] TaxController : Tax(married=false, children=0, salary=60000) = 11519
19:04:13.838 WARN  [http-nio-5120-exec-6] TaxController : Incorrect request: children
19:04:16.301 INFO  [SpringApplicationShutdownHook] GracefulShutdown : Commencing graceful shutdown. Waiting for active requests to complete
19:04:16.314 INFO  [tomcat-shutdown] GracefulShutdown : Graceful shutdown complete
  • Zeile 8: Spring Boot hat die Startseite [static/index.html] gefunden;
  • Zeilen 14–24: Meldungen unseres Controllers: Die Zeilen [INFO] protokollieren die Berechnungen, während die Zeilen [WARN] ungültige Anfragen protokollieren, zusammen mit den Namen der betroffenen Parameter. Die Zeilen 14–16 stammen von [curl], die Zeilen 17–19 vom Konsolenclient, die Zeilen 20–21 vom Browser und die Zeilen 22–24 vom Node.js-Client;
  • Die Namen der Threads ([http-nio-5120-exec-1] bis [exec-10]) zeigen, dass die Anfragen auf die Threads des Tomcat-Pools verteilt werden; aufeinanderfolgende Anfragen desselben Clients werden nicht unbedingt vom selben Thread bearbeitet.

13.7. Zusätzliche Informationen

13.7.1. Antworttypen und Fehlerbehandlung

Der Service [WsOperations] gibt Objekte vom Typ [ResponseEntity<?>] zurück: Allein anhand der Signaturen seiner Methoden ist unklar, welche Antworten sie erzeugen können, und der Compiler führt keine Prüfungen durch. Der Service [WsTax] gibt bei Erfolg den spezifischen Typ seiner Antwort zurück, [TaxResponse], und meldet Fehler über Ausnahmen, die von einem [@ExceptionHandler]-Handler in Antworten umgewandelt werden. Das ist bei Spring der gängigste Ansatz: Der Code der Methode behandelt nur den Normalfall, und die Werkzeuge (insbesondere der Generator für OpenAPI-Dokumente) kennen das JSON-Schema der Antwort, ohne dass man es ihnen ausdrücklich mitteilen muss. Ein Unit-Test kann außerdem direkt eine Controller-Methode aufrufen und ihr Ergebnis untersuchen, ohne über HTTP zu gehen. [ResponseEntity<T>] mit einem spezifischen Typ bleibt nützlich, wenn man den Statuscode wählen oder Header hinzufügen muss, zum Beispiel bei einer Antwort 201 (Created) mit ihrem Header [Location]: [ResponseEntity.created(uri).body(client)].

Ein in einem Controller platzierter [@ExceptionHandler]-Handler behandelt nur die Ausnahmen dieses Controllers. Um die Ausnahmen aller Controller einer Anwendung zu behandeln, platziert man die Handler in einer Klasse, die mit [@RestControllerAdvice] annotiert ist. Spring bietet außerdem die Klasse [ErrorResponseException], eine Ausnahme, die direkt ein [ProblemDetail] mitführt und die entsprechende Antwort ohne Handler erzeugt, sowie die Klasse [ResponseEntityExceptionHandler], die erweitert werden kann, um die Antworten auf Fehler anzupassen, die Spring MVC selbst erkennt (nicht lesbares JSON-Dokument, ungültiger Dokumenttyp usw.).

13.7.2. Ein gemeinsames Präfix für Routen

Wenn mehrere Routen ein Präfix gemeinsam haben, wird es einmalig mit der Annotation [@RequestMapping] angegeben, die auf der Controller-Klasse steht. Mit [@RequestMapping("/api/operations")] auf der Klasse [OperationsController] lauten die Routen zum Beispiel [GET /api/operations/add?a=1&b=2] and [POST /api/operations/calculation], ohne weitere Änderungen. Das ist auch eine einfache Möglichkeit, Versionen eines Service zu verwalten ([/api/v1/...], [/api/v2/...]).

13.7.3. Interceptoren und Validierung

Unsere Services validieren ihre Parameter selbst. Spring bietet zwei Mechanismen, um diesen Code aus den Controllern auszulagern:

  • Interceptoren: Eine Klasse, die die Schnittstelle [HandlerInterceptor] implementiert und über die Methode [addInterceptors] von [WebMvcConfigurer] registriert wird, wird vor und nach den Controller-Methoden ausgeführt; sie kann die Anfrage untersuchen und selbstständig antworten, ohne den Controller aufzurufen. Sie dienen unter anderem dem Logging, der Messung von Antwortzeiten und der Authentifizierung. Servlet-Filter ([jakarta.servlet.Filter]) erfüllen auf niedrigerer Ebene denselben Zweck;
  • Validierung: Mit dem Starter [spring-boot-starter-validation] (der Hibernate Validator bereitstellt, die Referenzimplementierung der Jakarta-Validation-API) können Komponenten eines DTO mit Constraints annotiert werden: [record TaxRequest(@NotNull Boolean married, @NotNull @Min(0) Integer children, @NotNull @Min(0) Integer salary)]. Ein Parameter [@Valid @RequestBody TaxRequest request] wird dann vor dem Aufruf der Methode validiert, und eine ungültige Anfrage wird mit einer 400-Antwort „Problem Details“ abgelehnt, wie wir sie selbst erstellt haben.

13.7.4. Hosting

Unsere Services werden mit [mvn spring-boot:run] ausgeführt, was für die Entwicklung geeignet ist. In der Produktion:

  • Die Anwendung wird zunächst mit [mvn package] paketiert: Das Spring-Boot-Plugin erzeugt eine einzige „ausführbare“ [.jar]-Datei, die die Anwendung, ihre Abhängigkeiten und den Tomcat-Server enthält. Sie kopieren sie einfach auf den Server und führen sie mit [java -jar ws-tax-9.0.jar] aus; die Konfiguration lässt sich über Kommandozeilenargumente ([--server.port=80]), Umgebungsvariablen oder eine Datei [application.properties] ändern, die neben der Datei [.jar] liegt;
  • Tomcat kann direkt dem Internet ausgesetzt werden, wird aber häufig hinter einem Reverse-Proxy (nginx oder Apache unter Linux, IIS unter Windows) platziert, der HTTPS-Anfragen entgegennimmt, Zertifikate verwaltet und die Last auf mehrere Instanzen der Anwendung verteilt;
  • Die Anwendung kann auch als Container-Image (Docker) bereitgestellt werden, das das Spring-Boot-Plugin ohne eine Datei [Dockerfile] erzeugen kann: [mvn spring-boot:build-image]. Das Image läuft dann auf jeder Container-Plattform, sei es auf Ihrem eigenen Server oder bei einem Hosting-Anbieter;
  • HTTPS ist unverzichtbar: Die Spring-Boot-Eigenschaften [server.ssl.*] konfigurieren das Zertifikat des Tomcat-Servers, wenn der Server direkt exponiert ist.

13.8. Fazit

Dieses Kapitel hat die REST/JSON-Webservices, die Nachfolger der SOAP-Webservices, vorgestellt, die mit Spring Boot und Spring MVC geschrieben werden. Wir haben Folgendes gesehen:

  • dass ein Webservice URLs und HTTP-Methoden mit den Annotationen [@RestController], [@GetMapping] und [@PostMapping] auf Java-Methoden abbildet und dass die Parameter dieser Methoden aus der Route ([@PathVariable]), dem Query-String ([@RequestParam]), dem Body (JSON, [@RequestBody]) oder dem Spring-Container (Konstruktorinjektion) stammen;
  • dass die Ergebnisse von Jackson als JSON gesendet werden und Fehler über einen Statuscode und ein „Problem Details“-Dokument gemeldet werden ([ProblemDetail], [ResponseEntity], [@ExceptionHandler]);
  • dass ein Java-Client [java.net.http.HttpClient] und Jackson verwendet und dass ein in einer beliebigen anderen Sprache geschriebener Client dasselbe tun kann;
  • dass die Schichtenarchitektur ihre Versprechen gehalten hat: Version 9 der Steuerberechnung verwendet die serverseitigen Schichten [dao] and [business] aus Version 5 ebenso wie deren clientseitige Schicht [ui] unverändert wieder; Es genügte, den Webservice (etwa 100 Zeilen) und eine neue Implementierung der Schnittstelle [ITaxBusiness] (etwa 60 Zeilen) zu schreiben.