11. Fallstudie: Die Anwendung RdvMedecins
11.1. Die Aufgabenstellung
Die Anwendung RdvMedecins verwaltet die Termine einer Arztpraxis. Jeder Arzt hat Zeitfenster (zum Beispiel von 8:00 bis 12:00 Uhr in 20-Minuten-Schritten); ein Termin besteht aus einem Tag, einem Zeitfenster und einem Klienten (einem Patienten). Dies ist die exakte Umsetzung in [Spring MVC] der [ASP.NET Core MVC]-Anwendung aus der vorherigen Lektion: gleiche Datenbank, gleiche Geschäftsregeln, gleiche Seiten, gleiche URLs, gleiche Übersetzungswörterbücher. Die HTML-Seiten werden vom Server mithilfe von [Thymeleaf]-Views generiert; der Datenbankzugriff erfolgt über [Spring Data JPA] und [Hibernate].
Drei Benutzerrollen teilen sich die Anwendung:
Rolle | Wer | Was sie tun können |
ADMIN | Der Administrator ([admin]) | Terminkalender anzeigen, Termine für beliebige Patienten vereinbaren und absagen; Ärzte und Klienten verwalten (auflisten, hinzufügen, bearbeiten, löschen) |
DOCTOR | Ärzte | Terminkalender anzeigen, Termine für beliebige Patienten vereinbaren und absagen |
USER | Klienten (Patienten) | Terminkalender anzeigen, ohne die Namen anderer Patienten zu sehen; einen Termin für sich selbst buchen; ihren Termin absagen; ihr Konto verwalten; ein Konto erstellen |
Wichtige Verwaltungsregeln:
- Keine Termine in der Vergangenheit;
- ein Zeitfenster kann pro Tag nur einmal gebucht werden;
- ein Patient darf jeweils nur einen bevorstehenden Termin haben;
- zwei Ärzte (oder zwei Klienten) dürfen nicht denselben Vor- und Nachnamen haben, und ein Login gehört nur zu einem Konto;
- Ein Arzt mit Terminen kann nicht gelöscht werden; ein Klient wird zusammen mit seinen Terminen gelöscht;
- die Anmeldeseite ist gegen Bots geschützt (CAPTCHA, begrenzte Versuche), und für die Erstellung eines Klientenkontos muss zuvor auf dieser Seite das CAPTCHA gelöst werden.
11.2. Verwendung der Anwendung
11.2.1. Die Anmeldeseite

Die Seite enthält zwei Schaltflächen: Anmelden und Patientenkonto erstellen. Bei beiden müssen Sie die im Bild gezeigten Zeichen eingeben. Die Schaltflächen FR / EN wechseln die Sprache:

Ein Fehler (hier ein falsch eingegebenes CAPTCHA) wird am Seitenende auf hellrosa Hintergrund angezeigt:

11.2.2. Der Kalender aus Sicht des Administrators und der Ärzte
Nach der Anmeldung gelangt der Administrator zur Kalenderseite. Er wählt einen Arzt und einen Tag aus:


Jedes Zeitfenster ist entweder frei (Schaltfläche Buchen) oder belegt (Name des Patienten, Schaltfläche Absagen). Ein Klick auf Buchen öffnet ein Fenster, in dem die Daten des Patienten abgefragt werden. Dieses Fenster wird, wie der Rest der Seite, vom Server generiert: Die URL enthält nun den Parameter [book=4], die Nummer des ausgewählten Zeitfensters:

Ein Klick auf „Absagen“ löst eine Bestätigungsabfrage aus (hier bei Dr. Pélissier, dessen Navigationsleiste die Administrationsmenüs nicht enthält):

11.2.3. Das Patientenportal
Ein Patient (Rolle USER) gelangt zu „Mein Bereich“: sein bevorstehender Termin, den er absagen kann, sowie Links zu seiner Kontoverwaltung und zum Kalender:

Im Kalender sieht er seinen eigenen Termin (in Blau), nicht aber die Namen anderer Patienten, die durch „Belegt“ ersetzt sind: Dieser Name erscheint nicht einmal im Quelltext der Seite. Da er bereits einen bevorstehenden Termin hat, kann er keinen weiteren vereinbaren: Es wird keine Schaltfläche „Buchen“ angezeigt (im Kalender für einen anderen Tag oder einen anderen Arzt – wo sein Termin nicht erscheint – erklärt eine Meldung den Grund):

Ein Patient ohne Termin kann ein freies Zeitfenster für sich selbst buchen: Das Buchungsfenster fordert den Benutzer nicht auf, einen Patienten auszuwählen.

Kontoverwaltung: persönliche Daten bearbeiten, das Passwort ändern oder das Konto (und seine Termine) löschen. Für jede Änderung ist das aktuelle Passwort erforderlich:

Ein Patient, der versucht, eine dem Administrator vorbehaltene Seite zu öffnen (hier [/doctors], von Hand eingegeben), erhält eine Fehlerseite:

11.2.4. Ärzte und Patienten verwalten
Der Administrator hat zwei zusätzliche Menüs, Ärzte und Patienten:


Das Formular zum Hinzufügen eines Arztes, mit Fehlern abgeschickt:

Ein Name, der mit dem eines vorhandenen Arztes identisch ist, wird abgelehnt, auch wenn er in Kleinbuchstaben geschrieben ist (wir werden sehen, dass es die Datenbank selbst ist, die Namen ohne Unterscheidung von Groß- und Kleinschreibung und Akzenten vergleicht):

Das Löschen eines Patienten erfordert eine Bestätigung:

11.2.5. Ein Patientenkonto erstellen
Auf der Anmeldeseite öffnet die Schaltfläche „Patientenkonto erstellen“ das Formular nur, wenn das CAPTCHA korrekt eingegeben wurde:


11.3. Installation und Ausführung
Die Anwendung befindet sich im Ordner [rdvmedecins2-spring-mvc] neben dem Ordner [examples]. Sie ist ein eigenständiges [Maven]-Projekt: Sie hängt nicht vom übergeordneten Projekt mit den Beispielen ab und hat ihren eigenen Maven Wrapper (siehe unten). Die Datei [README.md] im Ordner enthält alles Folgende.
11.3.1. Erforderliche Software
Zwei Softwarepakete genügen:
- JDK 21 ([Java Development Kit]), das den Compiler [javac] und die virtuelle Maschine [java] enthält. [Java] 21 ist eine LTS-Version (Long-Term Support). Eine kostenlose Distribution ist geeignet, zum Beispiel [Eclipse Temurin] (https://adoptium.net); unter [Linux] das Paket [openjdk-21-jdk]. Überprüfen Sie die Installation in einem Terminal:
| openjdk version "21.0.10" 2026-01-20
OpenJDK Runtime Environment (build 21.0.10+7-Ubuntu-124.04)
OpenJDK 64-Bit Server VM (build 21.0.10+7-Ubuntu-124.04, mixed mode, sharing)
|
- Ein [MySQL] 8 Server, zum Beispiel der von [Laragon] unter [Windows] (siehe Beispiel 28). [MariaDB] ist ebenfalls geeignet: Die Anwendung wurde damit getestet.
[Maven] muss nicht installiert werden: Das Skript [mvnw] (Maven Wrapper) lädt es beim ersten Start automatisch herunter, und anschließend lädt [Maven] die Projektbibliotheken aus dem Repository [Maven Central] herunter. Sie müssen daher beim ersten Kompilieren mit dem Internet verbunden sein. Der empfohlene Editor ist [Visual Studio Code] mit dem „Extension Pack for Java“ und dem „Spring Boot Extension Pack“; es lässt sich jedoch alles über die Befehlszeile erledigen.
11.3.2. Die Datenbank erstellen
Die Datenbank [dbrdvmedecins2] wird durch das Skript [database/dbrdvmedecins2.sql] erstellt. Öffnen Sie mit [Laragon] das Tool [HeidiSQL] (Schaltfläche Datenbank) und führen Sie das Skript dann über das Menü Datei / SQL-Datei ausführen aus. Über die Befehlszeile, im Anwendungsordner:
| mysql -u root -p < database/dbrdvmedecins2.sql
|
Die Option [-p] fragt nach dem Passwort für [root]; lassen Sie sie weg, wenn das Konto kein Passwort hat (wie bei [Laragon]). Es ist dieselbe Datenbank wie die der Version [ASP.NET Core]: Wenn sie bereits existiert, ist dieser Schritt optional. Das Skript kann jederzeit ausgeführt werden, um zu den ursprünglichen Daten zurückzukehren.
11.3.3. Datenbankzugriff konfigurieren
Alle Konfigurationseinstellungen befinden sich in der Datei [src/main/resources/application.properties] (weiter unten besprochen). Standardmäßig verbindet sich die Anwendung mit [MySQL] auf [localhost], Port 3306, mit dem Benutzer [root] ohne Passwort: Dies sind die Standardeinstellungen von [Laragon]. Wenn Ihr [root]-Konto ein Passwort hat, ist es am einfachsten, es in diese Datei zu schreiben, und zwar unter dem Schlüssel [spring.datasource.password]. Um kein Passwort in eine Projektdatei zu schreiben, können Sie es auch über eine Umgebungsvariable angeben, die Vorrang vor der Datei hat. Ihr Name leitet sich vom Namen des Schlüssels ab: Großbuchstaben, wobei [.] und [-] durch [_] ersetzt werden:
| export SPRING_DATASOURCE_PASSWORD=myPassword # Linux, macOS
set SPRING_DATASOURCE_PASSWORD=myPassword # Windows (cmd)
$env:SPRING_DATASOURCE_PASSWORD="myPassword" # Windows (PowerShell)
|
Die Variable gilt nur für das Terminal, in dem sie definiert wurde: Die Anwendung wird dann dort gestartet.
11.3.4. Die Anwendung starten
Öffnen Sie den Ordner [rdvmedecins2-spring-mvc] in [Visual Studio Code] (Menü Datei / Ordner öffnen), öffnen Sie dann ein Terminal (Menü Terminal / Neues Terminal) und geben Sie ein:
Unter [Windows] geben Sie [mvnw spring-boot:run] an der Eingabeaufforderung oder [.\mvnw spring-boot:run] in [PowerShell] ein. Beim ersten Ausführen führt [mvnw] den Download von [Maven] durch, das seinerseits die Bibliotheken herunterlädt, die Anwendung kompiliert und anschließend startet. Nach den Meldungen von [Maven] gibt die Konsole die Meldungen der Anwendung aus:
| . ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v4.1.1)
2026-09-25T18:46:42.404+02:00 INFO 19025 --- [ restartedMain] rdvmedecins.RdvMedecinsApplication : Starting RdvMedecinsApplication using Java 21.0.10 with PID 19025 (/home/serge/cours/rdvmedecins2-spring-mvc/target/classes started by serge in /home/serge/cours/rdvmedecins2-spring-mvc)
2026-09-25T18:46:42.422+02:00 INFO 19025 --- [ restartedMain] rdvmedecins.RdvMedecinsApplication : The following 1 profile is active: "dev"
2026-09-25T18:46:42.598+02:00 INFO 19025 --- [ restartedMain] .e.DevToolsPropertyDefaultsPostProcessor : Devtools property defaults active! Set 'spring.devtools.add-properties' to 'false' to disable
2026-09-25T18:46:42.598+02:00 INFO 19025 --- [ restartedMain] .e.DevToolsPropertyDefaultsPostProcessor : For additional web related logging consider setting the 'logging.level.web' property to 'DEBUG'
2026-09-25T18:46:43.729+02:00 INFO 19025 --- [ restartedMain] .s.d.r.c.RepositoryConfigurationDelegate : Bootstrapping Spring Data JPA repositories in DEFAULT mode.
2026-09-25T18:46:43.795+02:00 INFO 19025 --- [ restartedMain] .s.d.r.c.RepositoryConfigurationDelegate : Finished Spring Data repository scanning in 55 ms. Found 5 JPA repository interfaces.
2026-09-25T18:46:44.511+02:00 INFO 19025 --- [ restartedMain] o.s.boot.tomcat.TomcatWebServer : Tomcat initialized with port 8081 (http)
2026-09-25T18:46:44.524+02:00 INFO 19025 --- [ restartedMain] o.apache.catalina.core.StandardService : Starting service [Tomcat]
2026-09-25T18:46:44.525+02:00 INFO 19025 --- [ restartedMain] o.apache.catalina.core.StandardEngine : Starting Servlet engine: [Apache Tomcat/11.0.24]
2026-09-25T18:46:44.552+02:00 INFO 19025 --- [ restartedMain] b.w.c.s.WebApplicationContextInitializer : Root WebApplicationContext: initialization completed in 1949 ms
2026-09-25T18:46:44.747+02:00 INFO 19025 --- [ restartedMain] org.hibernate.orm.jpa : HHH008540: Processing PersistenceUnitInfo [name: default]
2026-09-25T18:46:44.783+02:00 INFO 19025 --- [ restartedMain] org.hibernate.orm.core : HHH000001: Hibernate ORM core version 7.4.5.Final
2026-09-25T18:46:45.287+02:00 INFO 19025 --- [ restartedMain] o.s.o.j.p.SpringPersistenceUnitInfo : No LoadTimeWeaver setup: ignoring JPA class transformer
2026-09-25T18:46:45.317+02:00 INFO 19025 --- [ restartedMain] com.zaxxer.hikari.HikariDataSource : HikariPool-1 - Starting...
2026-09-25T18:46:45.487+02:00 INFO 19025 --- [ restartedMain] com.zaxxer.hikari.pool.HikariPool : HikariPool-1 - Added connection com.mysql.cj.jdbc.ConnectionImpl@4a05c6b0
2026-09-25T18:46:45.488+02:00 INFO 19025 --- [ restartedMain] com.zaxxer.hikari.HikariDataSource : HikariPool-1 - Start completed.
2026-09-25T18:46:45.537+02:00 WARN 19025 --- [ restartedMain] org.hibernate.orm.core : HHH000511: The 5.5.5 version for [org.hibernate.dialect.MySQLDialect] is no longer supported, hence certain features may not work properly.The minimum supported version is 8.0.0. Check the community dialects project for available legacy versions.
2026-09-25T18:46:45.554+02:00 INFO 19025 --- [ restartedMain] org.hibernate.orm.connections.pooling : HHH10001005: Database info:
Database JDBC URL [jdbc:mysql://localhost:3306/dbrdvmedecins2]
Database driver: MySQL Connector/J
Database dialect: MySQLDialect
Database version: 5.5.5
Default catalog/schema: dbrdvmedecins2/undefined
Autocommit mode: undefined/unknown
Isolation level: REPEATABLE_READ [default REPEATABLE_READ]
JDBC fetch size: none
Pool: DataSourceConnectionProvider
Minimum pool size: undefined/unknown
Maximum pool size: undefined/unknown
2026-09-25T18:46:47.573+02:00 INFO 19025 --- [ restartedMain] org.hibernate.orm.core : HHH000489: No JTA platform available (set 'hibernate.transaction.jta.platform' to enable JTA platform integration)
2026-09-25T18:46:47.597+02:00 INFO 19025 --- [ restartedMain] j.LocalContainerEntityManagerFactoryBean : Initialized JPA EntityManagerFactory for persistence unit 'default'
2026-09-25T18:46:47.688+02:00 INFO 19025 --- [ restartedMain] o.s.d.j.r.query.QueryEnhancerFactories : Hibernate is in classpath; If applicable, HQL parser will be used.
Hibernate: select d1_0.id,d1_0.first_name,d1_0.last_name,d1_0.title,u1_0.id,u1_0.login,u1_0.name,u1_0.password,u1_0.role,u1_0.version,d1_0.`user`,d1_0.version from doctors d1_0 left join users u1_0 on u1_0.id=d1_0.`user` order by d1_0.last_name,d1_0.first_name
Hibernate: select c1_0.id,c1_0.first_name,c1_0.last_name,c1_0.title,u1_0.id,u1_0.login,u1_0.name,u1_0.password,u1_0.role,u1_0.version,c1_0.`user`,c1_0.version from clients c1_0 left join users u1_0 on u1_0.id=c1_0.`user` order by c1_0.last_name,c1_0.first_name
2026-09-25T18:46:52.549+02:00 INFO 19025 --- [ restartedMain] o.s.boot.tomcat.TomcatWebServer : Tomcat started on port 8081 (http) with context path '/'
2026-09-25T18:46:52.563+02:00 INFO 19025 --- [ restartedMain] rdvmedecins.RdvMedecinsApplication : Started RdvMedecinsApplication in 10.82 seconds (process running for 11.321)
2026-09-25T18:46:52.928+02:00 INFO 19025 --- [omcat-handler-0] o.a.c.c.C.[Tomcat].[localhost].[/] : Initializing Spring DispatcherServlet 'dispatcherServlet'
2026-09-25T18:46:52.929+02:00 INFO 19025 --- [omcat-handler-0] o.s.web.servlet.DispatcherServlet : Initializing Servlet 'dispatcherServlet'
2026-09-25T18:46:52.930+02:00 INFO 19025 --- [omcat-handler-0] o.s.web.servlet.DispatcherServlet : Completed initialization in 1 ms
|
Auf diese Konsole kommen wir im Abschnitt „Start der Anwendung“ zurück. Beachten Sie vorerst die Zeile [Tomcat started on port 8081]: Die Anwendung ist unter der Adresse [http://localhost:8081] bereit. Port 8081 erlaubt es, gleichzeitig ein Kursbeispiel (Port 5000) auszuführen. Die Version [ASP.NET Core] der Anwendung lauscht ebenfalls auf Port 8081: Starten Sie nicht beide gleichzeitig.
Beenden Sie die Anwendung, indem Sie im Terminal [Ctrl-C] eingeben.
11.3.5. Demo-Konten
Das Passwort jedes Kontos ist sein Benutzername; außerdem müssen Sie die Zeichen aus dem Bild eingeben, in Groß- oder Kleinbuchstaben:
Benutzername | Rolle |
[admin] | ADMIN (der Administrator) |
[pelissier], [tatou], [dupont] | DOCTOR (die Ärzte) |
[martin], [durand], [bistrou], [german] | USER (Patienten) |
Ein Leitfaden zum Erkunden der Anwendung:
- [admin]: Terminkalender, Frau Marie PELISSIER, heute: Ein Zeitfenster ist bereits von Frau Brigitte BISTROU gebucht. Buchen Sie ein Zeitfenster für Herrn Jean MARTIN und versuchen Sie dann, einen zweiten Termin für ihn zu buchen (wird abgelehnt). Menüs Ärzte und Patienten: hinzufügen, bearbeiten, löschen (Dr. PELISSIER, der Termine hat, kann nicht gelöscht werden);
- [pelissier]: Sein Tageskalender wird direkt angezeigt; die von Hand eingegebene Adresse [/doctors] liefert eine Fehlerseite 403;
- [martin]: Mein Bereich, sein Termin, der Kalender, in dem andere Patienten als „Belegt“ erscheinen; Mein Konto verwalten;
- Anmeldeseite: Patientenkonto erstellen, sich dann mit dem neuen Konto anmelden;
- Schaltflächen FR / EN: Die gesamte Oberfläche wechselt die Sprache, einschließlich der Datumsangaben.
11.3.6. Entwicklungsmodus
Der Befehl [./mvnw spring-boot:run] startet die Anwendung mit dem Profil [dev] (siehe [pom.xml], weiter unten): Die Konsole zeigt dann jeden SQL-Befehl an, den [Hibernate] an die Datenbank sendet (die beiden Zeilen [Hibernate: select ...] in der Konsole oben). Zwei weitere Werkzeuge erleichtern die Entwicklung:
- die Bibliothek [Spring Boot DevTools] (siehe [pom.xml]) startet die Anwendung automatisch neu, sobald eine Klasse im Ordner [target/classes] neu kompiliert wird. [Visual Studio Code] kompiliert bei jedem Speichern eine [.java]-Datei neu; ohne es müssten Sie in einem zweiten Terminal [./mvnw compile] eingeben. Der Neustart dauert nur wenige Sekunden: Es werden nur die Klassen der Anwendung neu geladen, nicht die Bibliotheken. Eine geänderte [templates/*.html]-View hingegen wird beim nächsten Anzeigen der Seite neu geladen, sobald sie auf dieselbe Weise nach [target/classes] kopiert wurde;
- Der Debugger: Mit dem „Extension Pack for Java“ erscheinen die Links Run und Debug über der Methode [main] in [RdvMedecinsApplication.java]; Debug startet die Anwendung unter der Kontrolle des Debuggers. Setzen Sie einen Haltepunkt, indem Sie in den Rand einer Codezeile klicken. Die Ansicht Spring Boot Dashboard im „Spring Boot Extension Pack“ bietet dieselben Befehle an.
11.3.7. Ein ausführbares Archiv
Um die Anwendung auf einem Server zu installieren, verpacken Sie sie in einem einzigen Archiv:
| ./mvnw package
java -jar target/rdvmedecins-1.0.jar
|
Der erste Befehl kompiliert die Anwendung und erstellt das Archiv [target/rdvmedecins-1.0.jar] (etwa 60 MB): Es enthält die Anwendung, alle ihre Bibliotheken und den Server [Tomcat] selbst. Der zweite Befehl startet es: Auf dem Rechner ist nur ein JDK (oder eine JRE) 21 erforderlich. Bei diesem Start hat die Anwendung nicht das Profil [dev] (die Konsole zeigt die SQL-Befehle nicht an), und [Spring Boot DevTools] ist nicht im Archiv enthalten. Jeder Schlüssel in [application.properties] kann in der Befehlszeile ersetzt werden, zum Beispiel mit [java -jar target/rdvmedecins-1.0.jar --server.port=9000].
11.3.8. Häufige Probleme
Beim Start fragt [Hibernate] die Datenbank nach ihrer Version ab, dann liest die Anwendung daraus die Listen der Ärzte und Klienten: Ist die Datenbank nicht erreichbar, hält die Anwendung sofort an, wobei in der Konsole ein Fehler angezeigt wird. Dieser Fehler ist oft in einem langen Aufrufstapel vergraben, und die letzte Zeile [Caused by: ...] ist wenig aussagekräftig ([Unable to determine Dialect without JDBC metadata]: [Hibernate] konnte die Datenbank nicht abfragen). Suchen Sie stattdessen nach der Meldung der Datenbank selbst, die [Hibernate] ebenfalls in einer Warnung am Anfang des Fehlers ausgibt. Zum Beispiel bei einer nicht vorhandenen Datenbank:
| ... WARN ... org.hibernate.orm.jdbc.error : HHH000247: ErrorCode: 1049, SQLState: 42000
... WARN ... org.hibernate.orm.jdbc.error : Unknown database 'dbunknown'
...
Caused by: java.sql.SQLSyntaxErrorException: Unknown database 'dbunknown'
...
Caused by: org.hibernate.HibernateException: Unable to determine Dialect without JDBC metadata (please set 'jakarta.persistence.jdbc.url' for common cases or 'hibernate.dialect' when a custom Dialect implementation must be provided)
|
Die häufigsten Meldungen:
Meldung | Wahrscheinliche Ursache |
[Communications link failure] oder [Connection refused] | [MySQL] wurde nicht gestartet oder lauscht nicht auf [localhost:3306] |
[Access denied for user 'root'@'localhost'] | Das Passwort für [MySQL] muss angegeben werden (siehe „Datenbankzugriff konfigurieren“) |
[Unknown database 'dbrdvmedecins2'] | Das Skript [database/dbrdvmedecins2.sql] wurde nicht ausgeführt |
[rdvmedecins.auth.jwt-secret must be at least 32 characters long] | Der geheime Schlüssel für die Tokens ist in [application.properties] zu kurz |
[Port 8081 was already in use] | Port 8081 ist bereits belegt (läuft die Version [ASP.NET Core]?): Beenden Sie sie oder ändern Sie [server.port] |
[JAVA_HOME is not set] oder [release version 21 not supported] | Das JDK fehlt oder ist älter als Version 21 |
[Could not transfer artifact] während [mvnw] läuft | Das Repository [Maven Central] ist nicht erreichbar (keine Internetverbindung, Proxy) |
Mit [MariaDB] gibt [Hibernate] beim Start außerdem eine harmlose Warnung aus: [HHH000511: The 5.5.5 version for [org.hibernate.dialect.MySQLDialect] is no longer supported]. [MariaDB] meldet sich nämlich beim [MySQL]-Treiber mit der Versionsnummer „5.5.5“, die [Hibernate] als sehr altes [MySQL] interpretiert.
11.4. Die Architektur der Anwendung

- Der Browser sendet seine Anfragen an den Server [Tomcat], der in die Anwendung integriert ist. Jede Anfrage durchläuft zunächst die Filterkette von [Spring Security] (konfiguriert durch [config/SecurityConfig.java]), die den Benutzer anhand des JWT-Tokens in seinem Cookie identifiziert und den Zugriff auf geschützte Seiten verweigert;
- [controllers]: die Controller der Web-Schicht. Sie laufen alle über ein einziges Bean, [ApplicationModel] (im Ordner [web]), das die Listen der Ärzte und Klienten im Speicher hält und andere Anfragen an die Geschäftsschicht weiterleitet;
- [auth]: die Anmeldung, die JWT-Tokens, das CAPTCHA, die Begrenzung der Versuche und der Pass für die Kontoerstellung;
- [web]: Elemente, die der Web-Schicht gemeinsam sind: der Cache und die Fassade [ApplicationModel], Übersetzung, Flash-Meldungen, Validierung, allen Views gemeinsame Attribute und Exception-Behandlung; [models]: Formular- und View-Templates;
- [business]: Geschäftsregeln und Transaktionen;
- [repositories]: die DAO-Schicht, eine [Spring Data JPA]-Schnittstelle pro Tabelle;
- [entities]: die [JPA]-Entitäten, die [Hibernate] aus der Datenbank liest und in sie schreibt; [domain]: die Kalenderobjekte, die von der Geschäftsschicht berechnet werden;
- [templates]: die [Thymeleaf]-Views, die die HTML-Seiten erzeugen; [i18n]: die Wörterbücher, die vom Übersetzer verwendet werden; [static]: das Stylesheet, das Seitenskript und [Bootstrap];
- [config]: die in [Java] geschriebene Konfiguration (Sicherheit, Sprache, Flash-Meldungen, typisierte Eigenschaften); [RdvMedecinsApplication.java] startet das Ganze.
Der Anwendungsordner:
| rdvmedecins2-spring-mvc/
├── .mvn/
│ └── wrapper/
│ └── maven-wrapper.properties
├── database/
│ ├── dbrdvmedecins2.sql
│ └── README.md
├── src/
│ └── main/
│ ├── java/
│ │ └── rdvmedecins/
│ │ ├── auth/
│ │ │ ├── AuthService.java
│ │ │ ├── Captcha.java
│ │ │ ├── CaptchaService.java
│ │ │ ├── CaptchaDrawing.java
│ │ │ ├── AttemptLimiterService.java
│ │ │ ├── RegistrationPassService.java
│ │ │ ├── README.md
│ │ │ ├── InvalidSessionException.java
│ │ │ └── ConnectedUser.java
│ │ ├── config/
│ │ │ ├── AuthProperties.java
│ │ │ ├── ProtectionProperties.java
│ │ │ ├── README.md
│ │ │ ├── SecurityConfig.java
│ │ │ └── WebConfig.java
│ │ ├── controllers/
│ │ │ ├── ScheduleController.java
│ │ │ ├── AuthController.java
│ │ │ ├── ClientsController.java
│ │ │ ├── ErrorController.java
│ │ │ ├── PatientAreaController.java
│ │ │ ├── RegistrationController.java
│ │ │ ├── LanguageController.java
│ │ │ ├── DoctorsController.java
│ │ │ ├── PersonsControllerBase.java
│ │ │ └── README.md
│ │ ├── domain/
│ │ │ ├── DoctorDaySchedule.java
│ │ │ ├── DoctorDaySlot.java
│ │ │ └── README.md
│ │ ├── entities/
│ │ │ ├── AbstractEntity.java
│ │ │ ├── Client.java
│ │ │ ├── Slot.java
│ │ │ ├── Doctor.java
│ │ │ ├── Person.java
│ │ │ ├── README.md
│ │ │ ├── Role.java
│ │ │ ├── Appointment.java
│ │ │ └── User.java
│ │ ├── business/
│ │ │ ├── Dates.java
│ │ │ ├── PersonData.java
│ │ │ ├── Business.java
│ │ │ ├── BusinessException.java
│ │ │ ├── BusinessService.java
│ │ │ └── README.md
│ │ ├── models/
│ │ │ ├── Forms.java
│ │ │ ├── ViewModels.java
│ │ │ ├── README.md
│ │ │ └── InputRules.java
│ │ ├── repositories/
│ │ │ ├── ClientRepository.java
│ │ │ ├── SlotRepository.java
│ │ │ ├── DoctorRepository.java
│ │ │ ├── PersonRepository.java
│ │ │ ├── README.md
│ │ │ ├── AppointmentRepository.java
│ │ │ └── UserRepository.java
│ │ ├── web/
│ │ │ ├── ApplicationModel.java
│ │ │ ├── CookieFlashMapManager.java
│ │ │ ├── Flash.java
│ │ │ ├── HtmlExceptionHandler.java
│ │ │ ├── FlashMessage.java
│ │ │ ├── CommonModel.java
│ │ │ ├── Utils.java
│ │ │ ├── README.md
│ │ │ ├── Translator.java
│ │ │ ├── FlashType.java
│ │ │ └── Validation.java
│ │ └── RdvMedecinsApplication.java
│ └── resources/
│ ├── i18n/
│ │ ├── en.json
│ │ └── fr.json
│ ├── static/
│ │ ├── css/
│ │ │ └── styles.css
│ │ ├── js/
│ │ │ └── app.js
│ │ └── lib/
│ │ └── bootstrap/
│ │ ├── css/
│ │ │ └── bootstrap.min.css
│ │ └── LICENSE
│ ├── templates/
│ │ ├── fragments/
│ │ │ ├── captcha.html
│ │ │ ├── person-fields.html
│ │ │ ├── confirmation.html
│ │ │ ├── errors.html
│ │ │ ├── flash.html
│ │ │ ├── navbar.html
│ │ │ └── booking.html
│ │ ├── persons/
│ │ │ ├── form.html
│ │ │ └── list.html
│ │ ├── schedule.html
│ │ ├── account.html
│ │ ├── error.html
│ │ ├── area.html
│ │ ├── registration.html
│ │ ├── layout.html
│ │ ├── login.html
│ │ └── README.md
│ ├── application-dev.properties
│ └── application.properties
├── mvnw
├── mvnw.cmd
├── pom.xml
└── README.md
|
Dies ist die Standardorganisation eines [Maven]-Projekts, wie in den Beispielen gesehen: der [Java]-Code in [src/main/java], gegliedert in Pakete (ein [Java]-Paket ist ein Ordner mit Klassen, dessen Name – hier zum Beispiel [rdvmedecins.web] – den Pfad widerspiegelt); alles andere (Konfiguration, Views, Wörterbücher, statische Dateien) in [src/main/resources]. Beim Kompilieren kopiert [Maven] den Inhalt von [src/main/resources] nach [target/classes], neben die kompilierten Klassen: Zusammen bilden diese den Klassenpfad (Classpath) der Anwendung – die Menge der Ordner und Archive, in denen die virtuelle Maschine nach Klassen und Dateien sucht. Deshalb verweist der Code auf ein Wörterbuch als [i18n/fr.json], ohne das Präfix [src/main/resources]. Der Ordner [target], der von [Maven] erstellt wird, ist nicht dargestellt.
Jeder wichtige Ordner enthält eine Datei namens [README.md], die seine Dateien auflistet. Die folgende Tabelle vergleicht die Ordner der beiden Versionen der Anwendung:
ASP.NET Core MVC | Spring MVC | Inhalt |
[Program.cs] | [RdvMedecinsApplication.java], [config/] | Start, Konfiguration |
[Config/] | [config/] | typisierte Eigenschaften |
[Auth/] | [auth/] | Authentifizierung |
[Controllers/] | [controllers/] | Controller |
[Web/], [Models/] | [web/], [models/] | Gemeinsame Services der Web-Schicht, Templates |
[Business/] | [business/] | Geschäftsschicht |
[Repositories/], [Data/] | [repositories/] | DAO-Schicht |
[Entities/], [Domain/] | [entities/], [domain/] | Entitäten, Kalenderelemente |
[Views/] | [templates/] | Views |
[i18n/] | [i18n/] | Wörterbücher |
[wwwroot/] | [static/] | statische Dateien |
[appsettings.json] | [application.properties] | Konfiguration |
[RdvMedecins.csproj] | [pom.xml] | Die Projektdatei |
Im Folgenden werden alle Dateien kommentiert, von den unteren Schichten (Datenbank) bis zu den oberen Schichten (Views).
11.5. Die Datenbank
Die Datenbank [dbrdvmedecins2] wird durch das Skript [database/dbrdvmedecins2.sql] erstellt (siehe „Die Datenbank erstellen“). Es ist wortgleich das Skript der Version [ASP.NET Core], dem lediglich eine Zeile mit [SET NAMES] vorangestellt ist: Beide Anwendungen können mit derselben Datenbank arbeiten, und die eine kann die andere ersetzen, ohne dass Änderungen nötig sind. Wir zeigen dies anhand zweier Auszüge: der Struktur, gefolgt von den Daten.
11.5.1. database/dbrdvmedecins2.sql
| -- =========================================================================
-- Datenbank [dbrdvmedecins2] - MySQL 8
--
-- Weiterentwicklung von [dbrdvmedecins]:
-- 1. die Tabellen [doctors] und [clients] erhalten eine Spalte [user],
-- Fremdschlüssel auf users(id): Jeder Arzt und jeder Client ist
-- nun auch ein Benutzer, der sich anmelden kann;
-- 2. eine dritte Rolle erscheint: DOCTOR (zusätzlich zu ADMIN und USER);
-- 3. das Skript erstellt eine Zeile in [users] für jeden Arzt (Rolle DOCTOR)
-- und für jeden Client (Rolle USER):
-- - login = Nachname in Kleinbuchstaben
-- - password = Nachname in Kleinbuchstaben, mit bcrypt gehasht (10 Runden)
-- - display name = Vorname + Nachname
--
-- 4. Eindeutigkeits-Constraints, alle BENANNT (die Anwendung erkennt
-- den Namen des verletzten Constraints in der MySQL-Fehlermeldung):
-- - unq_users_login : Ein Login gehört nur zu einem Konto;
-- - unq_doctors_first_name_last_name : Zwei Ärzte dürfen nicht denselben
-- Vor- und Nachnamen haben;
-- - unq_clients_first_name_last_name : dasselbe für die Clients.
-- Achtung: Die Kollation utf8mb4_unicode_ci vergleicht ohne Rücksicht auf
-- Groß-/Kleinschreibung und Akzente - "Hélène DUPONT" und "helene dupont"
-- gelten daher als identisch.
--
-- Die Tabelle [users] muss nun VOR [doctors] und [clients] erstellt werden
-- (diese referenzieren sie) und NACH ihnen gelöscht werden.
-- =========================================================================
-- das Skript ist in UTF-8 geschrieben
SET NAMES utf8mb4;
-- wir beginnen bei jeder Ausführung des Skripts mit einer leeren Datenbank (praktisch in der Entwicklung)
CREATE DATABASE IF NOT EXISTS dbrdvmedecins2 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbrdvmedecins2;
-- Reihenfolge beim Löschen: von den „Kind"-Tabellen zu den „Eltern"-Tabellen
DROP TABLE IF EXISTS appointments;
DROP TABLE IF EXISTS slots;
DROP TABLE IF EXISTS clients;
DROP TABLE IF EXISTS doctors;
DROP TABLE IF EXISTS users;
-- -------------------------------------------------------------------------
-- Tabelle [users]: die Benutzer, die sich an der Anwendung anmelden dürfen
-- -------------------------------------------------------------------------
CREATE TABLE users (
id INT AUTO_INCREMENT PRIMARY KEY,
version INT NOT NULL DEFAULT 0,
login VARCHAR(30) NOT NULL, -- login identifier
password VARCHAR(100) NOT NULL, -- HASHED password (bcrypt) - never in clear
name VARCHAR(40) NOT NULL, -- name displayed once logged in
role VARCHAR(10) NOT NULL, -- 'ADMIN', 'DOCTOR' or 'USER'
-- ein Login darf nur zu einem Konto gehören
CONSTRAINT unq_users_login UNIQUE (login)
);
-- -------------------------------------------------------------------------
-- Tabelle [doctors]: die Ärzte der Praxis
-- -------------------------------------------------------------------------
CREATE TABLE doctors (
id INT AUTO_INCREMENT PRIMARY KEY, -- primary key (technical identifier)
version INT NOT NULL DEFAULT 0, -- row version number (optimistic lock)
title VARCHAR(5) NOT NULL, -- Melle, Mme, Mr
last_name VARCHAR(20) NOT NULL,
first_name VARCHAR(20) NOT NULL,
`user` INT NOT NULL, -- foreign key -> users(id)
CONSTRAINT fk_doctors_user FOREIGN KEY (`user`) REFERENCES users(id),
-- ein Konto pro Arzt und ein Arzt pro Konto
CONSTRAINT unq_doctors_user UNIQUE (`user`),
-- zwei Ärzte dürfen nicht denselben Vor- und Nachnamen haben
CONSTRAINT unq_doctors_first_name_last_name UNIQUE (first_name, last_name)
);
-- -------------------------------------------------------------------------
-- Tabelle [clients]: die Patienten der Ärzte
-- -------------------------------------------------------------------------
CREATE TABLE clients (
id INT AUTO_INCREMENT PRIMARY KEY,
version INT NOT NULL DEFAULT 0,
title VARCHAR(5) NOT NULL,
last_name VARCHAR(20) NOT NULL,
first_name VARCHAR(20) NOT NULL,
`user` INT NOT NULL, -- foreign key -> users(id)
CONSTRAINT fk_clients_user FOREIGN KEY (`user`) REFERENCES users(id),
-- ein Konto pro Client und ein Client pro Konto
CONSTRAINT unq_clients_user UNIQUE (`user`),
-- zwei Clients dürfen nicht denselben Vor- und Nachnamen haben
CONSTRAINT unq_clients_first_name_last_name UNIQUE (first_name, last_name)
);
-- -------------------------------------------------------------------------
-- Tabelle [slots]: die Zeitfenster jedes Arztes
-- -------------------------------------------------------------------------
CREATE TABLE slots (
id INT AUTO_INCREMENT PRIMARY KEY,
version INT NOT NULL DEFAULT 0,
doctor_id INT NOT NULL, -- foreign key -> doctors(id)
start_hour INT NOT NULL, -- start hour of the slot
start_minute INT NOT NULL, -- start minute of the slot
end_hour INT NOT NULL, -- end hour of the slot
end_minute INT NOT NULL, -- end minute of the slot
CONSTRAINT fk_slots_doctor FOREIGN KEY (doctor_id) REFERENCES doctors(id)
);
-- -------------------------------------------------------------------------
-- Tabelle [appointments]: die von den Clients gebuchten Termine
-- -------------------------------------------------------------------------
CREATE TABLE appointments (
id INT AUTO_INCREMENT PRIMARY KEY,
version INT NOT NULL DEFAULT 0,
day DATE NOT NULL, -- day of the appointment
slot_id INT NOT NULL, -- foreign key -> slots(id)
client_id INT NOT NULL, -- foreign key -> clients(id)
CONSTRAINT fk_appointments_slot FOREIGN KEY (slot_id) REFERENCES slots(id),
CONSTRAINT fk_appointments_client FOREIGN KEY (client_id) REFERENCES clients(id),
-- dasselbe Zeitfenster am selben Tag kann nur einmal gebucht werden
CONSTRAINT unq1_appointments UNIQUE (day, slot_id)
);
|
Kommentieren wir diesen ersten Teil:
- Zeile 30: Das Skript teilt dem Server mit, dass es in UTF-8 geschrieben ist. Ohne diese Zeile würde der [mysql]-Client auf manchen Systemen akzentuierte Zeichen („Hélène“) in einer anderen Kodierung senden, und sie würden falsch gespeichert;
- Zeile 33: Die Datenbank wird erstellt, falls sie noch nicht existiert, mit dem Zeichensatz [utf8mb4] und der Kollation [utf8mb4_unicode_ci], wie in Beispiel 28: Zeichenkettenvergleiche ignorieren Groß-/Kleinschreibung und Akzente. Das gilt auch für Eindeutigkeitsbedingungen: [Hélène DUPONT] und [helene dupont] sind für [MySQL] dieselbe Person, und „Admin“ ist dasselbe Login wie „admin“;
- Zeilen 37–41: Das Skript beginnt bei jeder Ausführung mit einer leeren Datenbank. Die Tabellen werden von den „Kind“-Tabellen zu den „Eltern“-Tabellen gelöscht: Eine Tabelle, die von einem Fremdschlüssel referenziert wird ([users] zum Beispiel, referenziert von [doctors] und [clients]), kann nicht gelöscht werden, solange eine andere Tabelle sie noch referenziert. Die Tabellen werden in umgekehrter Reihenfolge erstellt;
- Zeilen 46–55: die Benutzerkonten. Jede Tabelle beginnt mit einem Primärschlüssel [id], der von der Datenbank vergeben wird ([AUTO_INCREMENT]), und einer Spalte [version], die beim Anlegen der Zeile auf 0 gesetzt wird;
- Zeilen 49–52: das Login, das Passwort, der nach der Anmeldung angezeigte Name und die Rolle ([ADMIN], [DOCTOR], oder [USER]). Die Spalte [password] enthält nie das Passwort selbst, sondern seinen Hash, [bcrypt] (siehe Beispiel 25): 60 Zeichen, die in der Spalte (100 Zeichen) problemlos Platz finden;
- Zeile 54: Ein Login gehört nur zu einem Konto. Wie in Beispiel 28 ist die Bedingung benannt: Wenn [MySQL] einen Schreibvorgang ablehnt, nennt seine Fehlermeldung den Namen der verletzten Bedingung, und die Geschäftsschicht wählt daran die anzuzeigende Meldung aus (siehe „Die Geschäftsschicht“);
- Zeilen 60–72: die Ärzte: Titel, Nachname, Vorname;
- Zeile 62: Die Spalte [version] dient der optimistischen Sperre (siehe Beispiel 28): Sie wird bei jeder Änderung der Zeile erhöht, wodurch erkannt werden kann, ob ein anderer Benutzer die Zeile zwischen dem Lesen und dem Schreiben geändert hat. Hier ist es [Hibernate], das sie erhöht, dank der Annotation [@Version] der Entitäten (siehe „Entitäten“);
- Zeilen 66–67: Jeder Arzt hat ein Konto: Die Spalte [user] ist ein Fremdschlüssel, der auf [users(id)] verweist. Die Datenbank lehnt einen Wert ab, der auf kein Konto verweist, und weigert sich, ein Konto zu löschen, das noch von einem Arzt referenziert wird. Da [user] in [MySQL] ein reserviertes Wort ist, steht der Spaltenname in Backticks;
- Zeile 69: Ein Konto gehört nur zu einem Arzt: Die Beziehung zwischen [doctors] und [users] ist eine „Eins-zu-eins“-Beziehung;
- Zeile 71: Zwei Ärzte dürfen nicht denselben Vor- und Nachnamen haben. Die Bedingung gilt für das Spaltenpaar: Zwei Ärzte können denselben Nachnamen haben, wenn sie nicht denselben Vornamen haben. Ein Arzt und ein Klient können dagegen denselben Nachnamen haben: Es sind zwei verschiedene Tabellen;
- Zeilen 77–89: Die Klienten (Patienten) folgen demselben Modell: ein Konto pro Klient (Fremdschlüssel [fk_clients_user], Eindeutigkeitsbedingung [unq_clients_user]); keine zwei Klienten dürfen denselben Vor- und Nachnamen haben;
- Zeilen 94–103: die Zeitfenster jedes Arztes (Fremdschlüssel [doctor_id]): Beginn in Stunde und Minute, Ende in Stunde und Minute. Ein Zeitfenster hat kein Datum: Es wiederholt sich jeden Tag;
- Zeilen 108–118: die Termine: ein Datum (Typ [DATE], ohne Uhrzeit), ein Zeitfenster und ein Klient, identifiziert durch zwei Fremdschlüssel;
- Zeile 117: Dasselbe Zeitfenster kann pro Tag nur einmal gebucht werden. Die Datenbank selbst erzwingt diese Regel: Wenn zwei Benutzer gleichzeitig dasselbe Zeitfenster buchen, wird das zweite [INSERT] abgelehnt, unabhängig davon, was die Anwendung unmittelbar zuvor geprüft hat.
Der zweite Teil des Skripts fügt die Beispieldaten ein:
| -- =========================================================================
-- Demodaten
-- =========================================================================
-- die Benutzer: Passwörter mit bcrypt gehasht (10 Salt-Runden)
-- admin/admin (ADMIN)
-- ein DOCTOR-Konto pro Arzt, ein USER-Konto pro Client
-- (das Demokonto user/user gibt es nicht mehr: Ein USER-Konto ist
-- nun IMMER das Konto eines Clients, der buchen und das Konto verwalten kann)
-- (login = password = Nachname in Kleinbuchstaben)
INSERT INTO users (login, password, name, role) VALUES
('admin', '$2b$10$YSNBJXXHX9mp13nPZb6YGu8M1jR6uvPwO1s2X73z0QAqBR7TOQjoq', 'Administrator', 'ADMIN'),
-- doctors
('pelissier', '$2b$10$DnSDOK5ONrdMxTTr1NKCHOphR3WSp5QAyG9S9ueruw9HwlxI.16ba', 'Marie PELISSIER', 'DOCTOR'),
('tatou', '$2b$10$PeovBO.gmJUKP4PglI/fwu4xtWOYSxoM5VTWjTj7uQ4wcd9P9.htS', 'Paul TATOU', 'DOCTOR'),
('dupont', '$2b$10$az7wvPKC1h0EiAxXwu/PU.vYjzmB04rd5B7QnK0mvxp4niYIHVoc.', 'Sophie DUPONT', 'DOCTOR'),
-- clients
('martin', '$2b$10$GT6S5pp.WdGapFw/UmocXesbC6LEjJfZzgatCUyG9Sf4o1iBNlqZW', 'Jean MARTIN', 'USER'),
('durand', '$2b$10$l2gl/zCder8E7Nh4VxGRX.0.SsO3FDiXt6YwqYq3v9nFzgC/jQCy6', 'Alice DURAND', 'USER'),
('bistrou', '$2b$10$naeRp2YUU6c.QDl5itJMAum3Y5aHdUV6jwIcsbp0D.64jPG4F6E9m', 'Brigitte BISTROU', 'USER'),
('german', '$2b$10$tTWxh3ROWF7NjhZOMnWDMOsZcnSWUiwwfy5C3G0.xhccTXALKyLeW', 'Luc GERMAN', 'USER');
-- die Ärzte: Die Spalte [user] wird anhand des Logins nachgeschlagen,
-- statt die Werte der Primärschlüssel von [users] vorauszusetzen
INSERT INTO doctors (title, last_name, first_name, `user`) VALUES
('Mme', 'PELISSIER', 'Marie', (SELECT id FROM users WHERE login = 'pelissier')),
('Mr', 'TATOU', 'Paul', (SELECT id FROM users WHERE login = 'tatou')),
('Melle','DUPONT', 'Sophie', (SELECT id FROM users WHERE login = 'dupont'));
INSERT INTO clients (title, last_name, first_name, `user`) VALUES
('Mr', 'MARTIN', 'Jean', (SELECT id FROM users WHERE login = 'martin')),
('Mme', 'DURAND', 'Alice', (SELECT id FROM users WHERE login = 'durand')),
('Melle','BISTROU', 'Brigitte', (SELECT id FROM users WHERE login = 'bistrou')),
('Mr', 'GERMAN', 'Luc', (SELECT id FROM users WHERE login = 'german'));
-- Zeitfenster von Arzt PELISSIER (doctor_id = 1): von 8:00 bis 12:00 Uhr in 20-Minuten-Schritten
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
(1, 8, 0, 8, 20), (1, 8, 20, 8, 40), (1, 8, 40, 9, 0),
(1, 9, 0, 9, 20), (1, 9, 20, 9, 40), (1, 9, 40, 10, 0),
(1, 10, 0, 10, 20), (1, 10, 20, 10, 40), (1, 10, 40, 11, 0),
(1, 11, 0, 11, 20), (1, 11, 20, 11, 40), (1, 11, 40, 12, 0);
-- Zeitfenster von Arzt TATOU (doctor_id = 2): von 14:00 bis 18:00 Uhr in 20-Minuten-Schritten
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
(2, 14, 0, 14, 20), (2, 14, 20, 14, 40), (2, 14, 40, 15, 0),
(2, 15, 0, 15, 20), (2, 15, 20, 15, 40), (2, 15, 40, 16, 0),
(2, 16, 0, 16, 20), (2, 16, 20, 16, 40), (2, 16, 40, 17, 0),
(2, 17, 0, 17, 20), (2, 17, 20, 17, 40), (2, 17, 40, 18, 0);
-- ein bereits gebuchter Termin, um ein belegtes Zeitfenster sofort im Terminkalender zu sehen
INSERT INTO appointments (day, slot_id, client_id) VALUES
(CURDATE(), 2, 3);
|
- Zeilen 5–21: die Demo-Konten: der Administrator, drei Ärzte (Rolle [DOCTOR]) und vier Klienten (Rolle [USER]). Das Passwort jedes Benutzers ist sein Login ([admin] / [admin], [pelissier] / [pelissier] ...). Die Hashes beginnen mit [$2b$10$]: dem Algorithmus [bcrypt] in seiner Version [2b] mit einem Kostenfaktor von 10 (siehe Beispiel 25). Der Encoder [BCryptPasswordEncoder] von [Spring Security], der für genau diese Version konfiguriert ist, kann sie überprüfen (siehe „Authentifizierung“);
- Zeilen 25–28: Die Spalte [user] jedes Arztes wird über eine Unterabfrage auf das Login ermittelt, statt die den Konten von der Datenbank zugewiesenen Kennungen vorauszusetzen;
- Zeilen 30–34: Die Klienten werden auf die gleiche Weise behandelt;
- Zeilen 36–41: zwölf 20-Minuten-Zeitfenster von 8:00 bis 12:00 Uhr für Dr. PELISSIER. Hier ist die ID des Arztes (1) fest im Code verankert: Die Tabelle [doctors] wurde gerade erst erstellt, ihre IDs beginnen also bei 1;
- Zeilen 43–48: zwölf Zeitfenster von 14:00 bis 18:00 Uhr für Dr. TATOU. Dr. DUPONT hat keine Zeitfenster: Sein Terminkalender ist leer;
- Zeilen 50–52: Für Brigitte BISTROU (Klient Nr. 3) ist bereits ein Termin im zweiten Zeitfenster von Dr. PELISSIER (8:20 Uhr) eingetragen. [CURDATE()] ist das Datum der Ausführung des Skripts: Bei der ersten Anmeldung zeigt der Kalender des heutigen Tages ein bereits gebuchtes Zeitfenster.
11.6. Projektkonfiguration
11.6.1. pom.xml
Die Datei [pom.xml] ([Project Object Model]) beschreibt das Projekt in [Maven]: seine Kennung, die [Java]-Version, die verwendeten Bibliotheken und die Art, die Anwendung zu starten. Sie entspricht der Datei [RdvMedecins.csproj] der Version [ASP.NET Core]. Die Beispiele hatten jeweils eine [pom.xml]-Datei, die alle von einer gemeinsamen [pom.xml]-Datei abgeleitet waren, die im Ordner [examples] liegt; die Fallstudie, ein eigenständiges Projekt, schreibt alles in ihre eigene Datei.
| <?xml version="1.0" encoding="UTF-8"?>
<!--
=========================================================================
pom.xml - die Maven-Projektdatei: Identität des Projekts, Java-Version,
verwendete Bibliotheken und Plugin, das die Anwendung kompiliert und ausführt.
Die Bibliotheken (Abhängigkeiten) werden beim ersten Build
von Maven Central heruntergeladen und im Ordner ~/.m2 des
Benutzers gespeichert. Ihre Versionen stehen hier nicht: Sie werden,
alle miteinander kompatibel, vom Spring-Boot-Parent-Projekt festgelegt.
=========================================================================
-->
<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>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>4.1.1</version>
<relativePath/>
</parent>
<groupId>course.springmvc</groupId>
<artifactId>rdvmedecins</artifactId>
<version>1.0</version>
<name>RdvMedecins</name>
<properties>
<!-- Java 21, LTS-Version (Long-Term Support) -->
<java.version>21</java.version>
</properties>
<dependencies>
<!-- Spring MVC und der Tomcat-Webserver, in die Anwendung eingebettet -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>
<!-- die Thymeleaf-Views -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>
<!-- Formularvalidierung (Bean Validation, Hibernate Validator) -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>
<!-- Spring Security: Authentifizierung per JWT-Token, Rollen, bcrypt-Hashing -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security-oauth2-resource-server</artifactId>
</dependency>
<!-- Spring Data JPA: das ORM Hibernate, Transaktionen, Repositories -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<!-- der MySQL-JDBC-Treiber (er passt auch zu MariaDB) -->
<dependency>
<groupId>com.mysql</groupId>
<artifactId>mysql-connector-j</artifactId>
<scope>runtime</scope>
</dependency>
<!-- die Entwicklungswerkzeuge: automatischer Neustart nach einer Änderung -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-devtools</artifactId>
<optional>true</optional>
</dependency>
</dependencies>
<build>
<plugins>
<!-- mvnw spring-boot:run führt die Anwendung mit dem Profil [dev] aus
(siehe src/main/resources/application-dev.properties) -->
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<profiles>
<profile>dev</profile>
</profiles>
</configuration>
</plugin>
</plugins>
</build>
</project>
|
Kommentieren wir diese Datei:
- Zeilen 18–23: das übergeordnete Projekt [spring-boot-starter-parent] in Version 4.1.1 von [Spring Boot]. Das Projekt erbt seine Einstellungen: die UTF-8-Kodierung der Quelldateien, die Compiler-Konfiguration, die Plugin-Konfiguration und vor allem die Versionen aller Bibliotheken, die [Spring Boot] integrieren kann – ausgewählt, damit sie miteinander kompatibel sind. Deshalb gibt keine der unten aufgeführten Abhängigkeiten eine Version an. Um auf eine neuere Version von [Spring Boot] zu wechseln, müssen Sie nur Zeile 21 ändern;
- Zeile 22: Das leere Element [relativePath] weist [Maven] an, das übergeordnete Projekt nicht im übergeordneten Ordner des Projekts zu suchen (dort befand sich das Parent der Beispiele), sondern in den Bibliotheks-Repositories;
- Zeilen 25–28: die Identität des Projekts: die Gruppe (per Konvention ein umgekehrter Domänenname), der Name des Artefakts, seine Version und ein menschenlesbarer Name. Das von [./mvnw package] erstellte Archiv heißt [artifact-version.jar] bzw. [rdvmedecins-1.0.jar]. Da kein Element [packaging] angegeben ist, handelt es sich um ein [jar]-Archiv, was der Standardfall ist;
- Zeilen 30–33: die [Java]-Version: Der Compiler erzeugt Code für [Java] 21 und weigert sich, mit einem älteren JDK zu kompilieren;
- Zeilen 35–73: die Abhängigkeiten. Fast alle sind Starter für [Spring Boot]: Ein Starter ist eine Abhängigkeit, die selbst keinen Code liefert, sondern einen zusammenhängenden Satz von Bibliotheken für eine bestimmte Funktion einbindet. Jeder Starter löst beim Start außerdem die entsprechende Autokonfiguration aus (siehe „Start der Anwendung“);
- Zeilen 37–40: [Spring MVC] und der in die Anwendung integrierte [Tomcat]-Webserver: Es muss kein Server installiert werden; die Anwendung selbst ist ein Webserver;
- Zeilen 42–45: die View-Engine [Thymeleaf] (siehe Beispiel 13);
- Zeilen 47–50: Formularvalidierung: die API [Bean Validation] ([@NotBlank], [@Size] ...) und ihre Implementierung, [Hibernate Validator] (siehe Beispiel 19);
- Zeilen 52–55: [Spring Security] mit seinem Modul „Resource Server“ [OAuth2], das ein JWT-Token überprüfen kann (siehe Beispiel 25). Es liefert außerdem den Hash [bcrypt] für Passwörter: keine separate Bibliothek;
- Zeilen 57–60: [Spring Data JPA] samt dem ORM [Hibernate], dem Transaktionsmanager und dem Connection-Pool [HikariCP] (siehe Beispiel 28);
- Zeilen 62–66: der JDBC-Treiber für [MySQL] und [mysql-connector-j], der auch für [MariaDB] geeignet ist. Der Scope [runtime] (Zeile 65) bedeutet, dass der Anwendungscode ihn zum Kompilieren nicht benötigt (er kommuniziert nur mit JPA und JDBC); der Treiber wird erst zur Laufzeit geladen;
- Zeilen 68–72: [Spring Boot DevTools], die Entwicklungswerkzeuge (automatischer Neustart). [optional] (Zeile 71): Die Abhängigkeit wird nicht an Projekte weitergegeben, die von ihr abhängen würden, und das [Spring Boot]-Plugin nimmt sie nicht in das ausführbare Archiv auf: Sie wird nur während der Entwicklung verwendet;
- Zeilen 79–87: das [Spring Boot]-Plugin für [Maven]. Dieses Plugin stellt den Befehl [spring-boot:run] bereit und wandelt bei einem Lauf von [./mvnw package] das standardmäßige [jar]-Archiv in ein ausführbares Archiv um, das alle Bibliotheken enthält;
- Zeilen 82–86: [spring-boot:run] aktiviert das Profil [dev], das die Datei [application-dev.properties] zur Konfiguration hinzufügt (siehe unten). Ein Profil ist ein Name, der eine Gruppe von Einstellungen bezeichnet; dieses gilt nur für [spring-boot:run]: Eine mit [java -jar] gestartete Anwendung hat kein aktives Profil, sofern keines angegeben wird ([java -jar target/rdvmedecins-1.0.jar --spring.profiles.active=dev]).
11.6.2. Der Maven Wrapper
Der Maven Wrapper ermöglicht es, das Projekt zu erstellen, ohne [Maven] installiert zu haben. Er besteht aus drei Dateien:
- [mvnw] (für [Linux] und [macOS]) und [mvnw.cmd] (für [Windows]): zwei Skripte, die vom Projekt [Apache Maven] bereitgestellt werden, nicht verändert werden sollten und hier nicht wiedergegeben sind. Sie lesen die folgende Datei, laden die darin angegebene Version von [Maven] herunter, falls sie noch nicht vorhanden ist, legen sie im Ordner [.m2/wrapper] im Home-Verzeichnis des Benutzers ab und führen dann den folgenden Befehl aus: [./mvnw spring-boot:run] führt [mvn spring-boot:run] mit der richtigen Version von [Maven] aus;
- [.mvn/wrapper/maven-wrapper.properties]:
| wrapperVersion=3.3.4
distributionType=only-script
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.11/apache-maven-3.9.11-bin.zip
|
- Zeile 1: die Version des Maven Wrappers selbst;
- Zeile 2: [only-script]: Der Wrapper besteht ausschließlich aus den Skripten [mvnw] und [mvnw.cmd], ohne das Archiv [maven-wrapper.jar], das seine früheren Versionen verwendeten;
- Zeile 3: der Download-Link für die [Maven]-Distribution: Version 3.9.11. Alle, die das Projekt bauen, verwenden somit dieselbe Version von [Maven], unabhängig davon, welche Version auf ihrem Rechner installiert sein mag.
Die von [Maven] heruntergeladenen Bibliotheken werden im Ordner [.m2/repository] im Home-Verzeichnis gespeichert: Sie werden von allen Projekten gemeinsam genutzt und nur einmal heruntergeladen.
11.6.3. src/main/resources/application.properties
Die Datei [application.properties] erfüllt denselben Zweck wie die Datei [appsettings.json] in der Version [ASP.NET Core]. Jede Zeile ordnet einem Schlüssel einen Wert zu; die Schlüsselteile werden durch Punkte getrennt ([spring.datasource.url]). [Spring Boot] enthält Hunderte von Schlüsseln, die seine Komponenten konfigurieren (die mit [server.], [spring.] usw. beginnenden); die Anwendung kann eigene hinzufügen (hier die mit [rdvmedecins.] beginnenden). Eine Zeile, die mit [#] beginnt, ist ein Kommentar.
| # =========================================================================
# application.properties - die Konfiguration der Anwendung.
#
# Jeder Wert kann ersetzt werden, ohne diese Datei zu ändern, durch eine
# Umgebungsvariable: spring.datasource.password wird dann als
# SPRING_DATASOURCE_PASSWORD geschrieben (Großbuchstaben, "." und "-" durch "_" ersetzt).
# =========================================================================
# der Listening-Port: weder 8080 (Standardport von Spring Boot, oft schon
# belegt) noch 5000 (der der Beispiele) - so kann alles gleichzeitig laufen
server.port=8081
# ---- die MySQL-Datenbank [dbrdvmedecins2] (Skript: database/dbrdvmedecins2.sql)
spring.datasource.url=jdbc:mysql://localhost:3306/dbrdvmedecins2
spring.datasource.username=root
spring.datasource.password=
# Hibernate erstellt oder ändert die Tabellen nicht: das ist die Aufgabe des SQL-Skripts
spring.jpa.hibernate.ddl-auto=none
# die Datenbankverbindung bleibt nicht geöffnet, während die View aufgebaut wird
spring.jpa.open-in-view=false
# ---- die Anfragen werden von "virtuellen" Threads verarbeitet (Java 21): ein
# Thread, der auf die Datenbank wartet, blockiert keinen Systemthread mehr
spring.threads.virtual.enabled=true
# ---- die Fehlerantworten enthalten niemals den Stack Trace
spring.web.error.include-stacktrace=never
# ---- Authentifizierung (siehe config/AuthProperties.java)
# geheimer Schlüssel der JWT-Token: mindestens 32 Zeichen (HMAC-SHA256).
# Muss in der Produktion unbedingt geändert werden (lange Zufallszeichenfolge).
rdvmedecins.auth.jwt-secret=change-me-to-a-long-random-string
# Gültigkeitsdauer eines Tokens, in Sekunden (7200 s = 2 h); das Cookie, das
# das Token trägt, hat dieselbe Lebensdauer
rdvmedecins.auth.jwt-expires-in-seconds=7200
# true in der Produktion (über HTTPS bereitgestellte Website): das Authentifizierungs-Cookie
# wird dann niemals über eine unverschlüsselte Verbindung gesendet
rdvmedecins.auth.cookie-secure=false
# ---- Schutz vor Robotern (siehe config/ProtectionProperties.java)
# Login: erlaubte Fehlschläge für denselben Login von derselben IP-Adresse ...
rdvmedecins.protection.login-max-failures=5
# ... vor einer Sperre dieser Dauer (die gesamte IP-Adresse wird ebenfalls gesperrt,
# wenn sie 5-mal mehr Fehlschläge ansammelt, alle Logins zusammen)
rdvmedecins.protection.login-block-minutes=15
# Erstellung von Client-Konten: maximal pro Stunde und pro IP-Adresse erstellte Konten.
# In einem Schulungsraum gehen oft alle Rechner über dieselbe Adresse nach draußen:
# bei Bedarf erhöhen.
rdvmedecins.protection.registration-max-per-hour=10
|
Kommentieren wir diese Datei:
- Zeile 11: der Port, auf dem der Server [Tomcat] lauscht. Der Standardport von [Spring Boot] ist 8080; die Beispiele lauschten auf Port 5000; die Anwendung lauscht auf Port 8081, wie die Version [ASP.NET Core];
- Zeile 14: Die Adresse der Datenbank in Form einer JDBC-URL (siehe Beispiel 28): das Protokoll [jdbc:mysql], gefolgt von Server, Port und Name der Datenbank. [Spring Boot] bestimmt daran, welcher Treiber geladen wird;
- Zeilen 15–16: Benutzername und Passwort für [MySQL]; die Standardwerte von [Laragon] sind [root] ohne Passwort. In Zeile 16 ist das Passwort einzutragen, falls das Konto [root] eines hat;
- Zeile 18: [Hibernate] kann Tabellen anhand der Entitäten selbst erstellen oder ändern; hier ändert es sie nicht: Die Datenbankstruktur ist die des SQL-Skripts, das mit der Version [ASP.NET Core] geteilt wird;
- Zeile 20: Standardmäßig hält [Spring Boot] die Datenbankverbindung bis zum Ende der Anfrage offen, auch während die View generiert wird (der Modus „Open in View“), und weist beim Start mit einer Warnung auf diese Wahl hin. Die Anwendung deaktiviert dieses Verhalten, wie in Beispiel 28 gezeigt: Alle Daten, die eine View benötigt, werden von der Geschäftsschicht innerhalb ihrer Transaktion gelesen, bevor die View gerendert wird. So bleibt eine Verbindung nie länger offen als nötig;
- Zeile 24: Anfragen werden von virtuellen Threads verarbeitet, einer Neuerung in [Java] 21. Ein Webserver verarbeitet jede Anfrage in einem Thread (einem Ausführungs-Thread); ein System-Thread ist eine teure Ressource, und [Tomcat] hält nur eine begrenzte Anzahl davon vor (standardmäßig 200). Ein Thread, der auf die Antwort der Datenbank wartet, tut jedoch nichts, bleibt aber belegt. Ein virtueller Thread ist ein leichtgewichtiger, von der virtuellen Maschine verwalteter Thread: Während er wartet, führt der System-Thread, der ihn beherbergte, einen anderen Thread aus. Der Anwendungscode muss nicht geändert werden, um davon zu profitieren;
- Zeile 27: Fehlerantworten enthalten nie den Aufrufstapel, der einem Angreifer das Innenleben der Anwendung offenbaren würde (siehe Kapitel 1);
- Zeilen 32–38: die Authentifizierungsschlüssel: der geheime Schlüssel, der die Tokens signiert (mindestens 32 Zeichen; in der Produktion durch eine lange Zufallszeichenfolge zu ersetzen), die Lebensdauer des Tokens (zwei Stunden) und die Option [Secure] im Cookie, das es trägt. In der Produktion wird die Site über HTTPS ausgeliefert, und das Cookie darf nie über eine unverschlüsselte Verbindung übertragen werden: Die Option ist auf [true] gesetzt;
- Zeilen 42–49: die Schwellenwerte für den Bot-Schutz (siehe Beispiel 27): die Anzahl der erlaubten fehlgeschlagenen Anmeldeversuche und die Dauer der daraus folgenden Sperre; die Anzahl der Klientenkonten, die pro Stunde von derselben IP-Adresse erstellt werden dürfen.
Die Schlüssel [rdvmedecins.auth.*] und [rdvmedecins.protection.*] werden als typisierte Records gelesen (siehe [config/AuthProperties.java], weiter unten). In der Datei werden zusammengesetzte Namen in Kleinbuchstaben geschrieben und durch Bindestriche getrennt ([jwt-secret]): Das ist die Konvention von [Spring Boot], das sie auf die Namen in [Java] ([jwtSecret]) abbildet.
[Spring Boot] liest die Konfiguration aus mehreren aufeinanderfolgenden Quellen, von denen jede die Werte der vorherigen überschreiben kann: [application.properties], dann [application-{profile}.properties] für jedes aktive Profil (siehe die folgende Datei), dann die Umgebungsvariablen und schließlich die Befehlszeilenargumente ([--server.port=9000]). Der Name einer Umgebungsvariablen wird vom Schlüssel abgeleitet: Großbuchstaben, wobei [.] und [-] durch [_] ersetzt werden. [spring.datasource.password] wird somit zu [SPRING_DATASOURCE_PASSWORD], und [rdvmedecins.auth.jwt-secret] wird zu [RDVMEDECINS_AUTH_JWT_SECRET]: So übergeben Sie der Anwendung in der Produktion ein Geheimnis, ohne es in eine Projektdatei zu schreiben.
11.6.4. src/main/resources/application-dev.properties
| # =========================================================================
# application-dev.properties - ergänzt application.properties, wenn das
# Profil [dev] aktiv ist (mvnw spring-boot:run aktiviert es, siehe pom.xml):
# die von Hibernate gesendeten SQL-Anweisungen werden in der Konsole angezeigt.
# =========================================================================
spring.jpa.show-sql=true
|
- Zeile 6: Wenn das Profil [dev] aktiv ist, liest [Spring Boot] die Datei [application-dev.properties] nach [application.properties] und führt die beiden zusammen: Die in der zweiten Datei vorhandenen Schlüssel ersetzen die der ersten; die übrigen bleiben erhalten. Während der Entwicklung wird daher der Schlüssel [spring.jpa.show-sql] hinzugefügt: [Hibernate] schreibt jeden SQL-Befehl, den es an die Datenbank sendet, in die Konsole, mit dem Präfix [Hibernate:]. Das entspricht der Datei [appsettings.Development.json] in der Version [ASP.NET Core], wobei das Profil die Rolle der Umgebung [Development] übernimmt. Wir haben gesehen, dass es [pom.xml] ist, die dieses Profil für [spring-boot:run] aktiviert.
11.6.5. config/AuthProperties.java
| // =========================================================================
// config/AuthProperties.java
// -------------------------------------------------------------------------
// Die [rdvmedecins.auth.*]-Properties aus application.properties, als
// typisierter Record. Spring Boot ordnet die Namen zu:
// rdvmedecins.auth.jwt-secret -> jwtSecret
// rdvmedecins.auth.jwt-expires-in-seconds -> jwtExpiresInSeconds
// rdvmedecins.auth.cookie-secure -> cookieSecure
// und konvertiert die Werte in den Typ der Komponenten (int, boolean).
// Eine Klasse, die ihn benötigt, erhält diesen Record per Dependency Injection:
// so vermeiden wir, überall Zeichenketten zu lesen.
// =========================================================================
package rdvmedecins.config;
import org.springframework.boot.context.properties.ConfigurationProperties;
@ConfigurationProperties("rdvmedecins.auth")
public record AuthProperties(
// geheimer Schlüssel zum Signieren / Prüfen der JWT-Token. Der Algorithmus HMAC-SHA256
// verlangt einen Schlüssel von mindestens 256 Bit, also 32 Byte.
String jwtSecret,
// Gültigkeitsdauer eines Tokens, in Sekunden; das Cookie, das es trägt,
// hat dieselbe Lebensdauer
int jwtExpiresInSeconds,
// true in der Produktion (HTTPS): das Authentifizierungs-Cookie wird niemals
// über eine unverschlüsselte Verbindung gesendet
boolean cookieSecure) {
}
|
Kommentieren wir diesen Code:
- Zeile 18: die Schlüssel [rdvmedecins.auth.*] aus [application.properties] in Form eines Records: einer Klasse, deren Felder – in Klammern deklariert (die „Komponenten“ des Records) – vom Konstruktor ein für alle Mal gesetzt werden. Der Compiler erzeugt diesen Konstruktor selbst, zusammen mit einer Getter-Methode für jede Komponente, mit demselben Namen: [jwtSecret()], [jwtExpiresInSeconds()], [cookieSecure()];
- Zeile 17: Die Annotation [@ConfigurationProperties] legt das Schlüsselpräfix fest. Beim Start erzeugt [Spring Boot] den Record, indem es seinen Konstruktor mit den Werten der Schlüssel [rdvmedecins.auth.jwt-secret], [rdvmedecins.auth.jwt-expires-in-seconds] und [rdvmedecins.auth.cookie-secure] aufruft, umgewandelt in den Typ der jeweiligen Komponente (["7200"] wird zur Ganzzahl 7200, [false] wird zum booleschen Wert [false]). Ein Wert, der nicht umgewandelt werden kann (Text, wo eine Zahl erwartet wird), lässt die Anwendung beim Start abstürzen, mit einer Meldung, die den fehlerhaften Schlüssel nennt. Ein fehlender Schlüssel ergibt den Standardwert des Typs: [null], 0 oder [false];
- Zeilen 21–27: die drei Komponenten. Der Record wird zu einem Bean, das eine Klasse, die es benötigt, über ihren Konstruktor erhält (Dependency Injection; siehe Beispiel 06): Das ist es, was [config/SecurityConfig.java] und [auth/AuthService.java] tun (siehe „Authentifizierung“). So muss man nicht überall Zeichenketten lesen: Die Namen werden vom Compiler geprüft, und die Werte sind bereits umgewandelt.
Dies ist die Technik aus Beispiel 25, in dem der Record mit der Annotation [@EnableConfigurationProperties(JwtProperties.class)] deklariert wurde. Die Fallstudie hat zwei davon und lässt sie von [Spring Boot] selbst finden, dank der Annotation [@ConfigurationPropertiesScan] an der Hauptklasse (siehe „Start der Anwendung“).
11.6.6. config/ProtectionProperties.java
| // =========================================================================
// config/ProtectionProperties.java
// -------------------------------------------------------------------------
// Die [rdvmedecins.protection.*]-Properties: die Schwellenwerte des Schutzes
// vor Robotern (siehe auth/AttemptLimiterService.java).
// =========================================================================
package rdvmedecins.config;
import org.springframework.boot.context.properties.ConfigurationProperties;
@ConfigurationProperties("rdvmedecins.protection")
public record ProtectionProperties(
// Login: Anzahl der Fehlschläge (falsches Captcha oder Passwort), die
// für denselben Login von derselben IP-Adresse erlaubt sind, bevor dieses Paar gesperrt wird ...
int loginMaxFailures,
// ... für diese Dauer (eine IP-Adresse wird ebenfalls gesperrt, wenn sie
// 5-mal mehr Fehlschläge ansammelt, alle Logins zusammen)
int loginBlockMinutes,
// Erstellung von Client-Konten: maximale Anzahl der Konten, die pro Stunde
// von derselben IP-Adresse erstellt werden
int registrationMaxPerHour) {
}
|
- Zeilen 11–21: die Schlüssel [rdvmedecins.protection.*], nach demselben Muster. Der Record wird in [auth/AttemptLimiterService.java] injiziert, der seine Schwellenwerte von dort bezieht (siehe „Authentifizierung“).
11.7. Start der Anwendung
Die Version [ASP.NET Core] hatte alle Startfunktionen in [Program.cs] zusammengefasst: die Registrierung jedes Services und anschließend den Aufbau der Middleware-Pipeline in einer bestimmten Reihenfolge. Bei [Spring Boot] ist diese Arbeit verteilt: Die Hauptklasse startet lediglich [Spring Boot], das seinerseits das Wesentliche selbst konfiguriert, und zwar anhand der verfügbaren Bibliotheken und der Datei [application.properties]; jeder Aspekt, den die Anwendung anders konfigurieren möchte, hat eine eigene Konfigurationsklasse im Ordner [config].
11.7.1. RdvMedecinsApplication.java
| // =========================================================================
// RdvMedecinsApplication.java
// -------------------------------------------------------------------------
// Der Einstiegspunkt der Anwendung: die main-Methode startet Spring Boot.
//
// @SpringBootApplication vereint drei Annotationen:
// - @Configuration: die Klasse kann Beans deklarieren (@Bean);
// - @EnableAutoConfiguration: Spring Boot konfiguriert selbst, was die
// vorhandenen Bibliotheken erfordern (Spring MVC, Thymeleaf, JPA, Spring
// Security ...), gemäß application.properties;
// - @ComponentScan: Spring sucht die annotierten Klassen (@Controller,
// @Service, @Component, @Repository ...) im Paket [rdvmedecins] und
// seinen Unterpaketen und macht sie zu Beans, die es denen bereitstellt, die
// sie benötigen (Dependency Injection).
//
// @ConfigurationPropertiesScan: die mit @ConfigurationProperties annotierten Records
// (Paket config) erhalten die Werte aus application.properties.
//
// Hier gibt es kein Äquivalent zur "Middleware-Pipeline" der Program.cs von ASP.NET
// Core: die Reihenfolge der Filter wird von Spring Boot und Spring Security festgelegt, und
// jeder Aspekt wird in einer eigenen Klasse konfiguriert (config/SecurityConfig,
// config/WebConfig ...).
// =========================================================================
package rdvmedecins;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationPropertiesScan;
@SpringBootApplication
@ConfigurationPropertiesScan
public class RdvMedecinsApplication {
public static void main(String[] args) {
SpringApplication.run(RdvMedecinsApplication.class, args);
}
}
|
Kommentieren wir diesen Code:
- Zeilen 34–36: die Methode [main], der Einstiegspunkt jedes [Java]-Programms, wie in den Beispielen gezeigt. [SpringApplication.run] erzeugt den Container von [Spring] (den „Application Context“, der alle Beans erzeugt und verwaltet), startet den Server [Tomcat] und gibt dann die Kontrolle zurück; das Programm läuft weiter, solange der Server lauscht. Die als Parameter übergebene Klasse dient als Ausgangspunkt der Konfiguration;
- Zeile 30: die Annotation [@SpringBootApplication] – die bereits in allen Beispielen vorhanden war – fasst die drei im Kommentar der Datei (Zeilen 6–14) erläuterten Annotationen zusammen. [@ComponentScan] bewirkt, dass [Spring] das Paket [rdvmedecins] und alle seine Unterpakete durchläuft: Jede annotierte Klasse – [@Controller], [@Service], [@Component] (oder [@Configuration], [@ControllerAdvice] ...) – wird darin zu einer Bean. Die Repository-Schnittstellen von [Spring Data JPA] werden auf dieselbe Weise in denselben Paketen gefunden, und zwar durch die Autokonfiguration von [Spring Data JPA] (siehe unten). Anders als in [Program.cs] gibt es also keine Liste von Services zu pflegen: Es genügt, eine annotierte Klasse in eines dieser Pakete zu legen. Deshalb liegt die Hauptklasse im Wurzelpaket, oberhalb aller anderen;
- Zeile 31: [@ConfigurationPropertiesScan] tut dasselbe für die mit [@ConfigurationProperties] annotierten Records (siehe [config/AuthProperties.java]).
Die Beans der Anwendung sind allesamt Singletons: eine einzige Instanz, die von allen Anfragen gemeinsam genutzt wird. Die Version [ASP.NET Core] unterschied drei Lebensdauern ([Singleton], [Scoped], [Transient]), weil ihre DAO-Schicht von einer pro Anfrage erzeugten [DbContext] -Instanz abhing. Bei [Spring] hängen die Repositories und die Geschäftsschicht von keiner Anfrage ab: Es ist [Spring] , das jeder Verarbeitung eine Verbindung aus dem Connection-Pool (einem Pool geöffneter Verbindungen, die von einer Abfrage zur nächsten wiederverwendet werden) und, bei Schreibzugriffen der Geschäftsschicht, deren Transaktion bereitstellt. Dieser Punkt wird in den Abschnitten zur DAO-Schicht und zur Geschäftsschicht ausführlicher behandelt.
11.7.2. Was Spring Boot automatisch konfiguriert
[@EnableAutoConfiguration], enthalten in [@SpringBootApplication], löst die Autokonfiguration aus: Beim Start durchsucht [Spring Boot] die im Klassenpfad vorhandenen Bibliotheken und die von der Anwendung bereits deklarierten Beans und erzeugt fehlende Beans selbst, konfiguriert gemäß [application.properties]. Anhand der oben gezeigten Startkonsole lässt sich dieser Vorgang nachverfolgen:
Was konfiguriert wird | Vorhanden dank | Konsolenmeldungen |
der Server [Tomcat] am Port [server.port] | [spring-boot-starter-webmvc] | [Tomcat initialized with port 8081], dann [Tomcat started on port 8081] |
das Servlet [DispatcherServlet], der Front-Controller von [Spring MVC], der alle Anfragen entgegennimmt und auf die Actions verteilt | [spring-boot-starter-webmvc] | [Initializing Servlet 'dispatcherServlet'], bei der ersten Anfrage |
die statischen Dateien im Ordner [static/], unverändert ausgeliefert ([/css/styles.css] ...) | [spring-boot-starter-webmvc] | keine |
die Engine [Thymeleaf]: Die View [schedule] ist die Datei [templates/schedule.html] | [spring-boot-starter-thymeleaf] | keine |
der Formular-Validator ([Hibernate Validator]) | [spring-boot-starter-validation] | keine |
Die Datenquelle ([DataSource]): ein Connection-Pool [HikariCP] zur URL [spring.datasource.url] | [spring-boot-starter-data-jpa], [mysql-connector-j] | [HikariPool-1 - Start completed] |
[Hibernate] (die „Fabrik“ für [EntityManager] und [JPA]), der Transaktionsmanager und die Bean [TransactionTemplate], die von der Geschäftsschicht verwendet wird | [spring-boot-starter-data-jpa] | [Hibernate ORM core version 7.4.5.Final], [Database info], [Initialized JPA EntityManagerFactory] |
eine Implementierung jeder der fünf Repository-Schnittstellen im Ordner [repositories/] (die sechste, [PersonRepository], ein gemeinsames Modell für Ärzte und Clients, ist mit [@NoRepositoryBean] markiert: [Spring Data JPA] implementiert sie nicht) | [spring-boot-starter-data-jpa] | [Found 5 JPA repository interfaces] |
automatischer Neustart und Deaktivierung des View-Caches von [Thymeleaf] | [spring-boot-devtools] | [Devtools property defaults active!], [restartedMain] |
Kommentieren wir einige Zeilen dieser Konsole:
- [The following 1 profile is active: "dev"]: das von [pom.xml] aktivierte Profil; [application-dev.properties] wird daher gelesen;
- [restartedMain] ist der Name des Threads, der die Anwendung startet: der von [Spring Boot DevTools], das sie nach jeder Neukompilierung neu startet. Bei einem Start mit [java -jar] ohne DevTools startet die Anwendung im Thread [main];
- die Warnung [HHH000511] erscheint nur mit [MariaDB] (siehe „Häufige Probleme“);
- die beiden Zeilen [Hibernate: select ...] sind Abfragen zum Laden des Caches (siehe unten), die über das Profil [dev] angezeigt werden. Hier sehen wir den Join, den [Hibernate] aus den Entitäten abgeleitet hat, um jeden Arzt zusammen mit seinem Konto [users] abzurufen;
- [Tomcat started on port 8081] steht nach diesen Abfragen: Der Server nimmt erst Anfragen an, wenn alle Beans erzeugt sind, einschließlich des Caches;
- Die letzten drei Zeilen erscheinen erst bei der ersten Anfrage: [Spring Boot] initialisiert [DispatcherServlet] erst dann, wenn es benötigt wird. Ihr Thread [tomcat-handler-0] (von dessen Namen die Konsole nur das Ende anzeigt) ist ein virtueller Thread (siehe [application.properties]).
Die Autokonfiguration tritt hinter der Anwendung zurück: Sie erzeugt eine Bean nur dann, wenn die Anwendung keine mit derselben Rolle deklariert hat. So überschreibt die Anwendung Standardeinstellungen, die ihr nicht genügen:
- Sicherheit: Ohne Konfiguration [Spring Boot] würde alle Seiten mit einem Anmeldeformular und einem beim Start generierten Passwort schützen; [config/SecurityConfig.java] deklariert eine eigene Filterkette und einen eigenen JWT-Token-Decoder (siehe „Authentifizierung“);
- Übersetzungen: Die Bean [messageSource], die [Thymeleaf] für seine Ausdrücke [#{...}] verwendet, ist die Klasse [web/Translator.java], die die JSON-Wörterbücher liest (siehe Beispiel 22 und „Die Web-Schicht: gemeinsame Services“);
- die Fehlerseite: Fehler (400, 403, 404, 500 ...) werden vom Server unter der Adresse [/error] behandelt. [Spring Boot] platziert dort üblicherweise einen eigenen Controller; [controllers/ErrorController.java] tritt an dessen Stelle (siehe Beispiel 24 und „Die Web-Schicht: Controller“);
- die Sprache jeder Anfrage und die Flash-Attribute: Das sind die beiden Beans aus [config/WebConfig.java], die weiter unten besprochen werden.
Es gibt auch keine zu konfigurierende Middleware-Pipeline wie in [Program.cs]: Jede Anfrage durchläuft die Filterkette von [Spring Security] – deren Reihenfolge von [Spring Security] selbst bestimmt wird –, bevor sie [DispatcherServlet] erreicht, das anhand der Controller-Annotationen die Action auswählt (siehe Beispiel 24).
11.7.3. config/WebConfig.java
| // =========================================================================
// config/WebConfig.java
// -------------------------------------------------------------------------
// Die Ergänzungen der Konfiguration von Spring MVC:
// - die Sprache jeder Anfrage, aus einem Cookie gelesen (siehe Beispiel 22);
// - die Flash-Attribute, in einem Cookie gespeichert (siehe web/CookieFlashMapManager).
// Die statischen Dateien des Ordners src/main/resources/static (css/, js/,
// lib/bootstrap/) werden von Spring Boot ohne Konfiguration bereitgestellt.
// =========================================================================
package rdvmedecins.config;
import java.time.Duration;
import java.util.Locale;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.FlashMapManager;
import org.springframework.web.servlet.LocaleResolver;
import org.springframework.web.servlet.i18n.CookieLocaleResolver;
import rdvmedecins.web.CookieFlashMapManager;
@Configuration
public class WebConfig {
// die Sprache jeder Anfrage: die des Cookies [rdvmedecins_language],
// von LanguageController gesetzt; sonst Englisch. Die Bean muss
// [localeResolver] heißen: unter diesem Namen sucht Spring MVC sie.
@Bean
public LocaleResolver localeResolver() {
CookieLocaleResolver resolver = new CookieLocaleResolver("rdvmedecins_language");
resolver.setDefaultLocale(Locale.ENGLISH);
resolver.setCookieMaxAge(Duration.ofDays(365));
resolver.setCookieHttpOnly(true);
resolver.setCookieSameSite("Lax");
return resolver;
}
// die Flash-Attribute in einem Cookie und nicht in der HTTP-Session. Die Bean
// muss [flashMapManager] heißen: sie ersetzt dann die von Spring MVC.
@Bean
public FlashMapManager flashMapManager() {
return new CookieFlashMapManager();
}
}
|
Kommentieren wir diesen Code:
- Zeile 23: Eine mit [@Configuration] annotierte Klasse deklariert Beans mithilfe von Methoden, die mit [@Bean] annotiert sind (siehe Beispiel 06). Beim Start ruft [Spring] jede dieser Methoden einmal auf und speichert das erhaltene Objekt als Bean. Die Bean trägt den Namen der Methode;
- Zeile 30: [LocaleResolver] bestimmt die Sprache ([Locale]) jeder Anfrage. [Spring MVC] sucht sie unter dem Namen [localeResolver]: Der Methodenname macht sie zum Ersatz für die von [Spring Boot] bereitgestellte Variante, die der bevorzugten Sprache des Browsers folgen würde;
- Zeile 31: Die Sprache wird wie in Beispiel 22 aus dem Cookie [rdvmedecins_language] gelesen. Dieses Cookie wird vom selben Objekt gesetzt, wenn [controllers/LanguageController.java] ihm die gewählte Sprache übermittelt (Schaltflächen FR / EN);
- Zeile 32: Ohne Cookie ist die Sprache Englisch;
- Zeilen 33–35: Das Cookie gilt ein Jahr; es ist [HttpOnly] (das Skript der Seite kann es nicht lesen) und [SameSite=Lax] (der Browser sendet es nicht bei Anfragen einer anderen Website mit, außer bei der bloßen Navigation zur Anwendung);
- Zeilen 41–44: [FlashMapManager] bewahrt die Flash-Attribute zwischen einem POST und der anschließenden Weiterleitung auf (das Muster Post/Redirect/Get; siehe Beispiel 20). Die [Spring MVC]-Bean speichert sie in der HTTP-Sitzung; die Anwendung ist jedoch zustandslos: Sie behält keine Benutzerdaten zwischen Anfragen, da der Benutzer anhand des JWT-Tokens in seinem Cookie identifiziert wird. Die Bean namens [flashMapManager] ersetzt daher die Bean namens [Spring MVC] durch die Klasse [web/CookieFlashMapManager.java], die die Flash-Attribute in einem Cookie speichert (siehe „Die Web-Schicht: gemeinsame Services“).
11.7.4. Laden des Caches beim Start
Die Listen der Ärzte und Clients werden auf fast jeder Seite angezeigt (Dropdown-Listen im Terminkalender, Verwaltungsseiten). Statt sie bei jeder Anfrage aus der Datenbank abzurufen, hält die Anwendung sie im Speicher der Bean [web/ApplicationModel.java], über die alle Controller laufen. Diese Bean lädt sie nach jedem Hinzufügen, Ändern oder Löschen eines Arztes oder Clients neu.
Das erstmalige Laden erfolgt beim Start in einer Methode dieser Bean, die mit [@PostConstruct] annotiert ist. Diese Annotation weist [Spring] an, die Methode aufzurufen, sobald das Objekt erzeugt und seine Abhängigkeiten injiziert sind (hier die Geschäftsschicht): also während des Starts, bevor der Server die erste Anfrage annimmt. Das sind die beiden Abfragen [Hibernate: select ...] in der Konsole. Ein Lesefehler wird nicht abgefangen: Die Anwendung beendet sich sofort, und der Fehler erscheint in der Konsole. Eine nicht erreichbare Datenbank (falsche URL, gestoppter [MySQL]-Server) beendet die Anwendung tatsächlich schon früher, sobald [Hibernate] initialisiert wird (siehe „Häufige Probleme“).
Für dieses Laden musste die Version [ASP.NET Core] in [Program.cs] ausdrücklich einen „Scope“ erzeugen, weil ihre Fassade vom [DbContext] einer Anfrage abhing. Das ist hier nicht der Fall: [ApplicationModel] ist ein Singleton, ebenso wie die Geschäftsschicht, die es verwendet. Die Datei wird im Abschnitt „Die Web-Schicht: gemeinsame Services“ dokumentiert.
11.7.5. Von Program.cs in ASP.NET Core zu Spring Boot
Für Leser, die mit der Version [ASP.NET Core] vertraut sind, hier die Stelle, an der sich jeder Teil von [Program.cs] wiederfindet:
Program.cs (ASP.NET Core) | Spring Boot |
[WebApplication.CreateBuilder(args)] ... [app.Run()] | [SpringApplication.run(...)] ([RdvMedecinsApplication.java]) |
[builder.Services.AddScoped<...>()], ein Aufruf pro Service | [@ComponentScan]: annotierte Klassen [@Service], [@Component], [@Controller] ...; die Registrierung von Schnittstellen (Autokonfiguration von [Spring Data JPA]); die Methoden [@Bean] der Klassen [@Configuration] |
[Configure<AuthOptions>(...)] und [IOptions<AuthOptions>] | Records [@ConfigurationProperties] und [@ConfigurationPropertiesScan] |
[AddDbContext] und [UseMySql] | Automatische Konfiguration der Datenquelle und von [Hibernate] auf Grundlage von [spring.datasource.*] |
[AddControllersWithViews] | Autokonfiguration von [DispatcherServlet] und [Thymeleaf] |
[AddJwtAuthentication], [UseAuthentication], [UseAuthorization] | [config/SecurityConfig.java] (Filterkette von [Spring Security]) |
[UseStaticFiles] (Ordner [wwwroot]) | Automatisch (Ordner [static]) |
[UseRequestLocalization] und [CookieRequestCultureProvider] | Bean [localeResolver] ([CookieLocaleResolver], [config/WebConfig.java]) |
[TempData] (Cookie) | Bean [flashMapManager] ([CookieFlashMapManager], [config/WebConfig.java]) |
[UseExceptionHandler], [UseStatusCodePagesWithReExecute] | die Adresse [/error], verarbeitet von [controllers/ErrorController.java] |
[CreateScope()], dann [LoadAsync()], vor [app.Run()] | Methode [@PostConstruct] aus [web/ApplicationModel.java] |
[appsettings.Development.json] und [ASPNETCORE_ENVIRONMENT] | [application-dev.properties] und das Profil [dev] |
[dotnet watch] | [Spring Boot DevTools] |
11.8. Die Entitäten
Die [JPA]-Entitäten bilden die Datenbanktabellen auf [Java]-Klassen ab (siehe Beispiel 28). Jede Entitätsklasse ist als [@Entity] annotiert; ihre Felder werden über Annotationen ([@Column], [@Id], [@JoinColumn] ...) aus dem Paket [jakarta.persistence] den Spalten zugeordnet. Diese Annotationen sind im Standard [JPA] (Jakarta Persistence) definiert; [Hibernate], die von [Spring Boot] verwendete Implementierung des Standards, liest sie beim Start der Anwendung, um zu bestimmen, welche Klasse in welche Tabelle und welches Feld in welche Spalte gehört. Die Datenbank wird nicht von [Hibernate] erzeugt, sondern durch das SQL-Skript [database/dbrdvmedecins2.sql] (siehe Abschnitt „Die Datenbank“): Die Entitäten müssen lediglich die bereits vorhandenen Tabellen korrekt beschreiben.
Die Entitäten der Anwendung befinden sich im Ordner [entities]:
Datei | Tabelle | Rolle |
[AbstractEntity.java] | - | Die gemeinsamen Felder [id] und [version] (optimistische Sperre) |
[Person.java] | - | Felder, die Ärzten und Clients gemeinsam sind: [title], [lastName], [firstName] sowie das Benutzerkonto |
[Doctor.java] | [doctors] | ein Arzt |
[Client.java] | [clients] | ein Patient |
[Slot.java] | [slots] | ein Terminfenster eines Arztes |
[Appointment.java] | [appointments] | ein Termin |
[User.java] | [users] | ein Benutzerkonto |
[Role.java] | - | eine Liste der drei Rollen |
11.8.1. entities/AbstractEntity.java
| // =========================================================================
// entities/AbstractEntity.java
// -------------------------------------------------------------------------
// Die beiden Felder, die allen Entitäten gemeinsam sind: die Kennung [id] und die
// Versionsnummer [version] (optimistische Sperre).
//
// @MappedSuperclass: diese Klasse hat keine Tabelle; ihre Felder werden den
// Tabellen der Kindklassen hinzugefügt (Doctor, Client, Slot, Appointment, User).
//
// Die Annotationen @Id, @Column, @Version ... stammen aus dem JPA-Standard (Jakarta
// Persistence, Paket jakarta.persistence): Hibernate liest sie beim Start,
// um zu wissen, welche Klasse in welche Tabelle und welches Feld in welche Spalte gehört.
// =========================================================================
package rdvmedecins.entities;
import jakarta.persistence.Column;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.MappedSuperclass;
import jakarta.persistence.Version;
@MappedSuperclass
public abstract class AbstractEntity {
// der Primärschlüssel, von der Datenbank erzeugt (Spalte AUTO_INCREMENT): Hibernate
// liest seinen Wert nach jedem INSERT zurück. Integer (und nicht int): eine noch
// nicht gespeicherte Entität hat eine id mit dem Wert null.
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
@Column(name = "id")
private Integer id;
// @Version: die optimistische Sperre. Jedes von Hibernate gesendete UPDATE trägt
// die Bedingung "WHERE id = ... AND version = <gelesener Wert>" und schreibt die
// um 1 erhöhte Version. Hat jemand die Zeile inzwischen geändert,
// wird keine Zeile aktualisiert: Hibernate wirft eine Exception
// (OptimisticLockException, die Spring in
// ObjectOptimisticLockingFailureException übersetzt, siehe business/BusinessService.java).
@Version
@Column(name = "version")
private Integer version;
public Integer getId() {
return id;
}
public Integer getVersion() {
return version;
}
}
|
- Zeile 23: [@MappedSuperclass] bezeichnet eine Elternklasse ohne Tabelle: Sie entspricht keiner Tabelle, aber ihre Felder und deren Annotationen werden zu denen ihrer Kindklassen hinzugefügt. Alle Entitäten der Anwendung erben von ihr und haben daher einen Bezeichner und eine Version. Die Klasse ist außerdem [abstract]: Ein Objekt vom Typ [AbstractEntity] wird nie erzeugt;
- Zeilen 29–32: der Primärschlüssel ([@Id]), Spalte [id]. [@GeneratedValue(strategy = GenerationType.IDENTITY)] gibt an, dass der Wert von der Datenbank erzeugt wird (Spalte [AUTO_INCREMENT]): [Hibernate] sendet [INSERT] ohne Bezeichner und liest anschließend den von der Datenbank vergebenen zurück. Wichtig für später: Das [INSERT] für eine neue Entität wird sofort beim Aufruf von [save] gesendet, weil [Hibernate] den Bezeichner sofort benötigt. Der Typ ist [Integer], nicht [int]: Ein [Integer] kann den Wert [null] haben, was bei einer noch nicht gespeicherten Entität der Fall ist;
- Zeilen 40–42: die Zeilenversion für die optimistische Sperre (siehe Beispiel 28). Mit [@Version] erledigt [Hibernate] die ganze Arbeit: Jedes [UPDATE] , das es sendet, enthält die Bedingung [WHERE id = ... AND version = <value read>] und schreibt die um 1 erhöhte Version. Wurde die Zeile zwischenzeitlich von jemand anderem geändert, wird keine Zeile aktualisiert, und [Hibernate] löst eine Exception aus, die [Spring] in [ObjectOptimisticLockingFailureException] übersetzt (siehe „Die Geschäftsschicht“). Das unterscheidet sich von [Entity Framework Core], wo die Anwendung die Version vor jedem Speichern selbst erhöhen musste;
- Zeilen 44–50: schreibgeschützte Zugriffsmethoden. Es gibt keine Methoden namens [setId] oder [setVersion]: Diese Werte werden ausschließlich von [Hibernate] geschrieben. Da die Annotation [@Id] an einem Feld (und nicht an einer Methode [getId]) steht, liest und schreibt [Hibernate] die Felder direkt – auch private –, ohne die Zugriffsmethoden zu verwenden. Man spricht von Feldzugriff.
11.8.2. entities/Person.java
| // =========================================================================
// entities/Person.java
// -------------------------------------------------------------------------
// Elternklasse (ohne Tabelle) der Entitäten [Doctor] und [Client]: eine Anrede, ein
// Nachname, ein Vorname - und das zugehörige Benutzerkonto (Spalte [user]).
//
// Eine in einer @MappedSuperclass deklarierte Relation wird von den
// Kindklassen genau wie die Spalten geerbt: die Relation [user] existiert daher
// in der Tabelle [doctors] UND in der Tabelle [clients].
// =========================================================================
package rdvmedecins.entities;
import jakarta.persistence.Column;
import jakarta.persistence.FetchType;
import jakarta.persistence.JoinColumn;
import jakarta.persistence.MappedSuperclass;
import jakarta.persistence.OneToOne;
@MappedSuperclass
public abstract class Person extends AbstractEntity {
@Column(name = "title", length = 5)
private String title; // Melle, Mme, Mr
@Column(name = "last_name", length = 20)
private String lastName;
@Column(name = "first_name", length = 20)
private String firstName;
// -----------------------------------------------------------------------
// Die Relation zum Benutzerkonto: ein Arzt (ein Client) hat EIN
// Konto, und ein Konto gehört zu EINER Person (Spalte [user] UNIQUE).
// - @OneToOne: Relation "one to one";
// - fetch = LAZY: der User wird nur dann aus der Datenbank gelesen, wenn er angefordert wird (in der
// Abfrage, siehe @EntityGraph in repositories/, oder durch Zugriff auf das Feld
// während einer Transaktion);
// - @JoinColumn: die Spalte des Fremdschlüssels. Die Backquotes
// (`user`) weisen Hibernate an, diesen Namen zu "schützen", der ein
// reserviertes Wort von MySQL ist.
// -----------------------------------------------------------------------
@OneToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "`user`")
private User user;
// dieselbe Spalte, als einfache Zahl gelesen: so kennen wir die id des
// Kontos, ohne den User zu laden. insertable / updatable = false: das oben stehende
// Feld [user] schreibt die Spalte, dieses hier liest nur.
@Column(name = "`user`", insertable = false, updatable = false)
private Integer userId;
public String getTitle() { return title; }
public void setTitle(String title) { this.title = title; }
public String getLastName() { return lastName; }
public void setLastName(String lastName) { this.lastName = lastName; }
public String getFirstName() { return firstName; }
public void setFirstName(String firstName) { this.firstName = firstName; }
public User getUser() { return user; }
public void setUser(User user) { this.user = user; }
public Integer getUserId() { return userId; }
}
|
- Zeilen 19–20: die Elternklasse – die ebenfalls keine zugeordnete Tabelle hat ([@MappedSuperclass]) – von [Doctor] und [Client], selbst eine Kindklasse von [AbstractEntity]. Ärzte und Clients haben dieselben Spalten: Sie werden nur einmal erfasst;
- Zeilen 22–29: die Anrede (Frau, Herr usw.), der Nachname und der Vorname. Das Attribut [length] von [@Column] legt die Spaltenbreite fest; es wird tatsächlich nur verwendet, wenn [Hibernate] die Tabellen selbst erzeugt, was hier nicht der Fall ist (siehe Abschnitt „JPA, Hibernate und Spring Data“): Es handelt sich nicht um eine Validierungsregel, sondern lediglich um eine genaue Dokumentation des SQL-Skripts;
- Zeilen 42–44: Die Beziehung zum Benutzerkonto in Form eines Feldes vom Typ [User] (das Objekt selbst, nicht sein Bezeichner). [@OneToOne] definiert eine „Eins-zu-eins“-Beziehung: Ein Arzt (ein Client) hat ein Konto, und ein Konto gehört höchstens einer Person (die Spalte [user] ist im SQL-Skript [UNIQUE] ). [@JoinColumn] benennt die Spalte, die den Fremdschlüssel enthält. [fetch = FetchType.LAZY] legt Lazy Loading fest: Wenn [Hibernate] eine Person liest, liest es ihr Konto nicht mit; stattdessen erhält das Feld [user] einen Proxy, ein Objekt, das den [User] vertritt und die Zeile der Tabelle [users] erst beim ersten Aufruf einer seiner Methoden liest, und nur, wenn die Transaktion noch offen ist. Um die Person samt ihrem Konto abzurufen, muss die Abfrage dies ausdrücklich anfordern (siehe „Die DAO-Schicht“);
- Zeile 43: [user] ist in [MySQL] ein reserviertes Wort: Würde es unverändert in einer SQL-Abfrage stehen, führte dies zu einem Syntaxfehler. Die Backticks um den Namen in [@JoinColumn] weisen [Hibernate] an, diesen Namen zu schützen: Es setzt ihn in jedem SQL-Befehl in Backticks, wie es auch das SQL-Skript tut;
- Zeilen 49–50: die gleiche Spalte [user], diesmal als einfache Zahl gelesen. So lässt sich die Konto-ID bestimmen, ohne das Konto selbst zu laden: Die Geschäftsschicht nutzt sie, um das Konto einer Person zu löschen. Eine Spalte darf nur von einem Feld geschrieben werden: [insertable = false, updatable = false] bedeutet, dass dieses Feld sie nur liest und dass das Feld [user] sie schreibt (bei [INSERT] und [UPDATE]);
- Zeilen 52–64: die Zugriffsmethoden. Eine Klasse, deren private Felder über Methoden namens [getXxx] gelesen und über Methoden namens [setXxx] geschrieben werden, folgt der JavaBean-Konvention; die [Thymeleaf]-Views beruhen auf dieser Konvention ([${doctor.lastName}] ruft [getLastName()] auf). Es gibt kein [setUserId]: Das Feld [userId] ist schreibgeschützt.
Hier die in der Anwendungskonsole erfasste SQL-Abfrage, die [Hibernate] sendet, um einen Arzt samt seinem Konto abzurufen (siehe [findWithUserById] in der DAO-Schicht). Man sieht die Spalte [user] mit ihren Backticks und den Join mit der Tabelle [users]:
| Hibernate: select d1_0.id,d1_0.first_name,d1_0.last_name,d1_0.title,u1_0.id,u1_0.login,u1_0.name,u1_0.password,u1_0.role,u1_0.version,d1_0.`user`,d1_0.version from doctors d1_0 left join users u1_0 on u1_0.id=d1_0.`user` where d1_0.id=?
|
Die Spalte [user] der Tabelle [doctors] (auch bekannt als [d1_0]) wird nur einmal gelesen, obwohl ihr zwei Felder entsprechen: [Hibernate] verwendet sie, um das Feld [userId] zu füllen, und verknüpft das Feld [user] mit dem durch den Join abgerufenen Datensatz. [?] ist ein Abfrageparameter (die ID des Arztes), der getrennt an die Datenbank gesendet wird.
11.8.3. entities/Doctor.java
| // =========================================================================
// entities/Doctor.java
// -------------------------------------------------------------------------
// Ein Arzt der Praxis (Tabelle [doctors]).
//
// SQL-Eindeutigkeits-Constraint: unq_doctors_first_name_last_name (zwei Ärzte dürfen nicht
// denselben Vor- und Nachnamen haben) - vom SQL-Skript erstellt,
// in der Geschäftsschicht an seinem Namen erkannt.
// =========================================================================
package rdvmedecins.entities;
import jakarta.persistence.Entity;
import jakarta.persistence.Table;
// @Entity: eine Klasse, deren Objekte die Zeilen einer Tabelle sind;
// @Table: der Name dieser Tabelle
@Entity
@Table(name = "doctors")
public class Doctor extends Person {
}
|
- Zeile 17: [@Entity] definiert die Klasse als Entität: Ihre Objekte sind Zeilen einer Tabelle;
- Zeile 18: [@Table] benennt diese Tabelle [doctors]. Ohne diese Annotation würde [Hibernate] eine Tabelle mit demselben Namen wie die Klasse suchen;
- Zeile 19: Die Klasse erbt alle ihre Felder von [Person] sowie den Bezeichner und die Version von [AbstractEntity]. Sie hat keinen expliziten Konstruktor: Der [Java]-Compiler stellt ihr daher einen Standardkonstruktor bereit – öffentlich und parameterlos –, den [JPA] genau so verlangt (siehe [Appointment.java]) und den auch die Geschäftsschicht verwenden wird ([Doctor::new]). Die Eindeutigkeitsbedingung [unq_doctors_first_name_last_name], die im Kommentar erwähnt wird, wird vom SQL-Skript angelegt; die Geschäftsschicht erkennt sie an ihrem Namen.
Anders als die Version [ASP.NET Core] deklariert [Doctor] nicht die inverse Beziehung zu seinen Zeitfenstern (eine Liste [@OneToMany]): Die Anwendung würde sie nicht verwenden; sie liest die Zeitfenster eines Arztes über die DAO-Schicht.
11.8.4. entities/Client.java
| // =========================================================================
// entities/Client.java
// -------------------------------------------------------------------------
// Achtung: [Client] bezeichnet hier einen PATIENTEN der Arztpraxis, keinen
// HTTP-Client! Es ist das Vokabular der ursprünglichen Fachdomäne, unverändert
// beibehalten (Tabelle [clients]).
//
// SQL-Eindeutigkeits-Constraint: unq_clients_first_name_last_name (siehe Doctor.java).
// =========================================================================
package rdvmedecins.entities;
import jakarta.persistence.Entity;
import jakarta.persistence.Table;
@Entity
@Table(name = "clients")
public class Client extends Person {
}
|
Ein Client, also ein Patient der Praxis (kein HTTP-Client): eine [Person] aus der Tabelle [clients] (Zeilen 15–17), ohne zusätzliche Felder.
11.8.5. entities/Slot.java
| // =========================================================================
// entities/Slot.java
// -------------------------------------------------------------------------
// Ein Zeitfenster eines Arztes (Tabelle [slots]): 8:00 - 8:20 usw.
// =========================================================================
package rdvmedecins.entities;
import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.FetchType;
import jakarta.persistence.JoinColumn;
import jakarta.persistence.ManyToOne;
import jakarta.persistence.Table;
@Entity
@Table(name = "slots")
public class Slot extends AbstractEntity {
@Column(name = "start_hour")
private int startHour; // Startstunde des Zeitfensters
@Column(name = "start_minute")
private int startMinute; // Startminute des Zeitfensters
@Column(name = "end_hour")
private int endHour; // Endstunde des Zeitfensters
@Column(name = "end_minute")
private int endMinute; // Endminute des Zeitfensters
// mehrere Zeitfenster für denselben Arzt: @ManyToOne ("many to one"),
// Fremdschlüssel [doctor_id]. Gleiche Technik wie Person.user / userId.
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "doctor_id")
private Doctor doctor;
@Column(name = "doctor_id", insertable = false, updatable = false)
private Integer doctorId;
public int getStartHour() { return startHour; }
public int getStartMinute() { return startMinute; }
public int getEndHour() { return endHour; }
public int getEndMinute() { return endMinute; }
public Doctor getDoctor() { return doctor; }
public Integer getDoctorId() { return doctorId; }
}
|
- Zeilen 19–29: Start- und Endstunde und -minute des Zeitfensters, vom Typ [int]: Diese Spalten sind in der Datenbank als [NOT NULL] deklariert; ein primitiver Typ – der nicht [null] sein kann – ist dafür geeignet;
- Zeilen 33–35: die „Viele-zu-eins“-Beziehung zum Arzt ([@ManyToOne]): mehrere Zeitfenster für einen Arzt, Fremdschlüssel in der Spalte [doctor_id]; der Arzt wird verzögert geladen ([LAZY]). Dieselbe Technik wie beim Konto einer Person;
- Zeilen 37–38: dieselbe Spalte [doctor_id], schreibgeschützt, in Form einer Zahl. Abfragen wie „Zeitfenster des Arztes Nr. 2“ zielen auf dieses Feld, ohne den Arzt laden zu müssen;
- Zeilen 40–45: schreibgeschützte Zugriffsmethoden: Die Anwendung erstellt oder ändert nie Zeitfenster (sie werden vom SQL-Skript angelegt).
Standardmäßig wird eine Beziehung [@ManyToOne] sofort geladen ([EAGER]): Das Lesen eines Zeitfensters würde auch seinen Arzt lesen und dann das Konto dieses Arztes ... Stattdessen sind alle Beziehungen der Anwendung als [LAZY] deklariert, und jede Abfrage fordert ausdrücklich die Beziehungen an, die sie benötigt: So wissen wir genau, welches SQL gesendet wird.
11.8.6. entities/Appointment.java
| // =========================================================================
// entities/Appointment.java
// -------------------------------------------------------------------------
// Ein Termin (Tabelle [appointments]): ein Client, in einem Zeitfenster, an einem bestimmten Tag.
//
// SQL-Eindeutigkeits-Constraint: unq1_appointments (day, slot_id) - ein Zeitfenster wird
// pro Tag nur einmal gebucht. Vom SQL-Skript erstellt, in der Geschäftsschicht
// an seinem Namen erkannt.
// =========================================================================
package rdvmedecins.entities;
import java.time.LocalDate;
import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.FetchType;
import jakarta.persistence.JoinColumn;
import jakarta.persistence.ManyToOne;
import jakarta.persistence.Table;
@Entity
@Table(name = "appointments")
public class Appointment extends AbstractEntity {
// LocalDate: ein Datum OHNE Uhrzeit, das genau dem SQL-Typ
// DATE der Spalte [day] entspricht
@Column(name = "day")
private LocalDate day;
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "client_id")
private Client client;
@Column(name = "client_id", insertable = false, updatable = false)
private Integer clientId;
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "slot_id")
private Slot slot;
@Column(name = "slot_id", insertable = false, updatable = false)
private Integer slotId;
// ein Konstruktor ohne Parameter wird von JPA benötigt (Hibernate erzeugt damit die
// aus der Datenbank gelesenen Objekte)
protected Appointment() {
}
// ein neuer Termin
public Appointment(LocalDate day, Slot slot, Client client) {
this.day = day;
this.slot = slot;
this.client = client;
}
public LocalDate getDay() { return day; }
public Client getClient() { return client; }
public Integer getClientId() { return clientId; }
public Slot getSlot() { return slot; }
public Integer getSlotId() { return slotId; }
}
|
- Zeile 22: die Terminetabelle. Ihre Eindeutigkeitsbedingung [unq1_appointments (day, slot_id)] stellt sicher, dass ein Zeitfenster pro Tag nur einmal reserviert wird;
- Zeilen 27–28: der Tag des Termins. Der Typ [LocalDate] (Paket [java.time]) stellt ein Datum ohne Uhrzeit dar: Er entspricht genau dem SQL-Typ [DATE] in der Spalte [day], unabhängig von der Zeitzone. [Hibernate] führt die Umwandlung in beide Richtungen durch;
- Zeilen 30–42: der Client und das Zeitfenster des Termins: zwei „Viele-zu-eins“-Beziehungen, jeweils mit einem Objektfeld (das die Spalte füllt) und einem schreibgeschützten numerischen Feld ([clientId], [slotId]);
- Zeilen 46–47: [JPA] verlangt von jeder Entität einen parameterlosen Konstruktor: [Hibernate] verwendet diesen Konstruktor, um die aus der Datenbank gelesenen Objekte zu erzeugen, bevor es ihre Felder füllt. Sobald eine Klasse einen Konstruktor deklariert (Zeilen 50–54), stellt der Compiler keinen Standardkonstruktor mehr bereit: Er muss daher selbst geschrieben werden. Er ist als [protected] deklariert: [Hibernate] kann ihn verwenden, aber der Rest der Anwendung, der ihn nicht sieht, ist gezwungen, den vollständigen Konstruktor zu benutzen. [JPA] akzeptiert einen Konstruktor mit [public] oder [protected], aber keinen mit [private]: [Hibernate] erzeugt seine Stellvertreter, indem es Kindklassen der Entitäten definiert, und eine Kindklasse muss den Konstruktor ihrer Elternklasse aufrufen können (deshalb darf eine Entitätsklasse auch nicht als [final] deklariert werden);
- Zeilen 50–54: der Konstruktor für einen neuen Termin: ein Datum, ein Zeitfenster, ein Client. Er füllt die Objektfelder [slot] und [client], die die Fremdschlüssel setzen; die schreibgeschützten Felder [clientId] und [slotId] werden erst gefüllt, wenn ein Termin aus der Datenbank gelesen wird;
- Zeilen 56–60: schreibgeschützte Zugriffsmethoden: Ein Termin wird nie geändert, sondern nur erstellt oder gelöscht.
11.8.7. entities/Role.java
| // =========================================================================
// entities/Role.java
// -------------------------------------------------------------------------
// Die drei Rollen eines Benutzers (Spalte users.role):
// - ADMIN : der Administrator - Termine + Verwaltung der Ärzte und Clients;
// - DOCTOR : ein Arzt - bucht und storniert Termine;
// - USER : ein Client (Patient) - bucht für sich selbst, verwaltet sein Konto.
//
// Eine Aufzählung (enum): der Compiler lehnt jeden anderen Wert ab. JPA
// speichert sie in der Datenbank als TEXT ('ADMIN' ...), wie es das SQL-Skript tut
// (siehe @Enumerated in User.java).
// =========================================================================
package rdvmedecins.entities;
public enum Role {
ADMIN,
DOCTOR,
USER
}
|
- Zeilen 15–19: die drei Rollen in Form einer Aufzählung ([enum]): Eine Variable vom Typ [Role] kann nur den Wert [Role.ADMIN], [Role.DOCTOR], [Role.USER] (oder [null]) haben, und der Compiler lehnt jeden anderen Wert ab. [Role] ist keine Entität: Es ist der Typ eines Feldes von [User]. Jeder Wert hat einen Namen ([name()] liefert ["ADMIN"]) und eine laufende Nummer ([ordinal()] liefert 0 für [ADMIN]): Zwischen beiden für die Datenbank zu wählen, ist das, was [@Enumerated] in [User.java] leistet.
11.8.8. entities/User.java
| // =========================================================================
// entities/User.java
// -------------------------------------------------------------------------
// Ein Benutzer, der sich an der Anwendung anmelden darf (Tabelle [users]).
// Jeder Arzt und jeder Client hat SEIN Benutzerkonto (Spalte [user]
// der Tabellen [doctors] und [clients], siehe Person.java).
//
// SQL-Eindeutigkeits-Constraint: unq_users_login (ein Login gehört nur zu einem
// Konto). Er wird vom Skript database/dbrdvmedecins2.sql erstellt;
// die Geschäftsschicht erkennt ihn an seinem NAMEN (siehe business/BusinessService.java).
// =========================================================================
package rdvmedecins.entities;
import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.EnumType;
import jakarta.persistence.Enumerated;
import jakarta.persistence.Table;
@Entity
@Table(name = "users")
public class User extends AbstractEntity {
@Column(name = "login", length = 30)
private String login;
// das GEHASHTE Passwort (bcrypt) - niemals im Klartext
@Column(name = "password", length = 100)
private String password;
// der Name, der nach der Anmeldung angezeigt wird - bei einem Arzt oder einem Client:
// "firstName LASTNAME" (z. B. "Marie PELISSIER")
@Column(name = "name", length = 40)
private String name;
// ADMIN, DOCTOR oder USER, in der Datenbank als Text (STRING) und nicht
// als Ordnungszahl (ORDINAL: 0, 1, 2) gespeichert
@Enumerated(EnumType.STRING)
@Column(name = "role", length = 10)
private Role role;
public String getLogin() { return login; }
public void setLogin(String login) { this.login = login; }
public String getPassword() { return password; }
public void setPassword(String password) { this.password = password; }
public String getName() { return name; }
public void setName(String name) { this.name = name; }
public Role getRole() { return role; }
public void setRole(Role role) { this.role = role; }
}
|
- Zeilen 20–22: die Konten der Benutzer, die sich anmelden dürfen: der Administrator, jeder Arzt und jeder Client. Die Bedingung [unq_users_login] verbietet zwei Konten mit demselben Login;
- Zeilen 24–25: der Benutzername;
- Zeilen 28–29: der Hash [bcrypt] des Passworts, nie das Passwort selbst (siehe Beispiel 25);
- Zeilen 33–34: der Name, der nach der Anmeldung in der Navigationsleiste angezeigt wird („Marie PELISSIER“);
- Zeilen 38–40: die Rolle. Standardmäßig würde [JPA] eine Aufzählung in der Datenbank über ihre laufende Nummer ablegen ([EnumType.ORDINAL]: 0, 1, 2), was zwei Nachteile hätte: Die Spalte [role] im SQL-Skript enthält Text, und das spätere Einfügen eines Wertes in die Mitte der Aufzählung würde die Reihenfolge der bereits gespeicherten Nummern verändern. [@Enumerated(EnumType.STRING)] speichert den Namen des Wertes (['ADMIN'] ...) und wandelt ihn beim Lesen wieder in [Role] um;
- Zeilen 42–52: die Getter. Die Klasse [User] deklariert keine Beziehung zu dem Arzt oder Client, dem sie gehört: Die Beziehung ist nur auf der Seite von [Person] bekannt, die den Fremdschlüssel trägt.
11.9. JPA, Hibernate und Spring Data
Die Version [ASP.NET Core] der Anwendung enthielt eine Klasse namens [DbContext], die das Kernstück von [Entity Framework Core] war: Sie hielt die Verbindung, stellte den Zugriff auf die Tabellen bereit, verfolgte die geladenen Entitäten und sendete Änderungen an die Datenbank. Die Version [Spring] hat kein von Hand geschriebenes Äquivalent: Diese Aufgaben sind auf Objekte verteilt, die [Spring Boot] beim Start anhand der Konfiguration selbst erzeugt. Dieser Abschnitt erklärt, wer was tut; er entspricht keiner [Java]-Datei des Projekts.
11.9.1. Drei Schichten
Der Datenzugriff beruht auf drei Schichten, die der Starter [spring-boot-starter-data-jpa] gemeinsam bereitstellt (siehe Abschnitt „Projektkonfiguration“):
- [JPA] (Jakarta Persistence) ist ein Standard: eine Menge von Schnittstellen und Annotationen ([@Entity], [EntityManager] ...), ohne Code, der sie zum Laufen bringt;
- [Hibernate] ist eine Implementierung dieses Standards: Es liest die Entitätsannotationen, schreibt die SQL-Befehle, sendet sie über JDBC ([mysql-connector-j]) an die Datenbank und wandelt die zurückgelieferten Zeilen in [Java]-Objekte um;
- [Spring Data JPA] ergänzt darüber die Repositories: Es genügt, ein DAO über eine Schnittstelle zu beschreiben, und [Spring] schreibt die Implementierung (siehe „Die DAO-Schicht“).
11.9.2. Der EntityManager und der Persistenzkontext
Das zentrale Objekt von [JPA] ist der [EntityManager] (der „Entitätsmanager“): Er ist zuständig für das Lesen ([find]), Speichern ([persist]) und Löschen ([remove]) von Entitäten sowie für das Ausführen von Abfragen. Er verwaltet einen Persistenzkontext: die Menge der Entitäten, die er gelesen oder gespeichert hat und die als „verwaltet“ gelten. Für jede verwaltete Entität behält er eine Kopie des aus der Datenbank gelesenen Zustands. Bei der Synchronisierung mit der Datenbank (dem *Flush*), die spätestens unmittelbar vor dem [COMMIT] der Transaktion erfolgt, vergleicht er jede Entität mit ihrer Kopie und sendet für jede geänderte selbst ein [UPDATE] (*Dirty Checking*). Es gibt daher keine Methode „Änderungen speichern“, die aufzurufen wäre: Es genügt, eine verwaltete Entität zu ändern. Ein Persistenzkontext stellt außerdem sicher, dass eine einzelne Zeile nur durch ein einziges Objekt repräsentiert wird: Liest man Arzt Nr. 1 innerhalb derselben Transaktion zweimal, erhält man zweimal dasselbe [Java]-Objekt.
Das ist genau das „Change Tracking“ von [DbContext] aus [Entity Framework Core], mit einem wichtigen Unterschied: Bei [Spring] ist der Persistenzkontext an die Transaktion gebunden. Er wird zu Beginn der Transaktion erzeugt und an ihrem Ende geschlossen ([COMMIT] oder [ROLLBACK]). Die von ihm verwalteten Entitäten werden dann losgelöst (detached): Es sind gewöhnliche [Java]-Objekte, die niemand mehr verfolgt. Ihre Änderung hat keine Auswirkung mehr auf die Datenbank, und ihre noch nicht geladenen [LAZY]-Beziehungen können nicht mehr geladen werden.
Die Anwendung manipuliert den [EntityManager] nie direkt: Das übernehmen die [Spring Data JPA]-Repositories an ihrer Stelle. Wird eine Repository-Methode aufgerufen, während eine Transaktion läuft (von der Geschäftsschicht geöffnet), verwendet sie den [EntityManager] dieser Transaktion: Alle während der Transaktion aufgerufenen Repositories teilen sich daher denselben Persistenzkontext, dieselbe Verbindung und dieselbe Transaktion. Läuft keine Transaktion, öffnen die von [JpaRepository] geerbten Methoden ([findById], [save] ...) für die Dauer des Aufrufs eine kurze Transaktion (bei Lesezugriffen schreibgeschützt); die in unseren Schnittstellen deklarierten Abfragen ([findAllByOrderByLastNameAscFirstNameAsc], die [@Query]-Methoden usw.) werden ohne Transaktion ausgeführt: [Spring] erzeugt für die Dauer des Aufrufs einen [EntityManager] und schließt ihn danach wieder. In beiden Fällen sind die zurückgegebenen Entitäten sofort losgelöst.
11.9.3. Die Konfiguration
Alles, was [Hibernate] benötigt, wird von [Spring Boot] erzeugt (das ist die Autokonfiguration), und zwar anhand der Schlüssel [spring.datasource.*] und [spring.jpa.*] der Datei [application.properties] (siehe Abschnitt „Projektkonfiguration“):
| # ---- die MySQL-Datenbank [dbrdvmedecins2] (Skript: database/dbrdvmedecins2.sql)
spring.datasource.url=jdbc:mysql://localhost:3306/dbrdvmedecins2
spring.datasource.username=root
spring.datasource.password=
# Hibernate erstellt oder ändert die Tabellen nicht: das ist die Aufgabe des SQL-Skripts
spring.jpa.hibernate.ddl-auto=none
# die Datenbankverbindung bleibt nicht geöffnet, während die View aufgebaut wird
spring.jpa.open-in-view=false
|
- Zeilen 2–4: Die Schlüssel [spring.datasource.*] beschreiben die Verbindung: die URL der Datenbank und JDBC (das Protokoll [jdbc:mysql:], den Rechner, den Port und den Datenbanknamen), den Benutzernamen und das Passwort. [Spring Boot] erzeugt daraus tatsächlich eine [DataSource], einen Connection-Pool. Eine Verbindung zu einer Datenbank zu öffnen, ist ressourcenintensiv: Diese [DataSource] ist ein Connection-Pool (die Bibliothek [HikariCP]), der einige Verbindungen offen hält und reihum verleiht;
- Zeile 6: [ddl-auto=none]: [Hibernate] erzeugt oder ändert keine Tabellen (es könnte sie mit dem Wert [create] aus den Entitäten erzeugen oder mit [update] anpassen): Die Datenbank wird durch das SQL-Skript beschrieben, und nur durch dieses;
- Zeile 8: [open-in-view=false] schließt den [EntityManager] , sobald die Transaktion endet, statt ihn bis zum Ende der HTTP-Anfrage offen zu halten (siehe unten).
Auf Grundlage von [DataSource] und den Entitäten erzeugt [Spring Boot] außerdem eine [EntityManagerFactory] (die [EntityManager] erzeugt), einen Transaktionsmanager ([JpaTransactionManager]) und ein [TransactionTemplate], das die Geschäftsschicht zum Öffnen ihrer Transaktionen verwendet. Der SQL-Dialekt (Besonderheiten von [MySQL]: [limit], Backticks usw.) wird automatisch aus der Datenbank abgeleitet, mit der Sie sich verbinden.
Die Datei [application-dev.properties], die ebenfalls gelesen wird, wenn das Profil [dev] aktiv ist (wie bei [./mvnw spring-boot:run]), fügt den Schlüssel [spring.jpa.show-sql=true] hinzu: [Hibernate] zeigt dann in der Konsole jeden SQL-Befehl an, den es sendet. Alle in diesem Kapitel gezeigten Abfragen wurden auf diese Weise erfasst.
Gegenüber [DbContext] in der Version [ASP.NET Core] fehlen zwei Elemente, weil sie nicht mehr nötig sind: die Liste der Tabellen (die Entitäten werden automatisch gefunden, da sie im Anwendungspaket oder einem seiner Unterpakete liegen) und die Details aus [OnModelCreating] (die „Eins-zu-eins“-Beziehung wird durch [@OneToOne] festgelegt, die Umwandlung der Rolle in Text durch [@Enumerated] und die Versionserhöhung durch [@Version]).
11.9.4. open-in-view=false: Beziehungen ausdrücklich laden
Standardmäßig ([spring.jpa.open-in-view=true]) öffnet [Spring Boot] zu Beginn jeder HTTP-Anfrage einen [EntityManager] und schließt ihn erst, nachdem die View erzeugt wurde: Eine View kann dann eine noch nicht geladene [LAZY]-Beziehung lesen ([${appointment.client.lastName}]), und [Hibernate] sendet die nötige Abfrage zum Zeitpunkt der Anzeige. Das ist bequem, aber SQL-Abfragen können dann von überall aus gesendet werden, auch aus einer [Thymeleaf]-View, die Verbindung bleibt während der gesamten Seitenerzeugung belegt, und eine Schleife über 20 Termine kann 20 kleine Abfragen statt einer auslösen (das sogenannte „N+1“-Problem). [Spring Boot] zeigt außerdem beim Start eine Warnung an, wenn der Schlüssel nicht angegeben ist.
Die Anwendung wählt [open-in-view=false]: [EntityManager] wird am Ende jeder Transaktion (oder jedes außerhalb einer Transaktion erfolgten Repository-Aufrufs) geschlossen, und Entitäten, die die Geschäftsschicht verlassen, sind losgelöst. Daraus ergibt sich eine Regel, die überall einzuhalten ist: Jeder Lesezugriff lädt ausdrücklich die Beziehungen, die die Seite benötigt, mithilfe von [@EntityGraph] oder [join fetch] (siehe „Die DAO-Schicht“). Das Lesen einer nicht geladenen [LAZY]-Beziehung – zum Beispiel des Kontos eines Arztes, das von einer Abfrage gelesen wurde, die es nicht angefordert hat – würde eine [LazyInitializationException] auslösen: Es kann nichts mehr gelesen werden; der [EntityManager] ist geschlossen. Dafür wissen wir genau, welche Abfragen wann gesendet werden: Sie alle befinden sich in der DAO-Schicht.
11.10. Die Domäne: der Terminkalender
Der Ordner [domain] enthält zwei Klassen, die keiner Tabelle entsprechen: Sie beschreiben den Terminkalender eines Arztes für einen einzelnen Tag, der von der Geschäftsschicht berechnet ([BusinessService.getDoctorDaySchedule]) und vom Terminkalender-Controller angezeigt wird.
11.10.1. domain/DoctorDaySlot.java
| // =========================================================================
// domain/DoctorDaySlot.java
// -------------------------------------------------------------------------
// Ein "fachliches" Objekt (ohne Tabelle), das einem Zeitfenster den an diesem Tag
// eventuell gebuchten Termin zuordnet.
//
// Ein Java-Record ist eine Klasse, deren Felder einmal und endgültig
// vom Konstruktor gesetzt werden (unveränderliches Objekt): genau das, was für
// ein berechnetes Objekt nötig ist, das danach niemand mehr ändert.
// =========================================================================
package rdvmedecins.domain;
import rdvmedecins.entities.Slot;
import rdvmedecins.entities.Appointment;
// appointment: null, wenn das Zeitfenster an diesem Tag frei ist
public record DoctorDaySlot(Slot slot, Appointment appointment) {
}
|
- Zeile 17: ein Zeitfenster und der für dieses Zeitfenster an diesem Tag vorgesehene Termin oder [null] , wenn das Zeitfenster frei ist. Ein Record (ab [Java] 16) deklariert in einer einzigen Zeile eine Klasse, deren Felder vom Konstruktor ein für alle Mal gesetzt werden: Der Compiler schreibt selbst die privaten und [final] (unveränderlichen) Felder, den Konstruktor mit zwei Parametern, die Zugriffsmethoden [slot()] und [appointment()] (ohne das Präfix [get]) sowie die Methoden [equals], [hashCode] und [toString]. Der Rumpf des Records in geschweiften Klammern ist hier leer. Records für die an die Geschäftsschicht übergebenen Daten sind uns bereits begegnet (siehe Beispiel 28).
11.10.2. domain/DoctorDaySchedule.java
| // =========================================================================
// domain/DoctorDaySchedule.java
// -------------------------------------------------------------------------
// Der vollständige Terminkalender eines Arztes für einen bestimmten Tag: die Liste seiner
// Zeitfenster, jedes frei oder durch einen Termin belegt. Berechnet von
// BusinessService.getDoctorDaySchedule, vom ScheduleController in eine
// HTML-Tabelle umgewandelt.
// =========================================================================
package rdvmedecins.domain;
import java.time.LocalDate;
import java.util.List;
import rdvmedecins.entities.Doctor;
public record DoctorDaySchedule(Doctor doctor, LocalDate day, List<DoctorDaySlot> doctorDaySlots) {
}
|
Der Terminkalender (Zeile 16): ein Arzt, ein Tag und die Liste seiner Zeitfenster – frei oder gebucht – in chronologischer Reihenfolge. Die [Thymeleaf]-Views können die Zugriffsmethoden eines Records lesen: [${schedule.day}] ruft [day()] auf.
11.11. Die DAO-Schicht
Ein DAO pro Tabelle, wie in Beispiel 28: Methoden ohne Geschäftslogik, die die Datenbank lediglich abfragen oder ändern. Sie werden hier als Repositories bezeichnet. Bei [Spring Data JPA] ist ein Repository eine einfache Schnittstelle: Beim Start der Anwendung erzeugt [Spring] eine Klasse, die sie implementiert, macht sie zu einer Bean und injiziert sie dort, wo sie benötigt wird. Die Schnittstelle erbt von [JpaRepository<T, ID>] ([T]: der Entitätstyp; [ID]: der Typ ihres Primärschlüssels), die die Standardmethoden bereitstellt: [findById], [findAll], [save], [deleteById], [getReferenceById] ... Anwendungsspezifische Abfragen werden auf drei Arten hinzugefügt:
- über den Methodennamen: [Spring Data JPA] analysiert den Namen ([find] ... [By] *Kriterien* [OrderBy] *Sortierung*) und leitet daraus die Abfrage ab. Ein Fehler in einem Feldnamen wird beim Start erkannt und führt zum Abbruch des Prozesses;
- in JPQL mit der Annotation [@Query]. [JPQL] (Jakarta Persistence Query Language) ist die Abfragesprache von [JPA]: Sie ähnelt SQL, bezieht sich aber auf Entitäten und ihre Felder ([Appointment], [a.client]) statt auf Tabellen und ihre Spalten. [Hibernate] übersetzt sie in SQL;
- in SQL mit [@Query(nativeQuery = true)], wenn [JPQL] nicht ausreicht.
Methoden, die möglicherweise nichts zurückgeben, liefern ein [Optional<T>] (Paket [java.util]): ein Behälter, der ein Objekt enthält oder leer ist. Der Aufrufer kann das Ergebnis nicht verwenden, ohne zuvor zu prüfen, ob es existiert ([isPresent()], [orElseThrow(...)] ...): Es gibt kein vergessenes [null].
Wie Entitäten verwalten auch Repositories keine Transaktionen: Die Geschäftsschicht öffnet sie.
11.11.1. repositories/PersonRepository.java
Die Repositories für Ärzte und Clients wären identisch: Eine generische Schnittstelle schreibt sie nur ein einziges Mal.
| // =========================================================================
// repositories/PersonRepository.java
// -------------------------------------------------------------------------
// Die DAO-Schicht, die Ärzten und Clients gemeinsam ist.
//
// Mit Spring Data JPA ist ein DAO ein einfaches INTERFACE: Spring schreibt
// seine Implementierung beim Start selbst. JpaRepository<T, Integer> bringt bereits
// findById, findAll, save, delete ... mit; wir fügen unsere Abfragen hinzu:
// - entweder über den NAMEN der Methode, den Spring Data in eine Abfrage übersetzt
// (findFirstByFirstNameAndLastName -> ... WHERE first_name = ? AND last_name = ? LIMIT 1);
// - oder über eine JPQL-Abfrage, in einer Annotation @Query geschrieben. JPQL
// ähnelt SQL, behandelt aber die Klassen und ihre Felder, nicht
// die Tabellen und ihre Spalten.
//
// Die DAOs der Ärzte und der Clients wären identisch: dieses
// GENERISCHE Interface schreibt sie nur einmal, wobei T Doctor oder Client ist.
// @NoRepositoryBean: Spring erstellt für dieses Interface selbst keinen DAO,
// sondern nur für seine Unter-Interfaces DoctorRepository und
// ClientRepository. In den Abfragen bezeichnet #{#entityName} die Entität des
// Unter-Interfaces (Doctor oder Client).
//
// Transaktionen: alle DAO-Methoden derselben HTTP-Anfrage
// verwenden die aktuelle Transaktion, falls es eine gibt (siehe BusinessService).
// =========================================================================
package rdvmedecins.repositories;
import java.util.List;
import java.util.Optional;
import org.springframework.data.jpa.repository.EntityGraph;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Modifying;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.NoRepositoryBean;
import rdvmedecins.entities.Person;
@NoRepositoryBean
public interface PersonRepository<T extends Person> extends JpaRepository<T, Integer> {
// nach Nachname, dann Vorname sortierte Liste, Benutzerkonto eingeschlossen.
// @EntityGraph(attributePaths = "user"): liefert das Konto ebenfalls, über einen
// Join (SELECT ... FROM doctors LEFT JOIN users ...). Ohne ihn würde das
// Konto erst beim ersten Zugriff gelesen - außerhalb einer
// Transaktion unmöglich: diese Listen werden vom Cache im Speicher gehalten
// (web/ApplicationModel.java), lange nach dem Ende der Anfrage.
@EntityGraph(attributePaths = "user")
List<T> findAllByOrderByLastNameAscFirstNameAsc();
// eine Person und ihr Konto
@EntityGraph(attributePaths = "user")
Optional<T> findWithUserById(int id);
// die Person, deren Benutzerkonto [userId] ist
@EntityGraph(attributePaths = "user")
Optional<T> findByUserId(int userId);
// die Person mit diesem Vor- und Nachnamen, falls es eine gibt. Der Vergleich
// wird von MySQL durchgeführt, also mit der Collation der Datenbank
// (utf8mb4_unicode_ci: unabhängig von Groß-/Kleinschreibung und Akzenten) -
// genau dieselbe Regel wie beim SQL-Eindeutigkeits-Constraint.
Optional<T> findFirstByFirstNameAndLastName(String firstName, String lastName);
// ein direkt an die Datenbank gesendetes DELETE, ohne die Person vorher zu lesen.
// @Modifying: die Abfrage ändert Daten (sie ist kein SELECT)
@Modifying
@Query("delete from #{#entityName} p where p.id = :id")
void remove(int id);
}
|
Kommentieren wir diesen Code:
- Zeile 39: [PersonRepository<T extends Person>] ist eine generische Schnittstelle: [T] ist ein Typparameter, der in den Unterschnittstellen durch einen konkreten Typ ersetzt wird ([Doctor] oder [Client]), wie [T] in [List<T>]. [extends Person] akzeptiert nur [Person] oder ihre Kindklassen für [T]: In Abfragen enthält [T] daher zwangsläufig die Felder [lastName], [firstName], [user], [userId] ... Die Schnittstelle erbt von [JpaRepository<T, Integer>]: Entität [T], Primärschlüssel vom Typ [Integer];
- Zeile 38: [@NoRepositoryBean] weist [Spring Data JPA] an, für diese Schnittstelle selbst kein Repository zu erzeugen, da sie sich auf keine konkrete Entität bezieht ([T] ist unbekannt), sondern nur für ihre Unterschnittstellen [DoctorRepository] und [ClientRepository];
- Zeilen 47–48: alle Personen, sortiert nach Nachname, dann nach Vorname. Der Methodenname ist die Abfrage: [findAll] (das Wort [All] steht nur der Lesbarkeit halber da), [By] ohne Kriterien (alle Zeilen), [OrderByLastNameAscFirstNameAsc] (aufsteigend nach Nachname, dann nach Vorname sortiert). [@EntityGraph(attributePaths = "user")] verlangt, dass die Beziehung [user] ebenfalls per Join in derselben Abfrage geladen wird; ohne sie wäre das Feld [user] jeder Person ein nicht geladener Proxy. Das ist hier unverzichtbar: Diese Listen werden vom Cache ([web/ApplicationModel.java]) noch lange nach dem Ende der Transaktion im Speicher gehalten, und die Views zeigen den Login jeder Person an;
- Zeilen 51–52: eine Person und ihr Konto oder ein leeres [Optional]. [JpaRepository] stellt bereits [findById] bereit, jedoch ohne das Konto; man kann ihr kein [@EntityGraph] hinzufügen, ohne alle ihre Verwendungen zu ändern. Deshalb deklarieren wir eine weitere Methode: In einem Methodennamen ignoriert [Spring Data JPA] den Text zwischen [find] und [By] (hier [WithUser]), der nur dazu dient, dem Leser mitzuteilen, was die Methode zurückgibt. Die Abfrage ist die von [findById] ([where id = ?]), und [@EntityGraph] fügt ihr den Join hinzu;
- Zeilen 55–56: die Person, deren Konto [userId] ist: Das Kriterium bezieht sich auf das (schreibgeschützte) Feld [userId] und damit direkt auf die Spalte [user]. So ruft ein angemeldeter Patient, dessen Token die Konto-ID enthält, seinen Client-Datensatz ab;
- Zeile 62: ein möglicher Namensvetter. [First] begrenzt das Ergebnis auf eine einzige Zeile ([limit ?] in SQL), [ByFirstNameAndLastName] erfüllt beide Kriterien, verknüpft durch [and]. Die Parameter der Methode werden den Kriterien der Reihe nach zugeordnet. Der Vergleich wird von [MySQL] gemäß der Kollation der Datenbank durchgeführt, ohne Beachtung von Groß-/Kleinschreibung und Akzenten, genau wie die Eindeutigkeitsbedingung;
- Zeilen 66–68: das Löschen einer Person über eine [JPQL]-Abfrage [delete], die direkt an die Datenbank gesendet wird, ohne die Person zuvor zu lesen (das Äquivalent zu [ExecuteDeleteAsync] aus [Entity Framework Core]). [@Modifying] zeigt an, dass die Abfrage Daten ändert: Ohne diese Annotation würde [Spring Data JPA] sie als [select] behandeln. Eine solche Abfrage muss innerhalb einer Transaktion laufen, die Schreibzugriffe erlaubt: Diese Transaktion öffnet die Geschäftsschicht. Sie läuft nicht über den Persistenzkontext und damit auch nicht über die optimistische Sperre;
- Zeile 67: Die Schnittstelle ist generisch, aber eine [JPQL]-Abfrage muss eine bestimmte Entität angeben: [delete from Doctor] oder [delete from Client]. [#{...}] leitet einen SpEL-Ausdruck ein (Spring Expression Language, die Ausdruckssprache von [Spring]), der beim Start ausgewertet wird; die Variable [#entityName] bezeichnet den Namen der Entität im jeweiligen Repository. Für [DoctorRepository] lautet die Abfrage dann [delete from Doctor p where p.id = :id];
- Zeilen 67–68: [:id] ist ein benannter Parameter der Abfrage, der (über den Namen) dem Methodenparameter [id] zugeordnet wird. Sein Wert wird getrennt vom Abfragetext an die Datenbank gesendet: Es gibt keine Zeichenkettenverkettung, daher ist eine SQL-Injection nicht möglich.
Hier die Abfragen, die [Hibernate] tatsächlich sendet, für die Liste der Clients (Zeile 48) und für die Suche nach einem Namensvetter unter den Ärzten (Zeile 62):
| Hibernate: select c1_0.id,c1_0.first_name,c1_0.last_name,c1_0.title,u1_0.id,u1_0.login,u1_0.name,u1_0.password,u1_0.role,u1_0.version,c1_0.`user`,c1_0.version from clients c1_0 left join users u1_0 on u1_0.id=c1_0.`user` order by c1_0.last_name,c1_0.first_name
Hibernate: select d1_0.id,d1_0.first_name,d1_0.last_name,d1_0.title,d1_0.`user`,d1_0.version from doctors d1_0 where d1_0.first_name=? and d1_0.last_name=? limit ?
|
Die erste ruft die Clients und ihre Konten in einer einzigen Abfrage ab ([left join users]); die zweite ruft ohne [@EntityGraph] nur die Tabelle [doctors] ab.
11.11.2. repositories/DoctorRepository.java
| // =========================================================================
// repositories/DoctorRepository.java
// -------------------------------------------------------------------------
// Der DAO der Ärzte: alles wird von PersonRepository geerbt.
// Spring Data baut seine Implementierung beim Start.
// =========================================================================
package rdvmedecins.repositories;
import rdvmedecins.entities.Doctor;
public interface DoctorRepository extends PersonRepository<Doctor> {
}
|
Das Repository der Ärzte (Zeile 11): [PersonRepository<Doctor>], sonst nichts. Diese Schnittstelle – anders als [@NoRepositoryBean] – wird von [Spring Data JPA] implementiert: Alle darin geerbten Methoden beziehen sich auf die Entität [Doctor].
11.11.3. repositories/ClientRepository.java
| // =========================================================================
// repositories/ClientRepository.java
// -------------------------------------------------------------------------
// Der DAO der Clients: der der Personen, plus eine Sperrmethode.
// =========================================================================
package rdvmedecins.repositories;
import java.util.Optional;
import org.springframework.data.jpa.repository.Query;
import rdvmedecins.entities.Client;
public interface ClientRepository extends PersonRepository<Client> {
// -----------------------------------------------------------------------
// setzt eine SPERRE (LOCK) auf die Zeile eines Clients bis zum Ende der aktuellen
// Transaktion (SELECT ... FOR UPDATE) und gibt seine id zurück
// (leeres Optional, wenn der Client nicht existiert). Eine zweite Transaktion, die
// dieselbe Sperre anfordert, WARTET, bis die erste beendet ist.
// Verwendet für die Buchung eines Termins (siehe BusinessService.addAppointment):
// zwei gleichzeitige Buchungen für denselben Patienten werden so
// eine NACH der anderen verarbeitet, und die zweite sieht den von der ersten erstellten Termin.
//
// nativeQuery = true: die Abfrage ist SQL, unverändert an die Datenbank gesendet,
// und nicht von Hibernate übersetztes JPQL. JPA kann diese Sperre ebenfalls setzen
// (@Lock(LockModeType.PESSIMISTIC_WRITE) auf einer JPQL-Abfrage), aber
// Hibernate schreibt dann "FOR UPDATE OF c1_0", eine MySQL-8-Syntax, die
// MariaDB (das "MySQL" mancher Distributionen) ablehnt. Dieses SQL
// funktioniert mit beiden.
// :id ist ein PARAMETER der Abfrage (keine Stringverkettung,
// also keine SQL-Injection möglich).
// -----------------------------------------------------------------------
@Query(value = "select id from clients where id = :id for update", nativeQuery = true)
Optional<Integer> lock(int id);
}
|
- Zeile 14: das Repository der Clients – das der Einzelpersonen, mit [T = Client], plus einer Methode;
- Zeilen 34–35: das Lesen eines Clients mit einer Sperre. [SELECT ... FOR UPDATE] setzt eine Sperre auf die Zeile bis zum Ende der aktuellen Transaktion: Eine andere Transaktion, die dieselbe Sperre anfordert, wartet, bis die erste abgeschlossen ist. Die Terminvergabe ([BusinessService.addAppointment]) nutzt dies, um zwei gleichzeitige Reservierungen für denselben Patienten nacheinander zu verarbeiten: Die zweite Reservierung sieht den von der ersten angelegten Termin und hält somit die Regel „nur ein bevorstehender Termin“ ein. Die Methode gibt nur die Client-ID zurück ([select id]), in einem leeren [Optional] , wenn der Client nicht existiert: Sie dient ausschließlich dazu, die Sperre zu erwerben und die Existenz des Clients zu prüfen;
- Zeile 34: [nativeQuery = true]: Die Abfrage ist in SQL geschrieben und wird unverändert an die Datenbank gesendet, nicht in [JPQL]. [JPA] kann diese Sperre allerdings selbst setzen: Die Annotation [@Lock(LockModeType.PESSIMISTIC_WRITE)], die einer Abfrage in [JPQL] hinzugefügt wird, weist [Hibernate] an, die Sperrklausel anzufügen. Bei [MySQL] 8 schreibt [Hibernate] dann jedoch [for update of c1_0] (die Sperre gilt nur für die angegebene Tabelle), eine Syntax, die spezifisch für [MySQL] 8 ist und die [MariaDB] – das oft anstelle von [MySQL] installiert ist – ablehnt. Das von Hand geschriebene SQL, [for update] ohne [of], funktioniert mit beiden. [:id] ist wiederum ein Abfrageparameter.
Die Abfrage, wie sie bei einer Reservierung in der Konsole erscheint:
| Hibernate: select id from clients where id = ? for update
|
11.11.4. repositories/SlotRepository.java
| // =========================================================================
// repositories/SlotRepository.java
// -------------------------------------------------------------------------
// DAO-Schicht der Entität [Slot].
// =========================================================================
package rdvmedecins.repositories;
import java.util.List;
import java.util.Optional;
import org.springframework.data.jpa.repository.EntityGraph;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Modifying;
import org.springframework.data.jpa.repository.Query;
import rdvmedecins.entities.Slot;
public interface SlotRepository extends JpaRepository<Slot, Integer> {
// ein Zeitfenster und sein Arzt
@EntityGraph(attributePaths = "doctor")
Optional<Slot> findWithDoctorById(int id);
// die Zeitfenster eines Arztes, in chronologischer Reihenfolge
List<Slot> findByDoctorIdOrderByStartHourAscStartMinuteAsc(int doctorId);
// löscht alle Zeitfenster eines Arztes (Löschen eines Arztes):
// DELETE FROM slots WHERE doctor_id = ?
@Modifying
@Query("delete from Slot s where s.doctorId = :doctorId")
void deleteByDoctor(int doctorId);
}
|
- Zeile 18: ein gewöhnliches Repository: Entität [Slot], Primärschlüssel [Integer];
- Zeilen 21–22: ein Zeitfenster und sein Arzt ([@EntityGraph(attributePaths = "doctor")]), nach dem Vorbild von [findWithUserById];
- Zeile 25: die Zeitfenster eines Arztes in chronologischer Reihenfolge: [ByDoctorId] filtert nach dem Feld [doctorId] (also der Spalte [doctor_id]), [OrderByStartHourAscStartMinuteAsc] sortiert nach Stunde und dann nach Startminute. [Hibernate] sendet [select ... from slots s1_0 where s1_0.doctor_id=? order by s1_0.start_hour,s1_0.start_minute];
- Zeilen 29–31: das Löschen der Zeitfenster eines Arztes mit einem einzigen [DELETE]. Die Geschäftsschicht ruft diese Methode vor dem Löschen des Arztes auf; andernfalls würde der Fremdschlüssel [slots.doctor_id] das Löschen verhindern. Die Methode heißt nicht [deleteByDoctorId]: Ein solcher Name würde ebenfalls von [Spring Data JPA] interpretiert, aber die abgeleitete Abfrage würde zuerst die Zeitfenster lesen und sie dann einzeln löschen; die Abfrage [@Query] sendet einen einzigen Befehl, [DELETE].
11.11.5. repositories/AppointmentRepository.java
| // =========================================================================
// repositories/AppointmentRepository.java
// -------------------------------------------------------------------------
// DAO-Schicht der Entität [Appointment].
//
// Die JPQL-Abfragen navigieren über die Relationsfelder (a.slot.doctorId) von einer
// Entität zur anderen: Hibernate schreibt die nötigen SQL-Joins
// selbst. "join fetch" liefert die verknüpfte Entität ebenfalls (das Äquivalent
// eines @EntityGraph).
// =========================================================================
package rdvmedecins.repositories;
import java.time.LocalDate;
import java.util.List;
import java.util.Optional;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Modifying;
import org.springframework.data.jpa.repository.Query;
import rdvmedecins.entities.Appointment;
public interface AppointmentRepository extends JpaRepository<Appointment, Integer> {
// ein Termin, sein Client und sein Zeitfenster
@Query("select a from Appointment a join fetch a.client join fetch a.slot where a.id = :id")
Optional<Appointment> read(int id);
// die Termine eines Arztes an einem bestimmten Tag, Client und Zeitfenster eingeschlossen.
// Die Tabelle [appointments] referenziert den Arzt nicht direkt: wir gehen über das Zeitfenster.
@Query("""
select a from Appointment a join fetch a.client join fetch a.slot s
where s.doctorId = :doctorId and a.day = :day""")
List<Appointment> doctorDayAppointments(int doctorId, LocalDate day);
// die Termine eines Clients ab dem Tag [fromDay] (einschließlich), in
// chronologischer Reihenfolge, mit dem Zeitfenster UND dem Arzt dieses Zeitfensters
@Query("""
select a from Appointment a join fetch a.slot s join fetch s.doctor
where a.clientId = :clientId and a.day >= :fromDay
order by a.day, s.startHour, s.startMinute""")
List<Appointment> clientUpcomingAppointments(int clientId, LocalDate fromDay);
// Anzahl der Termine eines Clients ab dem Tag [fromDay] (einschließlich)
long countByClientIdAndDayGreaterThanEqual(int clientId, LocalDate fromDay);
// Anzahl der (vergangenen oder zukünftigen) Termine eines Arztes
@Query("select count(a) from Appointment a where a.slot.doctorId = :doctorId")
long countByDoctor(int doctorId);
// löscht einen Termin: DELETE FROM appointments WHERE id = ?
@Modifying
@Query("delete from Appointment a where a.id = :id")
void remove(int id);
// löscht ALLE (vergangenen und zukünftigen) Termine eines Clients
@Modifying
@Query("delete from Appointment a where a.clientId = :clientId")
void deleteByClient(int clientId);
}
|
Kommentieren wir diesen Code:
- Zeilen 26–27: ein Termin mit seinem Client und seinem Zeitfenster. In [JPQL] führt [join fetch a.client] einen Join aus und lädt die verknüpfte Entität in das Ergebnis: Das ist das in der Abfrage geschriebene Äquivalent zu [@EntityGraph]. Ein Join erfolgt, indem man einem Beziehungsfeld folgt ([a.client]): [Hibernate] kennt den Fremdschlüssel ([@JoinColumn]) und schreibt die Bedingung [on] selbst. Bei [@Query] ist der Methodenname beliebig: Ausgeführt wird die geschriebene Abfrage. Der Name [findById] ist bereits durch die von [JpaRepository] geerbte Methode belegt, die weder den Client noch das Zeitfenster lädt;
- Zeilen 31–34: die Termine eines Arztes für einen bestimmten Tag, jeweils mit ihrem Client und ihrem Zeitfenster. Die Abfrage ist in einem Textblock [Java] (seit [Java] 15) geschrieben: eine durch drei Anführungszeichen ["""] begrenzte Zeichenkette, die sich über mehrere Zeilen erstrecken kann. Die Tabelle [appointments] verweist nicht direkt auf Ärzte: Wir gehen über das Zeitfenster, dem der Join den Alias [s] zuweist, und filtern dann nach [s.doctorId]. [a.day = :day] vergleicht zwei Daten: [Hibernate] übergibt [LocalDate] als SQL-[DATE]-Wert;
- Zeilen 38–42: die Termine eines Patienten ab dem Tag [fromDay] samt ihrem Zeitfenster und dem diesem Zeitfenster zugeordneten Arzt: [join fetch s.doctor] folgt der Beziehung vom Zeitfenster zu seinem Arzt (zwei verkettete Joins). Sortiert wird nach dem Tag, dann nach der Uhrzeit des Zeitfensters. Das zeigt „Mein Konto“ an. Der zugeordnete Arzt hat keinen eigenen Datensatz ([user]): Die Seite benötigt ihn nicht;
- Zeile 45: die Anzahl der Termine eines Clients ab dem Tag [fromDay] für die Regel „nur ein bevorstehender Termin“: [count] erzeugt ein [select count(...)], [GreaterThanEqual] erzeugt den Vergleich [>=]. Das Ergebnis hat den Typ [long];
- Zeilen 48–49: die Anzahl der Termine eines Arztes, um das Löschen eines Arztes zu verhindern, der welche hat. [a.slot.doctorId] folgt der Beziehung [slot] ohne [join fetch]: [Hibernate] fügt den Join mit [slots] zum Filtern hinzu, ohne etwas zu laden;
- Zeilen 52–54: das Stornieren eines Termins über einen direkten [DELETE] -Aufruf. [JpaRepository] stellt zwar [deleteById] bereit, aber diese Methode liest den Termin zuerst und löscht ihn dann;
- Zeilen 57–59: das Löschen aller Termine eines Clients, vergangener wie künftiger: Die Geschäftsschicht ruft dies vor dem Löschen des Clients auf, das der Fremdschlüssel [appointments.client_id] andernfalls verhindern würde.
Hier die Abfrage aus Zeile 42, wie [Hibernate] sie in SQL übersetzt: Die beiden [join fetch]es sind zu zwei Joins geworden, und die Spalten des Zeitfensters und des Arztes werden gleichzeitig mit denen des Termins gelesen:
| Hibernate: select a1_0.id,a1_0.client_id,a1_0.day,s1_0.id,d1_0.id,d1_0.first_name,d1_0.last_name,d1_0.title,d1_0.`user`,d1_0.version,s1_0.doctor_id,s1_0.end_hour,s1_0.end_minute,s1_0.start_hour,s1_0.start_minute,s1_0.version,a1_0.slot_id,a1_0.version from appointments a1_0 join slots s1_0 on s1_0.id=a1_0.slot_id join doctors d1_0 on d1_0.id=s1_0.doctor_id where a1_0.client_id=? and a1_0.day>=? order by a1_0.day,s1_0.start_hour,s1_0.start_minute
|
Beachten Sie, dass ein [join fetch] einen Inner Join erzeugt ([join]), während der [@EntityGraph] aus [PersonRepository] einen Outer Join erzeugte ([left join]): Hier muss jeder Termin ein Zeitfenster und jedes Zeitfenster einen Arzt haben.
11.11.6. repositories/UserRepository.java
| // =========================================================================
// repositories/UserRepository.java
// -------------------------------------------------------------------------
// DAO-Schicht der Entität [User]. Das Erstellen (oder Löschen) eines Arztes oder eines
// Clients erstellt (oder löscht) auch sein Konto - siehe business/BusinessService.java.
// =========================================================================
package rdvmedecins.repositories;
import java.util.Optional;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Modifying;
import org.springframework.data.jpa.repository.Query;
import rdvmedecins.entities.User;
public interface UserRepository extends JpaRepository<User, Integer> {
// Optional.empty(), wenn kein Benutzer diesen Login hat
Optional<User> findByLogin(String login);
@Modifying
@Query("delete from User u where u.id = :id")
void remove(int id);
}
|
- Zeile 20: das zu diesem Login gehörende Konto oder ein leeres [Optional]. Es wird für die Anmeldung ([AuthService]) verwendet und um zu prüfen, ob ein Login verfügbar ist, bevor er vergeben wird;
- Zeilen 22–24: das Löschen eines Kontos über einen direkten [DELETE]-Aufruf. Die Reihenfolge ist die Umkehrung der Erstellung: Die Geschäftsschicht löscht zuerst die Person, die auf das Konto verweist, und dann das Konto.
Erstellung und Änderung von Konten verwenden die von [save] geerbte Methode [JpaRepository]: Bei einer neuen Entität (ID [null]) ruft sie [persist] des [EntityManager] auf (ein [INSERT]); bei einer bereits gespeicherten Entität ruft sie [merge] auf. Wir werden sehen, dass die Geschäftsschicht [save] tatsächlich nur für Erstellungen benötigt.
11.12. Die Geschäftsschicht
Die Geschäftsschicht enthält die Geschäftsregeln der Anwendung: keine Termine in der Vergangenheit, nur ein bevorstehender Termin pro Patient, eindeutige Benutzernamen und Personen sowie die Möglichkeit, einen Arzt oder einen Client zu löschen. Sie stützt sich zum Lesen und Schreiben auf die DAO-Schicht (Ordner [repositories]), öffnet Transaktionen und weiß nichts über HTML oder die Sprache der Oberfläche. Genauer gesagt handelt es sich um die Schicht [PersonsBusiness] aus Beispiel 28.
11.12.1. business/Dates.java
| // =========================================================================
// business/Dates.java
// -------------------------------------------------------------------------
// Das heutige Datum. Es wird von GESCHÄFTSREGELN verwendet (keine Buchung
// in der Vergangenheit, nur ein ZUKÜNFTIGER Termin pro Patient): es gehört daher
// in die Geschäftsschicht. Die Web-Schicht verwendet es wieder.
// =========================================================================
package rdvmedecins.business;
import java.time.LocalDate;
public final class Dates {
private Dates() {
}
// das heutige Datum, in der Zeitzone des Servers
public static LocalDate today() {
return LocalDate.now();
}
}
|
- Zeile 12: eine Hilfsklasse, die lediglich eine Methode namens [static] enthält, die über den Klassennamen aufgerufen wird ([Dates.today()]). [final] verhindert das Ableiten von ihr;
- Zeilen 14–15: Ein [private] -Konstruktor verhindert das Erzeugen von [Dates]-Objekten, was keinen Sinn ergäbe;
- Zeilen 18–20: das heutige Datum in der Zeitzone des Servers in Form eines [LocalDate] (ein Datum ohne Uhrzeit, der Typ von [Appointment.day]). Zwei [LocalDate] -Objekte werden mit den folgenden Methoden verglichen: [day.isBefore(today)], [isAfter], [equals]. Das aktuelle Datum wird für Geschäftsregeln verwendet und befindet sich deshalb in der Geschäftsschicht; die Web-Schicht verwendet es wieder (zum Beispiel in [ScheduleController], um zu bestimmen, ob ein Tag noch buchbar ist).
11.12.2. business/BusinessException.java
| // =========================================================================
// business/BusinessException.java
// -------------------------------------------------------------------------
// Die Exception, die die Geschäftsschicht wirft, wenn eine GESCHÄFTSREGEL
// verletzt wird (Login bereits vergeben, Arzt mit noch bestehenden Terminen, Zeitfenster
// bereits gebucht ...). Sie trägt keinen Text, sondern einen Übersetzungs-
// SCHLÜSSEL (z. B. "ERRORS.LOGIN_TAKEN"): die Web-Schicht übersetzt ihn
// bei der Anzeige der Seite ins Französische oder Englische
// (siehe i18n/fr.json, i18n/en.json).
//
// Eine BusinessException ist keine Anomalie: sie ist eine normale Antwort
// ("dieser Login ist bereits vergeben"), dem Benutzer angezeigt. Jede andere
// Exception ist eine echte Anomalie, die zur Fehlerseite 500 führt.
//
// RuntimeException: eine "unchecked" Exception; die Methoden, die sie
// werfen, müssen sie nicht deklarieren (throws), und Spring bricht die
// von ihr unterbrochene Transaktion ab (ROLLBACK).
// =========================================================================
package rdvmedecins.business;
import java.util.Map;
public class BusinessException extends RuntimeException {
// Übersetzungsschlüssel der Meldung
private final String key;
// mögliche Parameter der Meldung ({minutes}...)
private final Map<String, String> params;
public BusinessException(String key) {
this(key, Map.of());
}
public BusinessException(String key, Map<String, String> params) {
super(key);
this.key = key;
this.params = params;
}
public String getKey() {
return key;
}
public Map<String, String> getParams() {
return params;
}
}
|
- Zeile 23: die Exception, die ausgelöst wird, wenn eine Geschäftsregel eine Operation ablehnt (siehe Beispiel 28). Sie erbt von [RuntimeException]: Es ist eine ungeprüfte (unchecked) Exception. In [Java] muss eine Methode, die eine geprüfte Exception auslösen kann, diese deklarieren ([throws ...]), und der Aufrufer muss sie behandeln; eine ungeprüfte Exception ist von dieser Pflicht ausgenommen. Eine weitere wichtige Folge: [Spring] macht eine durch eine ungeprüfte Exception unterbrochene Transaktion rückgängig ([ROLLBACK]) (während bei [@Transactional] eine geprüfte Exception standardmäßig den Commit der Transaktion zulassen würde);
- Zeilen 26 und 29: der Übersetzungsschlüssel der Meldung ([ERRORS.LOGIN_TAKEN]) und etwaige zugehörige Parameter. Unterschied zu Beispiel 28: Die Exception trägt keinen französischen Text, sondern einen Schlüssel. Die Geschäftsschicht kennt die Sprache der Oberfläche somit nicht: Die Web-Schicht übersetzt den Schlüssel anhand der Wörterbücher [i18n/fr.json] und [i18n/en.json] (siehe Abschnitt „Wörterbücher“). Die Felder sind [final]: Sie werden vom Konstruktor gesetzt und ändern sich nicht;
- Zeilen 31–33: der Konstruktor ohne Meldungsparameter. [this(key, Map.of())] ruft den anderen Konstruktor der Klasse mit einem leeren Wörterbuch auf: [Map.of()] erzeugt ein schreibgeschütztes Wörterbuch. Die Web-Schicht muss daher nie auf [null] prüfen. Die von [BusinessService] ausgelösten Exceptions verwenden tatsächlich nur diesen Konstruktor;
- Zeile 36: [super(key)] übergibt den Schlüssel an den Konstruktor der Elternklasse, die ihn als Exception-Meldung verwendet ([getMessage()]), nützlich in Fehlerprotokollen;
- Zeilen 41–47: die Zugriffsmethoden.
Eine [BusinessException] ist kein Fehler: Sie ist eine normale Antwort („dieser Login ist bereits vergeben“), die die Controller abfangen, um sie dem Benutzer anzuzeigen, entweder auf der Seite oder in einer Pop-up-Meldung. Jede andere Exception ist ein echter Fehler, der zu einer Fehlerseite 500 führt.
11.12.3. business/Business.java
| // =========================================================================
// business/Business.java
// -------------------------------------------------------------------------
// Der Vertrag der Geschäftsschicht: Lesezugriffe, Terminkalender, Termine, Verwaltung
// der Ärzte und der Clients.
//
// Optional<T>: ein Ergebnis, das fehlen kann (ein Arzt, der nicht existiert
// ...). Der Aufrufer ist gezwungen, diesen Fall zu behandeln: kein vergessenes null.
// =========================================================================
package rdvmedecins.business;
import java.time.LocalDate;
import java.util.List;
import java.util.Optional;
import rdvmedecins.domain.DoctorDaySchedule;
import rdvmedecins.entities.Client;
import rdvmedecins.entities.Slot;
import rdvmedecins.entities.Doctor;
import rdvmedecins.entities.Appointment;
public interface Business {
// ------------------------------------------------ Lesezugriffe
List<Client> getAllClients();
List<Doctor> getAllDoctors();
List<Slot> getAllSlots(int doctorId);
List<Appointment> getDoctorDayAppointments(int doctorId, LocalDate day);
Optional<Client> getClientById(int id);
Optional<Doctor> getDoctorById(int id);
Optional<Appointment> getAppointmentById(int id);
Optional<Slot> getSlotById(int id);
Optional<DoctorDaySchedule> getDoctorDaySchedule(int doctorId, LocalDate day);
// der Client (Patient), dessen Benutzerkonto [userId] ist
Optional<Client> getClientByUserId(int userId);
// die Termine eines Clients, von heute oder in der Zukunft, mit Zeitfenster und Arzt
List<Appointment> getClientUpcomingAppointments(int clientId);
// ------------------------------------------------ Termine (ADMIN, DOCTOR, USER)
// wirft eine BusinessException, wenn:
// - der Tag in der Vergangenheit liegt ("ERRORS.PAST_DATE");
// - der Patient bereits einen bevorstehenden Termin hat ("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
// - das Zeitfenster an diesem Tag bereits gebucht ist ("ERRORS.SLOT_ALREADY_BOOKED").
Appointment addAppointment(LocalDate day, Slot slot, Client client);
void deleteAppointment(Appointment appointment);
// ------------------------------------------------ Ärzte (ADMIN)
// erstellt den Arzt UND sein Benutzerkonto (Rolle DOCTOR)
Doctor addDoctor(PersonData data);
// bearbeitet den Arzt UND sein Benutzerkonto
Doctor editDoctor(int id, PersonData data);
// löscht den Arzt, seine Zeitfenster UND sein Konto - abgelehnt, wenn er Termine hat
void deleteDoctor(int id);
// ------------------------------------------------ Clients
// (der ADMIN; addClient wird auch für die Registrierung eines Patienten verwendet,
// editClient und deleteClient vom Patienten für sein eigenes Konto)
// erstellt den Client UND sein Benutzerkonto (Rolle USER)
Client addClient(PersonData data);
Client editClient(int id, PersonData data);
// löscht den Client, sein Konto UND alle seine Termine (vergangene und zukünftige)
void deleteClient(int id);
}
|
- Zeile 22: der Vertrag der Geschäftsschicht: was die anderen Schichten von ihr anfordern können, ohne festzulegen, wie es geschieht (Schnittstellen wurden in Beispiel 06 behandelt);
- Zeilen 25–47: die Lesezugriffe. Diejenigen, die möglicherweise nichts finden (Zeilen 33–44), liefern ein [Optional]: Ein unbekannter Arzt liefert ein leeres [Optional], nie ein [null]. Die Listen sind dagegen leer, wenn es nichts zurückzugeben gibt;
- Zeilen 50–56: Termine. Der Kommentar zu [addAppointment] listet die möglichen Fehlercodes auf: Das gehört zum Vertrag, den die Controller kennen müssen;
- Zeilen 60–66: Arztverwaltung (ADMIN vorbehalten). Jeder Arzt wird zusammen mit seinem Benutzerkonto erstellt, geändert und gelöscht;
- Zeilen 72–77: Client-Verwaltung nach derselben Logik. [addClient] dient auch dazu, einen Patienten zu registrieren, während [editClient] und [deleteClient] für Patienten verwendet werden, die ihre eigenen Konten verwalten.
Die Methoden einer Schnittstelle sind implizit [public] und [abstract]: Sie werden nicht ausdrücklich so definiert. Zwei Beans implementieren diesen Vertrag: [BusinessService], das weiter unten vorgestellt wird, und [ApplicationModel] (Ordner [web]), das ihn um einen Cache der Arzt- und Client-Listen erweitert und den Rest an [BusinessService] delegiert (siehe Abschnitt „Die Web-Schicht: gemeinsame Services“). Die Controller verwenden [ApplicationModel].
11.12.4. business/PersonData.java
| // =========================================================================
// business/PersonData.java
// -------------------------------------------------------------------------
// Die im Formular "Arzt" oder "Client" eingegebenen Daten, wie
// die Web-Schicht sie an die Geschäftsschicht weitergibt.
// =========================================================================
package rdvmedecins.business;
public record PersonData(
String title, // Mr, Mme, Melle
String lastName,
String firstName,
// Erstellung: optional (null), standardmäßig der Nachname in Kleinbuchstaben
// Bearbeitung: optional, der Login bleibt unverändert, wenn er fehlt
String login,
// Erstellung: optional, standardmäßig der Login
// Bearbeitung: optional, das Passwort bleibt unverändert, wenn es fehlt
String password,
// Bearbeitung: die Version des Datensatzes zum Zeitpunkt der Anzeige des
// Formulars (optimistische Sperre, siehe AbstractEntity.version)
Integer version) {
}
|
Die Daten eines zu erstellenden oder zu ändernden Arztes oder Clients, wie sie von der Web-Schicht übergeben werden (siehe Beispiel 28): ein Record, dessen Komponenten hier zeilenweise geschrieben sind, um Platz für Kommentare zu lassen (Zeilen 9–21). Anrede, Nachname und Vorname sind immer angegeben. Benutzername und Passwort (Zeilen 15 und 18) sind optional und werden auf [null] gesetzt, wenn sie nicht eingegeben werden: Bei der Erstellung ist der Standardwert der Nachname in Kleinbuchstaben; bei der Änderung bleiben sie unverändert. [version] (Zeile 21) ist die Version des Datensatzes, die beim Anzeigen des Bearbeitungsformulars gelesen wurde: Sie dient der optimistischen Sperre. Ihr Typ ist [Integer], nicht [int], damit sie [null] sein kann (bei der Erstellung gibt es keine Version).
11.12.5. business/BusinessService.java
Dies ist die umfangreichste Datei der Anwendung. Wir zeigen sie in fünf aufeinanderfolgenden Ausschnitten.
11.12.5.1. Die Deskriptoren
| // =========================================================================
// business/BusinessService.java
// -------------------------------------------------------------------------
// Implementierung der Geschäftsschicht.
//
// Die Verwaltung der Ärzte und Clients folgt drei Geschäftsregeln:
//
// 1. eine Person (Arzt oder Client) und ihr Benutzerkonto gehören IMMER
// zusammen: sie werden gemeinsam erstellt, bearbeitet und gelöscht, in
// derselben TRANSAKTION - entweder gelingt alles, oder nichts wird geschrieben;
// 2. der Login ist in der gesamten Anwendung eindeutig, und zwei Ärzte (oder
// zwei Clients) dürfen nicht denselben Vor- und Nachnamen haben;
// 3. Löschen:
// - ein ARZT mit Terminen kann nicht gelöscht werden (seine
// Patienten würden ihren Termin verlieren, ohne gewarnt zu werden): diese müssen
// zuerst storniert werden. Seine Zeitfenster verschwinden mit ihm;
// - ein CLIENT hingegen verschwindet mit ALLEN seinen Terminen (vergangenen und
// zukünftigen) - ob das Löschen vom ADMIN oder vom Patienten
// selbst ausgeht.
//
// Und zwei Regeln für die Buchung eines Termins, unabhängig von der Rolle
// dessen, der bucht (ADMIN, DOCTOR oder der Patient selbst):
// 4. kein Termin in der Vergangenheit;
// 5. ein Patient hat jeweils nur EINEN bevorstehenden Termin.
//
// Ärzte und Clients folgen genau denselben Regeln: der gemeinsame Code
// wird nur EINMAL geschrieben (generische private Methoden xxxPerson) und durch
// einen kleinen "Descriptor" parametrisiert, der angibt, mit welchem Personentyp wir es zu tun haben.
//
// Die TRANSAKTIONEN werden explizit durch ein TransactionTemplate geöffnet
// (siehe die Methode transaction, am Ende der Datei), um die Fehler, die die Datenbank
// zum Zeitpunkt des COMMIT meldet, in BusinessException zu übersetzen.
// =========================================================================
package rdvmedecins.business;
import java.time.LocalDate;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import java.util.function.Function;
import java.util.function.IntConsumer;
import java.util.function.IntToLongFunction;
import java.util.function.Supplier;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Collectors;
import org.springframework.core.NestedExceptionUtils;
import org.springframework.dao.DataIntegrityViolationException;
import org.springframework.dao.OptimisticLockingFailureException;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.stereotype.Service;
import org.springframework.transaction.support.TransactionTemplate;
import rdvmedecins.domain.DoctorDaySchedule;
import rdvmedecins.domain.DoctorDaySlot;
import rdvmedecins.entities.Client;
import rdvmedecins.entities.Slot;
import rdvmedecins.entities.Doctor;
import rdvmedecins.entities.Person;
import rdvmedecins.entities.Role;
import rdvmedecins.entities.Appointment;
import rdvmedecins.entities.User;
import rdvmedecins.repositories.ClientRepository;
import rdvmedecins.repositories.SlotRepository;
import rdvmedecins.repositories.DoctorRepository;
import rdvmedecins.repositories.PersonRepository;
import rdvmedecins.repositories.AppointmentRepository;
import rdvmedecins.repositories.UserRepository;
// @Service: eine Bean der Geschäftsschicht; eine einzige Instanz (Singleton)
// für die gesamte Anwendung
@Service
public class BusinessService implements Business {
// alles, was einen Arzt für die Geschäftsregeln von einem Client unterscheidet
private record Descriptor<T extends Person>(
PersonRepository<T> dao,
Supplier<T> factory, // Doctor::new oder Client::new
Role role, // DOCTOR oder USER
String notFoundKey, // Meldung, wenn die Person nicht existiert
String alreadyExistsKey, // Meldung, wenn derselbe Vor- und Nachname bereits existiert
// optional (null): falls vorhanden, wird das Löschen ABGELEHNT, solange
// die Person Termine hat (countAppointments > 0), mit der Meldung hasAppointmentsKey
IntToLongFunction countAppointments,
String hasAppointmentsKey,
// optional: was VOR der Person gelöscht werden muss (die Zeilen,
// die sie über einen Fremdschlüssel referenzieren)
IntConsumer beforeDelete) {
}
private final DoctorRepository doctorRepository;
private final ClientRepository clientRepository;
private final SlotRepository slotRepository;
private final AppointmentRepository appointmentRepository;
private final UserRepository userRepository;
private final PasswordEncoder hasher;
private final TransactionTemplate transactions;
private final Descriptor<Doctor> doctorDescriptor;
private final Descriptor<Client> clientDescriptor;
// alle Abhängigkeiten werden von der Dependency Injection von
// Spring bereitgestellt. TransactionTemplate: eine von Spring Boot bereitgestellte Bean, die
// Code in einer Transaktion ausführt.
public BusinessService(DoctorRepository doctorRepository, ClientRepository clientRepository,
SlotRepository slotRepository, AppointmentRepository appointmentRepository, UserRepository userRepository,
PasswordEncoder hasher, TransactionTemplate transactions) {
this.doctorRepository = doctorRepository;
this.clientRepository = clientRepository;
this.slotRepository = slotRepository;
this.appointmentRepository = appointmentRepository;
this.userRepository = userRepository;
this.hasher = hasher;
this.transactions = transactions;
doctorDescriptor = new Descriptor<>(
doctorRepository,
Doctor::new,
Role.DOCTOR,
"ERRORS.DOCTOR_NOT_FOUND",
"ERRORS.DOCTOR_ALREADY_EXISTS",
appointmentRepository::countByDoctor,
"ERRORS.DOCTOR_HAS_APPOINTMENTS",
// ein Arzt ohne Termine kann noch Zeitfenster haben:
// sie ergeben ohne ihn keinen Sinn mehr, wir löschen sie mit (sonst würde
// der Fremdschlüssel slots.doctor_id das Löschen verbieten)
slotRepository::deleteByDoctor);
clientDescriptor = new Descriptor<>(
clientRepository,
Client::new,
Role.USER,
"ERRORS.PATIENT_NOT_FOUND",
"ERRORS.PATIENT_ALREADY_EXISTS",
// kein countAppointments: das Löschen eines Clients wird nie abgelehnt;
// seine Termine (vergangene und zukünftige) werden mitgelöscht (sonst würde
// der Fremdschlüssel appointments.client_id das Löschen verbieten)
null,
null,
appointmentRepository::deleteByClient);
}
|
- Zeilen 6–24: Der Kopfkommentar fasst die fünf von der Klasse angewandten Geschäftsregeln zusammen;
- Zeilen 50–52: die Exceptions von [Spring] , die einen Datenbankfehler anzeigen, und ein Hilfsmittel zu ihrer Untersuchung (siehe den letzten Ausschnitt);
- Zeile 53: die Schnittstelle [PasswordEncoder] von [Spring Security], die die [bcrypt]-Hashes berechnet (siehe Beispiel 25). Die zugehörige Bean, ein [BCryptPasswordEncoder] mit dem Kostenfaktor 10 (demselben wie bei den Passwörtern im SQL-Skript), wird in [config/SecurityConfig.java] deklariert (siehe Abschnitt „Authentifizierung“);
- Zeile 55: [TransactionTemplate], das Code innerhalb einer Transaktion ausführt (siehe den letzten Ausschnitt);
- Zeilen 75–76: [@Service] macht die Klasse zu einer Bean der Geschäftsschicht. Wie alle Beans ist sie standardmäßig ein Singleton: eine einzige Instanz für die gesamte Anwendung, die von allen Anfragen gemeinsam genutzt wird. Das ist unproblematisch, da das Objekt keine anfragespezifischen Daten speichert: Seine Felder sind Abhängigkeiten, die ein für alle Mal gesetzt werden. Der Name der Bean ist der der Klasse mit kleingeschriebenem Anfangsbuchstaben: [businessService], der Name, auf den [ApplicationModel] in seinem [@Qualifier] verweist. Die Klasse implementiert die Schnittstelle [Business]: Sie muss alle ihre Methoden bereitstellen;
- Zeilen 79–92: alles, was einen Arzt in Bezug auf die Geschäftsregeln von einem Client unterscheidet: sein Repository, die Art, ein leeres Objekt zu erzeugen, die Rolle seines Kontos ([DOCTOR] oder [USER]), seine Fehlermeldungen und was beim Löschen geschieht. Da Ärzte und Clients denselben Regeln folgen, wird der Code für diese Regeln nur einmal geschrieben, und zwar in generischen Methoden, die einen Deskriptor entgegennehmen. Der Deskriptor ist ein generischer Record, der innerhalb der Klasse deklariert ist (und [private]: Niemand sonst verwendet ihn);
- Zeilen 81, 87 und 91: drei funktionale Schnittstellen des Pakets [java.util.function] – Schnittstellen mit einer einzigen Methode, die den Typ einer Funktion beschreiben. [Supplier<T>] ist eine parameterlose Funktion, die ein [T] zurückgibt (Methode [get()]); [IntToLongFunction] eine Funktion, die ein [int] entgegennimmt und ein [long] zurückgibt (Methode [applyAsLong]); [IntConsumer] eine Funktion, die ein [int] entgegennimmt und nichts zurückgibt (Methode [accept]). Ein Wert dieses Typs kann als Lambda ([x -> ...]) oder als Methodenreferenz ([Class::method]) geschrieben werden;
- Zeilen 94–102: die Felder der Klasse: die fünf Repositories, der Hash-Rechner, [TransactionTemplate] und die beiden Deskriptoren. [final] verhindert, dass sie nach dem Konstruktor geändert werden.
- Zeilen 107–109: Alle Abhängigkeiten werden per Dependency Injection von [Spring] bereitgestellt: Die Klasse hat nur einen Konstruktor, den [Spring] mit den Beans der angeforderten Typen aufruft. Die Repositories sind die von [Spring Data JPA] erzeugten Implementierungen; [TransactionTemplate] wird von [Spring Boot] erstellt;
- Zeilen 118–129: der Deskriptor für Ärzte. [new Descriptor<>(...)]: Das Diamant-Symbol [<>] erlaubt es dem Compiler, den Typparameter ([Doctor]) der Variablen abzuleiten, die das Objekt erhält. Die Werte werden in der Reihenfolge der Komponenten des Records angegeben;
- Zeile 120: [Doctor::new] ist eine Konstruktorreferenz: eine parameterlose Funktion, die ein [new Doctor()] zurückgibt. Sie hat den erwarteten Typ [Supplier<Doctor>]. Sie wird hier nicht aufgerufen, sondern jedes Mal, wenn ein Arzt angelegt wird;
- Zeile 124: [appointmentRepository::countByDoctor] ist eine Methodenreferenz: die Methode [countByDoctor] des Objekts [appointmentRepository], die einen [int] entgegennimmt und einen [long] zurückgibt – also einen Wert vom Typ [IntToLongFunction]. Das Löschen eines Arztes wird verweigert, solange er Termine hat;
- Zeile 129: entsprechend ist [slotRepository::deleteByDoctor] (mit einem [int], ohne Ergebnis) ein [IntConsumer]: Die Zeitfenster eines Arztes werden gelöscht, bevor der Arzt selbst gelöscht wird;
- Zeilen 131–142: der Deskriptor für Patienten. [Java] kennt weder benannte noch optionale Parameter: Die beiden überflüssigen Komponenten ([countAppointments] und [hasAppointmentsKey]) erhalten den Wert [null] (Zeilen 140–141). Das Löschen eines Patienten wird daher nie verweigert, und seine Termine (vergangene und künftige) werden vor dem Patienten selbst gelöscht; andernfalls würde der Fremdschlüssel [appointments.client_id] das Löschen verhindern.
11.12.5.2. Lesevorgänge und der Terminkalender
| // =======================================================================
// Lesezugriffe, außerhalb jeder Transaktion (jede DAO-Abfrage läuft allein,
// mit einem für die Dauer des Aufrufs geöffneten EntityManager)
// =======================================================================
@Override
public List<Client> getAllClients() {
return clientRepository.findAllByOrderByLastNameAscFirstNameAsc();
}
@Override
public List<Doctor> getAllDoctors() {
return doctorRepository.findAllByOrderByLastNameAscFirstNameAsc();
}
@Override
public List<Slot> getAllSlots(int doctorId) {
return slotRepository.findByDoctorIdOrderByStartHourAscStartMinuteAsc(doctorId);
}
@Override
public List<Appointment> getDoctorDayAppointments(int doctorId, LocalDate day) {
return appointmentRepository.doctorDayAppointments(doctorId, day);
}
@Override
public Optional<Client> getClientById(int id) {
return clientRepository.findWithUserById(id);
}
@Override
public Optional<Doctor> getDoctorById(int id) {
return doctorRepository.findWithUserById(id);
}
@Override
public Optional<Appointment> getAppointmentById(int id) {
return appointmentRepository.read(id);
}
@Override
public Optional<Slot> getSlotById(int id) {
return slotRepository.findWithDoctorById(id);
}
@Override
public Optional<Client> getClientByUserId(int userId) {
return clientRepository.findByUserId(userId);
}
@Override
public List<Appointment> getClientUpcomingAppointments(int clientId) {
return appointmentRepository.clientUpcomingAppointments(clientId, Dates.today());
}
// derselbe Algorithmus wie beim JSON-Server (und beim ursprünglichen Spring-Projekt)
@Override
public Optional<DoctorDaySchedule> getDoctorDaySchedule(int doctorId, LocalDate day) {
Optional<Doctor> doctor = getDoctorById(doctorId);
if (doctor.isEmpty()) {
return Optional.empty();
}
List<Slot> timeSlots = getAllSlots(doctorId);
// Nr. des Zeitfensters -> in diesem Zeitfenster gebuchter Termin
Map<Integer, Appointment> bookings = getDoctorDayAppointments(doctorId, day).stream()
.collect(Collectors.toMap(Appointment::getSlotId, Function.identity()));
List<DoctorDaySlot> doctorDaySlots = timeSlots.stream()
.map(slot -> new DoctorDaySlot(slot, bookings.get(slot.getId())))
.toList();
return Optional.of(new DoctorDaySchedule(doctor.get(), day, doctorDaySlots));
}
|
- Zeilen 6–54: Die Lesevorgänge delegieren einfach an die DAO-Schicht und übersetzen dabei die Namen der Repository-Methoden (die oft von [Spring Data JPA] vorgegeben sind) in fachliche Namen. [@Override] kennzeichnet eine Methode, die eine Methode der Schnittstelle implementiert: Der Compiler prüft, dass sie dort tatsächlich existiert, in [Business]. Diese Methoden starten keine Transaktion: Jede Abfrage läuft für sich, mit einem [EntityManager] , der für die Dauer des Aufrufs erstellt wird (siehe den Abschnitt „JPA, Hibernate und Spring Data“). Jede Methode lädt die von den Seiten benötigten Beziehungen (das Konto einer Person, den Arzt eines Zeitfensters, den Patienten und das Zeitfenster eines Termins): Die zurückgegebenen Entitäten sind detached, und Controller und Views können diese Beziehungen gefahrlos lesen;
- Zeile 53: die künftigen Termine eines Patienten: Die Geschäftsschicht übergibt dem Repository das aktuelle Datum;
- Zeilen 58–71: Berechnung des Terminkalenders eines Arztes für einen bestimmten Tag. Ein unbekannter Arzt liefert ein leeres [Optional] ([Optional.empty()]); andernfalls werden die Zeitfenster des Arztes und die Termine des Tages abgerufen. Der Terminkalender führt drei aufeinanderfolgende, voneinander unabhängige Lesevorgänge aus: Das ist für eine angezeigte Seite akzeptabel, die der Benutzer bei Bedarf neu lädt;
- Zeilen 65–66: Die Termine des Tages werden in einem Dictionary ([Map]) abgelegt, dessen Schlüssel der Bezeichner ihres Zeitfensters ist. [stream()] wandelt die Liste in einen Stream um: eine Folge von Elementen, die mit verketteten Operationen verarbeitet werden. [collect(Collectors.toMap(...))] legt die Elemente des Streams in einem Dictionary ab: Der Schlüssel jedes Termins wird von [Appointment::getSlotId] berechnet (eine Methodenreferenz, die auf jeden Termin angewendet wird), der Wert von [Function.identity()], der Funktion, die ihr Argument zurückgibt: den Termin selbst. [toMap] würde fehlschlagen, wenn zwei Schlüssel gleich wären, doch das kann nicht passieren: Die Constraint [unq1_appointments] verhindert, dass zwei Termine am selben Tag im selben Zeitfenster liegen. Das Dictionary erspart es, für jedes Zeitfenster die gesamte Terminliste zu durchlaufen;
- Zeilen 67–69: Jedes Zeitfenster wird mit seinem Termin verknüpft oder mit [null]: [get] gibt [null] zurück, wenn der Schlüssel fehlt, also wenn das Zeitfenster frei ist. [map] transformiert jedes Element des Streams mithilfe des Lambda-Ausdrucks [slot -> new DoctorDaySlot(...)]: eine anonyme Funktion, deren Parameter [slot] links vom Pfeil steht und deren Ergebnis rechts davon. [toList()] sammelt das Ergebnis in einer schreibgeschützten Liste. Die chronologische Reihenfolge der Zeitfenster, wie sie die Abfrage vorgibt, bleibt erhalten;
- Zeile 70: der Terminkalender in einem gefüllten [Optional] ([Optional.of]); [doctor.get()] extrahiert den Arzt aus seinem [Optional], von dem wir hier wissen, dass er nicht leer ist. Das Ergebnis ist ein Objekt des [DoctorDaySchedule]-Records [domain], den die Kalenderansicht anzeigen wird.
11.12.5.3. Einen Termin buchen
| // =======================================================================
// Termine
// =======================================================================
// -----------------------------------------------------------------------
// Buchung eines Termins, in einer Transaktion:
// 1. kein Termin in der Vergangenheit;
// 2. wir SPERREN die Zeile des Patienten (SELECT ... FOR UPDATE): bucht
// derselbe Patient zwei Zeitfenster im selben Moment (zwei Tabs,
// Doppelklick ...), wartet die zweite Transaktion auf das Ende der
// ersten - und sieht dann den Termin, den diese gerade erstellt hat;
// 3. nur ein bevorstehender Termin pro Patient;
// 4. schließlich das Einfügen. Wurde das Zeitfenster gerade von einem ANDEREN
// Patienten belegt, lehnt der SQL-Constraint unq1_appointments (day, slot_id)
// das Einfügen ab - von [transaction] in BusinessException übersetzt.
// -----------------------------------------------------------------------
@Override
public Appointment addAppointment(LocalDate day, Slot slot, Client client) {
return transaction(() -> {
LocalDate today = Dates.today();
if (day.isBefore(today)) {
throw new BusinessException("ERRORS.PAST_DATE");
}
int patientId = clientRepository.lock(client.getId())
.orElseThrow(() -> new BusinessException("ERRORS.PATIENT_NOT_FOUND"));
if (appointmentRepository.countByClientIdAndDayGreaterThanEqual(patientId, today) > 0) {
throw new BusinessException("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
}
// getReferenceById: eine "Referenz" auf das Zeitfenster und den Patienten,
// ohne sie erneut aus der Datenbank zu lesen - ihre id zu kennen genügt, um
// die Fremdschlüssel zu schreiben
Slot slotRef = slotRepository.getReferenceById(slot.getId());
Client patientRef = clientRepository.getReferenceById(patientId);
return appointmentRepository.save(new Appointment(day, slotRef, patientRef));
});
}
@Override
public void deleteAppointment(Appointment appointment) {
transaction(() -> {
appointmentRepository.remove(appointment.getId());
return null;
});
}
|
- Zeilen 19 und 35: Die gesamte Buchung findet innerhalb einer Transaktion statt: Die Methode übergibt [transaction] (siehe den letzten Auszug) einen parameterlosen Lambda-Ausdruck, [() -> { ... }], der die Aufgabe ausführt und den erstellten Termin zurückgibt. Ein Lambda-Ausdruck kann die Parameter der umgebenden Methode verwenden ([day], [slot], [client]), sofern sie nie geändert werden;
- Zeilen 21–23: keine Termine in der Vergangenheit. Diese Regel wird hier unabhängig von der Rolle der buchenden Person (ADMIN, DOCTOR oder Patient) durchgesetzt, selbst wenn die Web-Schicht die Schaltflächen „Buchen“ für vergangene Daten bereits ausgeblendet hat: Eine Anfrage kann manuell erzeugt werden;
- Zeilen 24–25: Die Zeile des Patienten wird gesperrt mit [SELECT ... FOR UPDATE] (siehe [ClientRepository]). Das ist eine pessimistische Sperre: Sie wird vor Beginn jeder Arbeit erworben, geht von einem möglichen Konflikt aus und bleibt bis zum Ende der Transaktion bestehen. Ohne sie könnten zwei gleichzeitig gesendete Buchungen für denselben Patienten (zwei Tabs, ein Doppelklick) beide den folgenden Test bestehen, bevor eine von ihnen ihren Termin gespeichert hat. Mit der Sperre wartet die zweite Transaktion, bis die erste beendet ist, und sieht dann den von ihr erstellten Termin. Ein Patient, der nicht gefunden wird (zwischenzeitlich gelöscht), wird abgelehnt: [orElseThrow] gibt den Inhalt des [Optional] zurück oder löst, falls er leer ist, die vom Lambda-Ausdruck erzeugte Ausnahme aus;
- Zeilen 26–28: nur ein künftiger Termin pro Patient;
- Zeilen 32–33: [getReferenceById] gibt eine Referenz auf eine Entität zurück – einen Stellvertreter –, die nur den Bezeichner enthält, ohne die Zeile aus der Datenbank zu lesen. Um die Fremdschlüssel für die Zeile [appointments] zu schreiben, genügt es, die Bezeichner des Zeitfensters und des Patienten zu kennen; sie müssen nicht erneut gelesen werden. Die als Parameter erhaltenen Objekte [slot] und [client] verwenden wir nicht direkt: Sie stammen aus der Web-Schicht, sind detached und gehören nicht zum Persistenzkontext dieser Transaktion;
- Zeile 34: das Einfügen. [save] speichert den neuen Termin (Schlüssel [IDENTITY]: [INSERT] wird sofort abgesetzt) und gibt ihn zurück. Wenn ein anderer Patient soeben dasselbe Zeitfenster gebucht hat, hat die Sperre dies nicht verhindert (sie gilt für den Datensatz des Patienten): Es ist die Eindeutigkeitsbedingung der Datenbank [unq1_appointments (day, slot_id)] , die das Einfügen ablehnt, und [transaction] übersetzt den Fehler in eine [BusinessException] mit dem Schlüssel [ERRORS.SLOT_ALREADY_BOOKED];
- Zeilen 39–44: Stornierung eines Termins, ohne besondere Regeln. Die Methode [remove] im Repository ist eine [@Modifying]-Abfrage: Sie benötigt eine Transaktion, die Schreibzugriffe erlaubt, daher der Aufruf von [transaction]. Der Lambda-Ausdruck muss einen Wert zurückgeben: Er gibt [null] zurück, den niemand verwendet.
Hier sind die bei einer Buchung gesendeten SQL-Befehle, wie sie in der Konsole protokolliert werden. Der erste liest das Zeitfenster und seinen Arzt ([getSlotById], vom Controller vor [addAppointment] aufgerufen); die nächsten drei gehören zur Transaktion: die Sperre, die Zählung und das Einfügen. Dank [getReferenceById] werden weder das Zeitfenster noch der Patient erneut gelesen:
| Hibernate: select s1_0.id,d1_0.id,d1_0.first_name,d1_0.last_name,d1_0.title,d1_0.`user`,d1_0.version,s1_0.doctor_id,s1_0.end_hour,s1_0.end_minute,s1_0.start_hour,s1_0.start_minute,s1_0.version from slots s1_0 left join doctors d1_0 on d1_0.id=s1_0.doctor_id where s1_0.id=?
Hibernate: select id from clients where id = ? for update
Hibernate: select count(a1_0.id) from appointments a1_0 where a1_0.client_id=? and a1_0.day>=?
Hibernate: insert into appointments (client_id,day,slot_id,version) values (?,?,?,?)
|
[INSERT] schreibt auch die Spalte [version]: [Hibernate] weist jeder neuen Entität die Version 0 zu.
11.12.5.4. Verwaltung von Ärzten und Patienten
| // =======================================================================
// Ärzte und Clients - die öffentlichen Methoden delegieren an die gemeinsamen
// privaten Methoden, mit dem passenden Descriptor
// =======================================================================
@Override
public Doctor addDoctor(PersonData data) {
return addPerson(doctorDescriptor, data);
}
@Override
public Doctor editDoctor(int id, PersonData data) {
return editPerson(doctorDescriptor, id, data);
}
@Override
public void deleteDoctor(int id) {
deletePerson(doctorDescriptor, id);
}
@Override
public Client addClient(PersonData data) {
return addPerson(clientDescriptor, data);
}
@Override
public Client editClient(int id, PersonData data) {
return editPerson(clientDescriptor, id, data);
}
// der Client, sein Konto UND alle seine Termine (ADMIN oder der Patient
// selbst über "Mein Konto verwalten": dieselbe Methode, dieselbe Regel)
@Override
public void deleteClient(int id) {
deletePerson(clientDescriptor, id);
}
// -----------------------------------------------------------------------
// Erstellung: zuerst das Benutzerkonto (die Person referenziert es),
// dann die Person - alles in EINER Transaktion.
// -----------------------------------------------------------------------
private <T extends Person> T addPerson(Descriptor<T> d, PersonData data) {
String lastName = data.lastName().trim().toUpperCase(Locale.ROOT);
String firstName = data.firstName().trim();
// die Regeln der Datenbank dbrdvmedecins2: Login = Nachname in Kleinbuchstaben,
// Passwort = Login - es sei denn, der ADMIN hat andere eingegeben
String login = (empty(data.login()) ? lastName : data.login()).toLowerCase(Locale.ROOT);
String password = empty(data.password()) ? login : data.password();
return transaction(() -> {
checkPersonUnique(d, firstName, lastName, null);
checkLoginFree(login);
User user = new User();
user.setLogin(login);
user.setPassword(hasher.encode(password));
user.setName(firstName + " " + lastName);
user.setRole(d.role());
userRepository.save(user);
T person = d.factory().get();
person.setTitle(data.title());
person.setLastName(lastName);
person.setFirstName(firstName);
person.setUser(user);
return d.dao().save(person);
});
}
// -----------------------------------------------------------------------
// Bearbeitung: die Person UND ihr Konto (der Anzeigename "firstName LASTNAME"
// muss mitziehen; Login und Passwort ändern sich nur, wenn sie
// eingegeben wurden).
// -----------------------------------------------------------------------
private <T extends Person> T editPerson(Descriptor<T> d, int id, PersonData data) {
return transaction(() -> {
T person = d.dao().findWithUserById(id).orElseThrow(() -> new BusinessException(d.notFoundKey()));
// optimistische Sperre: entspricht die Version in der Datenbank nicht mehr der des
// Formulars, hat jemand diesen Datensatz inzwischen bearbeitet - wir lehnen ab,
// statt seine Änderungen stillschweigend zu überschreiben.
// (Erfolgt die gleichzeitige Bearbeitung NACH diesem Lesen, erkennt es
// die Klausel "WHERE version = ..." des UPDATE.)
if (data.version() != null && !data.version().equals(person.getVersion())) {
throw new BusinessException("ERRORS.CONCURRENT_UPDATE");
}
String lastName = data.lastName().trim().toUpperCase(Locale.ROOT);
String firstName = data.firstName().trim();
checkPersonUnique(d, firstName, lastName, id);
// wir ändern lediglich die Objekte: die in der
// Transaktion gelesene Entität wird von JPA "verwaltet", das die nötigen UPDATEs beim
// COMMIT selbst sendet (save muss nicht aufgerufen werden)
person.setTitle(data.title());
person.setLastName(lastName);
person.setFirstName(firstName);
User user = person.getUser();
user.setName(firstName + " " + lastName);
if (!empty(data.login()) && !data.login().toLowerCase(Locale.ROOT).equals(user.getLogin())) {
String login = data.login().toLowerCase(Locale.ROOT);
checkLoginFree(login);
user.setLogin(login);
}
if (!empty(data.password())) {
user.setPassword(hasher.encode(data.password()));
}
return person;
});
}
// -----------------------------------------------------------------------
// Löschen, in EINER Transaktion, in der von den Fremdschlüsseln
// vorgegebenen Reihenfolge:
// 1. mögliche Ablehnung, wenn Termine bestehen (Arzt);
// 2. was die Person referenziert (Zeitfenster eines Arztes, Termine
// eines Clients);
// 3. die Person (sie referenziert ihr Konto);
// 4. ihr Konto.
// -----------------------------------------------------------------------
private <T extends Person> void deletePerson(Descriptor<T> d, int id) {
transaction(() -> {
T person = d.dao().findById(id).orElseThrow(() -> new BusinessException(d.notFoundKey()));
if (d.countAppointments() != null && d.countAppointments().applyAsLong(id) > 0) {
throw new BusinessException(d.hasAppointmentsKey());
}
if (d.beforeDelete() != null) {
d.beforeDelete().accept(id);
}
d.dao().remove(id);
userRepository.remove(person.getUserId());
return null; // [transaction] erwartet ein Ergebnis: hier brauchen wir keines
});
}
// lehnt Vor- und Nachnamen ab, die bereits von einer ANDEREN Person desselben Typs verwendet werden
// (currentId: die bearbeitete Person, die offensichtlich das
// Recht hat, ihren eigenen Vor- und Nachnamen zu behalten; null bei einer Erstellung)
private <T extends Person> void checkPersonUnique(Descriptor<T> d, String firstName, String lastName,
Integer currentId) {
Optional<T> namesake = d.dao().findFirstByFirstNameAndLastName(firstName, lastName);
if (namesake.isPresent() && !Objects.equals(namesake.get().getId(), currentId)) {
throw new BusinessException(d.alreadyExistsKey());
}
}
private void checkLoginFree(String login) {
if (userRepository.findByLogin(login).isPresent()) {
throw new BusinessException("ERRORS.LOGIN_TAKEN");
}
}
private static boolean empty(String text) {
return text == null || text.isEmpty();
}
|
- Zeilen 6–36: Die sechs öffentlichen Methoden delegieren mit dem passenden Deskriptor an die drei privaten generischen Methoden. Der Compiler leitet [T] aus dem Deskriptor ab: [Doctor] für [doctorDescriptor], [Client] für [clientDescriptor];
- Zeile 42: [<T extends Person>], vor dem Rückgabetyp geschrieben, macht [addPerson] zu einer generischen Methode: Sie hat einen eigenen Parameter vom Typ [T], der [Person] oder eine Unterklasse sein muss;
- Zeilen 43–48: Datenaufbereitung außerhalb der Transaktion. [trim()] entfernt führende und nachfolgende Leerzeichen aus der Zeichenkette; der Name wird großgeschrieben. [Locale.ROOT] erzwingt eine von der Sprache des Servers unabhängige Umwandlung (im Türkischen etwa ist die Kleinbuchstabenform von [I] nicht [i]). Standardmäßig entspricht der Benutzername dem Namen und steht immer in Kleinbuchstaben; standardmäßig entspricht das Passwort dem Benutzernamen: Das sind die Kontoregeln des SQL-Skripts. [a ? b : c] ist der Bedingungsoperator: [b] , wenn [a] wahr ist, [c] andernfalls;
- Zeilen 51–52: In der Transaktion die beiden Eindeutigkeitsregeln: keine doppelten Namen, freier Login. Diese werden vor dem Schreiben in die Datenbank geprüft, um eine klare Meldung anzuzeigen (siehe Beispiel 28);
- Zeilen 54–59: Das Benutzerkonto wird zuerst erstellt, da die Person darauf verweist (Fremdschlüssel). Das Passwort wird nie im Klartext gespeichert: [hasher.encode] berechnet seinen Hash, [bcrypt]. [save] sendet sofort [INSERT] (Schlüssel [IDENTITY]): Nach diesem Aufruf hat [user] einen Bezeichner und ist nun eine verwaltete Entität;
- Zeilen 61–66: Dann die Person. [d.factory().get()] bezeichnet die Factory-Referenz des Deskriptors: [new Doctor()] oder [new Client()]. [setUser(user)] verknüpft die Person mit ihrem Konto: Beim [INSERT] der Person [Hibernate] schreibt die Konto-ID in die Spalte [user]. Schlägt dieser zweite Schreibvorgang fehl, macht die Transaktion auch den ersten rückgängig: Ein Konto kann nie ohne Person existieren;
- Zeilen 75–111: Änderung der Person und ihres Kontos in einer einzigen Transaktion;
- Zeile 77: die Person und ihr Konto ([findWithUserById]) oder eine [BusinessException] mit dem Schlüssel des Deskriptors, falls sie nicht existiert;
- Zeilen 84–86: die optimistische Sperre (siehe Beispiel 28): Das Formular hat die Version des gelesenen Datensatzes bis zu seiner Anzeige mitgeführt; weicht die Version in der Datenbank ab, hat jemand den Datensatz in der Zwischenzeit geändert, und das System lehnt die Aktualisierung ab, statt dessen Arbeit stillschweigend zu überschreiben. Anders als bei der pessimistischen Sperre für Buchungen wird nichts blockiert: Wir gehen davon aus, dass Konflikte selten sind, und erkennen sie lediglich. Die Versionen sind [Integer], also Objekte: Wir vergleichen sie mit [equals], nicht mit [!=], das die Objektreferenzen vergleichen würde. Erfolgt die gleichzeitige Änderung nach diesem Lesen, erkennt sie die Bedingung [WHERE version = ...] des [UPDATE] (siehe den letzten Auszug);
- Zeilen 88–90: der neue Vor- und Nachname und die Prüfung auf Namensdoppelungen. Es wird der Bezeichner der Person übergeben: Die Person hat selbstverständlich das Recht, ihren eigenen Vor- und Nachnamen zu behalten;
- Zeilen 95–97: Das gelesene Objekt wird einfach geändert. In der Transaktion gelesen, wird es vom [EntityManager] verwaltet, der beim [COMMIT] von sich aus [UPDATE] sendet, indem er das Objekt mit dem gelesenen Zustand vergleicht (siehe den Abschnitt „JPA, Hibernate und Spring Data“): Es ist kein [save] aufzurufen. Das [UPDATE] erhöht die Version und prüft die alte;
- Zeilen 99–108: Das Konto folgt der Person. Es wurde zusammen mit der Person geladen ([@EntityGraph]) und wird ebenfalls verwaltet: Sein Anzeigename wird neu berechnet; sein Login ändert sich nur, wenn er eingegeben wurde und vom aktuellen abweicht (dann muss er verfügbar sein); sein Passwort ändert sich nur, wenn es eingegeben wurde; und es wird ebenfalls gehasht;
- Zeile 109: Die geänderte Person wird zurückgegeben; nach dem [COMMIT] ist sie detached, aber ihr Konto, das geladen wurde, bleibt für den Controller lesbar;
- Zeilen 122–135: Löschen innerhalb einer Transaktion, in der von den Fremdschlüsseln vorgegebenen Reihenfolge;
- Zeile 124: [findById] genügt: Das Konto wird nicht benötigt, nur sein Bezeichner, den das Feld [userId] liefert, ohne das Konto zu laden;
- Zeilen 125–127: mögliche Ablehnung: Ein Arzt mit geplanten Terminen kann nicht gelöscht werden (seine Patienten würden ihre Termine verlieren, ohne benachrichtigt zu werden). [d.countAppointments().applyAsLong(id)] ruft die im Deskriptor aufgeführte Funktion auf, also [appointmentRepository.countByDoctor(id)];
- Zeilen 128–130: Löschen der Verweise auf die Person: die Zeitfenster eines Arztes, die Termine eines Patienten;
- Zeilen 131–132: die Person, danach ihr Konto, auf das die Person verwies;
- Zeile 133: [transaction] erwartet eine Funktion, die ein Ergebnis zurückgibt: Es wird [null] zurückgegeben, das niemand verwenden wird;
- Zeilen 140–146: Eine Namensdoppelung wird abgelehnt, es sei denn, sie betrifft die Person, die gerade bearbeitet wird ([currentId], [null] bei einer Neuanlage). [Objects.equals(a, b)] vergleicht zwei Objekte und akzeptiert [null]: [namesake.get().getId().equals(null)] würde ebenfalls funktionieren, aber [Objects.equals] erspart die Prüfung, welches der beiden [null] sein könnte;
- Zeilen 148–152: Ein bereits vergebener Benutzername – bei einem Arzt, einem Patienten oder dem Administrator – wird abgelehnt;
- Zeilen 154–156: eine fehlende ([null]) oder leere Zeichenkette: So wird ein optionales Feld behandelt, das nicht ausgefüllt wurde.
Beachten Sie, dass nur Anlegevorgänge [save] aufrufen. Eine Aktualisierung ändert einfach vorhandene Entitäten, und ein Löschvorgang erfolgt über [delete]-Abfragen: Das ist die übliche Arbeitsweise mit [JPA].
11.12.5.5. Transaktionen und Eindeutigkeitsbedingungen
| // -----------------------------------------------------------------------
// führt [work] in einer Transaktion aus:
// transactions.execute(...) -> START TRANSACTION, dann die Arbeit, dann
// COMMIT, wenn alles gut gegangen ist; wird eine Exception geworfen
// (BusinessException eingeschlossen), ROLLBACK: nichts wird geschrieben.
//
// Die Prüfungen "Login frei" und "eindeutiger Vor- + Nachname" werden VOR
// dem Schreiben durchgeführt, um eine klare Meldung zu geben. Aber zwei ADMINs könnten
// im selben Moment denselben Login (oder denselben Arzt) speichern: in diesem
// seltenen Fall lehnt ein SQL-Eindeutigkeits-Constraint das zweite
// Schreiben ab - in dem Moment, in dem Hibernate die SQL-Anweisungen sendet, oft beim
// COMMIT, also NACH dem Ende der Arbeit. Deshalb fangen wir die
// Exceptions hier ab, RUND UM die Transaktion, um sie in dieselbe
// BusinessException zu übersetzen.
// -----------------------------------------------------------------------
private <R> R transaction(Supplier<R> work) {
try {
return transactions.execute(status -> work.get());
} catch (BusinessException e) {
throw e;
} catch (RuntimeException e) {
BusinessException businessError = translateDatabaseError(e);
if (businessError != null) {
throw businessError;
}
throw e; // eine echte Anomalie: Wir lassen sie weitergeben
}
}
// -----------------------------------------------------------------------
// Datenbankfehler -> BusinessException
//
// Spring übersetzt die Ausnahmen von Hibernate und des JDBC-Treibers in eine
// datenbankunabhängige Ausnahmehierarchie (DataAccessException):
// - OptimisticLockingFailureException: Das UPDATE "WHERE id = ... AND
// version = ..." hat keine Zeile geändert (optimistisches Sperren);
// - DataIntegrityViolationException: Eine Constraint der Datenbank hat
// den Schreibvorgang abgelehnt. Bei einer UNIQUE-Constraint nennt die MySQL-Fehlermeldung
// (die "most specific" Ursache der Ausnahme) den NAMEN der Constraint:
// Duplicate entry 'marie-PELISSIER' for key 'doctors.unq_doctors_first_name_last_name'
// (MySQL 8 stellt dem Namen den der Tabelle voran, MariaDB nicht). Deshalb
// VERGIBT das SQL-Skript für alle seine Constraints NAMEN.
// Jeder andere Fehler ist eine echte Anomalie: Wir geben null zurück (nicht übersetzt).
// -----------------------------------------------------------------------
private static final Map<String, String> CONSTRAINT_MESSAGES = Map.of(
"unq_users_login", "ERRORS.LOGIN_TAKEN",
"unq_doctors_first_name_last_name", "ERRORS.DOCTOR_ALREADY_EXISTS",
"unq_clients_first_name_last_name", "ERRORS.PATIENT_ALREADY_EXISTS",
"unq1_appointments", "ERRORS.SLOT_ALREADY_BOOKED");
private static final Pattern CONSTRAINT = Pattern.compile("for key '(?:[^'.]*\\.)?([^']+)'");
private static BusinessException translateDatabaseError(RuntimeException e) {
if (e instanceof OptimisticLockingFailureException) {
return new BusinessException("ERRORS.CONCURRENT_UPDATE");
}
if (e instanceof DataIntegrityViolationException) {
String message = String.valueOf(NestedExceptionUtils.getMostSpecificCause(e).getMessage());
Matcher match = CONSTRAINT.matcher(message);
if (match.find() && CONSTRAINT_MESSAGES.containsKey(match.group(1))) {
return new BusinessException(CONSTRAINT_MESSAGES.get(match.group(1)));
}
}
return null;
}
}
|
- Zeile 16: Alle Schreibvorgänge laufen über diese generische Methode: [R] ist der Ergebnistyp der Verarbeitung ([Appointment], [Doctor], [Client] oder [Object] , wenn der Lambda-Ausdruck [null] zurückgibt), und [Supplier<R>] ist der Typ einer parameterlosen Funktion, die ein [R] zurückgibt;
- Zeile 18: [transactions.execute(...)] öffnet eine Transaktion ([START TRANSACTION]), führt den übergebenen Lambda-Ausdruck aus, schließt die Transaktion dann mit einem Commit ab ([COMMIT]) und gibt das Ergebnis des Lambda-Ausdrucks zurück. Wirft der Lambda-Ausdruck eine ungeprüfte Ausnahme – einschließlich [BusinessException] –, wird die Transaktion zurückgerollt ([ROLLBACK]) und die Ausnahme erneut geworfen. Die Lambda-Funktion erhält den Transaktionsstatus als Parameter ([status]), womit sie ein Rollback anfordern könnte, ohne eine Ausnahme zu werfen; sie nutzt dies jedoch nicht – sie ruft einfach [work.get()] auf;
- Zeilen 19–20: Eine [BusinessException] (eine abgelehnte Geschäftsregel) wird unverändert an den Controller weitergereicht. Dieser Block muss vor dem folgenden stehen: [BusinessException] ist selbst eine [RuntimeException], und [Java] probiert die [catch]-Blöcke der Reihe nach aus;
- Zeilen 21–26: Jede andere Ausnahme wird von [translateDatabaseError] behandelt: Handelt es sich um einen bekannten Datenbankfehler, wird stattdessen die entsprechende [BusinessException] ausgelöst; andernfalls ist es eine echte Anomalie, die unverändert erneut geworfen wird und eine Fehlerseite 500 erzeugt;
- Zeilen 45–49: Für jede benannte Eindeutigkeitsbedingung des SQL-Skripts der zugehörige Übersetzungsschlüssel. Deshalb benennt das SQL-Skript alle seine Constraints. [Map.of(k1, v1, k2, v2...)] erstellt ein schreibgeschütztes Dictionary; [static final] macht es zu einer Klassenkonstante, die nur einmal erzeugt wird;
- Zeile 51: ein regulärer Ausdruck, der von [Pattern.compile] ein für alle Mal kompiliert wird. Er extrahiert den Namen der Constraint aus der Fehlermeldung der Datenbank (siehe unten);
- Zeilen 53–65: die Übersetzung eines Datenbankfehlers in eine [BusinessException] oder in [null] , wenn der Fehler nicht erkannt wird;
- Zeilen 54–56: [UPDATE ... WHERE id = ... AND version = ...] hat keine Zeile geändert: Jemand hat den Datensatz zwischen Lesen und Speichern geändert (optimistische Sperre). [instanceof] prüft den tatsächlichen Typ eines Objekts. Die empfangene Ausnahme ist eine [ObjectOptimisticLockingFailureException], ein Kind von [OptimisticLockingFailureException];
- Zeilen 57–63: Eine Datenbank-Constraint hat den Schreibvorgang abgelehnt;
- Zeile 58: Die [Spring]-Ausnahme umhüllt die [Hibernate]-Ausnahme, die ihrerseits die Ausnahme des Treibers [MySQL] umhüllt: Jede Ausnahme behält die vorherige als ihre Ursache ([getCause()]). [NestedExceptionUtils.getMostSpecificCause(e)] geht bis zur Grundursache zurück, der des Treibers, dessen Meldung die von [MySQL] ist. [String.valueOf] behandelt eine Meldung von [null] (es gibt dann die Zeichenkette ["null"] zurück);
- Zeilen 59–61: Der Name der Constraint wird in dieser Meldung gesucht und übersetzt, wenn er im Dictionary vorkommt. [find()] sucht den regulären Ausdruck in der Meldung; [group(1)] gibt zurück, was die erste Gruppe in Klammern erfasst hat. Jeder andere Fehler, einschließlich der Verletzung einer Constraint, die nicht im Dictionary steht, wird unübersetzt weitergegeben: Das ist eine echte Anomalie.
Die Fehlermeldung bei einer verletzten Eindeutigkeitsbedingung nennt den Namen der Constraint. Hier die Meldung von [MariaDB] , wenn derselbe Vor- und Nachname zweimal eingegeben wird (die Kollation unterscheidet nicht zwischen Groß- und Kleinbuchstaben: [marie pelissier] ist ein Duplikat von [Marie PELISSIER]):
| ERROR 1062 (23000) at line 1: Duplicate entry 'marie-pelissier' for key 'unq_doctors_first_name_last_name'
|
[MySQL] 8 schreibt [for key 'doctors.unq_doctors_first_name_last_name'], mit dem Tabellennamen als Präfix. Der reguläre Ausdruck [for key '(?:[^'.]*\.)?([^']+)'] akzeptiert beide Formen: [(?:[^'.]*\.)?] überspringt ein optionales Präfix, das mit einem Punkt endet (eine Gruppe [(?:...)] , die nichts erfasst), und die Gruppe [([^']+)] erfasst den Namen bis zum Apostroph. In der [Java]-Zeichenkette wird der Punkt als [\\.] geschrieben: Der Backslash wird verdoppelt, weil er innerhalb einer [Java]-Zeichenkette selbst ein Escape-Zeichen ist.
Es bleibt zu erklären, warum die Anwendung [TransactionTemplate] statt der Annotation [@Transactional] aus Beispiel 28 verwendet. Dafür gibt es zwei Gründe:
- Ein Fehler in der Datenbank zeigt sich nicht immer in der Arbeit selbst. Das [INSERT] für eine neue Entität wird sofort gesendet (Schlüssel [IDENTITY]): Eine durch eine Neuanlage verletzte Eindeutigkeitsbedingung löst während [save] eine Ausnahme aus, innerhalb des Lambda-Ausdrucks. Das [UPDATE] für eine geänderte Entität wird dagegen erst beim [COMMIT] gesendet (siehe [editPerson]): Erst dann meldet die Datenbank einen bereits vergebenen Login oder eine veraltete Version. Mit [@Transactional] erfolgt das [COMMIT] erst nach der Rückkehr der Methode, im [Spring]-Code, der sie umgibt: Die Methode kann die von ihr verursachten Fehler nicht abfangen. Beispiel 28 umging dieses Problem durch den Aufruf von [saveAndFlush], das das sofortige Senden der SQL-Befehle erzwingt. Mit [transactions.execute(...)] wird [COMMIT] innerhalb der Methode [transaction] ausgeführt: Ihr [try] behandelt alle Fehler, ob sie bei der Verarbeitung oder beim [COMMIT] auftreten;
- [@Transactional] arbeitet über einen Proxy: [Spring] umhüllt die Bean mit einem Objekt, das die Transaktion öffnet, bevor die Methode aufgerufen wird. Ein Aufruf von einer Methode zu einer anderen innerhalb desselben Objekts läuft nicht über diesen Proxy: Würde die Annotation an der privaten Methode [addPerson] stehen, die von [addDoctor] aufgerufen wird, hätte sie keine Wirkung. [TransactionTemplate] hat diese Einschränkung nicht: Es handelt sich um einen gewöhnlichen Methodenaufruf.
Schließlich gibt es im Fehlerfall nichts aufzuräumen: Der Persistenzkontext ist an die Transaktion gebunden und verschwindet mit ihr beim [ROLLBACK]. Die [ASP.NET Core]-Version hingegen musste das Change Tracking ihres [DbContext] leeren, der für die gesamte Anfrage bestand.
11.13. Authentifizierung
Die Datei [auth] enthält in umfassenderer Form die Beispiele 25 bis 27: das JWT-Token in einem Cookie, Rollen, CAPTCHA und Versuchsbegrenzung. Sie enthält außerdem einen „Pass“ zum Anlegen eines Patientenkontos. Die Konfiguration von [Spring Security] selbst, die diese Bausteine zusammenführt, liegt zusammen mit den anderen Konfigurationsklassen in der Datei [config/SecurityConfig.java]: Dort beginnen wir. Der Controller [AuthController], der am Ende dieses Abschnitts besprochen wird, liefert die Anmeldeseite aus.
11.13.1. config/SecurityConfig.java
Die Datei wird in zwei Auszügen vorgestellt. Der erste deklariert die Kryptografie-Beans: den Schlüssel, die Erzeugung und Prüfung von Token sowie das Hashen von Passwörtern.
| // =========================================================================
// config/SecurityConfig.java
// -------------------------------------------------------------------------
// Die Konfiguration von Spring Security (siehe Kapitel 8): Wer auf
// was zugreifen darf und wie der Benutzer bei jeder Anfrage erkannt wird.
//
// Spring Security ist eine Servlet-FILTERKETTE, die Spring
// MVC vorgeschaltet ist. Für jede Anfrage gilt:
// 1. Der OAuth2-Filter "resource server" sucht ein JWT-Token (hier im
// Cookie rdvmedecins_jwt), prüft dessen Signatur und Ablaufdatum
// und leitet daraus den Benutzer ab (Authentication);
// 2. der Autorisierungsfilter wendet die URL-Zugriffsregeln an;
// 3. erst danach ruft Spring MVC die Aktion auf, deren Annotationen
// @PreAuthorize (aktiviert durch @EnableMethodSecurity) die Rolle prüfen.
// Zwei Fehlerfälle, zwei für eine HTML-Anwendung passende Antworten:
// - kein authentifizierter Benutzer (kein Token, abgelaufenes oder gefälschtes Token)
// -> Weiterleitung auf die Anmeldeseite;
// - unzureichende Rolle -> Antwort 403, die ErrorController in eine Seite umwandelt.
// =========================================================================
package rdvmedecins.config;
import java.nio.charset.StandardCharsets;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder.BCryptVersion;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.oauth2.jose.jws.MacAlgorithm;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.JwtEncoder;
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
import org.springframework.security.oauth2.jwt.NimbusJwtEncoder;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter;
import org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter;
import org.springframework.security.web.AuthenticationEntryPoint;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.access.AccessDeniedHandler;
import org.springframework.security.web.servlet.util.matcher.PathPatternRequestMatcher;
import jakarta.servlet.http.HttpServletResponse;
import rdvmedecins.auth.AuthService;
import rdvmedecins.auth.ConnectedUser;
import rdvmedecins.web.Flash;
import rdvmedecins.web.FlashMessage;
@Configuration
@EnableMethodSecurity
public class SecurityConfig {
// der Schlüssel, der die Token signiert und prüft (symmetrischer Algorithmus HMAC-SHA256)
@Bean
public SecretKey jwtKey(AuthProperties auth) {
byte[] bytes = auth.jwtSecret().getBytes(StandardCharsets.UTF_8);
if (bytes.length < 32) {
// HMAC-SHA256 erfordert einen Schlüssel von mindestens 256 Bit: Wir melden das
// beim Start deutlich und nicht erst bei der ersten Anmeldung
throw new IllegalStateException(
"rdvmedecins.auth.jwt-secret must be at least 32 characters long (see application.properties).");
}
return new SecretKeySpec(bytes, "HmacSHA256");
}
// das Erstellen der Token (siehe auth/AuthService.java)
@Bean
public JwtEncoder jwtEncoder(SecretKey key) {
return NimbusJwtEncoder.withSecretKey(key).algorithm(MacAlgorithm.HS256).build();
}
// die Prüfung der Token: Signatur und Ablaufdatum
@Bean
public JwtDecoder jwtDecoder(SecretKey key) {
return NimbusJwtDecoder.withSecretKey(key).macAlgorithm(MacAlgorithm.HS256).build();
}
// das Hashen der Passwörter: bcrypt, 10 Runden, Version $2b$ - wie
// die Hashes des SQL-Skripts
@Bean
public PasswordEncoder passwordEncoder() {
return new BCryptPasswordEncoder(BCryptVersion.$2B, 10);
}
|
Kommentieren wir diesen Code:
- Zeilen 4–18: Der Kopfkommentar erinnert an das in Kapitel 8 besprochene Prinzip: [Spring Security] ist eine Kette von Servlet-Filtern, die ausgeführt werden, bevor die Anfrage [Spring MVC] erreicht. Ein Filter identifiziert den Benutzer anhand des Tokens, ein anderer wendet die Zugriffsregeln auf die URL an, und danach prüft die Annotation [@PreAuthorize] an jeder Action die Rolle;
- Zeile 54: [@Configuration] macht die Klasse zu einer Quelle von Beans: Jede ihrer mit [@Bean] annotierten Methoden wird beim Start einmal aufgerufen, und das zurückgegebene Objekt wird zu einer Singleton-Bean, die [Spring] überall dort injiziert, wo sie angefordert wird;
- Zeile 55: [@EnableMethodSecurity] aktiviert die Auswertung der [@PreAuthorize("hasRole('ADMIN')")]-Annotationen an Controllern (siehe Beispiel 26). Ohne sie würden diese Annotationen ohne jede Fehlermeldung ignoriert;
- Zeilen 59–69: der geheime Schlüssel, der Token signiert und prüft (siehe Beispiel 25). Der Parameter [AuthProperties auth] ist der Record, der die Eigenschaften [rdvmedecins.auth.*] aus [application.properties] typisiert abbildet (siehe „Projektkonfiguration“): [Spring] stellt ihn wie jede andere Bean bereit. Eine Neuerung gegenüber Beispiel 25: Ein zu kurzer Schlüssel wird abgelehnt. Der Algorithmus HMAC-SHA256 erfordert einen 256-Bit-Schlüssel, also 32 Bytes; die Bibliothek [Nimbus], die die Token erzeugt, würde dies erst bei der Erzeugung des ersten Tokens prüfen, also bei der ersten Anmeldung. Die hier geworfene Ausnahme verhindert stattdessen, bereits während der Erstellung der Bean, den Start der Anwendung, mit einer Meldung, die genau angibt, was zu korrigieren ist;
- Zeilen 72–81: Erzeugung der Token ([JwtEncoder]) und Prüfung ([JwtDecoder]) mit demselben Schlüssel; der Algorithmus ist symmetrisch. Der Decoder prüft die Signatur und das Ablaufdatum (Claim [exp]). Standardmäßig lässt er eine Toleranz von sechzig Sekunden für Zeitabweichungen zwischen Servern zu: Ein Token bleibt nach seinem Ablauf noch eine Minute gültig;
- Zeilen 85–88: Passwort-Hashing mit dem Algorithmus [bcrypt] (siehe Beispiel 25). Diesmal gibt es zwei Parameter: den Aufwand (10: Der Algorithmus führt 2^10 Berechnungsrunden aus, was einen Brute-Force-Angriff mit Millionen von Passwortversuchen sehr teuer macht) und die Version des Algorithmus. Die Passwörter im SQL-Skript wurden von einer Bibliothek gehasht, die Hashes mit dem Anfang [$2b$10$] schreibt, während [BCryptPasswordEncoder] standardmäßig [$2a$] schreibt. Beide Versionen werden problemlos geprüft; die Erzwingung der Version [$2B] (eine Konstante der Enumeration [BCryptVersion]: Das Zeichen [$] ist in einem [Java]-Bezeichner erlaubt) gibt den von der Anwendung erstellten Konten schlicht Hashes derselben Form wie denen im Skript.
Der zweite Auszug ist die Filterkette selbst mit ihren beiden Ersatzantworten.
| @Bean
public SecurityFilterChain securityFilters(HttpSecurity http, Flash flash) throws Exception {
AuthenticationEntryPoint toLogin = toLogin(flash);
AccessDeniedHandler accessDenied = (request, response, exception) ->
response.sendError(HttpServletResponse.SC_FORBIDDEN);
http
// 1. die URL-Zugriffsregeln, der Reihe nach geprüft. Die öffentlichen
// Seiten: Anmeldung, Kontoerstellung, Sprachauswahl,
// statische Dateien, Fehlerseite. Alle anderen erfordern einen
// authentifizierten Benutzer; die Rollen werden von den
// @PreAuthorize der Controller geprüft.
.authorizeHttpRequests(access -> access
.requestMatchers("/", "/login", "/register", "/register/**", "/language/**",
"/css/**", "/js/**", "/lib/**", "/error")
.permitAll()
.anyRequest().authenticated())
// 2. JWT-Token-Authentifizierung, aus dem Cookie gelesen
.oauth2ResourceServer(jwt -> jwt
.bearerTokenResolver(AuthService::tokenOf)
.authenticationEntryPoint(toLogin)
.accessDeniedHandler(accessDenied)
.jwt(config -> config.jwtAuthenticationConverter(converter())))
// 3. die beiden Fehlerfälle
.exceptionHandling(errors -> errors
.authenticationEntryPoint(toLogin)
.accessDeniedHandler(accessDenied))
// 4. Abmeldung (POST /logout): Cookie des Tokens löschen,
// dann zur Anmeldeseite wechseln. Nur POST: Ein einfacher
// Link (GET) auf einer anderen Website kann den Benutzer
// nicht ohne sein Wissen abmelden
.logout(out -> out
.logoutRequestMatcher(PathPatternRequestMatcher.withDefaults().matcher(HttpMethod.POST, "/logout"))
.deleteCookies(AuthService.JWT_COOKIE)
.logoutSuccessUrl("/login"))
// 5. der Server ist zustandslos: niemals eine HTTP-Sitzung
.sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
// 6. kein Anti-CSRF-Token: Die SameSite=Lax-Cookies schützen bereits
// die POST-Anfragen, die von anderen Websites kommen (siehe AuthService)
.csrf(csrf -> csrf.disable());
return http.build();
}
// -----------------------------------------------------------------------
// kein authentifizierter Benutzer -> Anmeldeseite. Falls ein Cookie
// vorhanden war, ist dessen Token nicht mehr gültig: Die Sitzung ist abgelaufen.
// Wir löschen dann das Cookie und benachrichtigen den Benutzer mit einer Flash-Nachricht
// (außerhalb von Spring MVC gesetzt, daher die Flash-Bean).
// -----------------------------------------------------------------------
private static AuthenticationEntryPoint toLogin(Flash flash) {
return (request, response, exception) -> {
if (AuthService.tokenOf(request) != null) {
AuthService.clearToken(response);
flash.put(request, response, FlashMessage.error("ERRORS.SESSION_EXPIRED"), "/login");
}
response.sendRedirect("/login");
};
}
// -----------------------------------------------------------------------
// vom Token zum authentifizierten Benutzer: Der Claim [name] ist dessen Name
// (Authentication.getName()), der Claim [role] dessen Rolle. Spring Security
// schreibt die Rollen mit dem Präfix ROLE_: Der Claim role=ADMIN wird zur
// Authority ROLE_ADMIN, die hasRole('ADMIN') prüft.
// -----------------------------------------------------------------------
private static JwtAuthenticationConverter converter() {
JwtGrantedAuthoritiesConverter roles = new JwtGrantedAuthoritiesConverter();
roles.setAuthoritiesClaimName(ConnectedUser.ROLE);
roles.setAuthorityPrefix("ROLE_");
JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
converter.setJwtGrantedAuthoritiesConverter(roles);
converter.setPrincipalClaimName(ConnectedUser.NAME);
return converter;
}
}
|
Gehen wir diesen Code durch:
- Zeile 2: Die Bean [SecurityFilterChain] beschreibt die Filterkette. [HttpSecurity] ist ein Builder-Objekt, das von [Spring Security] bereitgestellt wird: Jede darauf aufgerufene Methode ([authorizeHttpRequests], [oauth2ResourceServer], [logout] ...) konfiguriert einen Aspekt der Sicherheit, und [build()] (Zeile 40) erstellt die Kette. Jede erhält einen Lambda-Ausdruck (siehe Beispiel 25), der den jeweiligen Aspekt konfiguriert. Der Parameter [Flash flash] ist eine Bean der Anwendung (Ordner [web]), mit der eine Flash-Meldung von [Spring MVC] aus abgelegt wird;
- Zeilen 4–5: die Antwort auf eine unzureichende Rolle: [sendError(403)]. Der Lambda-Ausdruck implementiert die Schnittstelle [AccessDeniedHandler], die nur eine Methode hat (eine funktionale Schnittstelle). [sendError] erzeugt selbst keine Seite: Der [Tomcat]-Server leitet die Anfrage an [/error] weiter, wo [ErrorController] (siehe „Die Web-Schicht: Controller“) die Fehlerseite 403 erzeugt, wie in Beispiel 26;
- Zeilen 12–16: die Zugriffsregeln für URLs, in der Reihenfolge ausgewertet: Die erste, die auf die URL passt, gilt. Das Stammverzeichnis, die Anmeldung, die Kontoerstellung, die Sprachauswahl, statische Dateien und die Fehlerseite sind öffentlich ([/**] bezeichnet alles unterhalb eines Pfads). Jede andere URL erfordert einen authentifizierten Benutzer. Rollen werden hier nicht geprüft, sondern an jeder Action über [@PreAuthorize]: Die Regel steht somit neben dem Code, den sie schützt. [/error] muss öffentlich sein: Andernfalls würde die Fehlerseite für einen nicht angemeldeten Besucher selbst verweigert;
- Zeilen 18–22: Authentifizierung per JWT-Token, behandelt vom Modul „Resource Server“ ([OAuth2] „Resource Server“) von [Spring Security], wie in Beispiel 25. Standardmäßig sucht dieses Modul das Token im Header [Authorization: Bearer ...]; Zeile 19 gibt ihm einen anderen [BearerTokenResolver], der es aus dem Cookie [rdvmedecins_jwt] liest. [AuthService::tokenOf] ist eine Methodenreferenz: die Kurzschreibweise für den Lambda-Ausdruck [request -> AuthService.tokenOf(request)]. Die statische Methode [tokenOf] (Datei [auth/AuthService.java]) hat tatsächlich genau die Form, die die funktionale Schnittstelle [BearerTokenResolver] verlangt: Sie erhält die Anfrage und gibt das Token zurück oder [null]. Zeile 22: der Konverter, der aus dem geprüften Token den authentifizierten Benutzer erstellt (Zeilen 65–73);
- Zeilen 20 und 25: Derselbe Entry Point, [toLogin], wird zweimal angegeben, weil man auf zwei Arten nicht authentifiziert sein kann. Ein vorhandenes, aber ungültiges Token (abgelaufen, gefälscht) wird vom Filter des Resource Servers abgelehnt, der seinen eigenen Entry Point aufruft (Zeile 20). Kein Token: Der Filter lässt die anonyme Anfrage passieren, und der Autorisierungsfilter lehnt sie ab, indem er den Entry Point von [exceptionHandling] aufruft (Zeile 25). Entsprechend wird der Handler für unzureichende Rollen an beiden Stellen angegeben (Zeilen 21 und 26). Der Handler in [exceptionHandling] (Zeile 26) behandelt die Ablehnungen von [@PreAuthorize]; Zeile 21 ist eine Vorsichtsmaßnahme, damit die beiden Konfigurationen symmetrisch bleiben. Ohne jeden Handler würde der Resource Server auf seine eigene Weise mit einem Fehler 403 antworten, mit einem [WWW-Authenticate]-Header, der für einen [JavaScript]-Client gedacht ist, und ohne Fehlerseite;
- Zeilen 31–34: Die Abmeldung wird von [Spring Security] selbst behandelt; kein Controller hat eine Action namens [/logout]. [deleteCookies] löscht das Token-Cookie, danach wird der Browser zu [/login] umgeleitet. Zeile 32 akzeptiert nur die Methode POST: Ist der CSRF-Schutz deaktiviert (Zeile 39), [Spring Security] akzeptiert [/logout] mit jeder Methode – auch GET –, und ein einfaches Bild ([<img src="http://.../logout">]) auf einer anderen Website würde genügen, um den Benutzer abzumelden. [PathPatternRequestMatcher] beschreibt eine Anfrage durch ihre Methode und ihren Pfad;
- Zeile 36: [STATELESS]: [Spring Security] erstellt nie eine HTTP-Sitzung (das [JSESSIONID]-Cookie aus den Beispielen 20 und 23) und nutzt sie nicht, um den Benutzer zu verfolgen: Der Benutzer wird bei jeder Anfrage anhand seines Tokens erkannt. Der Server speichert zwischen den Anfragen nichts im Speicher;
- Zeile 39: Standardmäßig schützt [Spring Security] POST-Formulare vor dem CSRF-Angriff (eine Falle-Seite auf einer anderen Website, die ein Formular an unsere Website sendet), indem jedes Formular ein verstecktes Feld mit einem zufälligen Token enthalten muss. Das brauchen wir hier nicht, genau wie in Beispiel 25: Die Cookies der Anwendung sind [SameSite=Lax], und der Browser hängt sie nicht an ein POST an, das von einer anderen Website kommt; die schädliche Anfrage käme daher ohne das JWT-Token an – anonym – und würde abgelehnt;
- Zeilen 49–57: der Entry Point, also die Antwort auf eine nicht authentifizierte Anfrage: eine Umleitung auf die Anmeldeseite (siehe Beispiel 25). Neu (Zeilen 51–54): Enthielt die Anfrage ein Token-Cookie, war der Benutzer angemeldet, doch sein Token ist nicht mehr gültig (abgelaufen oder gefälscht). Wir löschen dieses nutzlos gewordene Cookie und legen eine Flash-Meldung „Sitzung abgelaufen“ ab, die die Anmeldeseite anzeigt, statt den Benutzer rätseln zu lassen, wie er dorthin gelangt ist. Die Meldung ist ein Übersetzungsschlüssel (siehe Beispiel 22). Wir befinden uns gerade in einem Filter von [Spring Security], vor [Spring MVC]: Das Objekt [RedirectAttributes] aus Beispiel 20 existiert noch nicht, daher die Bean [Flash] (abgelegt im Ordner [web]);
- Zeilen 65–73: Der Konverter aus Beispiel 26 nimmt das geprüfte Token und erstellt das Objekt [Authentication], das den Benutzer der Anfrage darstellt. Der Claim [role] liefert die Berechtigungen, mit dem Präfix [ROLE_]: Der Claim [role=ADMIN] wird zur Berechtigung [ROLE_ADMIN], die von [hasRole('ADMIN')] geprüft wird. Der Claim [name] wird zum Benutzernamen ([Authentication.getName()]). Die Claim-Namen sind die Konstanten im Record [ConnectedUser] (nächste Datei).
Dies ist in [Spring]das Äquivalent der Konfiguration des [JwtBearer]-Handlers für [ASP.NET Core] und seiner „Ereignisse“: [BearerTokenResolver] fungiert als das Ereignis [OnMessageReceived], und [AuthenticationEntryPoint] fungiert als [OnChallenge].
Untersuchen wir diese Antworten mit [curl], zunächst für Anfragen, die keine Anmeldung erfordern. Eine geschützte Seite, ohne Cookie angefordert, leitet auf die Anmeldeseite um:
| curl -i http://localhost:8081/schedule
|
| HTTP/1.1 302
Location: http://localhost:8081/login
Content-Length: 0
|
Um fortzufahren, benötigen wir ein Token. Dies ist das Token des Patienten [martin]; es wurde zu diesem Zweck mit dem geheimen Schlüssel aus [application.properties] von einem kleinen Programm erzeugt, das die Berechnung HMAC-SHA256 durchführt. Das zeigt, wie wichtig es ist, diesen geheimen Schlüssel zu schützen: Jeder, der ihn kennt, kann ein Token für beliebige Personen erzeugen. Der Leser braucht diese Berechnung allerdings nicht: Er meldet sich im Browser an und kopiert dann den Wert des Cookies [rdvmedecins_jwt] aus den Entwicklertools (F12). In der Produktion wird er durch eine lange Zufallszeichenfolge ersetzt (siehe „Projektkonfiguration“). Ein Token besteht aus drei Base64-kodierten Teilen, die durch Punkte getrennt sind: dem Header, dem Inhalt und der Signatur.
| eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1IiwibG9naW4iOiJtYXJ0aW4iLCJuYW1lIjoiSmVhbiBNQVJUSU4iLCJyb2xlIjoiVVNFUiIsImV4cCI6MTc5MDM2MjAzNiwiaWF0IjoxNzkwMzU0ODM2fQ.hA1rLedxez9s4xqNcNNjyni_kDI9h496EBk8Oj2apdQ
|
Nach der Dekodierung sind die ersten beiden Teile Klartext: Das Token ist signiert, nicht verschlüsselt.
| {"alg":"HS256"}
{"sub":"5","login":"martin","name":"Jean MARTIN","role":"USER","exp":1790362036,"iat":1790354836}
|
Mit diesem Token leitet das Stammverzeichnis der Website den Patienten auf seine Startseite „Mein Konto“ um:
| curl -i -H "Cookie: rdvmedecins_jwt=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1Ii...apdQ" http://localhost:8081/
|
| HTTP/1.1 302
Location: http://localhost:8081/my-area
Content-Length: 0
|
(Das Token ist im Befehl gekürzt.) Der Zugriff auf den Verwaltungsbereich der Ärzte, der ADMIN vorbehalten ist, wird verweigert: [@PreAuthorize] verweigert den Zugriff, der Handler [accessDenied] antwortet mit [sendError(403)], und die Fehlerseite wird vom [ErrorController] erzeugt:
| curl -i -H "Cookie: rdvmedecins_jwt=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1Ii...apdQ" http://localhost:8081/doctors
|
| HTTP/1.1 403
Content-Type: text/html;charset=UTF-8
<!doctype html>
...
<h1 class="display-4 text-danger">403</h1>
<p class="lead">Your role does not allow you to access this page.</p>
...
|
Der Angreifer versucht nun, sich als ADMIN auszugeben: Er ersetzt ["role":"USER"] durch ["role":"ADMIN"] im Inhalt des Tokens und behält die Signatur bei. Der geänderte Inhalt passt nicht mehr zur Signatur: Das Token wird abgelehnt und wie eine abgelaufene Sitzung behandelt:
| curl -i -H "Cookie: rdvmedecins_jwt=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1IiwibG9naW4iOiJtYXJ0aW4iLCJuYW1lIjoiSmVhbiBNQVJUSU4iLCJyb2xlIjoiQURNSU4iLCJleHAiOjE3OTAzNjIwMzYsImlhdCI6MTc5MDM1NDgzNn0.hA1rLedxez9s4xqNcNNjyni_kDI9h496EBk8Oj2apdQ" http://localhost:8081/doctors
|
| HTTP/1.1 302
Set-Cookie: rdvmedecins_jwt=; Path=/; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Set-Cookie: rdvmedecins_flash=eyJwYXRoIjoiL2xvZ2luIiwiZXhwaXJlcyI6MTc5MDM1NTA1OTIwNywiZmxhc2giOnsidHlwZSI6IkRBTkdFUiIsImtleSI6IkVSUk9SUy5TRVNTSU9OX0VYUElSRUQiLCJwYXJhbXMiOnt9fX0; Path=/; HttpOnly; SameSite=Lax
Location: http://localhost:8081/login
Content-Length: 0
|
Der Entry Point [toLogin] hat die drei erwarteten Aktionen ausgeführt: Das Token-Cookie wird gelöscht (der erste Header, [Set-Cookie], setzt es mit einer Lebensdauer von null auf leer zurück), eine Flash-Meldung wird im Cookie [rdvmedecins_flash] abgelegt (zweiter Header, dokumentiert in der Datei [web/CookieFlashMapManager.java]), und der Browser wird zu [/login] umgeleitet, wo die Meldung am Seitenende erscheint:

Dasselbe Verfahren gilt für ein abgelaufenes Token, und sogar auf einer öffentlichen Seite wie [/login]: Der Filter des Resource Servers prüft jedes vorgelegte Token, bevor die Zugriffsregeln ausgewertet werden.
Bleibt die Abmeldung. Per POST löscht sie das Token-Cookie und leitet auf die Anmeldeseite um:
| curl -i -X POST http://localhost:8081/logout
|
| HTTP/1.1 302
Set-Cookie: rdvmedecins_jwt=; Expires=Thu, 01 Jan 1970 00:00:10 GMT; Path=/
Location: http://localhost:8081/login
Content-Length: 0
|
Per GET sind die URL und [/logout] einfach geschützte Seiten wie jede andere – und dazu unbekannte: Ohne Token wird die Anfrage vom Entry Point auf die Anmeldeseite umgeleitet; mit gültigem Token würde sie eine Seite 404 liefern. Auf keinen Fall meldet sie den Benutzer ab:
| curl -i http://localhost:8081/logout
|
| HTTP/1.1 302
Location: http://localhost:8081/login
Content-Length: 0
|
11.13.2. auth/ConnectedUser.java
| // =========================================================================
// auth/ConnectedUser.java
// -------------------------------------------------------------------------
// Was das JWT-Token enthält und wie man es wieder ausliest.
//
// In Spring Security ist der Benutzer der Anfrage ein
// Authentication-Objekt, das im SecurityContext der Anfrage gespeichert ist. Bei
// der JWT-Token-Authentifizierung (siehe config/SecurityConfig.java) ist es ein
// JwtAuthenticationToken, das das geprüfte Token enthält: ein Jwt-Objekt, dessen
// "claims" die Felder des Tokens sind. Ein Controller
// erhält es über einen Parameter @AuthenticationPrincipal Jwt token.
//
// Die Claims unserer Token (siehe AuthService.setToken):
// sub : die ID des Benutzerkontos (JWT-Konvention: "subject")
// login : der Login
// name : der Anzeigename ("Marie PELISSIER") für die Navigationsleiste
// role : ADMIN, DOCTOR oder USER
// =========================================================================
package rdvmedecins.auth;
import org.springframework.security.oauth2.jwt.Jwt;
import rdvmedecins.entities.Role;
// der angemeldete Benutzer in typisierter Form
public record ConnectedUser(int userId, String login, String name, Role role) {
// die Namen der Claims
public static final String SUB = "sub";
public static final String LOGIN = "login";
public static final String NAME = "name";
public static final String ROLE = "role";
// der durch ein bereits geprüftes Token beschriebene Benutzer; null, wenn das Token
// fehlt (nicht authentifizierte Anfrage) oder fehlerhaft ist
public static ConnectedUser of(Jwt token) {
if (token == null) {
return null;
}
try {
return new ConnectedUser(
Integer.parseInt(token.getSubject()),
token.getClaimAsString(LOGIN),
token.getClaimAsString(NAME),
Role.valueOf(token.getClaimAsString(ROLE)));
} catch (RuntimeException e) {
// NumberFormatException, IllegalArgumentException, NullPointerException
return null;
}
}
public boolean isAdmin() {
return role == Role.ADMIN;
}
public boolean isPatient() {
return role == Role.USER;
}
}
|
Gehen wir diesen Code durch:
- Zeilen 6–11: In [Spring Security] ist der Benutzer der Anfrage ein Objekt [Authentication], das im [SecurityContext] der Anfrage gespeichert ist. Bei JWT-Token ist es ein [JwtAuthenticationToken], das das geprüfte Token enthält, ein [Jwt]-Objekt. Eine Action erhält es über einen Parameter, der mit [@AuthenticationPrincipal Jwt token] annotiert ist (siehe Beispiel 25);
- Zeile 26: der angemeldete Benutzer in typisierter Form: ein ganzzahliger Bezeichner, eine Rolle vom Typ [Role] (die Enumeration [ADMIN], [DOCTOR], [USER] aus dem Ordner [entities]) statt eines Tokens, dessen Claims über ihren Namen identifiziert werden. Dies ist ein Record (siehe „Die Domäne: Der Terminkalender“): [Java] erzeugt für uns den Konstruktor und die Zugriffsmethoden [userId()], [login()], [name()] und [role()];
- Zeilen 29–32: die Namen der Claims des Tokens, zu Konstanten zusammengefasst: Ein Tippfehler in [ConnectedUser.NAME] wird vom Compiler gemeldet, während ein Fehler in der Zeichenkette ["name"] erst zur Laufzeit entdeckt würde. Ein Record kann statische Felder enthalten: Sie gehören zur Klasse, nicht zu jedem Objekt;
- Zeilen 36–50: Die statische Methode [of] erstellt den Benutzer aus einem bereits geprüften Token (seine Signatur ist gültig) oder gibt [null] zurück. [getSubject()] liefert den Claim [sub], die als Text geschriebene Konto-ID; [Integer.parseInt] wandelt sie in eine ganze Zahl um. [Role.valueOf] liefert die Enumerationskonstante mit dem angegebenen Namen. Beide Methoden werfen eine Ausnahme, wenn der Text ungültig ist (oder wenn er [null] ist): Ein korrekt signiertes, aber unvollständiges Token liefert daher [null] statt eines Fehlers 500;
- Zeilen 52–58: zwei Methoden für Views und Controller, die den Vergleich von Rollen ersparen: [isAdmin()] und [isPatient()]. Eine [Thymeleaf]-View schreibt einfach [${user.isAdmin()}].
11.13.3. auth/AuthService.java
Die Datei wird in zwei Auszügen vorgestellt.
| // =========================================================================
// auth/AuthService.java
// -------------------------------------------------------------------------
// Die Authentifizierungslogik:
// - validateUser() : prüft ein Paar aus Login und Passwort;
// - setToken() : erstellt das JWT-Token eines validierten Benutzers
// und speichert es in einem Cookie;
// - clearToken() : löscht dieses Cookie;
// - currentUser() : der angemeldete Benutzer der aktuellen Anfrage.
//
// Wo wird das JWT-Token transportiert?
// Bei einem JavaScript-Client war es der Code des Clients, der das Token verwahrte
// und selbst jeder Anfrage hinzufügte (Header "Authorization: Bearer
// ..."). Ein Browser, der gewöhnliche HTML-Seiten anzeigt, kann das nicht:
// Damit er das Token bei jeder Anfrage von selbst mitsendet,
// muss es in einem COOKIE gespeichert sein. Die Optionen dieses Cookies sind für die
// Sicherheit wichtig:
// - HttpOnly : Das JavaScript der Seite kann das Cookie nicht lesen (ein
// eingeschleustes Skript könnte das Token somit nicht stehlen);
// - SameSite=Lax : Der Browser sendet das Cookie NICHT bei einem POST, der von
// einer anderen Website kommt. Da alle Aktionen, die Daten ändern,
// POSTs sind, kann eine präparierte Seite auf einer anderen Website nichts buchen oder
// löschen, indem sie sich als der Benutzer ausgibt
// (sogenannter CSRF-Angriff);
// - Secure : In der Produktion (HTTPS) wird das Cookie nie im Klartext übertragen;
// - Max-Age : Das Cookie verschwindet zugleich mit dem Ablauf des Tokens.
// =========================================================================
package rdvmedecins.auth;
import java.time.Duration;
import java.time.Instant;
import java.util.Optional;
import org.springframework.http.HttpHeaders;
import org.springframework.http.ResponseCookie;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.oauth2.jose.jws.MacAlgorithm;
import org.springframework.security.oauth2.jwt.JwsHeader;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.security.oauth2.jwt.JwtClaimsSet;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.JwtEncoder;
import org.springframework.security.oauth2.jwt.JwtEncoderParameters;
import org.springframework.security.oauth2.jwt.JwtException;
import org.springframework.stereotype.Service;
import org.springframework.web.util.WebUtils;
import jakarta.servlet.http.Cookie;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import rdvmedecins.config.AuthProperties;
import rdvmedecins.entities.User;
import rdvmedecins.repositories.UserRepository;
@Service
public class AuthService {
// der Name des Cookies, das das Token trägt
public static final String JWT_COOKIE = "rdvmedecins_jwt";
private final UserRepository userRepository;
private final PasswordEncoder hasher;
private final JwtEncoder encoder;
private final JwtDecoder decoder;
private final AuthProperties auth;
public AuthService(UserRepository userRepository, PasswordEncoder hasher, JwtEncoder encoder,
JwtDecoder decoder, AuthProperties auth) {
this.userRepository = userRepository;
this.hasher = hasher;
this.encoder = encoder;
this.decoder = decoder;
this.auth = auth;
}
// Optional.empty(), wenn der Login nicht existiert oder das Passwort falsch ist.
// matches hasht das eingegebene Passwort mit dem "Salt" aus dem
// gespeicherten Hash und vergleicht dann die beiden Ergebnisse.
public Optional<User> validateUser(String login, String password) {
return userRepository.findByLogin(login).filter(user -> hasher.matches(password, user.getPassword()));
}
|
Kommentieren wir diesen Code:
- Zeilen 11–26: Der Kommentar erklärt, warum das Token in einem Cookie gesendet wird, und welche Aufgabe jede seiner Optionen hat (siehe Beispiel 25). Ein Browser, der Links folgt und Formulare absendet, kann seinen Anfragen keinen Header [Authorization] hinzufügen; er sendet jedoch automatisch die Cookies zurück, die er erhalten hat;
- Zeile 57: [@Service] macht die Klasse zu einer Singleton-Bean (siehe Beispiel 06), genau wie [@Component]: Die beiden Annotationen sind gleichwertig, wobei [@Service] lediglich anzeigt, dass es sich um einen Service handelt;
- Zeile 61: der Name des Cookies, das das Token trägt;
- Zeilen 63–76: Der Service erhält die DAO mit den Benutzerkonten ([UserRepository], siehe „Die DAO-Schicht“), den [bcrypt]-Encoder, den Token-Encoder und -Decoder (die [SecurityConfig]-Beans) und die Authentifizierungseigenschaften. Die Felder sind [final]: Sie ändern sich nach der Konstruktion nicht;
- Zeilen 81–83: das Konto, wenn Benutzername und Passwort korrekt sind (siehe Beispiel 25). [findByLogin] gibt ein [Optional<User>] zurück, eine Box, die entweder ein Konto enthält oder leer ist (siehe „Die DAO-Schicht“); [filter] behält das Konto nur, wenn die Bedingung wahr ist; andernfalls gibt es eine leere Box zurück. Die Bedingung [hasher.matches(...)] hasht das eingegebene Passwort mit dem im gespeicherten Hash enthaltenen „Salt“ und vergleicht die beiden Ergebnisse: Das Passwort selbst wird nie gespeichert.
| // -----------------------------------------------------------------------
// erstellt das JWT-Token von [user] und legt es in einem Cookie ab.
// Das Token wird mit dem geheimen Schlüssel SIGNIERT (HMAC-SHA256): Der Browser
// kann es lesen (es ist nicht verschlüsselt), aber nicht ändern - jede
// Änderung würde die Signatur ungültig machen.
// -----------------------------------------------------------------------
public void setToken(HttpServletResponse response, User user) {
Instant now = Instant.now();
JwtClaimsSet claims = JwtClaimsSet.builder()
.subject(String.valueOf(user.getId()))
.claim(ConnectedUser.LOGIN, user.getLogin())
.claim(ConnectedUser.NAME, user.getName())
.claim(ConnectedUser.ROLE, user.getRole().name())
.issuedAt(now)
.expiresAt(now.plusSeconds(auth.jwtExpiresInSeconds()))
.build();
String token = encoder.encode(JwtEncoderParameters.from(JwsHeader.with(MacAlgorithm.HS256).build(), claims))
.getTokenValue();
ResponseCookie cookie = ResponseCookie.from(JWT_COOKIE, token)
.httpOnly(true)
.sameSite("Lax")
.secure(auth.cookieSecure())
.maxAge(Duration.ofSeconds(auth.jwtExpiresInSeconds()))
.path("/")
.build();
response.addHeader(HttpHeaders.SET_COOKIE, cookie.toString());
}
// löscht das Cookie: Wir setzen es erneut, leer, mit einer Lebensdauer von null
public static void clearToken(HttpServletResponse response) {
response.addHeader(HttpHeaders.SET_COOKIE, ResponseCookie.from(JWT_COOKIE, "").path("/").maxAge(0).build().toString());
}
// das in der Anfrage vorhandene Token, ob gültig oder nicht
public static String tokenOf(HttpServletRequest request) {
Cookie cookie = WebUtils.getCookie(request, JWT_COOKIE);
return cookie == null ? null : cookie.getValue();
}
// -----------------------------------------------------------------------
// der angemeldete Benutzer oder null.
// Normalerweise hat Spring Security ihn bereits ermittelt (SecurityContextHolder).
// Aber eine Fehlerseite wird durch eine ZWEITE interne Anfrage aufgebaut,
// die der Server an die Adresse /error sendet und die nicht erneut durch die
// Authentifizierung läuft: Wir lesen dann das Token des Cookies selbst, damit
// die Navigationsleiste der Fehlerseite den Benutzer anzeigt.
// -----------------------------------------------------------------------
public ConnectedUser currentUser(HttpServletRequest request) {
Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
if (authentication != null && authentication.getPrincipal() instanceof Jwt token) {
return ConnectedUser.of(token);
}
String token = tokenOf(request);
if (token == null) {
return null;
}
try {
return ConnectedUser.of(decoder.decode(token));
} catch (JwtException e) {
return null; // abgelaufenes oder gefälschtes Token
}
}
}
|
Kommentieren wir diesen Code:
- Zeilen 8–19: Das Token, erzeugt wie in Beispiel 25. Es enthält die Konto-ID (Claim [sub]), den Login, den in der Navigationsleiste angezeigten Namen, die Rolle, das Ausstellungsdatum ([iat], „issued at“) und das Ablaufdatum ([exp]), das standardmäßig zwei Stunden später liegt. [JwtClaimsSet.builder()] gibt ein Builder-Objekt zurück: Pro Claim wird eine Methode aufgerufen, gefolgt von [build()]. Zeile 18: Der Header des Tokens gibt den Algorithmus HS256 (HMAC-SHA256) an, und der Encoder signiert das gesamte Token mit dem geheimen Schlüssel;
- Zeilen 20–27: das Cookie, mit den Optionen aus Beispiel 25 ([HttpOnly], [SameSite=Lax]) und zwei weiteren: [Secure], in der Produktion aktiviert (Website als [HTTPS] ausgeliefert), verhindert, dass der Browser das Cookie über eine unverschlüsselte Verbindung sendet; [Path=/] stellt sicher, dass es bei allen Anfragen an die Website mitgesendet wird. [Max-Age] löscht das Cookie, wenn das Token abläuft. [ResponseCookie] erzeugt den Text des Headers [Set-Cookie], der von Zeile 27 der Antwort hinzugefügt wird;
- Zeilen 31–33: Das Löschen eines Cookies besteht darin, es erneut zu setzen, leer und mit einer Lebensdauer von null; der Browser löscht es sofort. Damit der Browser das zu löschende Cookie erkennt, muss der Pfad ([Path]) derselbe sein wie beim Setzen. Die Methode ist statisch: Sie hängt von keinem Feld des Objekts ab. Sie wird vom Entry Point [SecurityConfig] und vom Exception-Handler [HtmlExceptionHandler] (Datei [web]) verwendet, die keine Instanz von [AuthService] benötigen;
- Zeilen 36–39: das in der Anfrage vorhandene Token, ohne es zu prüfen. [WebUtils.getCookie] sucht unter den Cookies der Anfrage nach einem Cookie mit dem angegebenen Namen. Das ist die Methode, die [SecurityConfig] als [BearerTokenResolver] bereitstellt;
- Zeilen 49–63: der angemeldete Benutzer oder [null]. Im Normalfall (Zeilen 50–53) hat [Spring Security] ihn bereits ermittelt: [SecurityContextHolder.getContext().getAuthentication()] gibt das [Authentication]-Objekt der aktuellen Anfrage zurück, dessen „Principal“ das geprüfte Token ist. [instanceof Jwt token] prüft den Typ des Objekts und speichert es, wenn die Prüfung gelingt, in der Variablen [token], die bereits in [Jwt] umgewandelt wurde. Der zweite Fall (Zeilen 54–62) betrifft die Fehlerseite: Endet eine Anfrage mit einem Fehler 403 oder 404, erzeugt der Server die Seite über eine zweite, interne Anfrage an [/error]. Der Filter des Resource Servers verarbeitet diese interne Anfrage nicht: Der Benutzer ist dafür nicht authentifiziert. Damit die Navigationsleiste der Fehlerseite den Benutzer trotzdem anzeigt, prüfen wir das Cookie-Token selbst mit dem Decoder aus [SecurityConfig]; ein abgelaufenes oder gefälschtes Token löst eine [JwtException] aus, und wir geben [null] zurück.
Die Methode [currentUser] wird für jede Seite von [web/CommonModel.java] aufgerufen, das den Benutzer im Template für alle Views setzt.
11.13.4. auth/InvalidSessionException.java
| // =========================================================================
// auth/InvalidSessionException.java
// -------------------------------------------------------------------------
// Das Token ist gültig, aber das Konto, auf das es verweist, existiert nicht mehr: Es wurde
// seit der Anmeldung gelöscht (vom Patienten selbst in einem anderen
// Tab oder vom ADMIN). Wir behandeln diesen Fall wie eine abgelaufene Sitzung:
// web/HtmlExceptionHandler löscht das Cookie und leitet auf die
// Anmeldeseite weiter.
// =========================================================================
package rdvmedecins.auth;
public class InvalidSessionException extends RuntimeException {
public InvalidSessionException() {
super("the account of the connected user no longer exists");
}
}
|
- Zeilen 12–16: Ein Token kann gültig sein (korrekt signiert, nicht abgelaufen), obwohl das Konto, auf das es verweist, seit der Anmeldung des Benutzers gelöscht wurde. Die Patientenseiten erkennen dies, indem sie den zum Konto gehörenden Patienten suchen (Methode [connectedPatient] in der Datei [web/Utils.java]) und werfen dann diese Ausnahme; der Exception-Handler [HtmlExceptionHandler] (siehe Beispiel 24) fängt sie ab, löscht das Cookie und leitet mit der Meldung „Sitzung abgelaufen“ auf die Anmeldeseite um. Die Ausnahme leitet sich von [RuntimeException] ab: Es ist eine ungeprüfte Ausnahme, die Methoden nicht mit einer [throws]-Klausel deklarieren müssen. Der Konstruktor übergibt seine Meldung über [super(...)] an den Konstruktor der Elternklasse.
11.13.5. auth/Captcha.java
| // =========================================================================
// auth/Captcha.java
// -------------------------------------------------------------------------
// Ein CAPTCHA: id, für das versteckte Feld "captchaId" des Formulars;
// svg, das Bild, das unverändert in die Seite einzufügen ist.
// =========================================================================
package rdvmedecins.auth;
public record Captcha(String id, String svg) {
}
|
- Zeile 9: ein CAPTCHA, wie es die Seite erhält: der Bezeichner, der in ein verstecktes Formularfeld gehört, und das [SVG]-Bild, das unverändert in die Seite eingefügt wird. Ein einziger Record genügt: Das Objekt ist schreibgeschützt. Die erwartete Antwort erscheint hier nicht: Sie verlässt den Server nie.
11.13.6. auth/CaptchaService.java
| // =========================================================================
// auth/CaptchaService.java
// -------------------------------------------------------------------------
// Ein CAPTCHA ("Test zur Unterscheidung von Mensch und Roboter"), das vom
// Server selbst erzeugt wird, ohne externen Dienst: einige verzerrte Zeichen,
// durch Striche verwirrt, in einem SVG-Bild (siehe CaptchaDrawing.java). Ein
// Mensch liest sie ohne Schwierigkeit; ein Roboter, der lediglich in einer Schleife
// Formulare sendet, schafft das nicht.
//
// Funktionsweise:
// 1. generate() zeichnet einen zufälligen Text, wandelt ihn in ein Bild um und speichert die
// richtige Antwort IM SPEICHER DES SERVERS unter einer zufälligen Kennung;
// 2. die Seite zeigt das Bild an und legt die Kennung in ein verstecktes Feld des
// Formulars (die Antwort selbst verlässt den Server nie);
// 3. verify(id, input) vergleicht die Eingabe mit der erwarteten Antwort und
// VERGISST dann dieses CAPTCHA: Jedes Bild wird nur einmal verwendet, ein Roboter kann
// keine bereits gefundene Antwort wiederholen.
//
// SINGLETON-Bean (eine einzige Instanz für den gesamten Server), die von
// mehreren Anfragen PARALLEL genutzt wird: daher die ConcurrentHashMap, ein
// Dictionary, das mehrere Threads gleichzeitig lesen und ändern können,
// ohne es zu beschädigen.
//
// Akzeptierte Einschränkung: der Speicher eines einzelnen Prozesses. Bei mehreren Servern
// hinter einem Load Balancer wäre ein gemeinsamer Speicher nötig.
// =========================================================================
package rdvmedecins.auth;
import java.time.Duration;
import java.time.Instant;
import java.util.Map;
import java.util.UUID;
import java.util.concurrent.ConcurrentHashMap;
import org.springframework.stereotype.Service;
@Service
public class CaptchaService {
// Gültigkeitsdauer eines Bildes: Sie haben 10 Minuten, um das Formular auszufüllen
private static final Duration LIFETIME = Duration.ofMinutes(10);
// Speicherschutz: Darüber hinaus vergessen wir alle ausstehenden CAPTCHAs
private static final int MAX_CAPTCHAS = 10_000;
// die erwartete Antwort und ihr Ablaufdatum
private record Expected(String text, Instant expires) {
}
// id -> erwartete Antwort
private final Map<String, Expected> pending = new ConcurrentHashMap<>();
public Captcha generate() {
purge();
String text = CaptchaDrawing.randomText(5); // 5 Zeichen
String id = UUID.randomUUID().toString(); // eine zufällige, nicht erratbare Kennung
pending.put(id, new Expected(text, Instant.now().plus(LIFETIME)));
return new Captcha(id, CaptchaDrawing.svg(text));
}
// true, wenn [input] die richtige Antwort auf das CAPTCHA [id] ist (unabhängig
// von der Groß-/Kleinschreibung). Das CAPTCHA wird in jedem Fall verbraucht.
// remove ist ATOMAR: Wenn zwei Anfragen im selben Augenblick dasselbe CAPTCHA
// vorlegen, entfernt es nur eine - die andere scheitert.
public boolean verify(String id, String input) {
Expected expected = id == null ? null : pending.remove(id);
return expected != null && input != null
&& expected.expires().isAfter(Instant.now())
&& expected.text().equalsIgnoreCase(input.trim());
}
private void purge() {
Instant now = Instant.now();
pending.entrySet().removeIf(e -> !e.getValue().expires().isAfter(now));
if (pending.size() >= MAX_CAPTCHAS) {
pending.clear();
}
}
}
|
Der Service ist derselbe wie in Beispiel 27, mit zwei Ergänzungen: einer Ablaufzeit und einer Obergrenze. Gehen wir diesen Code durch:
- Zeile 37: eine Singleton-Bean – ein einziger Service für den gesamten Server, also eine einzige Liste ausstehender CAPTCHAs, die von allen Anfragen gemeinsam genutzt wird;
- Zeilen 41–44: Ein Bild ist zehn Minuten lang gültig, und die Anzahl ausstehender CAPTCHAs ist begrenzt. Bei jeder Anzeige der Anmeldeseite wird ein CAPTCHA im Speicher abgelegt; ohne Begrenzung würde ein Bot, der diese Seite millionenfach aufruft, ohne je zu antworten, schließlich den Speicher des Servers erschöpfen. [10_000]: Das Zeichen [_] trennt die Ziffern zur besseren Lesbarkeit in Gruppen;
- Zeilen 47–48: die erwartete Antwort und ihr Ablaufdatum. Der Record ist verschachtelt und privat: Er existiert nur für diesen Service. [Instant] stellt einen bestimmten, von der Zeitzone unabhängigen Zeitpunkt dar;
- Zeile 51: Bezeichner → erwartete Antwort. Der Service ist ein Singleton, der von nebenläufigen Anfragen genutzt wird, jede in ihrem eigenen Ausführungs-Thread ([thread]): daher [ConcurrentHashMap] (siehe Beispiel 27), ein Dictionary, das mehrere [threads] gleichzeitig lesen und ändern können, ohne es zu beschädigen. Das Feld ist mit dem Typ deklariert, den die Schnittstelle [Map] definiert: Der übrige Code hängt nicht von der gewählten Implementierung ab;
- Zeilen 53–59: Aufräumen, danach ein zufällig erzeugter Text aus fünf Zeichen, gespeichert unter einem zufälligen Bezeichner ([UUID.randomUUID()], 122 zufällige Bits, nicht zu erraten) und gezeichnet von [CaptchaDrawing];
- Zeilen 65–70: die Prüfung, identisch mit der aus Beispiel 27: Das CAPTCHA wird in jedem Fall aus dem Dictionary entfernt ([remove] gibt den entfernten Wert zurück oder [null]), dann prüfen wir, ob es existierte, ob es nicht abgelaufen ist und ob die Eingabe – ohne Leerzeichen – richtig ist, unabhängig von der Groß- und Kleinschreibung ([equalsIgnoreCase]). [remove] ist atomar: Legen zwei Anfragen dasselbe CAPTCHA zur selben Zeit vor, entfernt es nur eine; die andere erhält [null]. Jedes Bild wird daher nur einmal verwendet: Ein Bot kann eine zuvor gefundene Antwort nicht wiederverwenden;
- Zeilen 72–78: Bereinigung. [removeIf] entfernt aus dem Dictionary die Einträge, für die die Lambda-Funktion [true] zurückgibt – hier die abgelaufenen CAPTCHAs. Ist die Obergrenze weiterhin erreicht (ein Angriff läuft), werden alle ausstehenden CAPTCHAs verworfen: Gutgläubige Benutzer, die in diesem Moment das Formular ausfüllten, müssen ein neues Bild neu eingeben. Diese Situation tritt nur bei einem Angriff auf: Diese einfache Lösung genügt.
11.13.7. auth/CaptchaDrawing.java
Die Klasse, die das Bild zeichnet, ist die aus Beispiel 27. Sie wird in zwei Abschnitten vorgestellt: zuerst die „Schriftart“ der Zeichen, dann das Zeichnen.
| // =========================================================================
// auth/CaptchaDrawing.java
// -------------------------------------------------------------------------
// Das Zeichnen des SVG-Bildes (150 x 50 Pixel) eines CAPTCHAs, unverändert aus
// Beispiel 27 übernommen. Ein wichtiger Punkt: Jedes Zeichen wird mit
// STRICHEN (<path>) gezeichnet, nie als Text (<text>) geschrieben - sonst
// müsste ein Roboter nur den Quellcode des Bildes lesen.
// =========================================================================
package rdvmedecins.auth;
import java.security.SecureRandom;
import java.util.LinkedHashMap;
import java.util.Locale;
import java.util.Map;
final class CaptchaDrawing {
private static final int WIDTH = 150;
private static final int HEIGHT = 50;
// SecureRandom: ein "kryptografischer" Zufallszahlengenerator,
// unvorhersehbar (anders als Random, dessen Folge erraten werden könnte)
private static final SecureRandom RANDOM = new SecureRandom();
// Die "Schriftart": Jedes Zeichen ist eine Liste von Strichen, jeder Strich eine
// Folge von Punkten (x, y) in einem 4 x 6-Raster (y nach unten).
// Zeichen, die zu leicht miteinander zu verwechseln sind: ausgeschlossen (0 O, 1 I L).
private static final Map<Character, double[][]> FONT = new LinkedHashMap<>();
static {
FONT.put('A', new double[][] { { 0, 6, 2, 0, 4, 6 }, { 0.8, 3.8, 3.2, 3.8 } });
FONT.put('B', new double[][] { { 0, 0, 0, 6, 3, 6, 4, 5, 4, 4, 3, 3, 0, 3 }, { 0, 0, 3, 0, 4, 1, 4, 2, 3, 3 } });
FONT.put('C', new double[][] { { 4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5 } });
FONT.put('D', new double[][] { { 0, 0, 0, 6, 2.5, 6, 4, 4.5, 4, 1.5, 2.5, 0, 0, 0 } });
FONT.put('E', new double[][] { { 4, 0, 0, 0, 0, 6, 4, 6 }, { 0, 3, 3, 3 } });
FONT.put('F', new double[][] { { 4, 0, 0, 0, 0, 6 }, { 0, 3, 3, 3 } });
FONT.put('G', new double[][] { { 4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5, 4, 3.5, 2.5, 3.5 } });
FONT.put('H', new double[][] { { 0, 0, 0, 6 }, { 4, 0, 4, 6 }, { 0, 3, 4, 3 } });
FONT.put('J', new double[][] { { 4, 0, 4, 5, 3, 6, 1, 6, 0, 5 } });
FONT.put('K', new double[][] { { 0, 0, 0, 6 }, { 4, 0, 0, 3.5 }, { 1.3, 2.6, 4, 6 } });
FONT.put('M', new double[][] { { 0, 6, 0, 0, 2, 3.5, 4, 0, 4, 6 } });
FONT.put('N', new double[][] { { 0, 6, 0, 0, 4, 6, 4, 0 } });
FONT.put('P', new double[][] { { 0, 6, 0, 0, 3, 0, 4, 1, 4, 2, 3, 3, 0, 3 } });
FONT.put('Q', new double[][] { { 1, 0, 3, 0, 4, 1, 4, 5, 3, 6, 1, 6, 0, 5, 0, 1, 1, 0 }, { 2.5, 4.5, 4, 6.3 } });
FONT.put('R', new double[][] { { 0, 6, 0, 0, 3, 0, 4, 1, 4, 2, 3, 3, 0, 3 }, { 2, 3, 4, 6 } });
FONT.put('S', new double[][] { { 4, 1, 3, 0, 1, 0, 0, 1, 0, 2, 1, 3, 3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5 } });
FONT.put('T', new double[][] { { 0, 0, 4, 0 }, { 2, 0, 2, 6 } });
FONT.put('U', new double[][] { { 0, 0, 0, 5, 1, 6, 3, 6, 4, 5, 4, 0 } });
FONT.put('V', new double[][] { { 0, 0, 2, 6, 4, 0 } });
FONT.put('W', new double[][] { { 0, 0, 1, 6, 2, 2.5, 3, 6, 4, 0 } });
FONT.put('X', new double[][] { { 0, 0, 4, 6 }, { 4, 0, 0, 6 } });
FONT.put('Y', new double[][] { { 0, 0, 2, 3, 4, 0 }, { 2, 3, 2, 6 } });
FONT.put('Z', new double[][] { { 0, 0, 4, 0, 0, 6, 4, 6 } });
FONT.put('2', new double[][] { { 0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 0, 6, 4, 6 } });
FONT.put('3', new double[][] { { 0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 3, 3, 1.5, 3 }, { 3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5 } });
FONT.put('4', new double[][] { { 3, 6, 3, 0, 0, 4, 4, 4 } });
FONT.put('5', new double[][] { { 4, 0, 0, 0, 0, 3, 3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5 } });
FONT.put('6', new double[][] { { 4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5, 4, 4, 3, 3, 0, 3 } });
FONT.put('7', new double[][] { { 0, 0, 4, 0, 1.5, 6 } });
FONT.put('8', new double[][] { { 1, 3, 0, 2, 0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 3, 3, 1, 3, 0, 4, 0, 5, 1, 6, 3, 6, 4, 5, 4, 4, 3, 3 } });
FONT.put('9', new double[][] { { 4, 3, 1, 3, 0, 2, 0, 1, 1, 0, 3, 0, 4, 1, 4, 5, 3, 6, 1, 6, 0, 5 } });
}
private static final char[] ALPHABET = FONT.keySet().stream()
.map(String::valueOf).reduce("", String::concat).toCharArray();
// einige dunkle Farben, gut lesbar auf dem hellen Hintergrund
private static final String[] COLORS = { "#1f4e79", "#7b2d26", "#2e6b30", "#5b2c83", "#8a5a00", "#23395d", "#9c2a5b" };
|
Kommentieren wir diesen Code:
- Zeile 16: Die Klasse ist nicht [public]; ohne Modifizierer ist sie nur innerhalb ihres Pakets ([rdvmedecins.auth]) sichtbar, wo nur [CaptchaService] sie verwendet. [final] verbietet es, eine weitere Klasse von ihr abzuleiten;
- Zeile 23: [SecureRandom] ist ein „kryptografischer“ Zufallszahlengenerator: Seine Ausgaben sind unvorhersehbar, während die von [Random] anhand früherer Ausgaben erraten werden könnten. Für alle Ziehungen wird ein einziger Generator verwendet; er kann von mehreren [threads] gleichzeitig genutzt werden;
- Zeilen 28–62: die „Schriftart“: für jedes Zeichen eine Liste von Strichen, wobei jeder Strich eine Folge von (x, y)-Koordinaten in einem 4 × 6-Raster ist. [double[][]] ist ein Array von Arrays, hier in ausgeschriebener Form mit geschweiften Klammern geschrieben. Das Dictionary wird von einem [static { ... }]-Block (Zeilen 30–62) befüllt, der einmal beim Laden der Klasse ausgeführt wird. Leicht zu verwechselnde Zeichen (0 und O, 1, I und L) werden weggelassen. Eine [LinkedHashMap] bewahrt die Einfügereihenfolge der Schlüssel;
- Zeilen 64–65: Die verwendbaren Zeichen – also die Schlüssel der Schriftart – werden in einem Array von [char] gesammelt. Der Stream (siehe „Die Geschäftsschicht“) der Schlüssel wird in einzeichenige Zeichenketten umgewandelt ([String::valueOf]), die verkettet werden ([reduce("", String::concat)]), und anschließend wird die entstandene Zeichenkette in ein Array zerlegt ([toCharArray()]).
| private CaptchaDrawing() {
}
static String randomText(int length) {
StringBuilder text = new StringBuilder();
for (int i = 0; i < length; i++) {
text.append(ALPHABET[RANDOM.nextInt(ALPHABET.length)]);
}
return text.toString();
}
private static double randomBetween(double min, double max) {
return min + (max - min) * RANDOM.nextDouble();
}
private static String color() {
return COLORS[RANDOM.nextInt(COLORS.length)];
}
static String svg(String text) {
StringBuilder svg = new StringBuilder();
svg.append("<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"%d\" height=\"%d\" viewBox=\"0 0 %d %d\">"
.formatted(WIDTH, HEIGHT, WIDTH, HEIGHT));
svg.append("<rect width=\"100%\" height=\"100%\" fill=\"#f5f7fa\"/>");
// die Zeichen: jedes vergrößert, geneigt, verschoben, und jeder Punkt
// zufällig leicht bewegt
double step = (WIDTH - 20) / (double) text.length();
for (int i = 0; i < text.length(); i++) {
double scale = randomBetween(4.6, 5.6); // Größe einer Rastereinheit, in Pixeln
double angle = randomBetween(-0.35, 0.35); // Drehung, im Bogenmaß (etwa ±20°)
double cx = 10 + step * (i + 0.5) + randomBetween(-3, 3); // Mittelpunkt des Zeichens
double cy = HEIGHT / 2.0 + randomBetween(-4, 4);
StringBuilder d = new StringBuilder();
for (double[] stroke : FONT.get(text.charAt(i))) {
for (int k = 0; k < stroke.length; k += 2) {
// Rasterpunkt, auf (2, 3) zentriert, verzerrt, gedreht, platziert
double x = (stroke[k] - 2 + randomBetween(-0.2, 0.2)) * scale;
double y = (stroke[k + 1] - 3 + randomBetween(-0.2, 0.2)) * scale;
double px = cx + x * Math.cos(angle) - y * Math.sin(angle);
double py = cy + x * Math.sin(angle) + y * Math.cos(angle);
d.append(k == 0 ? 'M' : 'L').append(number(px)).append(' ').append(number(py)).append(' ');
}
}
svg.append("<path d=\"%s\" fill=\"none\" stroke=\"%s\" stroke-width=\"%s\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>"
.formatted(d.toString().trim(), color(), number(randomBetween(2.2, 3))));
}
// 3 verwirrende Striche: Kurven, die das Bild durchqueren
for (int n = 0; n < 3; n++) {
svg.append("<path d=\"M%s %s C%s %s %s %s %s %s\" fill=\"none\" stroke=\"%s\" stroke-width=\"1.3\"/>"
.formatted(number(randomBetween(0, 20)), number(randomBetween(5, 45)),
number(randomBetween(30, 60)), number(randomBetween(0, 50)), number(randomBetween(90, 120)), number(randomBetween(0, 50)),
number(randomBetween(130, 150)), number(randomBetween(5, 45)), color()));
}
svg.append("</svg>");
return svg.toString();
}
// eine Zahl mit Dezimalpunkt, unabhängig von der Sprache des Servers
// (im Französischen würde "%.1f" "12,5" schreiben - für SVG unlesbar)
private static String number(double value) {
return String.format(Locale.ROOT, "%.1f", value);
}
}
|
Kommentieren wir diesen Code:
- Zeilen 1–2: ein privater Konstruktor – die Klasse enthält nur statische Methoden, daher werden nie Objekte erzeugt;
- Zeilen 4–18: Zufallsauswahlen: ein Text der verlangten Länge, eine reelle Zahl zwischen zwei Grenzen, eine Farbe. [nextInt(n)] gibt eine ganze Zahl zwischen 0 und n – 1 zurück, [nextDouble()] eine reelle Zahl zwischen 0 und 1;
- Zeilen 20–58: Das Bild ist ein [SVG]-Text, zusammengesetzt in einem [StringBuilder] (eine Zeichenkette, die erweitert wird, ohne bei jedem hinzugefügten Element neu geschrieben werden zu müssen). Die Methode [formatted] ersetzt [%d] (eine ganze Zahl) und [%s] (eine Zeichenkette) der Reihe nach durch ihre Argumente. Jedes Zeichen (Zeilen 29–47) wird zu einem [<path>]-Pfad: Jeder Rasterpunkt wird leicht verschoben, vergrößert, gedreht und an seine Position im Bild gesetzt, mit zufällig gewählter Farbe und Strichstärke. Die Zeichen sind Linien, nie Text: Ein Roboter kann sie nicht aus dem Code des Bildes lesen. Danach durchqueren drei verwirrende Kurven das Bild (Zeilen 50–55);
- Zeilen 62–64: Die Zahlen in [SVG] werden mit Dezimalpunkt geschrieben. [Locale.ROOT] erzwingt diese Schreibweise unabhängig von der Sprache des Servers: Mit Französisch als Sprache würde [%.1f] ein Komma verwenden (siehe Kapitel 5).
11.13.8. auth/AttemptLimiterService.java
Die Datei wird in zwei Auszügen vorgestellt.
| // =========================================================================
// auth/AttemptLimiterService.java
// -------------------------------------------------------------------------
// Zweites Bollwerk gegen Roboter (das erste ist das CAPTCHA): Wir ZÄHLEN die
// Versuche und SPERREN oberhalb eines Schwellenwerts für eine gewisse Zeit.
//
// - Anmeldung: Nach loginMaxFailures Fehlversuchen (falsches CAPTCHA oder falsches
// Passwort) für denselben Login von derselben IP-Adresse wird dieses Paar
// für loginBlockMinutes Minuten gesperrt. Dieselbe IP-Adresse wird außerdem
// gesperrt, wenn sie 5-mal mehr Fehlversuche ansammelt, alle Logins zusammen (ein
// Roboter, der Tausende verschiedener Logins ausprobiert);
// - Kontoerstellung: höchstens registrationMaxPerHour erstellte Konten pro
// Stunde von derselben IP-Adresse.
//
// Vorsicht im Unterricht: Alle Rechner gehen oft über dieselbe IP-Adresse
// ins Internet. Deshalb gilt die Anmeldesperre zuerst für das Paar (IP, Login) - ein
// Student, der ein falsches Passwort eingibt, sperrt nicht seine Nachbarn - und deshalb lassen sich
// die Schwellenwerte
// in application.properties festlegen (rdvmedecins.protection.*).
//
// Singleton-Bean, von parallelen Anfragen aufgerufen: Alle öffentlichen Methoden
// sind "synchronized" - jeweils nur ein Thread liest UND ändert
// die Zähler.
// =========================================================================
package rdvmedecins.auth;
import java.time.Duration;
import java.time.Instant;
import java.util.HashMap;
import java.util.Locale;
import java.util.Map;
import org.springframework.stereotype.Service;
import rdvmedecins.config.ProtectionProperties;
@Service
public class AttemptLimiterService {
private static class Counter {
int count; // im aktuellen Zeitfenster gezählte Versuche
Instant start; // Beginn des Zählfensters
Instant blockedUntil = Instant.MIN; // Instant.MIN, wenn nicht gesperrt
}
private static final Duration ONE_HOUR = Duration.ofHours(1);
private final Map<String, Counter> counters = new HashMap<>();
private final int maxLoginFailures;
private final Duration loginBlockDuration;
private final int maxRegistrations;
public AttemptLimiterService(ProtectionProperties protection) {
this.maxLoginFailures = protection.loginMaxFailures();
this.loginBlockDuration = Duration.ofMinutes(protection.loginBlockMinutes());
this.maxRegistrations = protection.registrationMaxPerHour();
}
// ---------------------------------------------------------------- Anmeldung
// Anzahl der verbleibenden Sperrminuten (0 = der Versuch ist erlaubt)
public synchronized long loginBlockMinutes(String ip, String login) {
return Math.max(remainingMinutes(loginKey(ip, login)), remainingMinutes(ipKey(ip)));
}
public synchronized void loginFailure(String ip, String login) {
count(loginKey(ip, login), maxLoginFailures, loginBlockDuration, loginBlockDuration);
count(ipKey(ip), maxLoginFailures * 5, loginBlockDuration, loginBlockDuration);
}
// eine erfolgreiche Anmeldung setzt den Zähler DIESES Logins zurück
public synchronized void loginSuccess(String ip, String login) {
counters.remove(loginKey(ip, login));
}
// ---------------------------------------------------------------- Registrierung
public synchronized long registrationBlockMinutes(String ip) {
return remainingMinutes("registration|" + ip);
}
// Zeitfenster von einer Stunde; sobald das Kontingent erreicht ist, gesperrt bis zum Ende der Stunde
public synchronized void registrationSuccess(String ip) {
count("registration|" + ip, maxRegistrations, ONE_HOUR, ONE_HOUR);
}
|
Im Vergleich zu [LimiterService] aus Beispiel 27 schützt der Limiter zwei Vorgänge (die Anmeldung und die Kontoerstellung), die Anmeldesperre gilt für das Paar (IP-Adresse, Login), und die Schwellenwerte sind in [application.properties] konfigurierbar. Kommentieren wir diesen Code:
- Zeilen 40–44: ein Zähler: die Anzahl der Versuche, der Beginn des Zählfensters und das Ende der Sperre ([Instant.MIN], der frühestmögliche Zeitpunkt, wenn keine Sperre besteht). Dies ist eine statische, private verschachtelte Klasse: Sie existiert nur für diesen Service. Es ist eine gewöhnliche Klasse, kein Record: Ein aus dem Dictionary gelesener Zähler wird an Ort und Stelle geändert, was bei einem Record nicht erlaubt ist;
- Zeile 48: eine gewöhnliche [HashMap], keine [ConcurrentHashMap]: Das Zählen eines Versuchs umfasst das Lesen eines Zählers, seine Änderung und gegebenenfalls seinen Ersatz, und diese gesamte Abfolge von Operationen muss ablaufen, ohne dass eine andere Anfrage sie unterbricht. Das ist die Aufgabe des Schlüsselworts [synchronized] (siehe Beispiel 27), das an jeder öffentlichen Methode steht: Nur ein [thread] kann zur Zeit eine der [synchronized]-Methoden des Objekts ausführen; die anderen warten, bis sie an der Reihe sind;
- Zeilen 54–58: die Schwellenwerte, ein für alle Mal aus dem Record [ProtectionProperties] gelesen, der die Eigenschaften [rdvmedecins.protection.*] typisiert bereitstellt: die Anzahl erlaubter Anmeldefehlversuche (standardmäßig 5), die Sperrdauer (15 Minuten) und die Anzahl der pro Stunde erstellten Konten (10);
- Zeilen 63–65: die verbleibende Sperrzeit für einen Anmeldeversuch: die längere der beiden möglichen Sperrzeiten, die des Paars (IP-Adresse, Login) und die der IP-Adresse allein;
- Zeilen 67–70: Ein fehlgeschlagener Versuch wird doppelt gezählt. Für das Paar (IP-Adresse, Login): Fünf fehlgeschlagene Versuche mit demselben Login sperren diesen Login, nur von dieser Adresse aus. Für die IP-Adresse allein mit einem fünfmal höheren Schwellenwert: Auch ein Bot, der sehr viele verschiedene Logins ausprobiert, wird gesperrt. In einem Klassenraum verbinden sich oft alle Rechner über dieselbe IP-Adresse mit dem Internet: Ein Schüler, der ein falsches Passwort eingibt, soll seine Nachbarn nicht sperren, daher die Sperre nach Paar;
- Zeilen 73–75: Eine erfolgreiche Anmeldung setzt den Zähler für genau diesen Login zurück (nicht den der IP-Adresse);
- Zeilen 79–86: Bei der Kontoerstellung werden nur erfolgreiche Versuche gezählt: höchstens zehn Konten pro Stunde von derselben IP-Adresse. Ist das Kontingent erreicht, wird die Adresse für eine Stunde gesperrt.
| // ---------------------------------------------------------------- gemeinsame Mechanik
// (die privaten Methoden werden immer von einer synchronized-Methode aufgerufen)
private long remainingMinutes(String key) {
Counter c = counters.get(key);
if (c == null) {
return 0;
}
Duration remaining = Duration.between(Instant.now(), c.blockedUntil);
// auf die Minute AUFGERUNDET: 30 s verbleibende Sperre -> "1 minute"
return remaining.isNegative() || remaining.isZero() ? 0 : (remaining.toSeconds() + 59) / 60;
}
// zählt einen Versuch; wird der Schwellenwert im Zeitfenster erreicht, sperrt es
private void count(String key, int max, Duration window, Duration block) {
Instant now = Instant.now();
purge(now);
Counter c = counters.get(key);
if (c == null || Duration.between(c.start, now).compareTo(window) > 0) {
c = new Counter();
c.start = now;
counters.put(key, c);
}
c.count++;
if (c.count >= max) {
c.blockedUntil = now.plus(block);
c.count = 0; // nach der Sperre beginnen wir wieder bei null
c.start = c.blockedUntil;
}
}
// wir vergessen die Zähler, die nicht mehr nützlich sind (weder gesperrt noch aktuell)
private void purge(Instant now) {
if (counters.size() < 1000) {
return;
}
counters.values().removeIf(c -> c.blockedUntil.isBefore(now)
&& Duration.between(c.start, now).compareTo(ONE_HOUR) > 0);
}
private static String loginKey(String ip, String login) {
return "login|" + ip + "|" + login.trim().toLowerCase(Locale.ROOT);
}
private static String ipKey(String ip) {
return "ip|" + ip;
}
}
|
Gehen wir diesen Code durch:
- Zeilen 4–12: die verbleibende Sperrzeit, auf die nächste ganze Zahl aufgerundet: Bei noch 20 verbleibenden Sekunden bleibt „1 Minute“, nicht „0 Minuten“. [Duration.between] misst die Zeitdifferenz zwischen zwei Zeitpunkten. Diese privaten Methoden sind nicht [synchronized]: Sie werden immer von einer öffentlichen Methode aufgerufen, die die Sperre des Objekts bereits hält;
- Zeilen 15–30: das Zählen. Ein unbekannter Schlüssel oder einer, dessen Zählfenster abgelaufen ist, beginnt mit einem neuen Zähler. Wird der Schwellenwert erreicht, wird der Schlüssel gesperrt, und das Zählen beginnt nach Aufhebung der Sperre wieder bei null;
- Zeilen 33–39: Bereinigung nicht mehr benötigter Zähler (weder gesperrt noch aktuell), die nur durchgeführt wird, wenn das Dictionary mehr als 1000 Einträge enthält. [values()] ist eine Sicht auf die Werte des Dictionarys: [removeIf] entfernt daraus die Zähler, und die entsprechenden Einträge verschwinden aus dem Dictionary;
- Zeilen 41–47: Erzeugung der Schlüssel des Dictionarys. Der Login wird von Leerzeichen befreit und in Kleinbuchstaben umgewandelt: [Admin] und [admin] teilen sich denselben Zähler; ein Bot kann die Sperre nicht durch Ändern der Groß- und Kleinschreibung umgehen. [Locale.ROOT] macht die Umwandlung unabhängig von der Sprache des Servers.
Untersuchen wir die Sperre. Ein Bot, der den Login [robot] versucht, ohne das Bild lesen zu können, scheitert am CAPTCHA; jeder Fehlschlag wird gezählt. Beim sechsten Versuch ist das Paar (IP-Adresse, [robot]) gesperrt, und das CAPTCHA wird nicht einmal mehr geprüft. Hier ist die Meldung, die für jeden der sechs Versuche am Seitenende angezeigt wird:
| curl -X POST -d "login=robot&password=x&captchaId=unknown&captcha=ABCDE" http://localhost:8081/login
|
| <div>The characters you typed do not match the image. A new image is shown.</div>
<div>The characters you typed do not match the image. A new image is shown.</div>
<div>The characters you typed do not match the image. A new image is shown.</div>
<div>The characters you typed do not match the image. A new image is shown.</div>
<div>The characters you typed do not match the image. A new image is shown.</div>
<div>Too many failed attempts. Try again in 15 minute(s).</div>
|
Die anderen Logins bleiben von derselben Adresse aus nutzbar.
11.13.9. auth/RegistrationPassService.java
| // =========================================================================
// auth/RegistrationPassService.java
// -------------------------------------------------------------------------
// Der "Pass" für die Kontoerstellung.
//
// Um die Seite "Create a client account" zu öffnen, muss man zuvor das
// CAPTCHA der Anmeldeseite abgetippt haben (siehe
// RegistrationController, POST /register/access). Der Server stellt dann
// einen Pass aus:
// - eine zufällige Kennung, in einem HttpOnly-Cookie gespeichert;
// - 15 Minuten gültig (die Zeit zum Ausfüllen des Formulars, auch bei
// mehreren Versuchen nach Eingabefehlern);
// - verbraucht, sobald ein Konto erstellt wird: EIN gelöstes CAPTCHA = höchstens EIN
// Konto. Ein Roboter kann keine Konten in Serie erstellen.
//
// Ohne gültigen Pass leiten GET und POST /register auf die
// Anmeldeseite um: Das direkte Eintippen der URL /register ermöglicht es nicht,
// das CAPTCHA zu umgehen.
//
// Wie das CAPTCHA leben die Pässe im Speicher des Prozesses.
// =========================================================================
package rdvmedecins.auth;
import java.time.Duration;
import java.time.Instant;
import java.util.Map;
import java.util.UUID;
import java.util.concurrent.ConcurrentHashMap;
import org.springframework.http.ResponseCookie;
import org.springframework.stereotype.Service;
@Service
public class RegistrationPassService {
public static final String COOKIE = "rdvmedecins_registration";
private static final Duration LIFETIME = Duration.ofMinutes(15);
private static final int MAX_PASSES = 10_000;
// id -> Ablaufdatum
private final Map<String, Instant> passes = new ConcurrentHashMap<>();
// stellt einen neuen Pass aus; gibt dessen Kennung zurück
public String issue() {
purge();
String id = UUID.randomUUID().toString();
passes.put(id, Instant.now().plus(LIFETIME));
return id;
}
// true, wenn [id] ein vorhandener, nicht abgelaufener Pass ist
public boolean isValid(String id) {
Instant expires = id == null ? null : passes.get(id);
return expires != null && expires.isAfter(Instant.now());
}
// der Pass wurde verwendet: Wir vergessen ihn
public void consume(String id) {
if (id != null) {
passes.remove(id);
}
}
// das Cookie wird vom Browser nur an die Adressen /register... gesendet
public static ResponseCookie cookie(String id) {
return ResponseCookie.from(COOKIE, id).httpOnly(true).sameSite("Lax").maxAge(LIFETIME)
.path("/register").build();
}
// ... und es wird gelöscht, indem man es erneut setzt, leer, mit einer Lebensdauer von null
public static ResponseCookie clearedCookie() {
return ResponseCookie.from(COOKIE, "").maxAge(0).path("/register").build();
}
private void purge() {
Instant now = Instant.now();
passes.values().removeIf(expires -> !expires.isAfter(now));
if (passes.size() >= MAX_PASSES) {
passes.clear();
}
}
}
|
Sie können über die Anmeldeseite ein Patientenkonto erstellen, sofern Sie das CAPTCHA gelöst haben. Das Registrierungsformular wird durch nachfolgende Anfragen angezeigt und abgesendet: Diese Anfragen müssen wissen, dass eine vorherige Anfrage das CAPTCHA erfolgreich gelöst hat. Das ist die Aufgabe des Tokens, das von [RegistrationController] ausgestellt und geprüft wird (siehe „Die Web-Schicht: Controller“):
- Zeile 36: der Name des Cookies, das das Token trägt;
- Zeilen 38–42: Ein Token ist fünfzehn Minuten lang gültig; ausstehende Token werden wie die CAPTCHAs im Speicher gehalten, mit derselben Zeitbegrenzung;
- Zeilen 45–50: Ein Pass ist ein zufälliger Bezeichner, gespeichert zusammen mit seinem Ablaufdatum; der Controller legt ihn in einem Cookie ab;
- Zeilen 53–56: Das Registrierungsformular wird nur mit einem gültigen Token angezeigt – und akzeptiert. Die Prüfung verbraucht das Token nicht ([get], nicht [remove]): Der Benutzer kann das Formular mehrmals erneut absenden, wenn ihm Eingabefehler unterlaufen sind;
- Zeilen 59–63: Die Erstellung eines Kontos verbraucht den Pass: Das Lösen eines CAPTCHAs berechtigt zu einem Konto und nicht mehr;
- Zeilen 66–74: das Cookie und sein Löschen. [path("/register")] beschränkt das Senden des Cookies auf Anfragen an URLs, die mit [/register] beginnen: Andere Anfragen tragen es nicht unnötig mit sich. Das gelöschte Cookie muss denselben Pfad haben;
- Zeilen 76–82: Bereinigung, identisch mit der für das CAPTCHA.
11.13.10. controllers/AuthController.java
Der Controller der Anmeldeseite wird in zwei Auszügen gezeigt.
| // =========================================================================
// controllers/AuthController.java
// -------------------------------------------------------------------------
// Die NICHT geschützten Routen der Anmeldung:
// GET / leitet auf die Startseite der Rolle weiter (oder auf /login)
// GET /login zeigt das Anmeldeformular an (mit seinem CAPTCHA)
// POST /login prüft Versuchsgrenze, CAPTCHA, Login / Passwort
// (POST /logout, die Abmeldung, wird von Spring Security selbst behandelt,
// siehe config/SecurityConfig.java)
//
// Schutz vor Robotern in dieser Reihenfolge:
// 1. zu viele aktuelle Fehlversuche für diesen Login von dieser IP-Adresse?
// -> sofortige Ablehnung, ohne das Passwort überhaupt anzusehen;
// 2. falsche Antwort auf das CAPTCHA? -> Ablehnung (als Fehlversuch gezählt);
// 3. erst danach Prüfung des Passworts.
// Das Passwort eines in Schritt 1 oder 2 abgelehnten Versuchs prüfen wir NIE:
// Ein Roboter kann daher durch Beharren nichts lernen.
// =========================================================================
package rdvmedecins.controllers;
import java.util.Map;
import java.util.Optional;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import rdvmedecins.auth.AuthService;
import rdvmedecins.auth.CaptchaService;
import rdvmedecins.auth.AttemptLimiterService;
import rdvmedecins.auth.ConnectedUser;
import rdvmedecins.entities.Role;
import rdvmedecins.entities.User;
import rdvmedecins.models.ViewModels.LoginModel;
import rdvmedecins.models.ViewModels.Message;
@Controller
public class AuthController {
private final AuthService authService;
private final CaptchaService captchaService;
private final AttemptLimiterService limiter;
public AuthController(AuthService authService, CaptchaService captchaService, AttemptLimiterService limiter) {
this.authService = authService;
this.captchaService = captchaService;
this.limiter = limiter;
}
// die Startseite jeder Rolle direkt nach der Anmeldung
public static String homePage(Role role) {
return role == Role.USER ? "/my-area" : "/schedule";
}
// -----------------------------------------------------------------------
// GET /
// Die Route ist öffentlich (siehe SecurityConfig): Spring Security hat den Benutzer
// möglicherweise ermittelt, wenn das Cookie ein gültiges Token enthält,
// verlangt aber nichts. AuthService.currentUser() sagt, ob es einen gibt (oder null).
// -----------------------------------------------------------------------
@GetMapping("/")
public String home(HttpServletRequest request) {
ConnectedUser user = authService.currentUser(request);
return "redirect:" + (user != null ? homePage(user.role()) : "/login");
}
// -----------------------------------------------------------------------
// GET /login[?login=xxx]: Der optionale Parameter füllt das
// Login-Feld vor (genutzt direkt nach der Erstellung eines Kontos, siehe RegistrationController)
// -----------------------------------------------------------------------
@GetMapping("/login")
public String showLogin(@RequestParam(required = false) String login, HttpServletRequest request,
Model model) {
// bereits angemeldet (Token noch gültig): direkt zur Startseite
ConnectedUser user = authService.currentUser(request);
if (user != null) {
return "redirect:" + homePage(user.role());
}
String input = login == null ? "" : login.substring(0, Math.min(login.length(), 30));
return form(model, input, null);
}
// -----------------------------------------------------------------------
// POST /login
// Die Parameter der Aktion werden mit den Formularfeldern
// gleichen Namens gefüllt. required = false: Ein fehlendes Feld ergibt null (und keinen
// 400-Fehler) - der Code entscheidet, was damit zu tun ist.
// -----------------------------------------------------------------------
|
Kommentieren wir diesen Code:
- Zeilen 11–17: Die Reihenfolge der Anmeldeprüfungen ist wichtig. Das Passwort eines Versuchs, der wegen einer Sperre oder eines falschen CAPTCHAs abgelehnt wurde, wird nie geprüft: Ein hartnäckiger Bot erfährt nichts;
- Zeilen 41–52: [@Controller] macht die Klasse zu einem Controller, dessen Actions Namen von Views zurückgeben (siehe Beispiel 13). Er erhält die drei benötigten Services über seinen Konstruktor. Keine Annotationen [@PreAuthorize]: Seine Seiten sind öffentlich (siehe [SecurityConfig]);
- Zeilen 55–57: Die Startseite hängt von der Rolle ab: „Mein Bereich“ für einen Patienten, der Kalender für die anderen. Die Methode ist statisch: Sie hängt von keinem Feld des Objekts ab;
- Zeilen 65–69: Das Stammverzeichnis der Website leitet (Präfix [redirect:], siehe Beispiel 04) auf die Startseite der Rolle oder auf die Anmeldeseite um. Die Route ist öffentlich, aber der Filter des Resource Servers läuft für alle Anfragen: Enthält das Cookie ein gültiges Token, ist der Benutzer authentifiziert, auch hier; [authService.currentUser] gibt den Benutzer zurück oder [null];
- Zeilen 75–85: Ein bereits angemeldeter Benutzer wird auf seine Startseite umgeleitet. Der optionale Parameter [login], aus der URL abgeleitet ([@RequestParam(required = false)], siehe Beispiel 07), füllt das Feld nach der Erstellung eines Kontos vorab aus. [substring] behält höchstens die ersten dreißig Zeichen: Daten aus der Anfrage werden nie ohne Vorsichtsmaßnahmen verwendet.
| @PostMapping("/login")
public String logIn(
@RequestParam(required = false) String login,
@RequestParam(required = false) String password,
@RequestParam(required = false) String captchaId,
@RequestParam(required = false) String captcha,
HttpServletRequest request, HttpServletResponse response, Model model) {
login = login == null ? "" : login.trim();
password = password == null ? "" : password;
String ip = ipAddress(request);
// 1. zu viele aktuelle Fehlversuche?
long minutes = limiter.loginBlockMinutes(ip, login);
if (minutes > 0) {
return form(model, login,
new Message("ERRORS.TOO_MANY_ATTEMPTS", Map.of("minutes", String.valueOf(minutes))));
}
// 2. das CAPTCHA
if (!captchaService.verify(captchaId, captcha)) {
limiter.loginFailure(ip, login);
return form(model, login, Message.of("ERRORS.WRONG_CAPTCHA"));
}
// 3. das Passwort
Optional<User> user = login.isEmpty() || password.isEmpty()
? Optional.empty()
: authService.validateUser(login, password);
if (user.isEmpty()) {
limiter.loginFailure(ip, login);
return form(model, login, Message.of("LOGIN.ERROR"));
}
limiter.loginSuccess(ip, login);
authService.setToken(response, user.get());
return "redirect:" + homePage(user.get().getRole());
}
// die IP-Adresse des Besuchers. Hinter einem Reverse Proxy (nginx...)
// müsste man server.forward-headers-strategy=native aktivieren, um die
// des Besuchers und nicht die des Proxys zu erhalten.
public static String ipAddress(HttpServletRequest request) {
return request.getRemoteAddr();
}
// das Formular, immer mit einem NEUEN CAPTCHA (jedes Bild wird nur
// einmal verwendet); wir zeigen den eingegebenen Login erneut an, nie das Passwort
private String form(Model model, String login, Message error) {
model.addAttribute("model", new LoginModel("LOGIN.TITLE", error, login, captchaService.generate()));
return "login";
}
}
|
Gehen wir diesen Code durch:
- Zeilen 2–7: die Felder des Anmeldeformulars (siehe Beispiel 11), einschließlich der CAPTCHA-ID, die über ein verstecktes Feld übergeben wird, und der Eingabe des Benutzers. Alle sind optional ([required = false]): Ein fehlendes Feld ergibt [null] statt eines Fehlers 400, und es ist Sache der Action, zu entscheiden, was damit geschieht. Die Action erhält außerdem die Anfrage (für die IP-Adresse und das CAPTCHA), die Antwort (um das Token-Cookie dort abzulegen) und das View-Modell;
- Zeilen 8–9: Ein fehlender Benutzername wird zu einer leeren Zeichenkette, von Leerzeichen befreit; ein fehlendes Passwort wird zu einer leeren Zeichenkette;
- Zeilen 13–17: 1. Ein gesperrtes Paar wird nicht einmal verarbeitet: Weder das CAPTCHA noch das Passwort wird geprüft. Der Fehler ist eine zu übersetzende Meldung (Record [Message], Datei [models]): ein Übersetzungsschlüssel und ein Parameter – die Anzahl der Minuten, die zu warten sind. [Map.of] erstellt ein schreibgeschütztes Dictionary;
- Zeilen 20–23: 2. das CAPTCHA. Ein falsches CAPTCHA zählt als Fehlversuch (siehe Beispiel 27);
- Zeilen 26–32: 3. Erst dann das Passwort. Ein leerer Benutzername oder ein leeres Passwort wird nicht der rechenintensiven [bcrypt]-Berechnung unterzogen: Es wird direkt eine leere Box verwendet ([Optional.empty()]). Unbekannter Benutzername oder falsches Passwort: dieselbe, absichtlich vage Meldung (siehe Beispiel 25) und ein weiterer Fehlversuch;
- Zeilen 34–36: Erfolg: Zähler auf null zurückgesetzt, Token im Cookie abgelegt, Umleitung auf die Startseite der Rolle. [user.get()] holt das Konto aus seiner Box, von der wir wissen, dass sie nicht leer ist;
- Zeilen 42–44: die IP-Adresse des Clients, von der Netzwerkverbindung geliefert. Die Methode ist öffentlich und statisch: [RegistrationController] und [PatientAreaController] verwenden sie ebenfalls für den Rate-Limiter. Hinter einem zwischengeschalteten Server (einem Reverse Proxy wie [nginx]) wäre diese Adresse die des Proxys: Der Kommentar weist darauf hin, dass in diesem Fall die Eigenschaft von [Spring Boot] aktiviert werden sollte;
- Zeilen 48–51: Die Anmeldeseite, die immer ein neues CAPTCHA anzeigt: Jedes Bild wird nur einmal verwendet. Ihr Modell, der Record [LoginModel] (Ordner [models]), enthält den Übersetzungsschlüssel für den Seitentitel, etwaige Fehlermeldungen, den eingegebenen Benutzernamen (nie das Passwort) und das CAPTCHA. Es wird im Modell unter dem Namen [model] abgelegt, dem Namen, den alle Views der Anwendung verwenden. Die View ist [login] (Datei [templates/login.html]).
Die Behandlung eines Versuchs mit falschem CAPTCHA lässt sich mit [curl] beobachten: Die Anmeldeseite wird zurückgegeben (Statuscode 200), mit dem eingegebenen Benutzernamen, einem neuen Bild und der Fehlermeldung am Seitenende:
| curl -i -X POST -d "login=admin&password=admin&captchaId=unknown&captcha=ABCDE" http://localhost:8081/login
|
| HTTP/1.1 200
Content-Type: text/html;charset=UTF-8
...
value="admin" required>
...
<div class="error-zone" role="alert">
<div>The characters you typed do not match the image. A new image is shown.</div>
...
|
Die Antwort erwähnt das Passwort nicht, das nicht geprüft wurde. Eine erfolgreiche Anmeldung lässt sich dagegen nicht mit [curl] zeigen, da das Bild gelesen werden muss; sie ist im Browser sichtbar (siehe „Verwendung der Anwendung“): Die Antwort auf das POST ist eine Umleitung (302) auf die Startseite der Rolle, mit dem Header [Set-Cookie] , der das Token setzt.
11.14. Die Web-Schicht: gemeinsame Services
Bevor wir zu den Controllern und Views kommen, hier das, was sie gemeinsam haben: Übersetzung, von allen Views geteilte Attribute, Flash-Meldungen, Ausnahmebehandlung, Zwischenspeicherung der Arzt- und Patientenlisten, Aufbereitung von Formularen für die erneute Anzeige und einige Hilfsfunktionen. Alle diese Dateien befinden sich im Ordner [web]. Er vereint die meisten Techniken der Beispiele 15 bis 24.
11.14.1. web/Translator.java
Die Datei wird in zwei Auszügen vorgestellt.
| // =========================================================================
// web/Translator.java
// -------------------------------------------------------------------------
// Französische / englische Übersetzung der Oberfläche (siehe Beispiel 22).
//
// Die Wörterbücher sind DIESELBEN Dateien wie die der NestJS- und
// ASP.NET-Core-Versionen der Anwendung (i18n/fr.json, i18n/en.json), die nur
// einmal beim Start gelesen werden.
//
// Die Bean heißt [messageSource] und implementiert das Interface MessageSource
// von Spring: Sie ist daher diejenige, die Thymeleaf für die Ausdrücke
// #{KEY} der Views verwendet. Die Parameter eines Textes ({name}, {minutes}...) werden
// auf zwei Arten übergeben:
// #{AREA.HELLO('name', ${patient})} als Paare (Name, Wert);
// #{${message.key}(${message.params})} als Dictionary (Map).
//
// DIE AKTUELLE SPRACHE: Sie wird vom LocaleResolver (siehe config/WebConfig.java)
// bei jeder Anfrage anhand eines Cookies bestimmt. Spring legt sie in
// LocaleContextHolder ab und gibt sie an Thymeleaf weiter.
// =========================================================================
package rdvmedecins.web;
import java.io.IOException;
import java.io.InputStream;
import java.util.HashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import org.springframework.context.MessageSource;
import org.springframework.context.MessageSourceResolvable;
import org.springframework.core.io.ClassPathResource;
import org.springframework.stereotype.Component;
import tools.jackson.databind.JsonNode;
import tools.jackson.databind.ObjectMapper;
@Component("messageSource")
public class Translator implements MessageSource {
public static final List<String> LANGUAGES = List.of("fr", "en");
public static final String DEFAULT_LANGUAGE = "en";
// {name}: ein Parameter in einem Text
private static final Pattern PARAMETER = Pattern.compile("\\{(\\w+)\\}");
// Sprache -> (vollständiger Schlüssel "LOGIN.TITLE" -> Text)
private final Map<String, Map<String, String>> dictionaries = new HashMap<>();
public Translator() throws IOException {
ObjectMapper json = new ObjectMapper();
for (String language : LANGUAGES) {
try (InputStream stream = new ClassPathResource("i18n/" + language + ".json").getInputStream()) {
Map<String, String> dictionary = new HashMap<>();
flatten(json.readTree(stream), "", dictionary);
dictionaries.put(language, dictionary);
}
}
}
// die unterstützte Sprache, die [locale] entspricht: "fr_FR" -> "fr" ; "de" -> "en"
public static String language(Locale locale) {
String language = locale == null ? "" : locale.getLanguage();
return LANGUAGES.contains(language) ? language : DEFAULT_LANGUAGE;
}
// -----------------------------------------------------------------------
// translate("DOCTORS.ADDED", { name: "Marie PELISSIER" }, en)
// -> sucht "DOCTORS.ADDED" im Wörterbuch der Sprache und
// ersetzt {name} durch dessen Wert. Ein in der angeforderten Sprache fehlender Schlüssel
// wird auf Englisch gesucht; fehlt er überall, zeigen wir den Schlüssel
// selbst an (ein Versäumnis fällt so sofort auf).
// -----------------------------------------------------------------------
public String translate(String key, Map<String, String> params, Locale locale) {
if (key == null || key.isEmpty()) {
return "";
}
String text = dictionaries.get(language(locale)).get(key);
if (text == null) {
text = dictionaries.get(DEFAULT_LANGUAGE).getOrDefault(key, key);
}
if (params == null || params.isEmpty()) {
return text;
}
Matcher m = PARAMETER.matcher(text);
return m.replaceAll(r -> Matcher.quoteReplacement(params.getOrDefault(r.group(1), r.group())));
}
|
Dies ist der Übersetzungsservice aus Beispiel 22. Die Dictionaries [i18n/fr.json] und [i18n/en.json] sind dieselben Dateien wie in der Version [ASP.NET Core] und werden beim Start nur einmal gelesen (siehe „Dictionaries“). Kommentieren wir diesen Code:
- Zeilen 40–41: Die Klasse implementiert die Schnittstelle [MessageSource] von [Spring], der Schnittstelle für Services, die Text liefern, und die Bean heißt [messageSource] (das Argument von [@Component]). Unter diesem Namen sucht [Spring] die [MessageSource] der Anwendung: Unsere Bean ersetzt daher diejenige, die [Spring Boot] konfiguriert hätte, und diese Bean wird von [Thymeleaf] bei jedem Ausdruck [#{KEY}] in den Views abgefragt (siehe Beispiel 22);
- Zeilen 43–44: die unterstützten Sprachen und die Standardsprache. [List.of] erstellt eine schreibgeschützte Liste;
- Zeile 47: ein regulärer Ausdruck , der einen Parameter im Text erkennt: [{], ein oder mehrere Wortzeichen ([\w+], durch Klammern erfasst), [}]. In einer [Java]-Zeichenkette wird der Backslash als [\\] geschrieben. Das Muster wird einmal kompiliert ([Pattern.compile]) und dann wiederverwendet;
- Zeile 50: für jede Sprache ein Dictionary „vollständiger Schlüssel → Text“. Die Bean ist ein Singleton, das von nebenläufigen Anfragen genutzt wird; eine einfache [HashMap] genügt jedoch, da die vom Konstruktor befüllten Dictionaries danach nur noch gelesen werden;
- Zeilen 52–61: Der Konstruktor liest die beiden JSON-Dateien. [ClassPathResource] bezeichnet eine Datei im „Classpath“ – der Menge von Ordnern und Archiven, in denen die virtuelle Maschine nach Klassen sucht: Der Ordner [src/main/resources] wird bei der Kompilierung dorthin kopiert. [ObjectMapper] ist das Werkzeug zum Lesen und Schreiben von JSON aus der Bibliothek [Jackson] (Version 3, daher das Paket [tools.jackson]). [readTree] gibt den Dokumentbaum des JSON zurück, den die Methode [flatten] in ein Dictionary umwandelt. Das Konstrukt [try (...)] schließt den Stream am Ende des Blocks, auch wenn eine Ausnahme auftritt. Fehlt eine Datei, verhindert die [IOException]-Ausnahme, die durch [throws] deklariert ist, den Start der Anwendung;
- Zeilen 64–67: Die unterstützte Sprache, die dem [Locale] entspricht, dem [Java]-Objekt, das eine Sprache und optional ein Land beschreibt: [en_US] ergibt [en]; eine nicht verwaltete Sprache ergibt [en];
- Zeilen 76–89: die Übersetzung. Fehlt ein Schlüssel im Dictionary der angeforderten Sprache, wird er im englischen Dictionary gesucht; fehlt er überall, wird der Schlüssel selbst zurückgegeben ([getOrDefault(key, key)]): Eine Auslassung ist sofort auf dem Bildschirm sichtbar. Die Parameter des Textes [{name}] werden dann durch ihre Werte ersetzt (Zeile 88): [replaceAll] ruft die Lambda-Funktion für jeden gefundenen Parameter auf; [r.group(1)] ist der Name, der zwischen den geschweiften Klammern erfasst wurde, [r.group()] ist der gesamte gefundene Text, und [{name}] bleibt unverändert, wenn kein Wert angegeben ist. [Matcher.quoteReplacement] maskiert die Zeichen [$] und [\], die für [replaceAll] sonst eine besondere Bedeutung hätten.
| // die von Thymeleaf (oder Spring) übergebenen Parameter: ein einziges
// Dictionary oder Paare (Name, Wert)
@SuppressWarnings("unchecked")
private static Map<String, String> params(Object[] args) {
Map<String, String> params = new HashMap<>();
if (args == null || args.length == 0) {
return params;
}
if (args.length == 1 && args[0] instanceof Map<?, ?> dictionary) {
dictionary.forEach((name, value) -> params.put(String.valueOf(name), String.valueOf(value)));
return params;
}
for (int i = 0; i + 1 < args.length; i += 2) {
params.put(String.valueOf(args[i]), String.valueOf(args[i + 1]));
}
return params;
}
// { "LOGIN": { "TITLE": "Login" } } -> { "LOGIN.TITLE": "Login" }
private static void flatten(JsonNode node, String prefix, Map<String, String> result) {
for (Map.Entry<String, JsonNode> property : node.properties()) {
String key = prefix.isEmpty() ? property.getKey() : prefix + "." + property.getKey();
if (property.getValue().isObject()) {
flatten(property.getValue(), key, result);
} else {
result.put(key, property.getValue().asString());
}
}
}
// ------------------------------------------------ das Interface MessageSource
@Override
public String getMessage(String code, Object[] args, String defaultMessage, Locale locale) {
return translate(code, params(args), locale);
}
@Override
public String getMessage(String code, Object[] args, Locale locale) {
return translate(code, params(args), locale);
}
// eine Nachricht, die durch mehrere mögliche Codes beschrieben wird (zum Beispiel ein
// Validierungsfehler): Der erste im Wörterbuch vorhandene Code
// gewinnt; andernfalls die Standardnachricht, die selbst ein Schlüssel ist
@Override
public String getMessage(MessageSourceResolvable message, Locale locale) {
Map<String, String> dictionary = dictionaries.get(language(locale));
String[] codes = message.getCodes() == null ? new String[0] : message.getCodes();
for (String code : codes) {
if (dictionary.containsKey(code)) {
return translate(code, params(message.getArguments()), locale);
}
}
return translate(message.getDefaultMessage(), Map.of(), locale);
}
}
|
Gehen wir diesen Code durch:
- Zeilen 5–18: Die Parameter einer Nachricht werden auf zwei mögliche Arten als Array von Objekten ([Object[]]) übergeben. Eine View, die [#{AREA.HELLO('name', ${patient})}] schreibt, übergibt (Name, Wert)-Paare (Zeilen 14–16). Eine View, die eine Flash-Nachricht oder einen Fehler anzeigt, schreibt [#{${message.key}(${message.params})}]: Sie übergibt ein einziges Argument, das Parameterverzeichnis (Zeilen 10–13). [instanceof Map<?, ?> dictionary] prüft den Typ und speichert das umgewandelte Objekt in der Variablen [dictionary]; [<?, ?>] bedeutet „Schlüssel und Werte beliebigen Typs“. [String.valueOf] wandelt jedes Objekt in Text um;
- Zeilen 21–30: Abflachen von JSON: [{ "LOGIN": { "TITLE": "Login" } }] wird zu [{ "LOGIN.TITLE": "Login" }]. Die Methode ist rekursiv: Sie ruft sich für jedes verschachtelte Objekt selbst auf und erweitert dabei das Schlüsselpräfix;
- Zeilen 34–42: die beiden Hauptmethoden der Schnittstelle [MessageSource]: ein Code (der Schlüssel), seine Argumente und die Sprache. [@Override] weist den Compiler an zu prüfen, dass die Methode tatsächlich eine Methode der Schnittstelle neu definiert. Die von der ersten Methode angebotene Standardnachricht wird ignoriert: Ein fehlender Schlüssel wird unverändert angezeigt;
- Zeilen 47–57: Die dritte Methode erhält eine Nachricht, die durch mehrere mögliche Codes beschrieben wird, etwa solche, wie sie von [Spring] bei einem Validierungs- oder Konvertierungsfehler erzeugt werden ([typeMismatch.version], [typeMismatch] ...). Der erste im Verzeichnis gefundene Code hat Vorrang; andernfalls wird die Standardnachricht übersetzt. In dieser Anwendung sind die Nachrichten der Validierungsbedingungen Übersetzungsschlüssel (siehe [models/Forms.java]): Die Standardnachricht ist somit selbst ein Schlüssel.
Die Sprache der Anfrage taucht in den Controllern nirgends auf: Sie wird vom [LocaleResolver] (Bean [localeResolver] aus [config/WebConfig.java], siehe „Projektkonfiguration“) zu Beginn jeder Anfrage aus dem Cookie [rdvmedecins_language] gelesen; [Spring] übergibt sie dann an [Thymeleaf], das sie an [getMessage] weitergibt.
11.14.2. web/CommonModel.java
| // =========================================================================
// web/CommonModel.java
// -------------------------------------------------------------------------
// Was ALLE Views benötigen, unabhängig von der Seite (siehe Beispiel
// 15): @ControllerAdvice macht diese Klasse zu einer Ergänzung aller
// Controller, und jede @ModelAttribute-Methode, die vor jeder
// Aktion ausgeführt wird, fügt dem Modell der View ein Attribut hinzu:
// - user : der angemeldete Benutzer (oder null) für die Navigationsleiste;
// - language : "fr" oder "en";
// - path : die angeforderte URL (aktives Menü der Navigationsleiste,
// Link "Another image" des CAPTCHAs).
// Die Flash-Nachricht wird von Spring MVC selbst dem Modell hinzugefügt,
// unter dem Namen [flash] (siehe CookieFlashMapManager.java).
// =========================================================================
package rdvmedecins.web;
import java.util.Locale;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ModelAttribute;
import jakarta.servlet.http.HttpServletRequest;
import rdvmedecins.auth.AuthService;
import rdvmedecins.auth.ConnectedUser;
@ControllerAdvice
public class CommonModel {
private final AuthService authService;
public CommonModel(AuthService authService) {
this.authService = authService;
}
@ModelAttribute("user")
public ConnectedUser user(HttpServletRequest request) {
return authService.currentUser(request);
}
// Locale: die Sprache der Anfrage, von Spring bereitgestellt (siehe config/WebConfig.java)
@ModelAttribute("language")
public String language(Locale locale) {
return Translator.language(locale);
}
@ModelAttribute("path")
public String path(HttpServletRequest request) {
return request.getRequestURI();
}
}
|
Alle Seiten zeigen dieselbe Navigationsleiste: den Namen des angemeldeten Benutzers, seine rollenabhängigen Menüs, das aktuell ausgewählte, hervorgehobene Menü und die Schaltflächen FR / EN. Das Template jeder View muss daher den Benutzer, die Sprache und die angeforderte URL enthalten. Statt sie in jeder Action hinzuzufügen, ergänzen wir sie ein für alle Mal, wie in Beispiel 15:
- Zeile 26: [@ControllerAdvice] macht die Klasse zu einer Komponente aller Controller (siehe Beispiele 15 und 24);
- Zeilen 35–38: Eine Methode mit der Annotation [@ModelAttribute("user")] wird vor jeder Action ausgeführt, und der zurückgegebene Wert wird dem Template unter dem angegebenen Namen hinzugefügt. Hier ist es der angemeldete Benutzer oder [null], ermittelt über [AuthService.currentUser] (siehe [auth/AuthService.java]): Die Navigationsleiste zeigt [${user.name}], [${user.isAdmin()}] ... an. Wie Actions erhalten diese Methoden die Parameter, die sie benötigen – hier die Anfrage;
- Zeilen 41–44: die aktuelle Sprache ([fr] oder [en]) für das Attribut [lang] der Seite und die Schaltflächen FR / EN. Ein Parameter vom Typ [Locale] erhält die Sprache der Anfrage, die vom [LocaleResolver] festgelegt wird;
- Zeilen 47–49: der Pfad der angeforderten URL, zum Beispiel [/my-area]: Die Navigationsleiste hebt das Menü hervor, dessen Pfad so beginnt (siehe Beispiel 16), und der Link „Anderes Bild“ des CAPTCHA lädt die aktuelle Seite neu.
Die Flash-Nachricht, das vierte gemeinsame Datum, benötigt keine Methode: [Spring MVC] fügt sie dem Template selbst hinzu (siehe [CookieFlashMapManager.java], weiter unten). In [ASP.NET Core MVC] bestanden diese Daten aus Eigenschaften einer von allen Views gemeinsam genutzten Elternklasse; [Thymeleaf] kennt keine Elternklasse für die Views, stattdessen erhält das Template jeder View diese Daten.
11.14.3. web/FlashType.java
| // =========================================================================
// web/FlashType.java - die beiden Arten von Flash-Nachrichten (siehe Flash.java)
// =========================================================================
package rdvmedecins.web;
public enum FlashType {
SUCCESS, // Bootstrap-Klasse alert-success: oben auf der Seite
DANGER // ein Fehler: unten auf der Seite (siehe templates/fragments/errors.html)
}
|
- Zeilen 6–9: die beiden Typen von Flash-Nachrichten in Form einer Enumeration: ein Typ, dessen mögliche Werte ein für alle Mal festgelegt sind. Eine Erfolgsmeldung wird oben auf der Seite angezeigt (Fragment [templates/fragments/flash.html]), eine Fehlermeldung unten (Fragment [templates/fragments/errors.html]; siehe „Views“).
11.14.4. web/FlashMessage.java
| // =========================================================================
// web/FlashMessage.java
// -------------------------------------------------------------------------
// Eine "Flash"-Nachricht: eine Nachricht, die EINMAL auf der NÄCHSTEN Seite angezeigt wird
// (siehe Beispiel 20). key: Übersetzungsschlüssel; params: deren Parameter
// ({name}, {login}...).
// =========================================================================
package rdvmedecins.web;
import java.util.Map;
public record FlashMessage(FlashType type, String key, Map<String, String> params) {
// der Name des Flash-Attributs im Modell der Views
public static final String ATTRIBUTE = "flash";
public static FlashMessage success(String key) {
return new FlashMessage(FlashType.SUCCESS, key, Map.of());
}
public static FlashMessage success(String key, Map<String, String> params) {
return new FlashMessage(FlashType.SUCCESS, key, params);
}
public static FlashMessage error(String key) {
return new FlashMessage(FlashType.DANGER, key, Map.of());
}
public static FlashMessage error(String key, Map<String, String> params) {
return new FlashMessage(FlashType.DANGER, key, params);
}
public boolean successful() {
return type == FlashType.SUCCESS;
}
}
|
- Zeile 12: Eine Flash-Nachricht (siehe Beispiel 20) besteht aus einem Typ, einem Übersetzungsschlüssel und seinen Parametern – nicht aus bereits übersetztem Text – und wird von der nächsten Seite in deren Sprache übersetzt;
- Zeile 15: der Name, unter dem die Nachricht übergeben wird und unter dem die Views sie in ihrem Template finden: [flash]. Ein Controller schreibt zum Beispiel [redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.success("SCHEDULE.CANCELLED"))];
- Zeilen 17–31: vier statische Methoden, die eine Nachricht mit oder ohne Parameter erzeugen. Methoden mit gleichem Namen, aber unterschiedlichen Parametern sind Überladungen: Der Compiler wählt anhand der Argumente die richtige aus. [Map.of()] ist ein leeres Verzeichnis;
- Zeilen 33–35: ein Test für die Views: [${flash.successful()}].
11.14.5. web/CookieFlashMapManager.java
| // =========================================================================
// web/CookieFlashMapManager.java
// -------------------------------------------------------------------------
// Die "Flash"-Nachrichten: eine Nachricht, die EINMAL auf der NÄCHSTEN
// Seite angezeigt wird. Sie ist die natürliche Ergänzung des Musters "Post / Redirect / Get",
// das alle Formulare der Anwendung nutzen: Ein erfolgreicher POST baut
// keine Seite auf, sondern leitet (302) auf eine GET-Seite weiter; die Nachricht
// muss die Weiterleitung überstehen.
//
// Spring MVC bietet das standardmäßig an: Ein Controller legt ein Flash-Attribut ab
// (RedirectAttributes.addFlashAttribute, siehe Beispiel 20), das im Modell der
// NÄCHSTEN Anfrage landet und dann verschwindet. Standardmäßig
// hält Spring es in der HTTP-SITZUNG (SessionFlashMapManager). Aber unser
// Server ist ZUSTANDSLOS: Er behält nichts zwischen zwei Anfragen (das JWT-Token
// liegt in einem Cookie). Wir ersetzen daher den "Flash-Attribut-Manager"
// (FlashMapManager) von Spring durch unseren eigenen, der sie in einem
// COOKIE speichert - es ist die Bean [flashMapManager] aus config/WebConfig.java.
//
// AbstractFlashMapManager erledigt den Großteil der Arbeit (für welche Anfrage die
// Nachricht bestimmt ist, Ablauf...): Es bleibt nur, die
// Liste der Flash-Attribute zu lesen und zu schreiben. Wir behalten nur eines, als JSON-Text,
// base64-kodiert (ein Cookie kann nicht beliebige Zeichen enthalten).
//
// Das Cookie ist weder verschlüsselt noch signiert: Es enthält nur einen Übersetzungsschlüssel
// und dessen Parameter, die maskiert angezeigt werden. Ein Benutzer, der
// es veränderte, würde nur die Nachricht ändern, die er selbst sieht.
// =========================================================================
package rdvmedecins.web;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.Base64;
import java.util.List;
import org.springframework.http.HttpHeaders;
import org.springframework.http.ResponseCookie;
import org.springframework.web.servlet.FlashMap;
import org.springframework.web.servlet.support.AbstractFlashMapManager;
import org.springframework.web.util.WebUtils;
import jakarta.servlet.http.Cookie;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import tools.jackson.databind.ObjectMapper;
public class CookieFlashMapManager extends AbstractFlashMapManager {
public static final String COOKIE = "rdvmedecins_flash";
// was das Cookie enthält: die Seite, für die die Nachricht bestimmt ist, das
// Ablaufdatum (in Millisekunden), die Nachricht
private record CookieContent(String path, long expires, FlashMessage flash) {
}
private final ObjectMapper json = new ObjectMapper();
// die Flash-Attribute der vorherigen Anfrage (null: keine)
@Override
protected List<FlashMap> retrieveFlashMaps(HttpServletRequest request) {
Cookie cookie = WebUtils.getCookie(request, COOKIE);
if (cookie == null) {
return null;
}
try {
byte[] bytes = Base64.getUrlDecoder().decode(cookie.getValue());
CookieContent content = json.readValue(bytes, CookieContent.class);
FlashMap flashMap = new FlashMap();
flashMap.put(FlashMessage.ATTRIBUTE, content.flash());
flashMap.setTargetRequestPath(content.path());
flashMap.setExpirationTime(content.expires());
// eine ÄNDERBARE Liste: Spring entfernt die verbrauchten Nachrichten
// selbst daraus (List.of(...) würde eine unveränderliche Liste liefern)
return new ArrayList<>(List.of(flashMap));
} catch (RuntimeException e) {
return null; // unlesbares Cookie: Wir ignorieren es
}
}
// die für die nächsten Anfragen zu behaltende Liste: leer -> wir löschen das Cookie
@Override
protected void updateFlashMaps(List<FlashMap> flashMaps, HttpServletRequest request,
HttpServletResponse response) {
ResponseCookie cookie;
if (flashMaps.isEmpty() || !(flashMaps.getLast().get(FlashMessage.ATTRIBUTE) instanceof FlashMessage flash)) {
cookie = ResponseCookie.from(COOKIE, "").path("/").maxAge(0).build();
} else {
FlashMap last = flashMaps.getLast();
CookieContent content = new CookieContent(last.getTargetRequestPath(), last.getExpirationTime(), flash);
String value = Base64.getUrlEncoder().withoutPadding()
.encodeToString(json.writeValueAsString(content).getBytes(StandardCharsets.UTF_8));
cookie = ResponseCookie.from(COOKIE, value).path("/").httpOnly(true).sameSite("Lax").build();
}
response.addHeader(HttpHeaders.SET_COOKIE, cookie.toString());
}
}
|
In Beispiel 20 wurden die Flash-Attribute von [Spring MVC] zwischen der Weiterleitung und der nächsten Seite in der HTTP-Sitzung aufbewahrt: einem Speicherbereich auf dem Server, der für jeden Browser eigens angelegt und über das Cookie [JSESSIONID] identifiziert wird. Unser Server ist jedoch zustandslos: Er behält zwischen Anfragen nichts im Speicher, da der Benutzer über sein Token identifiziert wird. Diese Klasse speichert die Flash-Attribute daher in einem Cookie, genau wie es [TempData] in der [ASP.NET Core]-Version tat. Kommentieren wir diesen Code:
- Zeile 46: [Spring MVC] delegiert die Speicherung der Flash-Attribute an eine Bean vom Typ [FlashMapManager]. [AbstractFlashMapManager] erledigt den Großteil der Arbeit: Sie weiß, für welche Anfrage ein Flash-Attribut bestimmt ist, wann es abläuft und wann es verbraucht wurde. Eine abgeleitete Klasse muss nur zwei Methoden implementieren: das Lesen der Liste der ausstehenden Flash-Attribute (Zeilen 58–77) und das Speichern dieser Liste (Zeilen 80–94). Die Bean [flashMapManager] aus [config/WebConfig.java] erzeugt ein Objekt dieser Klasse; sie trägt den Namen, unter dem [Spring MVC] nach diesem Handler sucht, und ersetzt somit den von [Spring MVC];
- Zeilen 52–53: der Inhalt des Cookies: der Pfad der Seite, für die die Nachricht bestimmt ist, ihr Ablaufdatum (in Millisekunden) und die Nachricht;
- Zeile 55: [Jackson] wandelt ein Objekt in JSON-Text um und umgekehrt, auch einen Record;
- Zeilen 58–77: der Lesevorgang, der zu Beginn jeder Anfrage aufgerufen wird. Das Cookie wird dekodiert (Base64, dann JSON), und die Nachricht wird wieder in ein [FlashMap]-Objekt eingefügt (ein Verzeichnis von Flash-Attributen mit Zielpfad und Ablaufdatum), das einzige in der Liste. Die zurückgegebene Liste muss veränderbar sein (Zeilen 71–73): [Spring MVC] entfernt die Nachricht selbst aus der Liste, wenn es sie verbraucht. Ein unlesbares Cookie (zum Beispiel manuell verändert) darf die Seite nicht zum Absturz bringen: Die Exception wird abgefangen und das Cookie ignoriert;
- Zeilen 80–94: die Funktion, die aufgerufen wird, wenn sich die Liste geändert hat – eine Nachricht wurde gesendet, verbraucht oder ist abgelaufen. Eine leere Liste löscht das Cookie; andernfalls wird die zuletzt gesendete Nachricht in das Cookie geschrieben. Der in der Bedingung stehende Ausdruck [instanceof FlashMessage flash]prüft den Typ des Attributs und speichert es in der Variablen [flash], die in Zeile 88 verwendet wird. Der JSON-Text wird in Base64 kodiert ([Base64.getUrlEncoder()], eine Variante ohne die Zeichen [+] und [/]), weil ein Cookie nicht beliebige Zeichen enthalten darf; die Anführungszeichen und Akzente in JSON sind nicht zulässig. Das Cookie hat keine Ablaufzeit ([Max-Age]): Es ist ein Browser-Sitzungs-Cookie, und entscheidend ist die Ablaufzeit des Inhalts (standardmäßig drei Minuten);
- Zeilen 24–26: Das Cookie ist weder verschlüsselt noch signiert, anders als das Cookie von [TempData] und [ASP.NET Core]. Das ist unnötig: Es enthält nur einen Übersetzungsschlüssel und seine Parameter, die von den Views maskiert (escaped) angezeigt werden; ein Benutzer, der es veränderte, würde nur die Nachricht ändern, die er selbst sieht.
Wir haben bei [SecurityConfig] gesehen, dass eine Nachricht „Sitzung abgelaufen“ in diesem Cookie gespeichert wurde. Hier ist der dekodierte Inhalt des Cookies, das im folgenden Befehl verwendet wird (erfasst bei einem anderen Test als dem oben gezeigten: Nur das Ablaufdatum unterscheidet sich):
| {"path":"/login","expires":1790355130312,"flash":{"type":"DANGER","key":"ERRORS.SESSION_EXPIRED","params":{}}}
|
Die folgende Anfrage an [/login] verbraucht die Nachricht: Die Seite zeigt sie an, und die Antwort löscht das Cookie.
| curl -i -H "Cookie: rdvmedecins_flash=eyJwYXRoIjoiL2xvZ2luIiwiZXhwaXJlcyI6MTc5MDM1NTEzMDMxMiwiZmxhc2giOnsidHlwZSI6IkRBTkdFUiIsImtleSI6IkVSUk9SUy5TRVNTSU9OX0VYUElSRUQiLCJwYXJhbXMiOnt9fX0" http://localhost:8081/login
|
| HTTP/1.1 200
Set-Cookie: rdvmedecins_flash=; Path=/; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: text/html;charset=UTF-8
...
<div class="error-zone" role="alert">
<div>Your session has expired: please log in again.</div>
</div>
...
|
Die Nachricht wird nur einmal angezeigt: Beim erneuten Laden der Seite erscheint sie nicht mehr.
11.14.6. web/Flash.java
| // =========================================================================
// web/Flash.java
// -------------------------------------------------------------------------
// Eine Flash-Nachricht von ÜBERALL setzen, auch außerhalb von
// Spring MVC: Die JWT-Authentifizierung (abgelaufene Sitzung, siehe
// config/SecurityConfig.java) läuft in einem Spring-Security-Filter,
// VOR Spring MVC - ein RedirectAttributes existiert dort noch nicht.
// Wir wenden uns daher direkt an den FlashMapManager (CookieFlashMapManager).
// In einem Controller verwenden wir stattdessen RedirectAttributes.addFlashAttribute.
// =========================================================================
package rdvmedecins.web;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.FlashMap;
import org.springframework.web.servlet.FlashMapManager;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
@Component
public class Flash {
private final FlashMapManager manager;
public Flash(FlashMapManager manager) {
this.manager = manager;
}
// legt [message] ab, bestimmt für die Seite [target] (die nächste Anfrage)
public void put(HttpServletRequest request, HttpServletResponse response, FlashMessage message, String target) {
FlashMap flashMap = new FlashMap();
flashMap.put(FlashMessage.ATTRIBUTE, message);
flashMap.setTargetRequestPath(target);
manager.saveOutputFlashMap(flashMap, request, response);
}
}
|
In einem Controller wird eine Flash-Nachricht mit [RedirectAttributes.addFlashAttribute] angezeigt (siehe Beispiel 20). Der Einstiegspunkt von [SecurityConfig]hingegen wird in einem Filter von [Spring Security] ausgeführt, bevor [Spring MVC] die Anfrage übernommen hat:
- Zeile 20: [@Component] macht die Klasse zu einer Bean, die [SecurityConfig] als Parameter erhält;
- Zeilen 25–27: Die Bean erhält den Handler für Flash-Attribute, also unseren [CookieFlashMapManager];
- Zeilen 30–35: Wir erzeugen die [FlashMap] selbst – was normalerweise [Spring MVC] tut – einschließlich der Nachricht und des Pfads der Seite, die sie erhalten soll ([/login]). [saveOutputFlashMap] übergibt sie an den Handler, der das Cookie in die Antwort schreibt.
11.14.7. web/HtmlExceptionHandler.java
| // =========================================================================
// web/HtmlExceptionHandler.java
// -------------------------------------------------------------------------
// Wie Fehler zu HTML-Seiten werden. Drei Mechanismen
// teilen sich die Arbeit (siehe Beispiel 24):
//
// 1. diese Klasse: eine InvalidSessionException (seit der Anmeldung
// gelöschtes Konto) -> zurück zur Anmeldeseite;
// 2. eine Fehlerantwort 400, 403 oder 404 (ResponseStatusException, ausgelöst
// von einem Controller, unzureichende Rolle, unbekannte Seite...) wird
// vom Server an die Adresse /error weitergegeben: ErrorController macht daraus eine Seite;
// 3. jede andere Ausnahme (eine echte Anomalie) wird ins
// Server-Log geschrieben und dann ebenfalls an /error weitergegeben: Der Benutzer
// sieht die Fehlerseite 500 - nie den Stacktrace.
// =========================================================================
package rdvmedecins.web;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.servlet.support.RequestContextUtils;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import rdvmedecins.auth.AuthService;
import rdvmedecins.auth.InvalidSessionException;
@ControllerAdvice
public class HtmlExceptionHandler {
@ExceptionHandler(InvalidSessionException.class)
public String invalidSession(HttpServletRequest request, HttpServletResponse response) {
AuthService.clearToken(response);
// das Flash-Attribut der darauf folgenden Weiterleitung (das Äquivalent von
// RedirectAttributes.addFlashAttribute, für eine @ExceptionHandler-Methode)
RequestContextUtils.getOutputFlashMap(request)
.put(FlashMessage.ATTRIBUTE, FlashMessage.error("ERRORS.SESSION_EXPIRED"));
return "redirect:/login";
}
// die anderen Ausnahmen werden hier nicht behandelt: Sie werden
// an den Server weitergegeben, der sie an /error übergibt (Seite 500)
}
|
Der Kopfkommentar (Zeilen 4–14) beschreibt die drei Mechanismen, die Fehler in HTML-Seiten umwandeln (siehe Beispiel 24). Zwei davon benötigen keinen Code: Eine Fehlerantwort ([sendError(403)], eine von einem Controller ausgelöste [ResponseStatusException] , eine unbekannte URL) wird vom Server an die Adresse [/error] gesendet, wo [ErrorController] die Seite erzeugt; eine unbehandelte Exception wird samt Aufrufstapel im Serverprotokoll aufgezeichnet und dann ebenfalls an [/error]weitergeleitet, das die Fehlerseite 500 anzeigt. Der Benutzer sieht nie den Aufrufstapel, der einem Angreifer helfen würde (Eigenschaft [spring.web.error.include-stacktrace=never]; siehe „Projektkonfiguration“). Es bleibt ein Sonderfall, der hier behandelt wird:
- Zeile 27: [@ControllerAdvice], wie bei [CommonModel]: Die Methoden der Klasse gelten für alle Controller;
- Zeilen 30–31: Eine Methode mit [@ExceptionHandler] wird aufgerufen, wenn eine Action die angegebene Exception auslöst (siehe Beispiel 24). Sie kann die Anfrage und die Antwort erhalten und wie eine Action einen View-Namen oder eine Weiterleitung zurückgeben;
- Zeilen 32–37: Das Konto des angemeldeten Benutzers wurde seit der Anmeldung gelöscht, obwohl sein Token noch gültig ist (siehe [auth/InvalidSessionException.java]). Wir löschen das Token-Cookie, zeigen eine Flash-Nachricht „Sitzung abgelaufen“ an und leiten zur Anmeldeseite weiter: Der Benutzer wird behandelt, als wäre seine Sitzung abgelaufen. Eine Methode mit der Annotation [@ExceptionHandler] kann keinen Parameter vom Typ [RedirectAttributes] annehmen: [RequestContextUtils.getOutputFlashMap(request)] gibt direkt die [FlashMap] zurück, die die Weiterleitung an die nächste Seite übergibt.
11.14.8. web/ApplicationModel.java
Die Datei wird in zwei Auszügen dargestellt.
| // =========================================================================
// web/ApplicationModel.java
// -------------------------------------------------------------------------
// Der Cache / die Fassade, die im JSON-Server bereits vorhanden ist (Äquivalent der Klasse
// [ApplicationModel] des ursprünglichen Spring-Projekts): Die Listen der
// Ärzte und Clients werden beim Start einmal gelesen und dann
// aus dem Speicher bereitgestellt.
//
// Diese Listen können sich ÄNDERN (der ADMIN fügt Ärzte und Clients hinzu, bearbeitet und löscht sie):
// Jeder Schreibvorgang läuft daher über diese Fassade,
// die die betroffene Liste unmittelbar danach neu lädt. Das ist der ganze Sinn
// eines EINZIGEN Einstiegspunkts in die Geschäftsschicht: Die Regel "Schreiben =>
// Cache neu laden" steht nur hier.
//
// Die Fassade ist eine SINGLETON-Bean wie die Geschäftsschicht selbst: Bei Spring
// hängen die DAOs und die Geschäftsschicht von keiner Anfrage ab (Spring
// ordnet jedem Thread SEINE Transaktion und SEINE Verbindung zu). Cache
// und Fassade können daher dasselbe Objekt sein.
//
// Spring verarbeitet die Anfragen PARALLEL auf mehreren Threads. Wir ändern daher nie
// eine Liste an Ort und Stelle: Wir ERSETZEN sie vollständig durch eine
// neue. Das Austauschen einer Referenz ist atomar; "volatile" garantiert, dass
// alle Threads sofort die neue Liste sehen.
// =========================================================================
package rdvmedecins.web;
import java.time.LocalDate;
import java.util.List;
import java.util.Objects;
import java.util.Optional;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Service;
import jakarta.annotation.PostConstruct;
import rdvmedecins.domain.DoctorDaySchedule;
import rdvmedecins.entities.Client;
import rdvmedecins.entities.Slot;
import rdvmedecins.entities.Doctor;
import rdvmedecins.entities.Appointment;
import rdvmedecins.business.PersonData;
import rdvmedecins.business.Business;
// derselbe Vertrag wie die Geschäftsschicht (Business)
@Service
public class ApplicationModel implements Business {
private final Business business;
private volatile List<Doctor> doctors = List.of();
private volatile List<Client> clients = List.of();
// zwei Beans implementieren Business: BusinessService und ApplicationModel
// selbst. @Qualifier bezeichnet anhand ihres Namens die gewünschte.
public ApplicationModel(@Qualifier("businessService") Business business) {
this.business = business;
}
// -----------------------------------------------------------------------
// Erstladen der beiden Listen. @PostConstruct: Spring ruft
// diese Methode auf, sobald das Objekt erstellt und seine Abhängigkeiten injiziert sind, beim
// Start der Anwendung. Ein Lesefehler wird nicht abgefangen:
// Er stoppt den Server, statt ihn "leer" starten zu lassen (eine
// nicht erreichbare Datenbank stoppt ihn schon früher, sobald Hibernate startet).
// -----------------------------------------------------------------------
@PostConstruct
public void load() {
reloadDoctors();
reloadClients();
}
private void reloadDoctors() {
doctors = List.copyOf(business.getAllDoctors());
}
private void reloadClients() {
clients = List.copyOf(business.getAllClients());
}
// ------------------------------------------------ Lesezugriffe auf den Cache
@Override
public List<Doctor> getAllDoctors() {
return doctors;
}
@Override
public List<Client> getAllClients() {
return clients;
}
// der Arzt, dessen Benutzerkonto [userId] ist - dient dazu, für einen angemeldeten
// Arzt dessen eigenen Terminkalender vorauszuwählen
public Optional<Doctor> getDoctorByUserId(int userId) {
return doctors.stream().filter(d -> Objects.equals(d.getUserId(), userId)).findFirst();
}
|
Listen von Ärzten und Clients werden auf fast jeder Seite angezeigt (Dropdown-Listen im Terminkalender, Administrationsseiten). Statt sie bei jeder Anfrage aus der Datenbank abzurufen, halten wir sie im Speicher: Dies sind Daten mit Anwendungsbereich (siehe Beispiel 23). Kommentieren wir diesen Code:
- Zeilen 45–46: Die Klasse ist eine Singleton-Bean, die die Schnittstelle [Business] implementiert, die Schnittstelle der Geschäftsschicht (siehe „Die Geschäftsschicht“): Für die Controller ist diese Klasse die Geschäftsschicht, und sie ist die einzige, die sie erhalten (zum Beispiel [public ScheduleController(ApplicationModel application)]). Sie ist eine Fassade: ein einziger Einstiegspunkt, der verbirgt, was dahinter liegt. In [ASP.NET Core]musste der Cache ein von der Fassade getrennter Service sein, weil die Geschäftsschicht dort nur für die Dauer einer Anfrage existiert; mit [Spring] ist die Geschäftsschicht selbst ein Singleton (es ist [Spring] , das jeden [thread] seiner Transaktion und seiner Datenbankverbindung zuordnet): Ein einziges Objekt genügt (Zeilen 15–18);
- Zeile 48: die eigentliche Geschäftsschicht, [BusinessService], an die die Fassade die Anfragen weiterleitet;
- Zeilen 50–51: der Cache selbst: die beiden Listen, die anfangs leer sind ([List.of()]). [Spring] verarbeitet Anfragen parallel in mehreren [threads]-Instanzen. Eine gemeinsam genutzte Liste darf daher niemals verändert werden, während eine andere Anfrage sie durchläuft. Die gewählte Regel ist einfach: Eine Liste wird nie verändert, sondern durch eine neue ersetzt. Das Ersetzen einer Referenz erfolgt in einem einzigen Schritt, und das Schlüsselwort [volatile] stellt sicher, dass alle [threads]-Instanzen die neue Liste sofort sehen; ohne es könnte ein [thread] weiterhin einen alten Wert lesen, der im Cache seines Prozessors gespeichert ist;
- Zeilen 55–57: Zwei Beans haben den Typ [Business]: [BusinessService] und [ApplicationModel] selbst. Einfach „ein [Business]“ anzufordern wäre mehrdeutig, und [Spring] würde den Start verweigern. [@Qualifier("businessService")] verweist per Name auf die gewünschte Bean; eine mit [@Service] deklarierte Bean heißt standardmäßig wie ihre Klasse, mit kleinem Anfangsbuchstaben;
- Zeilen 66–70: das erstmalige Laden der beiden Listen. [@PostConstruct] lässt die Methode von [Spring] aufrufen, sobald das Objekt erzeugt und seine Abhängigkeiten injiziert wurden, beim Start der Anwendung, bevor der Server Anfragen annimmt. Ein Lesefehler wird nicht abgefangen: Er beendet die Anwendung, was besser ist, als einen Server mit leeren Listen zu starten (eine nicht erreichbare Datenbank beendet die Anwendung übrigens noch früher, sobald [Hibernate] startet; siehe „Installation und Ausführung“);
- Zeilen 72–78: das Neuladen einer Liste: Die gesamte Liste wird aus der Datenbank gelesen und ersetzt die im Cache. [List.copyOf] erzeugt eine schreibgeschützte Kopie der Liste;
- Zeilen 82–90: Die Listen werden aus dem Speicher geliefert. Die zurückgegebene Liste ist die des Caches selbst: Da sie schreibgeschützt ist, würde ein Aufrufer, der ein Element hinzufügen will, eine Exception auslösen, und der Cache kann nicht versehentlich verändert werden;
- Zeilen 94–96: der einem Konto zugeordnete Arzt, aus dem Cache abgerufen: Ein angemeldeter Arzt sieht sofort seinen eigenen Terminkalender. Der Stream der Ärzte wird gefiltert ([filter]), und [findFirst] gibt den ersten ausgewählten Arzt in einem [Optional] zurück, das leer ist, wenn keiner passt. [getUserId()] gibt einen [Integer] (ein Objekt) zurück, und [userId] ist ein [int]: [Objects.equals] vergleicht die beiden Werte ohne Fehlerrisiko, selbst wenn [Integer] gleich [null] war.
| // ------------------------------------------------ einfache Delegierungen
@Override
public List<Slot> getAllSlots(int doctorId) {
return business.getAllSlots(doctorId);
}
@Override
public List<Appointment> getDoctorDayAppointments(int doctorId, LocalDate day) {
return business.getDoctorDayAppointments(doctorId, day);
}
@Override
public Optional<Client> getClientById(int id) {
return business.getClientById(id);
}
@Override
public Optional<Doctor> getDoctorById(int id) {
return business.getDoctorById(id);
}
@Override
public Optional<Appointment> getAppointmentById(int id) {
return business.getAppointmentById(id);
}
@Override
public Optional<Slot> getSlotById(int id) {
return business.getSlotById(id);
}
@Override
public Optional<DoctorDaySchedule> getDoctorDaySchedule(int doctorId, LocalDate day) {
return business.getDoctorDaySchedule(doctorId, day);
}
// kein Cache hier: Es kommt auf die aktuellsten Daten an (ein Patient,
// der gerade sein Konto bearbeitet oder gelöscht hat)
@Override
public Optional<Client> getClientByUserId(int userId) {
return business.getClientByUserId(userId);
}
@Override
public List<Appointment> getClientUpcomingAppointments(int clientId) {
return business.getClientUpcomingAppointments(clientId);
}
@Override
public Appointment addAppointment(LocalDate day, Slot slot, Client client) {
return business.addAppointment(day, slot, client);
}
@Override
public void deleteAppointment(Appointment appointment) {
business.deleteAppointment(appointment);
}
// ------------------------------------------------ Schreibzugriffe => Neuladen
@Override
public Doctor addDoctor(PersonData data) {
Doctor doctor = business.addDoctor(data);
reloadDoctors();
return doctor;
}
@Override
public Doctor editDoctor(int id, PersonData data) {
Doctor doctor = business.editDoctor(id, data);
reloadDoctors();
return doctor;
}
@Override
public void deleteDoctor(int id) {
business.deleteDoctor(id);
reloadDoctors();
}
@Override
public Client addClient(PersonData data) {
Client client = business.addClient(data);
reloadClients();
return client;
}
@Override
public Client editClient(int id, PersonData data) {
Client client = business.editClient(id, data);
reloadClients();
return client;
}
@Override
public void deleteClient(int id) {
business.deleteClient(id);
reloadClients();
}
}
|
Kommentieren wir diesen Code:
- Zeilen 3–58: Die übrigen Anfragen werden unverändert an die Geschäftsschicht weitergereicht;
- Zeilen 38–43: Der Kontoinhaber wird absichtlich nicht im Cache gesucht; ein Patient, der sein Konto gerade geändert oder gelöscht hat, muss so betrachtet werden, wie er in der Datenbank erscheint;
- Zeilen 60–101: Auf jede Schreiboperation, die Ärzte oder Clients betrifft, folgt ein Neuladen der betreffenden Liste. Da diese Bean der einzige Einstiegspunkt der Controller zur Geschäftsschicht ist, wird die Regel „Schreiben = Cache neu laden“ nur hier umgesetzt, und der Cache kann nicht veralten. Lehnt die Geschäftsschicht die Operation ab ([BusinessException]), beendet die Exception die Methode, bevor der Cache neu geladen wird, da dieser Schritt dann nicht mehr nötig ist.
11.14.9. web/Validation.java
| // =========================================================================
// web/Validation.java
// -------------------------------------------------------------------------
// Was nötig ist, um ein abgelehntes Formular ERNEUT ANZUZEIGEN: die Eingabefehler
// Feld für Feld und die rot umrandeten Felder.
// =========================================================================
package rdvmedecins.web;
import java.util.Collection;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
import org.springframework.validation.BindingResult;
import org.springframework.validation.FieldError;
import rdvmedecins.models.ViewModels.FormState;
import rdvmedecins.models.ViewModels.Message;
public final class Validation {
private Validation() {
}
// -----------------------------------------------------------------------
// BindingResult (von Spring beim Binding und der Validierung
// des Formulars gefüllt) -> das Dictionary Feld -> Schlüssel der Nachricht, wobei
// nur die erste Nachricht jedes Felds behalten wird: { "lastName": "ERRORS.LASTNAME_REQUIRED", ... }
//
// Ein KONVERTIERUNGSFEHLER (ein Text, wo eine Zahl erwartet wird:
// version="abc") hat den Code "typeMismatch" und eine technische Nachricht auf
// Englisch: Wir ersetzen sie durch den Schlüssel ERRORS.INVALID_FORM.
// -----------------------------------------------------------------------
public static Map<String, String> errorsOf(BindingResult result) {
Map<String, String> errors = new HashMap<>();
for (FieldError error : result.getFieldErrors()) {
String key = error.isBindingFailure() || error.getDefaultMessage() == null
? "ERRORS.INVALID_FORM"
: error.getDefaultMessage();
errors.putIfAbsent(error.getField(), key);
}
return errors;
}
// -----------------------------------------------------------------------
// die von jedem fachlichen Eingabefehler betroffenen Formularfelder
// (ein Duplikat): Sie werden rot umrandet, die Nachricht steht unten auf der Seite
// -----------------------------------------------------------------------
public static final Map<String, List<String>> BUSINESS_ERROR_FIELDS = Map.of(
"ERRORS.LOGIN_TAKEN", List.of("login"),
"ERRORS.DOCTOR_ALREADY_EXISTS", List.of("firstName", "lastName"),
"ERRORS.PATIENT_ALREADY_EXISTS", List.of("firstName", "lastName"));
// der Zustand eines (erneut) anzuzeigenden Formulars: eine Nachricht unter jedem Feld,
// das von der Validierung abgelehnt wurde (errors), und die rot umrandeten Felder,
// diese plus gegebenenfalls weitere (otherFields)
public static FormState state(Map<String, String> errors, Collection<String> otherFields) {
Set<String> fields = new HashSet<>(errors.keySet());
if (otherFields != null) {
fields.addAll(otherFields);
}
return new FormState(errors, fields);
}
// DIE Fehlermeldung der Seite, unten auf der Seite angezeigt: [error], falls
// vorhanden, sonst "The form contains errors.", falls es
// Feldfehler gibt, sonst nichts
public static Message pageMessage(Map<String, String> errors, Message error) {
if (error != null) {
return error;
}
return errors.isEmpty() ? null : Message.of("ERRORS.INVALID_FORM");
}
}
|
Wird ein Formular abgelehnt, wird die Seite mit den eingegebenen Daten erneut angezeigt, mit einer Nachricht unter jedem ungültigen Feld, den rot hervorgehobenen ungültigen Feldern und einer Nachricht am Ende der Seite. Diese Klasse bereitet diese Informationen für die Controller auf:
- Zeilen 22–25: eine Hilfsklasse (Utility-Klasse): [final] (es kann keine Unterklasse gebildet werden), ein privater Konstruktor (es können keine Objekte dieser Klasse erzeugt werden) und nur statische Methoden;
- Zeilen 36–45: wandelt das [BindingResult] (siehe Beispiele 09 und 19), das von [Spring] beim Formular-Binding und bei der Validierung befüllt wird, in ein einfaches Verzeichnis „Feld → Nachrichtenschlüssel“ um. [putIfAbsent] fügt einen Eintrag nur hinzu, wenn das Feld noch keinen hat: Nur die erste Nachricht je Feld bleibt erhalten, und unter dem Feld wird nur eine Nachricht angezeigt. Die Nachrichten der Validierungsbedingungen sind Übersetzungsschlüssel (siehe [models/Forms.java]); ein Konvertierungsfehler ([isBindingFailure()]: Text, wo eine Zahl erwartet wird) hat dagegen eine technische Nachricht auf Englisch, die durch den Schlüssel [ERRORS.INVALID_FORM] ersetzt wird;
- Zeilen 51–54: Bestimmte Fehler der Geschäftsschicht betreffen bestimmte Felder: ein bereits vergebener Benutzername oder ein Arzt bzw. Client mit demselben Namen. Diese Felder werden rot hervorgehoben, die Nachricht erscheint am Ende der Seite. [Map.of] erzeugt das Verzeichnis als einzelnen Ausdruck;
- Zeilen 59–65: der Zustand des anzuzeigenden Formulars: die Nachrichten unter den Feldern und die rot hervorzuhebenden Felder – also jene mit einer Nachricht – plus die Felder [otherFields] (jene, die einen fachlichen Fehler anzeigen). Ein [HashSet] ist eine Menge: Jedes Element kommt nur einmal vor. Das Ergebnis ist ein [FormState]-Record (siehe [models/ViewModels.java]);
- Zeilen 70–75: die Nachricht am Ende der Seite: die spezifische Fehlermeldung, falls vorhanden; andernfalls, wenn es Feldfehler gibt, die Nachricht „Das Formular enthält Fehler“; andernfalls nichts ([null]).
11.14.10. web/Utils.java
| // =========================================================================
// web/Utils.java
// -------------------------------------------------------------------------
// Kleine Hilfsfunktionen der Web-Schicht:
// - labels: "Mme Alice DURAND";
// - dates: "yyyy-MM-dd", Uhrzeiten "8:05", Tage "Wednesday 23 September 2026";
// - input: Lesen einer vom Browser gesendeten positiven ganzen Zahl;
// - patient: der Patient (Entität Client) des angemeldeten Benutzers.
//
// Eine "Utility"-Klasse: nur statische Methoden, wir erzeugen nie
// ein Objekt dieser Klasse (privater Konstruktor).
// =========================================================================
package rdvmedecins.web;
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
import java.time.format.ResolverStyle;
import java.util.Locale;
import java.util.Optional;
import org.springframework.security.oauth2.jwt.Jwt;
import rdvmedecins.auth.InvalidSessionException;
import rdvmedecins.auth.ConnectedUser;
import rdvmedecins.entities.Client;
import rdvmedecins.entities.Slot;
import rdvmedecins.entities.Person;
public final class Utils {
private Utils() {
}
// ----------------------------------------------------------------- Bezeichnungen
// "Mme Alice DURAND"
public static String label(Person p) {
return p.getTitle() + " " + p.getFirstName() + " " + p.getLastName();
}
// ----------------------------------------------------------------- Datumsangaben
// das Format der Datumsangaben in den URLs und im Feld <input type="date">;
// STRIKT: "2026-02-30" wird abgelehnt (und nicht auf den 2. März zurückgeführt)
private static final DateTimeFormatter ISO = DateTimeFormatter.ofPattern("uuuu-MM-dd")
.withResolverStyle(ResolverStyle.STRICT);
// das Datum, wenn [text] ein existierendes Datum im Format yyyy-MM-dd ist
public static Optional<LocalDate> validDate(String text) {
try {
return Optional.of(LocalDate.parse(text, ISO));
} catch (DateTimeParseException | NullPointerException e) {
return Optional.empty();
}
}
public static String iso(LocalDate day) {
return day.format(ISO);
}
// "8:05" statt "8:5"
public static String formatTime(int h, int m) {
return "%d:%02d".formatted(h, m);
}
public static String time(Slot s) {
return formatTime(s.getStartHour(), s.getStartMinute()) + " - " + formatTime(s.getEndHour(), s.getEndMinute());
}
// "mercredi 23 septembre 2026" / "Wednesday 23 September 2026", je nach
// Sprache der Anfrage
public static String formatDay(LocalDate day, Locale language) {
return day.format(DateTimeFormatter.ofPattern("EEEE d MMMM yyyy", language));
}
// ----------------------------------------------------------------- Eingabe
// "3" -> 3 ; "", "abc", "-2", "+2", null -> null
public static Integer positiveInteger(String value) {
if (value == null || !value.matches("\\d{1,9}")) {
return null;
}
int n = Integer.parseInt(value);
return n > 0 ? n : null;
}
// ----------------------------------------------------------------- Benutzer
// der durch das Token der Anfrage beschriebene Benutzer (Parameter
// @AuthenticationPrincipal Jwt token einer Aktion). Ein gültiges, aber
// unvollständiges Token (fehlende Claims) wird wie eine abgelaufene Sitzung behandelt.
public static ConnectedUser user(Jwt token) {
ConnectedUser user = ConnectedUser.of(token);
if (user == null) {
throw new InvalidSessionException();
}
return user;
}
// ----------------------------------------------------------------- Patient
// -----------------------------------------------------------------------
// Der Patient (Entität Client), der dem angemeldeten Benutzer entspricht.
//
// Das JWT-Token enthält nur die ID des KONTOS (users.id). Für eine Rolle
// USER finden wir den zugehörigen Client anhand der Spalte clients.user.
//
// Gibt es keinen, wurde das Konto seit der Anmeldung gelöscht,
// während sein Token noch gültig ist: Wir behandeln das wie eine
// abgelaufene Sitzung (siehe InvalidSessionException).
// -----------------------------------------------------------------------
public static Client connectedPatient(ApplicationModel application, ConnectedUser user) {
if (user == null) {
throw new InvalidSessionException();
}
return application.getClientByUserId(user.userId()).orElseThrow(InvalidSessionException::new);
}
}
|
Kommentieren wir diesen Code:
- Zeilen 38–40: der Name eines Arztes oder eines Clients: „Mme Alice DURAND“. Der Parameter hat den Typ [Person], die Elternklasse der Entitäten [Doctor] und [Client] (siehe „Entitäten“): Dieselbe Funktion dient für beide;
- Zeilen 46–47: das Datumsformat in den URL-Entitäten und im Feld [<input type="date">]. Der Modus [STRICT] lehnt ein nicht existierendes Datum ab: [2026-02-30] ist ein Fehler, statt in den 2. März umgewandelt zu werden (siehe Beispiel 12). In diesem Modus wird das Jahr als [uuuu] geschrieben: [yyyy] würde sich auf das Jahr „der Ära“ beziehen, sodass auch die Ära angegeben werden müsste (vor oder nach Christus);
- Zeilen 50–56: das Datum, wenn der Text ein gültiges Datum im Format [yyyy-MM-dd] ist; andernfalls ist es leer. Ein Text im Format [null] löst eine [NullPointerException] aus, die als falsch geschriebenes Datum abgefangen wird: Das Format [catch (A | B e)] fängt zwei Arten von Exceptions ab;
- Zeilen 58–60: die Umkehroperation: ein Datum, umgewandelt in den Text [yyyy-MM-dd];
- Zeilen 63–69: eine Uhrzeit im Format [8:05] (das Format [%02d] schreibt eine ganze Zahl mit mindestens zwei Stellen, links mit Nullen aufgefüllt) und die Zeit eines Zeitfensters: [8:00 - 8:20];
- Zeilen 73–75: ein ausgeschriebener Tag in der Sprache der Anfrage, die der Controller als Parameter erhält ([Locale]): „mercredi 23 septembre 2026“ oder „Wednesday 23 September 2026“. [EEEE] ist der ausgeschriebene Wochentag, und [MMMM] ist der Monat;
- Zeilen 80–86: ein vom Browser gesendeter Bezeichner (in der URL oder einem Formularfeld): eine streng positive ganze Zahl oder [null]. Der reguläre Ausdruck [\d{1,9}] akzeptiert nur Ziffern, bis zu neun: keine Vorzeichen, keine Leerzeichen und keine für einen [int] zu große Zahlen. Der Controller muss dann einfach auf [null] prüfen;
- Zeilen 93–99: der anhand des Anfrage-Tokens identifizierte Benutzer, den eine Action über einen Parameter mit der Annotation [@AuthenticationPrincipal Jwt token] erhält. Ein korrekt signiertes, aber unvollständiges Token wird als abgelaufene Sitzung behandelt;
- Zeilen 113–118: der dem angemeldeten Benutzer zugeordnete Patient (Entität [Client]). Das JWT-Token enthält nur die Konto-ID; wir suchen den mit diesem Konto verknüpften Client. Existiert er nicht mehr, wurde das Konto seit der Anmeldung des Benutzers gelöscht: [InvalidSessionException] wird von [HtmlExceptionHandler] behandelt, wie oben gesehen, der zur Anmeldeseite weiterleitet. [orElseThrow] entnimmt den Client dem [Optional] oder löst die von seinem Argument erzeugte Exception aus, wenn [Optional] leer ist. [InvalidSessionException::new] ist eine Konstruktorreferenz: die Kurzform des Lambda-Ausdrucks [() -> new InvalidSessionException()].
Zwei Arten von Klassen übertragen Daten zwischen Browser, Controllern und Views: Formulare, die vom Model-Binding anhand dessen, was der Browser sendet, befüllt und anschließend validiert werden, und View-Modelle, die von den Controllern für die Views vorbereitet werden. Erstere sind JavaBeans, Letztere sind Records; wir werden sehen, warum. Sie liegen im Ordner [models], zusammen mit den Eingaberegeln, die sie gemeinsam nutzen.
| // =========================================================================
// models/InputRules.java
// -------------------------------------------------------------------------
// Die gemeinsamen Eingaberegeln der Formulare für "Personen".
// =========================================================================
package rdvmedecins.models;
import java.util.List;
public final class InputRules {
private InputRules() {
}
public static final List<String> TITLES = List.of("Mr", "Mme", "Melle");
// login: Kleinbuchstaben, Ziffern, Punkt, Bindestrich, Unterstrich - höchstens 30 Zeichen
public static final String LOGIN_FORMAT = "^[a-z0-9._-]{1,30}$";
// Mindestlänge eines von einem Patienten GEWÄHLTEN Passworts
public static final int PASSWORD_MIN = 6;
// " dupont " -> "dupont" ; " " -> null
public static String clean(String value) {
return value == null || value.isBlank() ? null : value.trim();
}
// ein leeres Feld -> null; bei einem Passwort entfernen wir die
// Leerzeichen NICHT (sie können Teil davon sein)
public static String emptyToNull(String value) {
return value == null || value.isEmpty() ? null : value;
}
}
|
- Zeile 15: die möglichen Anreden. Sie dienen zur Erzeugung der Dropdown-Liste für die Formulare (siehe [ViewModels.java], weiter unten);
- Zeile 18: das Format eines Benutzernamens, beschrieben durch einen regulären Ausdruck: 1 bis 30 Zeichen, bestehend aus Kleinbuchstaben, Ziffern, Punkt, Unterstrich und Bindestrich. [^] und [$] bezeichnen den Anfang und das Ende des Textes;
- Zeile 21: die Mindestlänge eines von einem Patienten gewählten Passworts;
- Zeilen 18 und 21: Diese beiden Felder sind Konstanten: [static final], initialisiert mit einem im Programm fest vorgegebenen Wert. Der Compiler kennt ihre Werte, wodurch sie als Argumente einer Annotation verwendet werden können, zum Beispiel [@Size(min = InputRules.PASSWORD_MIN)]. Für die Liste [TITLES] (Zeile 15), die zur Laufzeit erzeugt wird, gilt das nicht;
- Zeilen 24–26: Bereinigung einer Eingabe: Leerzeichen am Anfang und am Ende werden entfernt, und ein leeres oder nur aus Leerzeichen bestehendes Feld ([isBlank()]) wird zu [null], also zu „nicht vorhanden“;
- Zeilen 30–32: Bei einem Passwort wird ein leeres Feld zu [null], die Leerzeichen bleiben aber erhalten: Sie sind Teil des Passworts.
Die Datei wird in zwei Auszügen dargestellt.
| // =========================================================================
// models/Forms.java
// -------------------------------------------------------------------------
// Die Felder der Formulare für "Personen" und ihre Constraints. Drei
// Formulare teilen sich dieselben Identitätsfelder (Anrede, Vorname, Nachname):
//
// PersonFields Anrede, Vorname, Nachname
// ├─ PersonForm + OPTIONALER Login / Passwort, Version
// │ (der ADMIN fügt einen Arzt / Client hinzu oder bearbeitet ihn)
// ├─ RegistrationForm + PFLICHT-Login / -Passwort / -Bestätigung
// │ (ein Patient erstellt sein Konto)
// └─ MyAccountForm + Login, optionales neues Passwort,
// PFLICHT-Feld aktuelles Passwort, Version
// (ein Patient bearbeitet sein Konto)
//
// MODEL BINDING: Wenn eine Controller-Aktion einen Parameter einer
// dieser Klassen erhält, erzeugt Spring MVC das Objekt und füllt jedes Feld über
// seinen Setter mit dem Parameter gleichen Namens (siehe Beispiel 18).
//
// VALIDIERUNG: Mit @Valid prüft Spring anschließend die Constraints
// (@NotBlank, @Size...) und legt die Fehler im BindingResult ab, das auf
// den Parameter folgt (siehe Beispiele 09 und 19).
//
// Die Fehlermeldungen sind Übersetzungs-SCHLÜSSEL (siehe i18n/*.json).
//
// EINGABEBEREINIGUNG: Die Setter entfernen überflüssige Leerzeichen
// (eine leere Eingabe wird zu null) und setzen den Login in Kleinbuchstaben. Ein
// Passwort hingegen wird nicht "bereinigt" (Leerzeichen können Teil davon sein).
//
// Die Klassen sind in der Klasse Forms "verschachtelt" (static): eine einzige
// Datei für vier kleine Klassen. Sie werden als
// Forms.PersonForm... bezeichnet.
// =========================================================================
package rdvmedecins.models;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Pattern;
import jakarta.validation.constraints.Size;
public final class Forms {
private Forms() {
}
// ------------------------------------------------------------------ gemeinsame Basis
public abstract static class PersonFields {
@NotNull(message = "ERRORS.INVALID_TITLE")
@Pattern(regexp = "Mr|Mme|Melle", message = "ERRORS.INVALID_TITLE")
private String title;
// maximale Längen = die der SQL-Spalten (VARCHAR(20))
@NotBlank(message = "ERRORS.FIRSTNAME_REQUIRED")
@Size(max = 20, message = "ERRORS.FIRSTNAME_TOO_LONG")
private String firstName;
@NotBlank(message = "ERRORS.LASTNAME_REQUIRED")
@Size(max = 20, message = "ERRORS.LASTNAME_TOO_LONG")
private String lastName;
public String getTitle() { return title; }
public void setTitle(String title) { this.title = title; }
public String getFirstName() { return firstName; }
public void setFirstName(String firstName) { this.firstName = InputRules.clean(firstName); }
public String getLastName() { return lastName; }
public void setLastName(String lastName) { this.lastName = InputRules.clean(lastName); }
}
|
Der Kopfkommentar (Zeilen 4–32) beschreibt die drei „Personen“-Formulare und ihre gemeinsame Basis. Die Formulare folgen dem Vorgehen aus den Beispielen 18 und 19: Eine Action erhält einen mit [@Valid] annotierten Parameter, gefolgt von einem Parameter [BindingResult]. [Spring MVC] erzeugt das Objekt, befüllt es mit den empfangenen Feldern (Model-Binding), prüft dann die durch die Annotationen festgelegten Bedingungen (Validierung) und speichert eventuelle Fehler in [BindingResult]. Diese Annotationen ([@NotNull], [@NotBlank], [@Size], [@Pattern]) stammen aus dem Standard [Bean Validation] (Paket [jakarta.validation]), der durch den Starter [spring-boot-starter-validation] samt seiner Implementierung [Hibernate Validator] eingebunden wird. Kommentieren wir diesen Code:
- Zeilen 41–44: eine Klasse, deren einziger Zweck darin besteht, vier kleine verschachtelte Klassen in einer einzigen Datei zusammenzufassen. Da sie als [static] deklariert sind, sind sie von jeder Instanz von [Forms] unabhängig: Man bezeichnet sie als [Forms.PersonForm] oder, nach einem [import], einfach als [PersonForm];
- Zeile 47: die Identitätsfelder, die allen drei Formularen gemeinsam sind. Die Klasse ist abstrakt ([abstract]): Man kann von ihr kein Objekt erzeugen, sondern nur davon ableiten;
- Zeilen 49–51: die Anrede, die erforderlich ist ([@NotNull]) und aus der Liste ausgewählt wird ([@Pattern]). Die Werte werden im regulären Ausdruck [Mr|Mme|Melle] wiederholt ([|] bedeutet „oder“): Das Argument einer Annotation muss eine Konstante sein, was die Liste [InputRules.TITLES] nicht ist. [@Pattern] verlangt, dass der gesamte Text dem Ausdruck entspricht;
- Zeilen 53–60: der Vorname und der Nachname, die erforderlich sind und höchstens 20 Zeichen lang sein dürfen: die Spaltenbreiten in SQL (siehe „Die Datenbank“). [@NotBlank] weist [null], leeren Text und Text, der nur aus Leerzeichen besteht, zurück. Jede Bedingung hat ihre eigene Nachricht; die Nachrichten sind Übersetzungsschlüssel (siehe Beispiel 22), die von der View in die Sprache des Benutzers übersetzt werden;
- Zeilen 62–69: die Getter, jeweils in einer einzigen Zeile geschrieben. Die Setter bereinigen die Eingabe dabei gleich mit: Da das Model-Binding die Felder vor der Validierung über die Setter aktualisiert, wird der bereinigte Wert validiert. Ein aus Leerzeichen bestehender Vorname wird zu [null], und es ist [@NotBlank], das ihn zurückweist.
Warum JavaBeans und keine Records? Eine JavaBean ist eine gewöhnliche Klasse mit einem parameterlosen Konstruktor und, für jede Eigenschaft, einem Paar aus [getXxx()] und [setXxx()]. [Spring MVC] erzeugt das leere Objekt und ruft dann für jedes empfangene Feld einen Setter auf: Jedes Feld wird einzeln verarbeitet. [Spring MVC] kann auch einen Record befüllen, ruft dazu aber seinen Konstruktor mit allen Feldern auf einmal auf: Kann auch nur ein einziges Feld nicht umgewandelt werden (etwa Text im numerischen Feld [version]), wird das Objekt nicht konstruiert, und es werden keine Bedingungen geprüft. Bei einer JavaBean verhindert ein Konvertierungsfehler in einem Feld die Validierung der anderen nicht: Der Benutzer sieht alle Fehler auf einmal. Die JavaBean erlaubt außerdem, die Eingaben in den Settern zu bereinigen.
| // ------------------------------------------------------------------ ADMIN
public static class PersonForm extends PersonFields {
// optional (siehe business/PersonData.java)
@Pattern(regexp = InputRules.LOGIN_FORMAT, message = "ERRORS.INVALID_LOGIN")
private String login;
// optional; höchstens 72 Zeichen (darüber hinaus ignoriert bcrypt den Rest)
@Size(max = 72, message = "ERRORS.PASSWORD_TOO_LONG")
private String password;
// verstecktes Feld des Bearbeitungsformulars (optimistisches Sperren).
// Integer: Ein fehlendes oder leeres Feld ergibt null; ein Text, der keine
// Zahl ist, ergibt einen Binding-Fehler (typeMismatch)
private Integer version;
public String getLogin() { return login; }
public void setLogin(String login) { this.login = lowerCase(InputRules.clean(login)); }
public String getPassword() { return password; }
public void setPassword(String password) { this.password = InputRules.emptyToNull(password); }
public Integer getVersion() { return version; }
public void setVersion(Integer version) { this.version = version; }
}
// ------------------------------------------------------------------ Registrierung eines Patienten
public static class RegistrationForm extends PersonFields {
@NotNull(message = "ERRORS.LOGIN_REQUIRED")
@Pattern(regexp = InputRules.LOGIN_FORMAT, message = "ERRORS.INVALID_LOGIN")
private String login;
// zwei @Size-Constraints, jeweils mit ihrer Nachricht
@NotNull(message = "ERRORS.PASSWORD_REQUIRED")
@Size(min = InputRules.PASSWORD_MIN, message = "ERRORS.PASSWORD_TOO_SHORT")
@Size(max = 72, message = "ERRORS.PASSWORD_TOO_LONG")
private String password;
@NotNull(message = "ERRORS.CONFIRMATION_REQUIRED")
private String confirmation;
public String getLogin() { return login; }
public void setLogin(String login) { this.login = lowerCase(InputRules.clean(login)); }
public String getPassword() { return password; }
public void setPassword(String password) { this.password = InputRules.emptyToNull(password); }
public String getConfirmation() { return confirmation; }
public void setConfirmation(String confirmation) { this.confirmation = InputRules.emptyToNull(confirmation); }
}
// ------------------------------------------------------------------ "Manage my account"
public static class MyAccountForm extends PersonFields {
@NotNull(message = "ERRORS.LOGIN_REQUIRED")
@Pattern(regexp = InputRules.LOGIN_FORMAT, message = "ERRORS.INVALID_LOGIN")
private String login;
// optional: leer = Passwort unverändert
@Size(min = InputRules.PASSWORD_MIN, message = "ERRORS.PASSWORD_TOO_SHORT")
@Size(max = 72, message = "ERRORS.PASSWORD_TOO_LONG")
private String password;
private String confirmation;
// das AKTUELLE Passwort, erforderlich für jede Änderung des Kontos
@NotNull(message = "ERRORS.CURRENT_PASSWORD_REQUIRED")
private String currentPassword;
private Integer version;
public String getLogin() { return login; }
public void setLogin(String login) { this.login = lowerCase(InputRules.clean(login)); }
public String getPassword() { return password; }
public void setPassword(String password) { this.password = InputRules.emptyToNull(password); }
public String getConfirmation() { return confirmation; }
public void setConfirmation(String confirmation) { this.confirmation = InputRules.emptyToNull(confirmation); }
public String getCurrentPassword() { return currentPassword; }
public void setCurrentPassword(String password) { this.currentPassword = InputRules.emptyToNull(password); }
public Integer getVersion() { return version; }
public void setVersion(Integer version) { this.version = version; }
}
private static String lowerCase(String text) {
return text == null ? null : text.toLowerCase(java.util.Locale.ROOT);
}
}
|
Kommentieren wir diesen Code:
- Zeile 2: das Formular aus ADMIN zum Hinzufügen oder Ändern eines Arztes oder eines Clients. Die Klasse erbt die Identitätsfelder, ihre Bedingungen und ihre Zugriffsmethoden;
- Zeilen 4–6: der Login, der hier optional ist (bleibt er leer, wird er beim Anlegen standardmäßig der Name in Kleinbuchstaben und bleibt beim Ändern unverändert; siehe „Die Geschäftsschicht“), aber im richtigen Format vorliegen muss, wenn er angegeben wird. Wie alle Bedingungen von [Bean Validation] außer [@NotNull] und [@NotBlank] akzeptiert [@Pattern] den Wert [null]: Das macht das Feld optional. Der Setter (Zeile 18) bereinigt den Login und wandelt ihn in Kleinbuchstaben um (Methode [lowerCase], Zeilen 89–91);
- Zeilen 8–10: das Passwort, das ebenfalls optional ist, mit höchstens 72 Zeichen: Der Algorithmus [bcrypt] ignoriert die folgenden Zeichen. Es wird nicht bereinigt, sondern lediglich auf [null] gesetzt, wenn es leer ist (Zeile 21);
- Zeilen 12–15: die Version des Datensatzes in einem versteckten Feld des Änderungsformulars (optimistisches Sperren; siehe Beispiel 28). Der Typ [Integer] – nicht [int] – akzeptiert den Wert [null]: Ein fehlendes oder leeres Feld ergibt [null]. Text, der keine Zahl ist, erzeugt einen Konvertierungsfehler, den [web/Validation.java] in die Nachricht „Das Formular enthält Fehler“ umwandelt;
- Zeile 28: Ein Patient legt ein Konto an. Der Login ist erforderlich (Zeile 30): [@NotNull] genügt, da der Setter eine leere Eingabe in [null] umwandelt;
- Zeilen 34–38: das Passwort, erforderlich, 6 bis 72 Zeichen lang. Zwei Annotationen [@Size] auf demselben Feld: Eine Annotation, die als wiederholbar deklariert ist, kann mehrfach vorkommen, hier, damit jede Grenze ihre eigene Nachricht hat;
- Zeilen 40–41: die Passwortbestätigung, erforderlich. Die Prüfung, ob das Passwort mit seiner Bestätigung übereinstimmt, betrifft zwei Felder: Sie wird vom Controller vorgenommen ([RegistrationController], siehe „Die Web-Schicht: Controller“);
- Zeile 54: Ein Patient ändert sein Konto. Der Login ist erforderlich; das neue Passwort ist optional (Zeilen 60–63): Bleibt es leer, bleibt es unverändert, und seine Bestätigung (Zeile 65) ist hier daher nicht erforderlich. Das aktuelle Passwort hingegen ist für jede Änderung erforderlich (Zeilen 67–69), ebenso die Version des Datensatzes in einem versteckten Feld (Zeile 71);
- Zeilen 89–91: Umwandlung des Benutzernamens in Kleinbuchstaben. [Locale.ROOT] macht die Umwandlung unabhängig von der Sprache des Servers (im Türkischen zum Beispiel ist der Kleinbuchstabe von [I] nicht [i]). Der vollständige Name [java.util.Locale] erspart eine Zeile wie [import].
11.15.3. models/ViewModels.java
Die Datei wird in zwei Auszügen dargestellt.
| // =========================================================================
// models/ViewModels.java
// -------------------------------------------------------------------------
// Die "View-Modelle": was jeder Controller an
// seine View übergibt, unter dem Namen [model]. Es sind Records: unveränderliche Objekte,
// die der Controller in einem Zug aufbaut und die die View nur
// liest (${model.schedule.rows}...).
//
// Regel, der alle Seiten folgen: keine Logik in den Views. Die
// Controller bereiten bereits FORMATIERTE Daten vor ("Mme Marie
// PELISSIER", "8:00 - 8:20", selected = true...), die außerdem nach
// der Rolle des Benutzers gefiltert sind; die Views platzieren sie lediglich im HTML.
// =========================================================================
package rdvmedecins.models;
import java.util.List;
import java.util.Map;
import java.util.Set;
import rdvmedecins.auth.Captcha;
public final class ViewModels {
private ViewModels() {
}
// -------------------------------------------------------------------------
// was ALLEN Seiten gemeinsam ist, vom Layout gelesen
// (templates/layout.html): der Schlüssel des Seitentitels und DIE Fehlermeldung
// der Seite, unten auf der Seite angezeigt (null: kein Fehler)
// -------------------------------------------------------------------------
public interface ViewModel {
String pageTitle();
Message error();
}
// eine zu übersetzende Nachricht: ihr Schlüssel und ihre Parameter
public record Message(String key, Map<String, String> params) {
public static Message of(String key) {
return new Message(key, Map.of());
}
}
// eine Option einer Dropdown-Liste (Arzt, Patient)
public record OptionView(int id, String label, boolean selected) {
}
// ------------------------------------------------------------------ Anmeldung
public record LoginModel(String pageTitle, Message error, String login, Captcha captcha) implements ViewModel {
}
// ------------------------------------------------------------------ Terminkalender
public record ScheduleRowView(
int slotId,
String time, // "8:00 - 8:20"
boolean free,
String patient, // angezeigter Name für einen gebuchten Zeitslot; null = "Booked"
boolean mine, // der Termin des angemeldeten Patienten
boolean bookable, // Schaltfläche "Book" anzeigen?
String bookUrl,
Integer appointmentId) { // nur gefüllt, wenn die Schaltfläche "Cancel" angezeigt wird
}
public record ScheduleView(String doctor, String day, List<ScheduleRowView> rows) {
}
public record BookingView(
int slotId,
String time,
List<OptionView> clients, // ADMIN / DOCTOR: die zur Auswahl stehenden Patienten
String patient) { // USER: Der Patient ist der Benutzer selbst
}
public record ScheduleModel(
String pageTitle,
Message error,
List<OptionView> doctors,
Integer doctorId,
String day, // "yyyy-MM-dd"
ScheduleView schedule,
BookingView booking,
String backUrl, // der angezeigte Terminkalender, ohne Buchungsdialog
// Patient, der bereits einen bevorstehenden Termin hat: die Nachricht, die erklärt,
// warum es keine Schaltfläche "Book" gibt
String info) implements ViewModel {
}
|
Die View-Modelle folgen einer Regel, die bereits in den Beispielen angewendet wurde: keine Logik in den Views. Die Controller bereiten Daten vor, die bereits formatiert („Mme Marie PELISSIER“, „8:00 – 8:20“) und entsprechend der Rolle des Benutzers bereits gefiltert sind; die Views setzen sie lediglich in das HTML ein. Dies sind Records: Sie werden einmal vom Controller konstruiert und anschließend nur von der View gelesen, die zum Beispiel [${model.schedule.rows}] schreibt; [Thymeleaf] ruft dann die Zugriffsmethoden [schedule()], gefolgt von [rows()] auf. Jeder Controller legt das Template seiner View unter dem Namen [model] ab. Kommentieren wir diesen Code:
- Zeilen 32–36: das, was allen Seiten gemeinsam ist und vom Template [templates/layout.html] gelesen wird (siehe „Views“): der Übersetzungsschlüssel des Seitentitels und die Fehlermeldung der Seite, die unten angezeigt wird, oder [null]. Dies ist eine Schnittstelle, keine Elternklasse: Ein Record kann nicht von einer Klasse erben, wohl aber Schnittstellen implementieren. Ein Record mit den Komponenten [pageTitle] und [error] besitzt automatisch die Zugriffsmethoden [pageTitle()] und [error()]: Er implementiert die Schnittstelle ohne eine einzige zusätzliche Codezeile;
- Zeilen 39–44: eine zu übersetzende Nachricht: ihr Schlüssel und ihre Parameter. Die statische Methode [of] erzeugt eine Nachricht ohne Parameter;
- Zeilen 47–48: eine Option einer Dropdown-Liste (ein Arzt, ein Patient), bereits als ausgewählt oder nicht ausgewählt markiert (siehe Beispiel 18);
- Zeilen 51–52: die Anmeldeseite: der bereits eingegebene Benutzername und das anzuzeigende CAPTCHA. Der Rumpf des Records ist leer: Alles steckt in seinen Komponenten;
- Zeilen 55–64: ein Eintrag im Terminkalender, also ein Zeitfenster. Der Controller hat bereits alles festgelegt: ob der Name des Patienten angezeigt wird oder nicht (ein Patient darf die Namen anderer nicht sehen: [patient] ist dann gleich [null], und die View zeigt „Gebucht“ an), ob die Schaltfläche „Buchen“ angezeigt wird oder nicht und ob die Schaltfläche „Stornieren“ angezeigt wird oder nicht ([appointmentId] ist belegt). [appointmentId] ist ein [Integer], der gleich [null] sein kann;
- Zeilen 66–67: der Terminkalender eines Arztes für einen bestimmten Tag: der Arzt, der ausgeschriebene Tag und die Zeilen;
- Zeilen 69–74: das Buchungsfenster: die Liste der Patienten für ADMIN und die Ärzte oder nur der Name des angemeldeten Patienten bei einem einzelnen Patienten;
- Zeilen 76–88: die Seite des Terminkalenders: die Liste der Ärzte, der ausgewählte Arzt und Tag, der Terminkalender ([null] solange kein Arzt ausgewählt ist), das Buchungsfenster (falls zutreffend), die URL des Terminkalenders ohne dieses Fenster (Zeile 84) und die Nachricht, die einem Patienten erklärt, warum er keine Buchung vornehmen kann.
| // ------------------------------------------------------------------ Formulare für "Personen"
// die in den Formularfeldern angezeigten Werte (nie das Passwort)
public record PersonValues(String title, String firstName, String lastName, String login, Integer version) {
public static PersonValues empty() {
return new PersonValues("Mr", "", "", "", null);
}
}
// der Zustand eines abgelehnten Formulars: die UNTER jedem Feld angezeigte Nachricht
// (Feld -> Schlüssel der Nachricht) und die rot umrandeten Felder (Bootstrap-Klasse
// is-invalid): die mit einer Nachricht plus gegebenenfalls weitere
// (doppelter Vor- und Nachname, vergebener Login...)
public record FormState(Map<String, String> errors, Set<String> invalidFields) {
public static FormState empty() {
return new FormState(Map.of(), Set.of());
}
public String errorOf(String field) {
return errors.get(field);
}
public String invalidClass(String field) {
return invalidFields.contains(field) ? "is-invalid" : "";
}
}
// eine Option der Anredeliste
public record TitleOption(String value, boolean selected) {
}
// was das gemeinsame Fragment person-fields.html verwendet (Anrede, Vorname, Nachname)
public interface FormView extends ViewModel {
PersonValues values();
FormState state();
// eine "default"-Methode: im Interface geschrieben, von den Records geerbt
default List<TitleOption> titles() {
return InputRules.TITLES.stream().map(t -> new TitleOption(t, t.equals(values().title()))).toList();
}
}
public record PersonFormModel(
String pageTitle,
Message error,
PersonValues values,
FormState state,
boolean creating, // true: hinzufügen; false: bearbeiten
String action, // URL des POST
String listUrl) implements FormView {
}
public record RegistrationModel(String pageTitle, Message error, PersonValues values, FormState state)
implements FormView {
public int passwordMin() {
return InputRules.PASSWORD_MIN;
}
}
public record MyAccountModel(String pageTitle, Message error, PersonValues values, FormState state)
implements FormView {
public int passwordMin() {
return InputRules.PASSWORD_MIN;
}
}
// ------------------------------------------------------------------ Listen der Ärzte / Clients
// die für jeden Personentyp spezifischen Übersetzungsschlüssel
public record PersonKeys(
String title, // "Doctors"
String add, // "Add a doctor"
String edit, // "Edit a doctor"
String empty, // "No doctors."
String confirmDelete, // "Delete this doctor and their account?"
String added, // "Doctor {name} has been added (login: {login})."
String edited,
String deleted) {
}
public record PersonView(String title, String firstName, String lastName, String login, String editUrl,
String deleteUrl) {
}
public record PersonListModel(String pageTitle, Message error, PersonKeys keys, String addUrl,
List<PersonView> persons) implements ViewModel {
}
// ------------------------------------------------------------------ Patientenbereich
public record AppointmentView(int id, String day, String time, String doctor, String scheduleUrl) {
}
public record AreaModel(String pageTitle, Message error, String patient, List<AppointmentView> appointments)
implements ViewModel {
}
// ------------------------------------------------------------------ Fehlerseite
public record ErrorModel(String pageTitle, Message error, int code, String message) implements ViewModel {
}
}
|
Gehen wir diesen Code durch:
- Zeilen 4–9: die in den Feldern eines „Personen“-Formulars angezeigten Werte; niemals das Passwort – ein Passwort wird nicht an den Browser zurückgesendet. [empty()] liefert die Werte eines Formulars zum Hinzufügen;
- Zeilen 15–28: der Zustand eines Formulars, vorbereitet von [web/Validation.java]: die Nachrichten unter den Feldern und die rot hervorzuhebenden Felder. Ein Record darf Methoden haben: [errorOf] gibt die Nachricht eines Feldes (oder [null]) zurück, [invalidClass] gibt die Klasse [Bootstrap] [is-invalid] zurück, die ein Feld rot umrahmt, oder eine leere Zeichenkette. Views schreiben zum Beispiel [th:classappend="${state.invalidClass('login')}"], wobei [state] auf [model.state] verweist;
- Zeilen 31–32: eine Option der Liste der Anreden, wobei die ausgewählte markiert ist (siehe Beispiel 18);
- Zeilen 35–44: das, was das gemeinsame Fragment [person-fields.html] verwendet, das die Felder Anrede, Vorname und Nachname der drei Formulare anzeigt: die Werte und den Status. Eine Schnittstelle kann von einer anderen erben ([extends ViewModel]). Zeilen 41–43: Eine Default-Methode ([default]) ist eine Methode, deren Code in der Schnittstelle selbst steht; die Klassen und Records, die die Schnittstelle implementieren, erben sie. Hier die aus den Werten des Formulars erzeugte Liste der Anreden: Der Stream der Anreden wird ([map]) in Optionen umgewandelt, und [toList()] sammelt das Ergebnis in einer Liste. Die drei Formular-Templates profitieren davon ohne zusätzlichen Code;
- Zeilen 46–54: das ADMIN-Formular, das zum Hinzufügen und Ändern von Einträgen dient (siehe Beispiel 28): der Modus, die URL zum Absenden des Formulars und die URL der Liste für die Zurück-Schaltfläche;
- Zeilen 56–70: die Formulare für Registrierung und Kontoverwaltung; sie übergeben der View die Mindestlänge des Passworts, die als Parameter [{min}] in der Fehlermeldung des Feldes und, bei der Registrierung, im Hilfetext verwendet wird. Eine gewöhnliche Methode im Rumpf des Records genügt: Die View schreibt [${model.passwordMin()}];
- Zeilen 75–84: Die Verwaltungsseiten für Ärzte und Clients sind dieselben Views; nur ihre Texte unterscheiden sich. Dieser Record enthält die für jede Personenart spezifischen Übersetzungsschlüssel;
- Zeilen 86–92: eine Zeile aus der Liste der Ärzte oder Clients mit den Adressen ihrer Schaltflächen Bearbeiten und Löschen sowie das Template der Listenseite;
- Zeilen 95–100: der Bereich des Patienten: sein Name und seine anstehenden Termine, jeweils mit einem Link zum Tageskalender;
- Zeilen 103–104: die Fehlerseite: der HTTP-Code und der Nachrichtenschlüssel.
11.16. Die Web-Schicht: Controller
Controller sind der sichtbare Teil der Web-Schicht: Jeder von ihnen empfängt die Anfragen einer Gruppe von Seiten, liest deren Parameter, befragt die Geschäftsschicht (immer über den Service [ApplicationModel]), wählt dann eine View aus und übergibt ihr ein Modell oder leitet die Anfrage weiter. Eine Action gibt eine Zeichenkette zurück: entweder den Namen einer View (["schedule"] bezeichnet die Datei [templates/schedule.html]; siehe Beispiel 13) oder eine Weiterleitung (["redirect:/login"]; siehe Beispiel 04). Das View-Template ist immer ein einziges Objekt, ein [record] aus der Datei [models/ViewModels.java], abgelegt im [Model] von Spring unter dem Namen [model]. Alle POST-Formulare folgen dem Muster Post/Redirect/Get (siehe Beispiel 20); alle Nachrichten sind Übersetzungsschlüssel, die von der View übersetzt werden. Der Login-Controller [AuthController] wurde zusammen mit der Authentifizierung auskommentiert.
11.16.1. controllers/LanguageController.java
| // =========================================================================
// controllers/LanguageController.java
// -------------------------------------------------------------------------
// GET /language/fr, GET /language/en: die beiden Schaltflächen FR / EN der Navigationsleiste.
// Nicht geschützte Route: Man muss die Sprache wechseln können, bevor man
// sich anmeldet.
//
// Die Wahl wird im Cookie des CookieLocaleResolver gespeichert (siehe
// config/WebConfig.java): Bei jeder folgenden Anfrage liest Spring MVC es wieder ein
// und legt die Sprache der Anfrage fest (der Parameter Locale der Aktionen, die
// Sprache der Nachrichten #{...} der Views). Dann kehren wir zu der Seite zurück,
// von der wir kamen.
// =========================================================================
package rdvmedecins.controllers;
import java.net.URI;
import java.net.URISyntaxException;
import java.util.Locale;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.server.ResponseStatusException;
import org.springframework.web.servlet.LocaleResolver;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import rdvmedecins.web.Translator;
@Controller
public class LanguageController {
private final LocaleResolver localeResolver;
public LanguageController(LocaleResolver localeResolver) {
this.localeResolver = localeResolver;
}
@GetMapping("/language/{language}")
public String change(@PathVariable String language, HttpServletRequest request, HttpServletResponse response) {
if (!Translator.LANGUAGES.contains(language)) {
// -> Fehlerseite 404 (siehe ErrorController)
throw new ResponseStatusException(HttpStatus.NOT_FOUND);
}
// setzt das Sprach-Cookie
localeResolver.setLocale(request, response, Locale.of(language));
return "redirect:" + originPage(request);
}
// -----------------------------------------------------------------------
// die vorherige Seite gemäß dem HTTP-Header "Referer", den der
// Browser sendet. Wir behalten nur deren Pfad (/schedule?...): Eine Weiterleitung auf
// eine vollständige, von der Anfrage gelieferte Adresse würde es ermöglichen,
// den Benutzer auf eine andere Website zu schicken (sogenannte "Open-Redirect"-Schwachstelle).
// -----------------------------------------------------------------------
private static String originPage(HttpServletRequest request) {
String referer = request.getHeader(HttpHeaders.REFERER);
if (referer == null) {
return "/";
}
try {
URI url = new URI(referer);
String path = url.getRawPath();
// "//site.com/..." würde vom Browser als Adresse
// auf einer ANDEREN Website verstanden: ebenfalls abgelehnt
if (!url.isAbsolute() || path == null || !path.startsWith("/") || path.startsWith("//")
|| path.startsWith("/language/")) {
return "/";
}
return url.getRawQuery() == null ? path : path + "?" + url.getRawQuery();
} catch (URISyntaxException e) {
return "/";
}
}
}
|
Dies ist mehr oder weniger der Controller aus Beispiel 22: dieselbe Route [/language/{language}], dasselbe Cookie von [CookieLocaleResolver], dieselbe Rückkehr zur ursprünglichen Seite über den Header [Referer]. Kommentieren wir ihn:
- Zeile 32: [@Controller] macht die Klasse zu einem MVC-Controller, der beim Start erkannt und von [Spring] als Bean erzeugt wird (ein Objekt, dessen Erzeugung Spring verwaltet und das es an anderer Stelle injizieren kann, siehe Beispiel 06);
- Zeilen 35–39: Der Controller erhält per Dependency Injection den [LocaleResolver] , der in [config/WebConfig.java] definiert ist. Die Klasse hat nur einen Konstruktor: Spring ruft ihn auf und liefert die angeforderten Beans, ohne dass er mit [@Autowired] annotiert werden muss. Alle Controller der Anwendung sind so geschrieben;
- Zeilen 41–42: die Route [GET /language/{language}]. [@PathVariable] ordnet den Parameter [language] dem Segment [{language}] der URL zu (siehe Beispiel 02). Die Action erhält außerdem die Anfrage und die Antwort des Servers ([Servlet]): Man deklariert sie einfach als Parameter, und Spring MVC stellt sie bereit;
- Zeilen 43–46: Eine unbekannte Sprache ([/language/de]) liefert eine 404-Seite. Die Action erzeugt diese Seite nicht: Sie löst eine [ResponseStatusException] aus, die Spring MVC in eine 404-Fehlerantwort umwandelt; der Server leitet die Anfrage dann an [/error] weiter, wo [ErrorController] (unten) die Seite erzeugt;
- Zeile 48: [setLocale] setzt das Sprach-Cookie (sein Name [rdvmedecins_language], seine Lebensdauer von einem Jahr und seine Optionen [HttpOnly] und [SameSite=Lax] wurden in [WebConfig] festgelegt). Bei jeder weiteren Anfrage liest [CookieLocaleResolver] dieses Cookie und legt die Sprache der Anfrage fest;
- Zeile 49: Rückkehr zur vorherigen Seite. Das Präfix [redirect:] fordert von Spring MVC eine 302-Antwort an;
- Zeilen 58–76: die vorherige Seite, ermittelt anhand des Headers [Referer]. Wir behalten nur den Pfad und die Parameter ([/schedule?doctorId=1&day=...]): Eine Weiterleitung auf eine vollständige, von der Anfrage gelieferte URL könnte den Benutzer auf eine andere Website schicken (eine Schwachstelle, die als „Open Redirect“ bekannt ist);
- Zeilen 68–71: Abgelehnt werden die folgenden Fälle, was zur Rückkehr zur Wurzel der Website führt: eine relative Adresse, ein Pfad, der mit [//] beginnt (den der Browser als Adresse einer anderen Website interpretieren würde), und eine Seite mit dem Namen [/language/...], die den Browser in eine Schleife schicken würde. [getRawPath] und [getRawQuery] stellen Pfad und Parameter so wieder her, wie sie in der URL standen, weiterhin kodiert ([%20] ...), bereit zum erneuten Einfügen in eine URL.
Prüfen wir das mit [curl]:
| curl -i -H "Referer: http://localhost:8081/login" http://localhost:8081/language/en
|
| HTTP/1.1 302
Set-Cookie: rdvmedecins_language=en; Path=/; Max-Age=31536000; Expires=Sat, 25 Sep 2027 16:47:10 GMT; HttpOnly; SameSite=Lax
Location: http://localhost:8081/login
Content-Length: 0
|
Das Cookie ist gesetzt, und der Browser wird auf die Anmeldeseite umgeleitet, die nun auf Englisch angezeigt wird.
Die Hauptseite der Anwendung und der funktionsreichste Controller. Gehen wir ihn Abschnitt für Abschnitt durch.
11.16.2.1. Der URL-Code der Seite
| // =========================================================================
// controllers/ScheduleController.java
// -------------------------------------------------------------------------
// Die Seite des Terminkalenders: Auswahl eines Arztes und eines Tages, Terminkalender
// dieses Arztes an diesem Tag, Buchung und Stornierung von Terminen.
//
// GET /schedule?doctorId=1&day=2026-09-23 die Seite
// GET /schedule?doctorId=1&day=2026-09-23&book=7 dieselbe Seite, mit
// geöffnetem Buchungsdialog
// für Slot 7
// POST /schedule/book erstellt einen Termin
// POST /schedule/cancel storniert einen Termin
//
// Die gesamte Seite wird durch ihre URL beschrieben: Sie lässt sich neu laden, in
// die Lesezeichen aufnehmen, die Schaltfläche "Zurück" des Browsers lässt sich verwenden - ohne eine Zeile
// JavaScript.
//
// Was jeder sieht und tun kann:
//
// | Rolle | angezeigter gebuchter Slot | Book | Cancel |
// |---------------|-----------------------------------|--------------------|---------|
// | ADMIN, DOCTOR | Name des Patienten | für einen Patienten | ja |
// | | | aus einer Liste | |
// | USER (Patient)| "Booked" oder IHR Name, wenn es | für sich selbst, wenn | nein (*) |
// | | ihr eigener Termin ist | sie keinen | |
// | | | bevorstehenden Termin haben | |
//
// (*) Der Patient storniert seinen Termin auf seiner Seite "My area".
//
// VERTRAULICHKEIT: Bei einem Patienten wird der Name der ANDEREN Patienten nicht
// einfach von der View verborgen - er wird nie in das an die View
// übergebene Modell gelegt. Das an den Browser gesendete HTML enthält ihn daher nicht,
// auch nicht versteckt (sonst würde ihn ein einfaches "Seitenquelltext anzeigen" verraten).
//
// Keine Buchung in der Vergangenheit: Die Schaltfläche "Book" erscheint nur
// für heute und die folgenden Tage (und die Geschäftsschicht würde sie ohnehin
// ablehnen).
//
// Sicherheit: Alle URLs unter /schedule erfordern einen authentifizierten Benutzer
// (siehe SecurityConfig: anyRequest().authenticated()). @PreAuthorize an einer
// Aktion verlangt zusätzlich eine der aufgeführten Rollen. Ohne gültiges Token: zurück zu
// /login; unzureichende Rolle: Seite 403.
// =========================================================================
package rdvmedecins.controllers;
import java.time.LocalDate;
import java.util.List;
import java.util.Locale;
import java.util.Optional;
import org.springframework.http.HttpStatus;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.server.ResponseStatusException;
import org.springframework.web.servlet.mvc.support.RedirectAttributes;
import jakarta.servlet.http.HttpServletRequest;
import rdvmedecins.auth.ConnectedUser;
import rdvmedecins.domain.DoctorDaySchedule;
import rdvmedecins.entities.Client;
import rdvmedecins.entities.Slot;
import rdvmedecins.entities.Person;
import rdvmedecins.entities.Role;
import rdvmedecins.entities.Appointment;
import rdvmedecins.business.Dates;
import rdvmedecins.business.BusinessException;
import rdvmedecins.models.ViewModels.ScheduleModel;
import rdvmedecins.models.ViewModels.ScheduleView;
import rdvmedecins.models.ViewModels.ScheduleRowView;
import rdvmedecins.models.ViewModels.Message;
import rdvmedecins.models.ViewModels.OptionView;
import rdvmedecins.models.ViewModels.BookingView;
import rdvmedecins.web.ApplicationModel;
import rdvmedecins.web.FlashMessage;
import rdvmedecins.web.Utils;
@Controller
@RequestMapping("/schedule")
public class ScheduleController {
// was der Controller über den Benutzer weiß, um die Anzeige zu bestimmen
private record Rights(
boolean manager, // ADMIN oder DOCTOR
Client patient, // der angemeldete Client (Rolle USER), sonst null
boolean patientCanBook) { // USER ohne bevorstehenden Termin
}
// die versteckten Felder doctorId / day, beiden POST-Formularen gemeinsam
private record ScheduleRequest(int doctorId, LocalDate day) {
}
private final ApplicationModel application;
public ScheduleController(ApplicationModel application) {
this.application = application;
}
|
- Zeilen 7–12: die Routen der Seite. Beachten Sie, dass das Buchungsfenster nicht von [JavaScript] geöffnet wird: Es ist ein Parameter der URL ([book=7]), der den Server anweist, die Seite mit geöffnetem Fenster zu rendern. Die Schaltfläche „Buchen“ ist daher einfach ein Link. Die gesamte Seite wird durch ihre URL beschrieben: Sie können sie neu laden, als Lesezeichen speichern oder die Schaltfläche „Zurück“ des Browsers verwenden;
- Zeilen 20–28: was jede Rolle sieht und tun kann. Diese Tabelle ist die „Spezifikation“ der Seite: Der Rest des Controllers setzt sie um;
- Zeilen 30–33: die Datenschutzregel, auf die wir noch zurückkommen: Die Namen anderer Patienten werden nicht von der View ausgeblendet; sie werden nie an den Browser gesendet;
- Zeilen 39–42: Sicherheit. Die Klasse enthält keine Sicherheitsannotationen: Es ist die Konfiguration von [Spring Security] ([anyRequest().authenticated()], siehe [config/SecurityConfig.java]), die für jede Adresse [/schedule...] einen angemeldeten Benutzer verlangt. Actions, die zusätzlich eine Rolle erfordern, werden mit [@PreAuthorize] annotiert (siehe Beispiel 26);
- Zeilen 84–86: [@RequestMapping("/schedule")], auf die Klasse angewendet, ist das Präfix aller Routen des Controllers (siehe Beispiel 02);
- Zeilen 88–93: das, was der Controller über den angemeldeten Benutzer weiß, einmal pro Anfrage berechnet (siehe die Methode [rights], weiter unten). Dies ist ein Record (siehe „Die Domäne: Der Terminkalender“), dessen Zugriffsmethoden [rights.manager()], [rights.patient()] ... sind. Dieser [record] ist privat und innerhalb der Klasse deklariert: Er wird nur von dieser Klasse verwendet. Ein Manager ist ein ADMIN oder ein DOCTOR; [patient] wird nur für einen Client (Rolle USER) befüllt;
- Zeilen 95–97: der Name des Arztes und das Datum, gelesen aus den versteckten Feldern der beiden POST-Formulare der Seite, nach der Umwandlung;
- Zeilen 99–103: der Service [ApplicationModel] (siehe „Die Web-Schicht: Gemeinsame Services“), der vom Konstruktor empfangen wird.
11.16.2.2. GET /schedule
| // -----------------------------------------------------------------------
// GET /schedule
// Die URL-Parameter werden unverarbeitet gelesen (request.getParameter), um einen
// FEHLENDEN Parameter (null) von einem LEEREN Parameter (?doctorId=) zu unterscheiden.
// -----------------------------------------------------------------------
@GetMapping
public String show(@AuthenticationPrincipal Jwt token, HttpServletRequest request,
Locale locale, Model model) {
String error = null;
ConnectedUser user = Utils.user(token);
Rights rights = rights(user);
// der Tag: der aus der URL, wenn er gültig ist, sonst heute
LocalDate day = Dates.today();
String rawDay = request.getParameter("day");
if (rawDay != null) {
Optional<LocalDate> requestedDay = Utils.validDate(rawDay);
if (requestedDay.isPresent()) {
day = requestedDay.get();
} else {
error = "ERRORS.INVALID_DATE";
}
}
boolean dayBookable = !day.isBefore(Dates.today());
// der Arzt: der aus der URL; fehlt er, bei einem angemeldeten Arzt dieser selbst
String rawDoctorId = request.getParameter("doctorId");
Integer doctorId = Utils.positiveInteger(rawDoctorId);
if (rawDoctorId == null && user.role() == Role.DOCTOR) {
doctorId = application.getDoctorByUserId(user.userId()).map(d -> d.getId()).orElse(null);
}
// die Dropdown-Liste der Ärzte ("final": in der Lambda-Funktion verwendbar)
final Integer chosenId = doctorId;
List<OptionView> doctors = application.getAllDoctors().stream()
.map(d -> option(d, d.getId().equals(chosenId)))
.toList();
// der Terminkalender, wenn ein Arzt gewählt ist (und das Datum gültig)
ScheduleView schedule = null;
if (doctorId != null && error == null) {
Optional<DoctorDaySchedule> doctorSchedule = application.getDoctorDaySchedule(doctorId, day);
if (doctorSchedule.isEmpty()) {
error = "ERRORS.DOCTOR_NOT_FOUND";
} else {
schedule = scheduleView(doctorSchedule.get(), rights, dayBookable, locale);
}
}
|
- Zeile 7: [@GetMapping] ohne Pfad: Die Action antwortet auf [GET /schedule], das Präfix des Controllers;
- Zeilen 8–9: die Parameter der Action, die alle von Spring MVC bereitgestellt werden. [@AuthenticationPrincipal Jwt token] ist das [JWT]-Token des angemeldeten Benutzers, das bereits von [Spring Security] verifiziert wurde (siehe „Authentifizierung“); [request] bietet Zugriff auf die Rohparameter der URL; [locale] ist die Sprache der Anfrage, festgelegt von [CookieLocaleResolver]; [model] ist das Template, das die Action für die View befüllt. Die Action deklariert die Parameter [doctorId] oder [day] nicht: Sie liest sie selbst aus der Anfrage ([HttpServletRequest], siehe Beispiel 05): [request.getParameter] gibt [null] für einen fehlenden Parameter und eine leere Zeichenkette für einen leeren Parameter zurück ([?doctorId=]). Diese beiden Fälle müssen unterschieden werden (siehe unten);
- Zeilen 11–12: der angemeldete Benutzer und seine Berechtigungen. [Utils.user] (Ordner [web]) liest die Informationen des Tokens (Claims: ID, Login, Name, Rolle) und wandelt sie in ein Objekt [ConnectedUser] um;
- Zeilen 15–25: das angeforderte Datum, wenn es gültig ist; andernfalls heute. Fehlt der [day]-Parameter, wird ohne Fehlermeldung der heutige Tag zurückgegeben. Ist er vorhanden, aber ungültig ([day=2026-02-30]), wird eine Fehlermeldung erzeugt. [Utils.validDate] gibt ein [Optional] zurück (siehe „Die DAO-Schicht“), das mit [isPresent()] geprüft wird, bevor sein Wert mit [get()] extrahiert wird. Buchungen sind nur ab heute möglich ([dayBookable]);
- Zeilen 28–32: der angeforderte Arzt. [Utils.positiveInteger] gibt eine streng positive ganze Zahl oder [null] zurück, wenn der Wert fehlt, leer oder ungültig ist: Der Typ ist [Integer], die „Objekt“-Version des Typs [int], die [null]sein kann. Fehlt der [doctorId]-Parameter in der URL , sieht ein angemeldeter Arzt seinen eigenen Terminkalender: Das ist seine Startseite. Ist er leer ([doctorId=], die Option „Arzt auswählen“ in der Liste), wird kein Kalender angezeigt. Zeile 31: [map(d -> d.getId())] wandelt das von [getDoctorByUserId] zurückgegebene [Optional<Doctor>] in ein [Optional<Integer>] um, und [orElse(null)] extrahiert daraus den Wert oder [null] , wenn es leer ist;
- Zeilen 35–38: die Optionen der Dropdown-Liste der Ärzte, gelesen aus dem Cache von [ApplicationModel]; die Option des angeforderten Arztes ist ausgewählt (siehe die Methode [option] am Ende der Datei). [stream()] wandelt die Liste in einen Stream um, den [map] Element für Element verarbeitet und den [toList()] wieder in eine Liste umwandelt. [d -> option(...)] ist ein Lambda: eine anonyme Funktion, die an Ort und Stelle definiert wird. Ein Lambda kann eine lokale Variable nur verwenden, wenn sie nie wieder verändert wird: Deshalb wird [doctorId], das in Zeile 31 verändert wird, in Zeile 35 in eine Variable [final] (die nicht verändert werden kann) kopiert. In Zeile 37 werden die beiden [Integer]-Werte mit [equals] verglichen, das ihre Werte vergleicht, und nicht mit [==], das zwei Objekte vergleichen würde: ein klassischer Fallstrick von [Java];
- Zeilen 41–49: Der Terminkalender wird nur berechnet, wenn ein Arzt ausgewählt und das Datum gültig ist. Eine unbekannte Arzt-ID löst eine Nachricht aus, keine Fehlerseite. Der von der Geschäftsschicht berechnete Kalender (ein Objekt [DoctorDaySchedule] aus dem Ordner [domain]) wird von der Methode [scheduleView] formatiert, die weiter unten besprochen wird.
11.16.2.3. Das Buchungsfenster und das View-Template
| // der Buchungsdialog: nur, wenn der angeforderte Slot von diesem Benutzer
// gebucht werden kann
BookingView booking = null;
Integer slotId = Utils.positiveInteger(request.getParameter("book"));
if (schedule != null && slotId != null) {
Optional<ScheduleRowView> row = schedule.rows().stream()
.filter(r -> r.slotId() == slotId && r.bookable())
.findFirst();
if (row.isPresent()) {
booking = new BookingView(
row.get().slotId(),
row.get().time(),
rights.manager()
? application.getAllClients().stream().map(c -> option(c, false)).toList()
: List.of(),
rights.patient() != null ? Utils.label(rights.patient()) : null);
}
}
model.addAttribute("model", new ScheduleModel(
"SCHEDULE.PAGE_TITLE",
error == null ? null : Message.of(error),
doctors,
doctorId,
Utils.iso(day),
schedule,
booking,
doctorId != null ? scheduleUrl(doctorId, day, null) : "/schedule",
patientInfo(rights, schedule)));
return "schedule";
}
|
- Zeilen 3–8: das Zeitfenster, für das die URL eine Reservierung anfordert ([book=7]). Es muss im angezeigten Kalender erscheinen und von diesem Benutzer buchbar sein: Eine manuell erstellte URL (ein vergangenes Zeitfenster, ein belegtes Zeitfenster oder ein Zeitfenster eines anderen Arztes) öffnet das Fenster nicht. [filter] behält nur die Zeilen, die die Bedingung erfüllen, und [findFirst] gibt die erste davon in einem [Optional] zurück (leer, wenn keine passt);
- Zeilen 9–17: das Template des Fensters. Ein Manager wählt einen Patienten aus einer Liste (alle Clients, aus dem Cache gelesen); ein Patient bucht für sich selbst: Das Fenster zeigt einfach seinen Namen an. [List.of()] ist eine leere Liste;
- Zeilen 20–29: das Seiten-Template, ein [ScheduleModel] (siehe [models/ViewModels.java]), das im Template unter dem Namen [model] abgelegt wird. Die Argumente des Konstruktors des [record] sind in der Reihenfolge seiner Felder aufgeführt: der Schlüssel des Seitentitels, ein eventueller Fehler (eine [Message]: ein Übersetzungsschlüssel und seine Parameter), die Ärzte, der ausgewählte Arzt, der Tag im Format [yyyy-MM-dd], der Kalender, das Buchungsfenster usw. [condition ? value1 : value2] ergibt [value1] , wenn die Bedingung wahr ist, andernfalls [value2] ;
- Zeile 28: die Adresse des angezeigten Kalenders ohne das Buchungsfenster – das ist die Adresse der Schaltfläche, die das Fenster schließt;
- Zeile 29: eine Informationsnachricht für Patienten, die bereits einen anstehenden Termin haben: Sie erklärt, warum sie keine Schaltfläche „Buchen“ sehen. Sie wird von der Methode [patientInfo] am Ende der Datei berechnet;
- Zeile 30: der Name der View: [templates/schedule.html].
11.16.2.4. POST /schedule/book
| // -----------------------------------------------------------------------
// POST /schedule/book Felder: doctorId, day, slotId, clientId
//
// Bei einem Patienten (USER) wird das Feld clientId IGNORIERT: Er bucht immer
// für sich selbst. Einem vom Browser gesendeten Feld zu vertrauen,
// würde einem geschickten Patienten erlauben, im Namen eines anderen zu buchen.
//
// Muster "Post / Redirect / Get": Was auch immer das Ergebnis ist, wir bauen hier
// keine Seite auf - wir legen eine Flash-Nachricht ab und leiten
// auf den Terminkalender weiter (siehe Beispiel 20).
// -----------------------------------------------------------------------
@PostMapping("/book")
@PreAuthorize("hasAnyRole('ADMIN', 'DOCTOR', 'USER')")
public String book(
@RequestParam(required = false) String doctorId,
@RequestParam(required = false) String day,
@RequestParam(required = false) String slotId,
@RequestParam(required = false) String clientId,
@AuthenticationPrincipal Jwt token,
RedirectAttributes redirect) {
ScheduleRequest req = readScheduleRequest(doctorId, day);
Integer sltId = Utils.positiveInteger(slotId);
if (req == null || sltId == null) {
// -> Seite "invalid request" (siehe ErrorController)
throw new ResponseStatusException(HttpStatus.BAD_REQUEST);
}
ConnectedUser user = Utils.user(token);
Optional<Client> client;
if (user.isPatient()) {
client = Optional.of(Utils.connectedPatient(application, user));
} else {
Integer cliId = Utils.positiveInteger(clientId);
if (cliId == null) {
// kein Patient gewählt: Wir öffnen den Buchungsdialog erneut
redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.error("ERRORS.CHOOSE_PATIENT"));
return "redirect:" + scheduleUrl(req.doctorId(), req.day(), sltId);
}
client = application.getClientById(cliId);
}
Optional<Slot> slot = application.getSlotById(sltId);
FlashMessage flash;
if (client.isEmpty()) {
flash = FlashMessage.error("ERRORS.PATIENT_NOT_FOUND");
} else if (slot.isEmpty() || slot.get().getDoctorId() != req.doctorId()) {
flash = FlashMessage.error("ERRORS.SLOT_NOT_FOUND");
} else {
try {
// die Regeln (nicht in der Vergangenheit, nur ein bevorstehender Termin pro
// Patient, freier Slot) werden von der Geschäftsschicht geprüft
application.addAppointment(req.day(), slot.get(), client.get());
flash = FlashMessage.success("SCHEDULE.BOOKED");
} catch (BusinessException e) {
// dieselbe Regel, aber eine Nachricht in der 2. Person, wenn der
// Patient selbst bucht ("You already have..." statt
// "This patient..."). Die anderen Ausnahmen (echte
// Anomalien) werden nicht abgefangen: Seite 500.
flash = e.getKey().equals("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT") && user.isPatient()
? FlashMessage.error("SCHEDULE.ALREADY_BOOKED_INFO")
: FlashMessage.error(e.getKey(), e.getParams());
}
}
redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, flash);
return "redirect:" + scheduleUrl(req.doctorId(), req.day(), null);
}
|
- Zeile 13: [@PreAuthorize] verlangt zusätzlich zu einem angemeldeten Benutzer eine der aufgeführten Rollen (siehe Beispiel 26). Die Annotation enthält einen Ausdruck, der von [Spring Security] vor dem Aufruf der Methode ausgewertet wird: [hasAnyRole('ADMIN', 'DOCTOR', 'USER')] ist wahr, wenn der Benutzer eine dieser Rollen hat. Hier schafft er keine weitere Einschränkung; er dokumentiert die Regel und würde sie schützen, falls eine vierte Rolle hinzukäme;
- Zeilen 15–18: die Formularfelder im Buchungsfenster (siehe Beispiel 11). [@RequestParam] bindet jeden Methodenparameter an das gleichnamige Feld; [required = false]: Ein fehlendes Feld ergibt [null] statt eines 400-Fehlers von Spring (MVC). Sie werden als Zeichenketten empfangen und dann sorgfältig umgewandelt;
- Zeile 20: [RedirectAttributes] dient dazu, vor einer Weiterleitung eine Flash-Nachricht anzuzeigen (siehe Beispiel 20);
- Zeilen 21–26: „Arzt“ und „Tag“ sind versteckte Formularfelder; sie ermöglichen dem Benutzer die Rückkehr zum angezeigten Kalender. Sind sie ungültig, stammt die Anfrage nicht von unserer Seite – sie wurde manuell erstellt. Die Exception [ResponseStatusException(HttpStatus.BAD_REQUEST)] erzeugt eine 400-Antwort, die der Server in eine Fehlerseite umwandelt (siehe [ErrorController]);
- Zeilen 29–31: Bei einem Patienten wird das Feld [clientId] ignoriert – das System bucht immer für den Patienten selbst. Sich auf dieses vom Browser gesendete Feld zu verlassen, würde es einem böswilligen Patienten ermöglichen, eine Buchung im Namen eines anderen vorzunehmen. [Utils.connectedPatient] identifiziert den Client anhand des Tokens; [Optional.of] legt ihn in einem [Optional] ab, damit er denselben Typ hat wie der in Zeile 39;
- Zeilen 33–38: Ein Administrator, der keinen Patienten ausgewählt hat, wird zusammen mit einer Flash-Fehlermeldung zum Buchungsfenster (der URL mit [book]) umgeleitet. [addFlashAttribute] speichert die Nachricht in den Flash-Attributen, die [web/CookieFlashMapManager.java] in einem Cookie bis zur nächsten Anfrage transportiert;
- Zeilen 42–47: Der Patient muss existieren, und das Zeitfenster muss existieren und zum Arzt im Kalender gehören: Man kann kein Zeitfenster eines Arztes bei einem anderen buchen;
- Zeile 52: Die Geschäftsregeln (nicht in der Vergangenheit, Zeitfenster frei, nur ein anstehender Termin pro Patient) werden von der Geschäftsschicht geprüft, die bei einer Ablehnung eine [BusinessException] auslöst;
- Zeilen 54–62: Jede [BusinessException] wird samt Schlüssel und Parametern zu einer Flash-Fehlermeldung. Bei einem Patienten wird die Nachricht „Dieser Patient hat bereits einen anstehenden Termin“ durch eine Nachricht in der zweiten Person ersetzt. Die anderen Exceptions werden nicht abgefangen: Das sind echte Fehler, die zu einer 500-Fehlerseite führen. ([C#] hat für diesen Fall einen Exception-Filter, [catch ... when], den es in [Java] nicht gibt: Die Bedingung wird im [catch]-Block geprüft);
- Zeilen 64–65: das PRG-Schema: Unabhängig vom Ergebnis wird eine Flash-Nachricht angezeigt und der Benutzer zum Kalender umgeleitet, der die Nachricht anzeigt.
11.16.2.5. POST /schedule/cancel
| // -----------------------------------------------------------------------
// POST /schedule/cancel Felder: appointmentId, doctorId, day
// (ein Patient storniert SEINEN Termin von "My area" aus, nicht von hier)
// -----------------------------------------------------------------------
@PostMapping("/cancel")
@PreAuthorize("hasAnyRole('ADMIN', 'DOCTOR')")
public String cancel(
@RequestParam(required = false) String appointmentId,
@RequestParam(required = false) String doctorId,
@RequestParam(required = false) String day,
RedirectAttributes redirect) {
ScheduleRequest req = readScheduleRequest(doctorId, day);
Integer id = Utils.positiveInteger(appointmentId);
if (req == null || id == null) {
throw new ResponseStatusException(HttpStatus.BAD_REQUEST);
}
Optional<Appointment> appointment = application.getAppointmentById(id);
if (appointment.isEmpty()) {
// bereits storniert (von jemand anderem oder durch Doppelklick)
redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.error("ERRORS.APPOINTMENT_NOT_FOUND"));
} else {
application.deleteAppointment(appointment.get());
redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.success("SCHEDULE.CANCELLED"));
}
return "redirect:" + scheduleUrl(req.doctorId(), req.day(), null);
}
|
- Zeilen 5–6: Die Stornierung ist Administratoren vorbehalten; ein Patient storniert seinen Termin über „Mein Bereich“ (siehe [PatientAreaController]). Ein Patient, der diese Anfrage sendet, würde eine 403-Seite erhalten: [Spring Security] weist den Methodenaufruf zurück, und sein Handler für Zugriffsverweigerungen (siehe [SecurityConfig]) antwortet mit einem 403-Fehler, den der Server an [/error] weiterleitet;
- Zeilen 12–16: dieselben Prüfungen wie bei der Buchung;
- Zeilen 17–20: Ein bereits stornierter Termin (durch Doppelklick oder Stornierung durch einen anderen Manager) liefert eine Fehlermeldung, keine Fehlerseite;
- Zeilen 21–25: das Löschen, gefolgt vom PRG-Schema.
Mit dem Token-Cookie eines angemeldeten Patienten (dem von Herrn Jean MARTIN, das der Leser aus seinem Browser kopiert; siehe „Authentifizierung“; hier abgekürzt als [...]) wird die Anfrage abgelehnt:
| curl -i -b "rdvmedecins_jwt=..." -X POST http://localhost:8081/schedule/cancel -d "appointmentId=1&doctorId=1&day=2026-09-25"
|
| HTTP/1.1 403
Content-Type: text/html;charset=UTF-8
<!doctype html>
...
<h1 class="display-4 text-danger">403</h1>
<p class="lead">Your role does not allow you to access this page.</p>
...
|
| // -----------------------------------------------------------------------
// wer ist angemeldet, und was darf er auf dieser Seite tun?
// -----------------------------------------------------------------------
private Rights rights(ConnectedUser user) {
if (!user.isPatient()) {
return new Rights(true, null, false);
}
Client patient = Utils.connectedPatient(application, user);
List<Appointment> upcoming = application.getClientUpcomingAppointments(patient.getId());
return new Rights(false, patient, upcoming.isEmpty());
}
// -----------------------------------------------------------------------
// der Terminkalender des Arztes, für die View formatiert - und nach Rechten gefiltert
// -----------------------------------------------------------------------
private ScheduleView scheduleView(DoctorDaySchedule doctorSchedule, Rights rights, boolean dayBookable,
Locale locale) {
int doctorId = doctorSchedule.doctor().getId();
LocalDate day = doctorSchedule.day();
List<ScheduleRowView> rows = doctorSchedule.doctorDaySlots().stream().map(dds -> {
Slot slot = dds.slot();
Appointment appointment = dds.appointment();
boolean free = appointment == null;
// der Termin des angemeldeten Patienten?
boolean mine = appointment != null && rights.patient() != null && appointment.getClientId().equals(rights.patient().getId());
return new ScheduleRowView(
slot.getId(),
Utils.time(slot),
free,
// DER Vertraulichkeitspunkt: Ein Patient erhält den Namen nur
// SEINES Termins; für die anderen null (die View zeigt "Booked" an)
appointment != null && (rights.manager() || mine) ? Utils.label(appointment.getClient()) : null,
mine,
free && dayBookable && (rights.manager() || rights.patientCanBook()),
scheduleUrl(doctorId, day, slot.getId()),
appointment != null && rights.manager() ? appointment.getId() : null);
}).toList();
return new ScheduleView(Utils.label(doctorSchedule.doctor()), Utils.formatDay(day, locale), rows);
}
// ----------------------------------------------------------------- Hilfsfunktionen
// die versteckten Felder doctorId / day der POST-Formulare; null, wenn sie ungültig sind
private static ScheduleRequest readScheduleRequest(String rawDoctorId, String rawDay) {
Integer doctorId = Utils.positiveInteger(rawDoctorId);
Optional<LocalDate> day = Utils.validDate(rawDay);
return doctorId == null || day.isEmpty() ? null : new ScheduleRequest(doctorId, day.get());
}
private static String scheduleUrl(int doctorId, LocalDate day, Integer book) {
String url = "/schedule?doctorId=" + doctorId + "&day=" + Utils.iso(day);
return book == null ? url : url + "&book=" + book;
}
private static OptionView option(Person p, boolean selected) {
return new OptionView(p.getId(), Utils.label(p), selected);
}
// -----------------------------------------------------------------------
// die Informationsnachricht für einen Patienten, der bereits einen bevorstehenden Termin hat
// (warum es keine Schaltfläche "Book" gibt), oder null. Überflüssig, wenn SEIN
// Termin im angezeigten Terminkalender erscheint (in Blau): Das ist direkt
// nach der Buchung der Fall, wo die Nachricht fehl am Platz wäre.
// -----------------------------------------------------------------------
private static String patientInfo(Rights rights, ScheduleView schedule) {
if (rights.patient() == null || rights.patientCanBook()) {
return null;
}
boolean appointmentShown = schedule != null && schedule.rows().stream().anyMatch(ScheduleRowView::mine);
return appointmentShown ? null : "SCHEDULE.ALREADY_BOOKED_INFO";
}
}
|
- Zeilen 4–11: Ein Administrator hat alle Berechtigungen; ein Patient kann buchen, wenn er keine anstehenden Termine hat;
- Zeilen 16–17: Der von der Geschäftsschicht berechnete Kalender wird in Array-Elemente umgewandelt, eines pro Zeitfenster ([ScheduleRowView]);
- Zeile 20: Die an [map] übergebene Lambda-Funktion erstreckt sich hier über mehrere Zeilen: Ihr Rumpf ist ein von geschweiften Klammern umschlossener Block, der mit einem [return] endet;
- Zeile 25: [mine] legt fest, ob der Termin dem angemeldeten Patienten gehört;
- Zeile 28: Die View erhält nur bereits formatierte Daten ([8:00 - 8:20]); sie hat nichts mehr zu berechnen;
- Zeile 32: die Datenschutzkontrolle der Anwendung. Der Name des Patienten wird nur für einen Administrator oder für den Patienten, dem der Termin gehört, in das Modell aufgenommen. Für alle anderen enthält das Modell [null], und die View zeigt „Gebucht“ an. Der Name wird nicht einfach von der View ausgeblendet: Er wird nie an den Browser gesendet, und „Seitenquelltext anzeigen“ würde ihn nicht verraten;
- Zeilen 34–36: was die View anzeigen muss, wie vom Controller bestimmt: die Schaltfläche „Buchen“ (freies Zeitfenster, Datum nicht vergangen und Benutzer zum Buchen berechtigt), ihr Link (die URL der Seite zusammen mit [book]) und die Schaltfläche „Stornieren“ ([appointmentId] wird nur für einen Administrator befüllt). Die View trifft keine Entscheidungen: Sie befolgt diese Anweisungen;
- Zeile 38: der vollständige Terminkalender: der Arzt, der Tag, formatiert in der Sprache der Anfrage („Freitag 25. September 2026“), die Zeilen;
- Zeilen 44–48: die Werte der beiden versteckten Felder, die den POST-Formularen gemeinsam sind: ein [ScheduleRequest] oder [null] , wenn sie ungültig sind;
- Zeilen 50–53: die URL des Terminkalenders eines Arztes an einem bestimmten Tag, gegebenenfalls mit geöffnetem Buchungsfenster. Alle Weiterleitungen der Controller erzeugen sie mit dieser Methode: Die URLs der Seite werden an einer einzigen Stelle geschrieben;
- Zeilen 55–57: eine Option einer Dropdown-Liste (ID, Bezeichnung, Auswahl), sowohl für Ärzte als auch für Clients: Der Parameter hat den Typ [Person], die Elternklasse beider Entitäten;
- Zeilen 59–71: die Informationsnachricht für den Patienten, der bereits einen anstehenden Termin hat. Sie wird nicht gesendet, wenn dieser Termin im angezeigten Kalender erscheint: Der Name des Patienten in Blau genügt, und genau diese Seite sieht der Patient unmittelbar nach der Buchung, wo die Nachricht „Sie haben bereits einen anstehenden Termin“ fehl am Platz wäre. Zeile 69: [anyMatch] gibt an, ob mindestens eine Zeile des Streams die Bedingung erfüllt; [ScheduleRowView::mine] ist eine Methodenreferenz: das Äquivalent des Lambdas [r -> r.mine()].
Dies empfängt der Browser von Herrn Jean (Rolle USER) für den Kalender von Frau PELISSIER, der zwei reservierte Zeitfenster hat (Auszug):
| curl -b "rdvmedecins_jwt=..." "http://localhost:8081/schedule?doctorId=1&day=2026-09-26"
|
| <div class="card p-3">
<h5>Schedule for Saturday 26 September 2026 - Mme Marie PELISSIER</h5>
...
<tr>
<td>8:20 - 8:40</td>
<td>
<span class="badge text-bg-secondary">Booked</span>
</td>
<td>
</td>
</tr>
...
<tr>
<td>9:00 - 9:20</td>
<td>
<span class="badge text-bg-primary">Mr Jean MARTIN</span>
</td>
<td>
</td>
</tr>
|
Das Zeitfenster um 8:20 Uhr ist von einem anderen Patienten reserviert: Sein Name erscheint nirgends auf der Seite. Das Zeitfenster um 9:00 Uhr ist der Termin von Herrn MARTIN: Sein Name erscheint in Blau. Da er bereits einen anstehenden Termin hat, wird keine Schaltfläche „Buchen“ angezeigt. Die Informationsnachricht („Sie haben bereits einen anstehenden Termin ...“) erscheint hier nicht, da dieser Termin direkt vor seinen Augen liegt; sie erscheint im Kalender eines anderen Tages oder eines anderen Arztes, um das Fehlen der Schaltflächen zu erklären.
11.16.3. controllers/PersonsControllerBase.java
| // =========================================================================
// controllers/PersonsControllerBase.java
// -------------------------------------------------------------------------
// Die Verwaltung der Ärzte und die der Clients (dem ADMIN vorbehalten) sind
// IDENTISCH: gleiche Liste, gleiches Formular, gleiche Regeln. Statt
// dieselben Aktionen zweimal zu schreiben, schreiben wir sie einmal in dieser
// ABSTRAKTEN und GENERISCHEN Klasse, von der DoctorsController
// (@RequestMapping("/doctors")) und ClientsController
// (@RequestMapping("/clients")) erben. Jede Unterklasse muss nur ihre
// "Konfiguration" liefern: welche Methoden aufzurufen sind, welche Bezeichnungen anzuzeigen sind.
//
// Die HIER festgelegten Routen (@GetMapping("/add")...) werden geerbt und
// ergänzen die Route der Unterklasse. Wir erhalten daher für jede:
//
// GET /doctors Liste
// GET /doctors/add leeres Formular
// POST /doctors/add Erstellung
// GET /doctors/{id}/edit vorausgefülltes Formular
// POST /doctors/{id}/edit Bearbeitung
// POST /doctors/{id}/delete Löschung
//
// (und dieselben URLs unter /clients). Auch die Views sind gemeinsam:
// templates/persons/list.html und templates/persons/form.html.
//
// Eine abstrakte Klasse ist nie eine Bean: Nur ihre konkreten Unterklassen,
// die mit @Controller annotiert sind, sind Controller.
//
// SICHERHEIT: @PreAuthorize("hasRole('ADMIN')") steht an DIESER Klasse
// und nicht an den Unterklassen. Um zu entscheiden, welche Regel für eine
// Aktion gilt, betrachtet Spring Security die Annotation der Methode, dann die der
// Klasse, die die Methode DEKLARIERT - hier PersonsControllerBase. Stünde sie
// nur an DoctorsController, würde die Annotation für die
// geerbten Aktionen ignoriert: Ein USER könnte /doctors öffnen!
// =========================================================================
package rdvmedecins.controllers;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.function.BiFunction;
import java.util.function.Function;
import java.util.function.IntConsumer;
import java.util.function.Supplier;
import org.springframework.http.HttpStatus;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.ui.Model;
import org.springframework.validation.BindingResult;
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.server.ResponseStatusException;
import org.springframework.web.servlet.mvc.support.RedirectAttributes;
import jakarta.validation.Valid;
import rdvmedecins.entities.Person;
import rdvmedecins.business.PersonData;
import rdvmedecins.business.BusinessException;
import rdvmedecins.models.Forms.PersonForm;
import rdvmedecins.models.ViewModels.PersonKeys;
import rdvmedecins.models.ViewModels.FormState;
import rdvmedecins.models.ViewModels.PersonFormModel;
import rdvmedecins.models.ViewModels.PersonListModel;
import rdvmedecins.models.ViewModels.Message;
import rdvmedecins.models.ViewModels.PersonView;
import rdvmedecins.models.ViewModels.PersonValues;
import rdvmedecins.web.FlashMessage;
import rdvmedecins.web.Validation;
@PreAuthorize("hasRole('ADMIN')")
public abstract class PersonsControllerBase<T extends Person> {
// -----------------------------------------------------------------------
// was jede Unterklasse liefern muss. Die letzten fünf Felder sind
// FUNKTIONEN (funktionale Interfaces aus java.util.function): Die
// Unterklasse legt darin Methodenreferenzen ab, application::getAllDoctors...
// -----------------------------------------------------------------------
protected record PersonsConfig<T>(
String url, // "/doctors" oder "/clients"
PersonKeys keys,
Supplier<List<T>> list, // () -> Liste
Function<Integer, Optional<T>> find, // id -> Person
Function<PersonData, T> add, // data -> erstellte Person
BiFunction<Integer, PersonData, T> edit, // (id, data) -> bearbeitete Person
IntConsumer delete) { // id -> nichts
}
protected abstract PersonsConfig<T> config();
// die gemeinsamen Views
private static final String LIST_VIEW = "persons/list";
private static final String FORM_VIEW = "persons/form";
// -----------------------------------------------------------------------
// GET /doctors (oder /clients)
// -----------------------------------------------------------------------
@GetMapping
public String list(Model model) {
PersonsConfig<T> config = config();
List<PersonView> persons = config.list().get().stream()
.map(p -> new PersonView(p.getTitle(), p.getFirstName(), p.getLastName(), login(p),
config.url() + "/" + p.getId() + "/edit",
config.url() + "/" + p.getId() + "/delete"))
.toList();
model.addAttribute("model", new PersonListModel(config.keys().title(), null, config.keys(),
config.url() + "/add", persons));
return LIST_VIEW;
}
// -----------------------------------------------------------------------
// GET /doctors/add
// -----------------------------------------------------------------------
@GetMapping("/add")
public String addForm(Model model) {
return showForm(model, null, PersonValues.empty(), Map.of(), null, null);
}
// -----------------------------------------------------------------------
// POST /doctors/add
// [form] wurde von Spring MVC gefüllt UND validiert (@Valid): Das
// darauf folgende BindingResult sagt, ob die Eingabe korrekt ist.
// -----------------------------------------------------------------------
@PostMapping("/add")
public String add(@Valid PersonForm form, BindingResult result, Model model,
RedirectAttributes redirect) {
if (result.hasErrors()) {
return showForm(model, null, enteredValues(form), Validation.errorsOf(result),
null, null);
}
try {
T person = config().add().apply(data(form));
redirect.addFlashAttribute(FlashMessage.ATTRIBUTE,
FlashMessage.success(config().keys().added(), messageParams(person)));
return "redirect:" + config().url();
} catch (BusinessException e) {
return showBusinessError(model, redirect, null, enteredValues(form), e);
}
}
// -----------------------------------------------------------------------
// GET /doctors/{id}/edit
// {id:\d+}: Die ID muss aus Ziffern bestehen - /doctors/abc/edit
// passt auf keine Route (Seite 404)
// -----------------------------------------------------------------------
@GetMapping("/{id:\\d+}/edit")
public String editForm(@PathVariable int id, Model model) {
T person = config().find().apply(id)
.orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND));
PersonValues values = new PersonValues(person.getTitle(), person.getFirstName(), person.getLastName(),
login(person), person.getVersion());
return showForm(model, id, values, Map.of(), null, null);
}
// -----------------------------------------------------------------------
// POST /doctors/{id}/edit
// -----------------------------------------------------------------------
@PostMapping("/{id:\\d+}/edit")
public String edit(@PathVariable int id, @Valid PersonForm form, BindingResult result,
Model model, RedirectAttributes redirect) {
if (result.hasErrors()) {
return showForm(model, id, enteredValues(form), Validation.errorsOf(result),
null, null);
}
try {
T person = config().edit().apply(id, data(form));
redirect.addFlashAttribute(FlashMessage.ATTRIBUTE,
FlashMessage.success(config().keys().edited(), messageParams(person)));
return "redirect:" + config().url();
} catch (BusinessException e) {
return showBusinessError(model, redirect, id, enteredValues(form), e);
}
}
// -----------------------------------------------------------------------
// POST /doctors/{id}/delete
// (die Bestätigung "Are you sure?" wird abgefragt, bevor das Formular
// gesendet wird, siehe static/js/app.js)
// -----------------------------------------------------------------------
@PostMapping("/{id:\\d+}/delete")
public String delete(@PathVariable int id, RedirectAttributes redirect) {
Optional<T> person = config().find().apply(id);
FlashMessage flash;
try {
config().delete().accept(id);
flash = FlashMessage.success(config().keys().deleted(), messageParams(person.orElse(null)));
} catch (BusinessException e) {
flash = FlashMessage.error(e.getKey(), e.getParams());
}
redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, flash);
return "redirect:" + config().url();
}
// ----------------------------------------------------------------- private Methoden
// id null: Erstellungsformular; sonst: Bearbeitungsformular.
// errors: Feld -> Schlüssel der Nachricht; error: die Nachricht unten auf der Seite;
// otherFields: zusätzliche rot zu umrandende Felder
private String showForm(Model model, Integer id, PersonValues values,
Map<String, String> errors, String error, List<String> otherFields) {
PersonsConfig<T> config = config();
boolean creating = id == null;
FormState state = Validation.state(errors, otherFields);
model.addAttribute("model", new PersonFormModel(
creating ? config.keys().add() : config.keys().edit(),
Validation.pageMessage(errors, error == null ? null : Message.of(error)),
values,
state,
creating,
creating ? config.url() + "/add" : config.url() + "/" + id + "/edit",
config.url()));
return FORM_VIEW;
}
// eine Geschäftsregel hat den Schreibvorgang abgelehnt: Wir zeigen das Formular erneut an,
// mit der Eingabe des Benutzers und der Nachricht der Geschäftsschicht
private String showBusinessError(Model model, RedirectAttributes redirect, Integer id,
PersonValues values, BusinessException e) {
if (e.getKey().equals("ERRORS.DOCTOR_NOT_FOUND") || e.getKey().equals("ERRORS.PATIENT_NOT_FOUND")) {
// zwischenzeitlich von einem anderen ADMIN gelöscht: zurück zur Liste
redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.error(e.getKey()));
return "redirect:" + config().url();
}
// die Nachricht steht unten auf der Seite; die betroffenen Felder, falls vorhanden, werden
// rot umrandet, damit der Benutzer sofort sieht, was zu korrigieren ist
return showForm(model, id, values, Map.of(), e.getKey(),
Validation.BUSINESS_ERROR_FIELDS.get(e.getKey()));
}
// was der Benutzer eingegeben hat (Passwort ausgenommen: Wir senden es nie
// an den Browser zurück)
private static PersonValues enteredValues(PersonForm f) {
return new PersonValues(
f.getTitle() == null ? "" : f.getTitle(),
f.getFirstName() == null ? "" : f.getFirstName(),
f.getLastName() == null ? "" : f.getLastName(),
f.getLogin() == null ? "" : f.getLogin(),
f.getVersion());
}
// das validierte Formular -> die von der Geschäftsschicht erwarteten Daten
private static PersonData data(PersonForm f) {
return new PersonData(f.getTitle(), f.getLastName(), f.getFirstName(), f.getLogin(), f.getPassword(),
f.getVersion());
}
// {name} und {login} der Nachrichten "added / edited / deleted"
private static Map<String, String> messageParams(Person person) {
return person == null
? Map.of("name", "", "login", "")
: Map.of("name", person.getFirstName() + " " + person.getLastName(), "login", login(person));
}
private static String login(Person p) {
return p.getUser() == null ? "" : p.getUser().getLogin();
}
}
|
Die Behandlung von Ärzten und Clients ist identisch. Statt zwei ähnliche Controller zu schreiben, schreiben wir ihre Actions einmal in einer abstrakten, generischen Elternklasse. Kommentieren wir diesen Code:
- Zeilen 15–20: die für Ärzte erzeugten Routen; dieselben gibt es unter [/clients];
- Zeilen 22–23: Auch die Views werden gemeinsam genutzt (Datei [templates/persons]);
- Zeilen 25–26: Die Klasse ist nicht mit [@Controller] annotiert und könnte, da sie abstrakt ist, ohnehin nicht instanziiert werden: Nur ihre Unterklassen [DoctorsController] und [ClientsController] sind Beans und empfangen Anfragen;
- Zeilen 28–33 und Zeile 70: Die Beschränkung auf die Rolle ADMIN und [@PreAuthorize("hasRole('ADMIN')")] wird auf diese Klasse angewendet. Auf eine Klasse angewendet, gilt die Annotation für alle ihre Methoden. Um zu bestimmen, welche Regel für eine Action gilt, prüft [Spring Security] jedoch die Annotation der Methode und dann die der Klasse, die die Methode deklariert. Die Actions [list], [add] ... sind aber hier in [PersonsControllerBase] deklariert und werden von [DoctorsController] nur geerbt. Würde die Annotation auf [DoctorsController] angewendet, würde sie für sie ignoriert: Ein Patient (USER) könnte [/doctors] öffnen. Das unterscheidet sich von [ASP.NET Core MVC], wo das Attribut [[Authorize(Roles = "ADMIN")]] einer Unterklasse auch für geerbte Actions gilt;
- Zeile 71: Die Klasse ist abstrakt ([abstract]: Man kann von ihr kein Objekt erzeugen; sie existiert nur, um daraus abzuleiten) und generisch: [T] ist ein Typparameter, den jede Unterklasse durch [Doctor] oder [Client] ersetzt. [T extends Person] ist eine Einschränkung: [T] muss [Person] oder eine ihrer abgeleiteten Klassen sein; der Code kann daher [p.getFirstName()] oder [p.getUser()] verwenden, die allen Personen gemeinsam sind;
- Zeilen 78–86: die von jeder Unterklasse bereitgestellte Konfiguration in Form eines [record]: die Basis-URL, die Texte (Übersetzungsschlüssel, gruppiert im [record], [PersonKeys] und [models/ViewModels.java]) und fünf Funktionen , die zum Auflisten, Suchen, Hinzufügen, Ändern und Löschen aufzurufen sind. Eine in einer Variablen gespeicherte Funktion hat als Typ eine funktionale Schnittstelle aus dem Paket [java.util.function] (siehe „Die Geschäftsschicht“): [Supplier<R>] (keine Parameter, gibt ein [R] zurück, Methode [get]), [Function<P, R>] (ein Parameter: [P]; gibt ein [R] zurück; Methode: [apply]), [BiFunction<P1, P2, R>] (zwei Parameter), [IntConsumer] (ein [int]; gibt nichts zurück; Methode [accept]). [protected]: [record] ist nur für die Klasse und ihre Unterklassen (und das Paket) sichtbar;
- Zeile 88: eine abstrakte Methode: Jede Unterklasse muss sie implementieren, um ihre Konfiguration anzugeben;
- Zeilen 91–92: die beiden Views, bezeichnet durch ihren Pfad im Ordner [templates];
- Zeilen 97–108: die Liste. Routing-Annotationen, die auf Methoden einer Elternklasse angewendet werden, werden vererbt: In Kombination mit dem [@RequestMapping("/doctors")] der Unterklasse ergeben sie [GET /doctors]. [config.list().get()] ruft die in der Konfiguration angegebene Funktion auf. Für jede Person enthält das Modell die URL-Werte ihrer Schaltflächen Bearbeiten und Löschen;
- Zeilen 113–116: das leere Formular. [Map.of()] ist ein leeres Verzeichnis: kein Fehler;
- Zeilen 123–138: das Hinzufügen in drei Schritten, wie in Beispiel 28. Der Parameter [form] wurde von Spring MVC mit den gesendeten Feldern befüllt, dann anhand seiner Annotationen validiert ([@NotBlank], [@Size] ..., siehe [models/Forms.java]), weil er mit [@Valid] annotiert ist (siehe Beispiel 19). Das Validierungsergebnis steht im unmittelbar folgenden Parameter [BindingResult]: Eine ungültige Eingabe zeigt das Formular erneut an, mit den eingegebenen Werten und einer Nachricht unter jedem fehlerhaften Feld; eine gültige Eingabe wird an die Geschäftsschicht übergeben, dann wird der Browser mit einer Flash-Nachricht zur Liste umgeleitet (PRG); eine Ablehnung durch die Geschäftsschicht (ein doppelter Name, ein bereits verwendeter Login) zeigt das Formular erneut an;
- Zeilen 145–152: das vorausgefüllte Bearbeitungsformular. [{id:\\d+}] ist eine Pfadvariable, die mit einem regulären Ausdruck verknüpft ist: Der Bezeichner muss aus Ziffern bestehen ([\d+], wobei [\] in der [Java]-Zeichenkette verdoppelt wird). [/doctors/abc/edit] entspricht daher keiner Route, was zu einer 404-Seite führt. Ein nicht existierender Benutzer führt ebenfalls zu einem 404: [orElseThrow] ruft den Wert aus dem [Optional] ab oder löst, wenn es leer ist, die vom Lambda erzeugte Exception aus. Die Versionsnummer, ein verstecktes Feld des Formulars, dient dem optimistischen Sperren (siehe Beispiel 28);
- Zeilen 157–172: die Aktualisierung, nach demselben Muster wie das Einfügen;
- Zeilen 179–191: das Löschen. Die Person wird vorher abgerufen, um ihren Namen in der Erfolgsmeldung anzuzeigen ([orElse(null)]: die Person oder [null] , wenn sie nicht existierte). Eine Ablehnung durch die Geschäftsschicht (ein Arzt, der Termine hat) führt zu einer Flash-Fehlermeldung auf der Listenseite;
- Zeilen 198–212: das Formular, sowohl für das Anlegen ([id] ist gleich [null]) als auch für das Ändern: Nur die Anrede und die Postanschrift ändern sich. [Validation.state] und [Validation.pageMessage] (Ordner [web]) bereiten die Fehler je Feld, die rot hervorzuhebenden Felder und die Nachricht am Ende der Seite vor;
- Zeilen 216–227: Eine Person, die inzwischen (von einem anderen Administrator) gelöscht wurde, wird in der Liste angezeigt; andere fachliche Fehler zeigen das Formular erneut an, mit der Nachricht am Seitenende und den betroffenen, rot hervorgehobenen Feldern ([Validation.BUSINESS_ERROR_FIELDS] ordnet jedem Fehlercode die entsprechenden Felder zu: [firstName] und [lastName] bei einem Namensvetter);
- Zeilen 231–238: die erneut anzuzeigenden Werte – niemals das Passwort;
- Zeilen 241–244: die an die Geschäftsschicht übermittelten Daten;
- Zeilen 247–251: die Parameter [{name}] und [{login}] für Erfolgsmeldungen: Vor- und Nachname der Person und ihr Login;
- Zeilen 253–255: der Login des zugehörigen Kontos (eine leere Zeichenkette, falls das Konto fehlte, als Vorsichtsmaßnahme: Jeder hat ein Konto).
11.16.4. controllers/DoctorsController.java
| // =========================================================================
// controllers/DoctorsController.java
// -------------------------------------------------------------------------
// Verwaltung der Ärzte (nur Rolle ADMIN). Alle Aktionen werden
// von PersonsControllerBase geerbt: Hier bleibt nur zu sagen, WAS
// aufzurufen ist und WELCHE Bezeichnungen anzuzeigen sind.
//
// Die Beschränkung auf die Rolle ADMIN steht an der Elternklasse (siehe den
// Kommentar "SECURITY" von PersonsControllerBase).
// =========================================================================
package rdvmedecins.controllers;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import rdvmedecins.entities.Doctor;
import rdvmedecins.models.ViewModels.PersonKeys;
import rdvmedecins.web.ApplicationModel;
@Controller
@RequestMapping("/doctors")
public class DoctorsController extends PersonsControllerBase<Doctor> {
private final PersonsConfig<Doctor> config;
public DoctorsController(ApplicationModel application) {
// application::getAllDoctors: eine "Methodenreferenz", die
// Methode getAllDoctors des Objekts application, in einer Variablen gespeichert
this.config = new PersonsConfig<>(
"/doctors",
new PersonKeys(
"DOCTORS.TITLE",
"DOCTORS.ADD",
"DOCTORS.EDIT",
"DOCTORS.EMPTY",
"DOCTORS.DELETE_CONFIRM",
"DOCTORS.ADDED",
"DOCTORS.UPDATED",
"DOCTORS.DELETED"),
application::getAllDoctors,
application::getDoctorById,
application::addDoctor,
application::editDoctor,
application::deleteDoctor);
}
@Override
protected PersonsConfig<Doctor> config() {
return config;
}
}
|
- Zeilen 8–9: Die Beschränkung auf die Rolle ADMIN wird aus dem oben erläuterten Grund von der Elternklasse getragen;
- Zeilen 20–22: ein Controller ([@Controller]), dessen Routen alle mit [/doctors] beginnen. Er erbt ([extends]) von [PersonsControllerBase<Doctor>]: Der Typ [T] der Elternklasse wird zu [Doctor];
- Zeilen 26–45: Der Konstruktor erhält [ApplicationModel] per Injection und erzeugt die Konfiguration ein für alle Mal: die Basis-URL und die für Ärzte spezifischen Übersetzungsschlüssel;
- Zeilen 40–44: die aufzurufenden Funktionen, bei denen es sich um Methoden von
***[ApplicationModel]*** handelt. ***[application::getAllDoctors] ist eine *Methodenreferenz: Sie ruft die Methode nicht auf, sondern verweist auf sie. Der Compiler wandelt sie in einen Wert der von [record] erwarteten funktionalen Schnittstelle um ([Supplier<List<Doctor>>] bei der ersten), deren Methode [get] [application.getAllDoctors()] aufruft. Dies ist eine Kurzschreibweise für das Lambda [() -> application.getAllDoctors()];
- Zeile 29: [new PersonsConfig<>(...)]: Der Operator [<>], bekannt als „Diamond“-Operator, erlaubt dem Compiler, den generischen Typ abzuleiten ([Doctor]);
- Zeilen 47–50: Die abstrakte Methode der Elternklasse, hier mit [@Override] geschrieben, weist den Compiler an zu prüfen, dass sie tatsächlich eine Methode der Elternklasse überschreibt.
Wie wir bei der Authentifizierung gesehen haben, erhält ein Patient, der [/doctors] anfordert, eine 403-Seite: Der auf der Elternklasse gesetzte Schutz funktioniert also. Wir stellen außerdem fest, dass die Navigationsleiste dieser Fehlerseite den Benutzer anzeigt (siehe die [currentUser]-Methode von [auth/AuthService.java]). Mit dem Token-Cookie von Herrn Jean MARTIN (Rolle USER):
| curl -i -b "rdvmedecins_jwt=..." http://localhost:8081/doctors
|
| HTTP/1.1 403
Content-Type: text/html;charset=UTF-8
<!doctype html>
...
<span class="badge text-bg-light text-primary">USER</span>
<span class="text-white">Jean MARTIN</span>
...
<h1 class="display-4 text-danger">403</h1>
<p class="lead">Your role does not allow you to access this page.</p>
...
|
11.16.5. controllers/ClientsController.java
| // =========================================================================
// controllers/ClientsController.java
// -------------------------------------------------------------------------
// Verwaltung der Clients (der PATIENTEN der Praxis), nur Rolle ADMIN.
// Gleiches Prinzip wie DoctorsController (siehe dessen Kommentare).
// =========================================================================
package rdvmedecins.controllers;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import rdvmedecins.entities.Client;
import rdvmedecins.models.ViewModels.PersonKeys;
import rdvmedecins.web.ApplicationModel;
@Controller
@RequestMapping("/clients")
public class ClientsController extends PersonsControllerBase<Client> {
private final PersonsConfig<Client> config;
public ClientsController(ApplicationModel application) {
this.config = new PersonsConfig<>(
"/clients",
new PersonKeys(
"CLIENTS.TITLE",
"CLIENTS.ADD",
"CLIENTS.EDIT",
"CLIENTS.EMPTY",
"CLIENTS.DELETE_CONFIRM",
"CLIENTS.ADDED",
"CLIENTS.UPDATED",
"CLIENTS.DELETED"),
application::getAllClients,
application::getClientById,
application::addClient,
application::editClient,
application::deleteClient);
}
@Override
protected PersonsConfig<Client> config() {
return config;
}
}
|
Derselbe Controller für Clients: andere Route (Zeilen 16–18), andere Übersetzungsschlüssel, andere Methoden von [ApplicationModel] (Zeilen 34–38).
11.16.6. controllers/RegistrationController.java
| // =========================================================================
// controllers/RegistrationController.java
// -------------------------------------------------------------------------
// "Create a client account": Ein Patient, der noch kein Konto hat,
// erstellt es selbst. NICHT geschützte Routen (man hat per
// Definition noch kein Konto):
//
// POST /register/access Schaltfläche "Create a client account" der
// Anmeldeseite: prüft das CAPTCHA DIESER Seite und öffnet dann
// das Formular
// GET /register das Formular
// POST /register die Erstellung, dann zurück zur Anmeldeseite
//
// Der Ablauf ist durch EIN CAPTCHA gegen Roboter geschützt, das der
// Anmeldeseite:
// 1. Die Schaltfläche "Create a client account" sendet das Anmeldeformular
// an /register/access; ist das CAPTCHA korrekt abgetippt, stellt der Server
// einen Pass aus (siehe auth/RegistrationPassService.java);
// 2. ohne gültigen Pass schickt /register zurück auf die
// Anmeldeseite - das direkte Eintippen der URL nützt nichts;
// 3. der Pass wird bei der Erstellung verbraucht: Ein gelöstes CAPTCHA
// ermöglicht die Erstellung EINES Kontos;
// 4. zusätzlich ist die Anzahl der pro Stunde und IP-Adresse erstellten Konten
// begrenzt (siehe auth/AttemptLimiterService.java).
//
// Das erstellte Konto ist genau dasjenige, das der ADMIN auf der Seite
// "Clients" erstellen würde (dieselbe Methode der Geschäftsschicht: addClient), außer
// dass der Patient seinen Login und sein Passwort WÄHLT (Pflicht,
// mit Bestätigung).
// =========================================================================
package rdvmedecins.controllers;
import java.nio.charset.StandardCharsets;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import org.springframework.http.HttpHeaders;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.CookieValue;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.servlet.mvc.support.RedirectAttributes;
import org.springframework.web.util.UriUtils;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import jakarta.validation.Valid;
import rdvmedecins.auth.CaptchaService;
import rdvmedecins.auth.AttemptLimiterService;
import rdvmedecins.auth.RegistrationPassService;
import rdvmedecins.business.PersonData;
import rdvmedecins.business.BusinessException;
import rdvmedecins.models.Forms.RegistrationForm;
import rdvmedecins.models.ViewModels.RegistrationModel;
import rdvmedecins.models.ViewModels.Message;
import rdvmedecins.models.ViewModels.PersonValues;
import rdvmedecins.web.ApplicationModel;
import rdvmedecins.web.FlashMessage;
import rdvmedecins.web.Validation;
@Controller
@RequestMapping("/register")
public class RegistrationController {
private final ApplicationModel application;
private final CaptchaService captchaService;
private final AttemptLimiterService limiter;
private final RegistrationPassService passes;
public RegistrationController(ApplicationModel application, CaptchaService captchaService,
AttemptLimiterService limiter, RegistrationPassService passes) {
this.application = application;
this.captchaService = captchaService;
this.limiter = limiter;
this.passes = passes;
}
// -----------------------------------------------------------------------
// POST /register/access Felder: captchaId, captcha (die der
// Anmeldeseite; ebenfalls gesendeter Login und Passwort werden ignoriert)
// -----------------------------------------------------------------------
@PostMapping("/access")
public String access(@RequestParam(required = false) String captchaId,
@RequestParam(required = false) String captcha,
HttpServletRequest request, HttpServletResponse response, RedirectAttributes redirect) {
String ip = AuthController.ipAddress(request);
// zu viele kürzlich von dieser Adresse erstellte Konten: kein Grund weiterzumachen
long minutes = limiter.registrationBlockMinutes(ip);
if (minutes > 0) {
redirect.addFlashAttribute(FlashMessage.ATTRIBUTE,
FlashMessage.error("ERRORS.TOO_MANY_ACCOUNTS", Map.of("minutes", String.valueOf(minutes))));
return "redirect:/login";
}
// CAPTCHA fehlt oder ist falsch: zurück zur Anmeldeseite, mit
// einem neuen Bild (ein Fehlversuch zählt als Anmeldefehler)
if (!captchaService.verify(captchaId, captcha)) {
limiter.loginFailure(ip, "");
redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.error("ERRORS.CAPTCHA_BEFORE_ACCOUNT"));
return "redirect:/login";
}
// richtiges CAPTCHA: Wir stellen den Pass aus und öffnen das Formular
response.addHeader(HttpHeaders.SET_COOKIE, RegistrationPassService.cookie(passes.issue()).toString());
return "redirect:/register";
}
// -----------------------------------------------------------------------
// GET /register
// @CookieValue: der Wert des Cookies dieses Namens (null, wenn es fehlt)
// -----------------------------------------------------------------------
@GetMapping
public String form(@CookieValue(name = RegistrationPassService.COOKIE, required = false) String pass,
Model model, RedirectAttributes redirect) {
if (!passes.isValid(pass)) {
return backToLogin(redirect);
}
return show(model, PersonValues.empty(), Map.of(), null, null);
}
// -----------------------------------------------------------------------
// POST /register
// Der Parameter [form] wird von Spring MVC vor
// dem Aufruf gefüllt und VALIDIERT: Das Ergebnis der Validierung steht in [result].
// -----------------------------------------------------------------------
@PostMapping
public String create(@Valid RegistrationForm form, BindingResult result,
@CookieValue(name = RegistrationPassService.COOKIE, required = false) String pass,
HttpServletRequest request, HttpServletResponse response, Model model,
RedirectAttributes redirect) {
if (!passes.isValid(pass)) {
return backToLogin(redirect);
}
String ip = AuthController.ipAddress(request);
PersonValues values = new PersonValues(
form.getTitle() == null ? "Mr" : form.getTitle(),
form.getFirstName() == null ? "" : form.getFirstName(),
form.getLastName() == null ? "" : form.getLastName(),
form.getLogin() == null ? "" : form.getLogin(),
null);
// 1. zu viele kürzlich von dieser Adresse erstellte Konten?
long minutes = limiter.registrationBlockMinutes(ip);
if (minutes > 0) {
return show(model, values, Map.of(),
new Message("ERRORS.TOO_MANY_ACCOUNTS", Map.of("minutes", String.valueOf(minutes))), null);
}
// 2. alle Eingabefehler auf einmal (Felder + Bestätigung):
// Der Benutzer korrigiert sie alle in einem Zug
Map<String, String> errors = new HashMap<>(Validation.errorsOf(result));
if (!errors.containsKey("password") && !errors.containsKey("confirmation")
&& !form.getPassword().equals(form.getConfirmation())) {
errors.put("confirmation", "ERRORS.PASSWORDS_DIFFER");
}
if (!errors.isEmpty()) {
return show(model, values, errors, null, null);
}
// 3. die Erstellung (Client + USER-Konto, in einer Transaktion)
try {
application.addClient(new PersonData(form.getTitle(), form.getLastName(),
form.getFirstName(), form.getLogin(), form.getPassword(), null));
} catch (BusinessException e) {
// Login oder Vor- und Nachname bereits vergeben: Der Pass bleibt gültig
return show(model, values, Map.of(), Message.of(e.getKey()),
Validation.BUSINESS_ERROR_FIELDS.get(e.getKey()));
}
// 4. der Pass wurde verwendet: Er erlaubt nicht, ein 2. Konto zu erstellen
passes.consume(pass);
response.addHeader(HttpHeaders.SET_COOKIE, RegistrationPassService.clearedCookie().toString());
limiter.registrationSuccess(ip);
// 5. zurück zur Anmeldeseite, Login vorausgefüllt
redirect.addFlashAttribute(FlashMessage.ATTRIBUTE,
FlashMessage.success("REGISTRATION.DONE", Map.of("login", form.getLogin())));
return "redirect:/login?login=" + UriUtils.encodeQueryParam(form.getLogin(), StandardCharsets.UTF_8);
}
// ----------------------------------------------------------------- private Methoden
// kein gültiger Pass: zurück zur Anmeldeseite
private static String backToLogin(RedirectAttributes redirect) {
redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.error("ERRORS.CAPTCHA_BEFORE_ACCOUNT"));
return "redirect:/login";
}
// das Formular; nie ein an den Browser zurückgesendetes Passwort
private static String show(Model model, PersonValues values, Map<String, String> errors,
Message error, List<String> otherFields) {
model.addAttribute("model", new RegistrationModel("REGISTRATION.TITLE",
Validation.pageMessage(errors, error), values, Validation.state(errors, otherFields)));
return "registration";
}
}
|
Kommentieren wir diesen Code:
- Zeilen 14–24: Schutz vor Bots in vier Schritten. Das CAPTCHA und die Begrenzung der Versuche wurden in Beispiel 27 zusammen mit der Authentifizierung behandelt;
- Zeilen 66–81: Die Routen [/register...] sind in [SecurityConfig] ([permitAll()]) als öffentlich deklariert, und der Controller hat keine Annotationen ([@PreAuthorize]): Seine Seiten sind für alle offen. Er erhält vier Services per Injection;
- Zeilen 87–90: Die Schaltfläche „Patientenkonto erstellen“ auf der Anmeldeseite sendet das Anmeldeformular an diese Adresse (Attribut [formaction]; siehe Beispiel 21). Nur die CAPTCHA-Felder werden gelesen;
- Zeile 91: die IP-Adresse des Browsers, über eine statische Methode von [AuthController];
- Zeilen 94–99: Von dieser Adresse wurden in der letzten Stunde zu viele Konten angelegt: Weiterleitung zur Anmeldeseite, mit einer Pop-up-Meldung, die die Anzahl der Minuten bis zum nächsten Versuch angibt. [Map.of("minutes", ...)] erzeugt das Wörterbuch der Meldungsparameter;
- Zeilen 103–107: Ein fehlendes oder falsches CAPTCHA zählt als fehlgeschlagener Anmeldeversuch (mit leerem Benutzernamen): Ein Bot kann nicht unbegrenzt weiter probieren. Bei der Rückkehr zur Anmeldeseite wird ein neues Bild angezeigt;
- Zeilen 110–111: Das CAPTCHA ist korrekt: Ein Token (siehe [auth/RegistrationPassService.java]) wird über einen der Antwort hinzugefügten [Set-Cookie]-Header in einem Cookie gespeichert, und der Browser wird zum Formular weitergeleitet;
- Zeilen 118–125: das Formular, aber nur mit gültigem Token. Die direkte Eingabe der Adresse [/register] bewirkt nichts. [@CookieValue] bindet den Parameter [pass] an den Wert des gleichnamigen Cookies ([null] , wenn er fehlt, dank [required = false]);
- Zeilen 132–136: die Erstellung. Das Formular [RegistrationForm] (Ordner [models]) wurde von Spring MVC gebunden und validiert ([@Valid]), das Ergebnis liegt in [result];
- Zeilen 137–139: Das Token wird erneut geprüft: Die POST-Anfrage kann gesendet worden sein, ohne das Formular zu durchlaufen;
- Zeilen 141–146: die Werte, die im Fehlerfall erneut angezeigt werden, ohne das Passwort. Die Standardanrede ist [Mr];
- Zeilen 149–153: die Zeitbegrenzung, die zum Zeitpunkt der Erstellung erneut geprüft wird;
- Zeilen 157–164: Eingabefehler, Feld für Feld (siehe Beispiel 19). [Validation.errorsOf] fasst sie in einem Wörterbuch (Feld, Meldungsschlüssel) zusammen, das in eine [HashMap] kopiert wird, damit es ergänzt werden kann. Die Übereinstimmung von Passwort und Bestätigung – die zwei Felder betrifft – wird hier manuell geprüft; sie wird nur getestet, wenn diese beiden Felder ansonsten korrekt sind. Alle Fehler werden gemeinsam gemeldet: Der Benutzer korrigiert sie alle auf einmal;
- Zeilen 167–174: Erstellung des Clients und seines USER-Kontos mit der Methode der Geschäftsschicht, die auch ADMIN verwendet. Ist ein Benutzername oder eine Kombination aus Vor- und Nachname bereits vergeben, wird das Formular erneut angezeigt, wobei die betroffenen Felder rot hervorgehoben sind; das Token bleibt gültig;
- Zeilen 177–179: Das Token wurde verwendet: Es wird serverseitig verbraucht und sein Cookie gelöscht. Die Erstellung wird schließlich auf das Stundenlimit angerechnet;
- Zeilen 182–184: Rückkehr zur Anmeldeseite, mit vorausgefülltem Benutzernamen und einer Erfolgsmeldung. [UriUtils.encodeQueryParam] kodiert den Benutzernamen, damit er in eine URL eingefügt werden kann;
- Zeilen 190–193: ohne Pass Rückkehr zur Anmeldeseite mit einer Meldung;
- Zeilen 196–201: das Formular, das von [Validation] vorbereitet wird, ähnlich denen für Ärzte und Clients. Eine Methode mit dem Modifizierer [static] verwendet keine Felder des Objekts; sie kann ohne dieses aufgerufen werden.
11.16.7. controllers/PatientAreaController.java
| // =========================================================================
// controllers/PatientAreaController.java
// -------------------------------------------------------------------------
// Die PERSÖNLICHEN Seiten des Patienten (Rolle USER), die er direkt
// nach der Anmeldung sieht:
//
// GET /my-area Startseite: [Manage my account],
// [View a schedule] und sein bevorstehender Termin
// POST /my-area/cancel storniert SEINEN Termin
// GET /my-account Bearbeitungsformular seines Kontos
// POST /my-account Bearbeitung
// POST /my-account/delete Löschung des Kontos (und seiner Termine)
//
// Goldene Regel dieses Controllers: Der betroffene Patient ist IMMER der des
// Tokens (Utils.connectedPatient), nie eine vom
// Browser gesendete Kennung. Ein Patient kann daher weder sehen noch bearbeiten noch stornieren, was
// einem anderen Patienten gehört, auch nicht, indem er seine Anfragen selbst baut.
//
// Jede Änderung oder Löschung des Kontos erfordert das AKTUELLE
// Passwort: Jemand, der eine offen gelassene Sitzung gefunden hat, könnte
// weder das Passwort ändern noch das Konto löschen. Fehler beim aktuellen Passwort
// werden als Anmeldefehler gezählt (gleiche Grenze).
// =========================================================================
package rdvmedecins.controllers;
import java.util.HashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Optional;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.servlet.mvc.support.RedirectAttributes;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import jakarta.validation.Valid;
import rdvmedecins.auth.AuthService;
import rdvmedecins.auth.AttemptLimiterService;
import rdvmedecins.entities.Client;
import rdvmedecins.entities.Appointment;
import rdvmedecins.business.PersonData;
import rdvmedecins.business.BusinessException;
import rdvmedecins.models.Forms.MyAccountForm;
import rdvmedecins.models.ViewModels.AreaModel;
import rdvmedecins.models.ViewModels.Message;
import rdvmedecins.models.ViewModels.MyAccountModel;
import rdvmedecins.models.ViewModels.AppointmentView;
import rdvmedecins.models.ViewModels.PersonValues;
import rdvmedecins.web.ApplicationModel;
import rdvmedecins.web.FlashMessage;
import rdvmedecins.web.Utils;
import rdvmedecins.web.Validation;
@Controller
@PreAuthorize("hasRole('USER')")
public class PatientAreaController {
private final ApplicationModel application;
private final AuthService authService;
private final AttemptLimiterService limiter;
public PatientAreaController(ApplicationModel application, AuthService authService,
AttemptLimiterService limiter) {
this.application = application;
this.authService = authService;
this.limiter = limiter;
}
// -----------------------------------------------------------------------
// GET /my-area
// -----------------------------------------------------------------------
@GetMapping("/my-area")
public String area(@AuthenticationPrincipal Jwt token, Locale locale, Model model) {
Client patient = patient(token);
List<AppointmentView> appointments = application.getClientUpcomingAppointments(patient.getId()).stream()
.map(a -> new AppointmentView(
a.getId(),
Utils.formatDay(a.getDay(), locale),
Utils.time(a.getSlot()),
Utils.label(a.getSlot().getDoctor()),
// Link zum Terminkalender des Arztes an diesem Tag: Der Patient sieht dort seinen Namen
"/schedule?doctorId=" + a.getSlot().getDoctorId() + "&day=" + Utils.iso(a.getDay())))
.toList();
model.addAttribute("model", new AreaModel("AREA.TITLE", null, Utils.label(patient), appointments));
return "area";
}
// -----------------------------------------------------------------------
// POST /my-area/cancel Feld: appointmentId
// -----------------------------------------------------------------------
@PostMapping("/my-area/cancel")
public String cancelAppointment(@RequestParam(required = false) String appointmentId, @AuthenticationPrincipal Jwt token,
RedirectAttributes redirect) {
Client patient = patient(token);
Integer id = Utils.positiveInteger(appointmentId);
Optional<Appointment> appointment = id == null ? Optional.empty() : application.getAppointmentById(id);
// ein nicht existierender Termin und der eines ANDEREN Patienten erhalten
// dieselbe Antwort: Wir verraten nichts über die Termine der anderen
if (appointment.isEmpty() || !appointment.get().getClientId().equals(patient.getId())) {
redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.error("ERRORS.APPOINTMENT_NOT_FOUND"));
} else {
application.deleteAppointment(appointment.get());
redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.success("SCHEDULE.CANCELLED"));
}
return "redirect:/my-area";
}
// -----------------------------------------------------------------------
// GET /my-account
// -----------------------------------------------------------------------
@GetMapping("/my-account")
public String accountForm(@AuthenticationPrincipal Jwt token, Model model) {
Client patient = patient(token);
PersonValues values = new PersonValues(patient.getTitle(), patient.getFirstName(), patient.getLastName(),
patient.getUser().getLogin(), patient.getVersion());
return show(model, values, Map.of(), null, null);
}
// -----------------------------------------------------------------------
// POST /my-account
// -----------------------------------------------------------------------
@PostMapping("/my-account")
public String editAccount(@Valid MyAccountForm form, BindingResult result,
@AuthenticationPrincipal Jwt token, HttpServletRequest request, HttpServletResponse response,
Model model, RedirectAttributes redirect) {
Client patient = patient(token);
PersonValues values = new PersonValues(
form.getTitle() == null ? patient.getTitle() : form.getTitle(),
form.getFirstName() == null ? "" : form.getFirstName(),
form.getLastName() == null ? "" : form.getLastName(),
form.getLogin() == null ? "" : form.getLogin(),
form.getVersion());
Map<String, String> errors = new HashMap<>(Validation.errorsOf(result));
if (!errors.containsKey("password") && form.getPassword() != null
&& !form.getPassword().equals(form.getConfirmation())) {
errors.put("confirmation", "ERRORS.PASSWORDS_DIFFER");
}
if (!errors.isEmpty()) {
return show(model, values, errors, null, null);
}
// das aktuelle Passwort
Message passwordError = checkCurrentPassword(request, patient, form.getCurrentPassword());
if (passwordError != null) {
// falsches Passwort: Die Nachricht steht auch UNTER dem Feld
Map<String, String> fieldErrors = passwordError.key().equals("ERRORS.WRONG_CURRENT_PASSWORD")
? Map.of("currentPassword", passwordError.key())
: Map.of();
return show(model, values, fieldErrors, passwordError, null);
}
try {
Client client = application.editClient(patient.getId(), new PersonData(form.getTitle(),
form.getLastName(), form.getFirstName(), form.getLogin(),
form.getPassword(), // null = unverändert
form.getVersion()));
// Login und Anzeigename stehen IM Token: Wir stellen ein
// neues aus, sonst würde die Navigationsleiste den alten Namen behalten
authService.setToken(response, client.getUser());
redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.success("MY_ACCOUNT.UPDATED"));
return "redirect:/my-area";
} catch (BusinessException e) {
return show(model, values, Map.of(), Message.of(e.getKey()),
Validation.BUSINESS_ERROR_FIELDS.get(e.getKey()));
}
}
// -----------------------------------------------------------------------
// POST /my-account/delete Feld: deletePassword
// Das Konto, der Client und ALLE seine Termine verschwinden gemeinsam,
// dann wird der Patient abgemeldet.
// -----------------------------------------------------------------------
@PostMapping("/my-account/delete")
public String deleteAccount(@RequestParam(required = false) String deletePassword,
@AuthenticationPrincipal Jwt token, HttpServletRequest request, HttpServletResponse response,
RedirectAttributes redirect) {
Client patient = patient(token);
Message passwordError = checkCurrentPassword(request, patient, deletePassword);
if (passwordError != null) {
redirect.addFlashAttribute(FlashMessage.ATTRIBUTE,
FlashMessage.error(passwordError.key(), passwordError.params()));
return "redirect:/my-account";
}
application.deleteClient(patient.getId());
AuthService.clearToken(response);
redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.success("MY_ACCOUNT.DELETED"));
return "redirect:/login";
}
// ----------------------------------------------------------------- private Methoden
// der Patient des Tokens
private Client patient(Jwt token) {
return Utils.connectedPatient(application, Utils.user(token));
}
// null, wenn das aktuelle Passwort korrekt ist; sonst die Fehlermeldung
private Message checkCurrentPassword(HttpServletRequest request, Client patient, String password) {
String ip = AuthController.ipAddress(request);
String login = patient.getUser().getLogin();
long minutes = limiter.loginBlockMinutes(ip, login);
if (minutes > 0) {
return new Message("ERRORS.TOO_MANY_ATTEMPTS", Map.of("minutes", String.valueOf(minutes)));
}
boolean ok = password != null && !password.isEmpty()
&& authService.validateUser(login, password).isPresent();
if (!ok) {
limiter.loginFailure(ip, login);
return Message.of("ERRORS.WRONG_CURRENT_PASSWORD");
}
return null;
}
private static String show(Model model, PersonValues values, Map<String, String> errors,
Message error, List<String> otherFields) {
model.addAttribute("model", new MyAccountModel("MY_ACCOUNT.TITLE",
Validation.pageMessage(errors, error), values, Validation.state(errors, otherFields)));
return "account";
}
}
|
Sehen wir uns diesen Code im Einzelnen an:
- Zeilen 14–17: die goldene Regel dieses Controllers: Der betreffende Patient ist immer derjenige, der dem Token zugeordnet ist, niemals eine vom Browser gesendete Kennung;
- Zeilen 63–65: Patienten vorbehalten. Hier gilt [@PreAuthorize] an der Klasse für alle Actions, da sie alle in dieser Klasse deklariert sind. Der Controller hat keine [@RequestMapping]-Annotation: Jede Action gibt ihre vollständige URL an, da sie kein gemeinsames Präfix haben ([/my-area], [/my-account]);
- Zeilen 81–95: die Seite „Mein Bereich“. Die Methode [patient] (weiter unten) identifiziert den Client anhand des Tokens; wurde das Konto des Clients seit der Anmeldung gelöscht, löst sie eine [InvalidSessionException] aus, die [web/HtmlExceptionHandler.java] behandelt, indem sie den Benutzer zur Anmeldeseite zurückleitet. Das Datum wird von [Utils.formatDay] in der Sprache der Anfrage formatiert (siehe Beispiel 22); jeder Termin enthält einen Link zum Terminkalender des Arztes für diesen Tag (Zeile 91);
- Zeilen 100–115: Stornierung des Termins des Patienten. In Zeile 105 liefert eine ungültige Kennung ein leeres [Optional] ([Optional.empty()]). Ein nicht existierender Termin und der eines anderen Patienten (Zeile 108) erhalten dieselbe Antwort: Über die Termine anderer Patienten werden keine Informationen preisgegeben;
- Zeilen 120–126: das Kontoformular, vorausgefüllt mit der Versionsnummer (optimistisches Sperren);
- Zeilen 131–134: der Ablauf der Änderung in drei Schritten: Validierung, Prüfung des aktuellen Passworts, Geschäftsschicht;
- Zeilen 136–141: die Werte, die im Fehlerfall erneut angezeigt werden – niemals Passwörter;
- Zeilen 143–150: Eingabefehler. Das neue Passwort ist optional (leer: unverändert); seine Bestätigung wird nur geprüft, wenn sie eingegeben wurde;
- Zeilen 153–160: das aktuelle Passwort. Ein falsches Passwort wird unter seinem Feld und am Seitenende angezeigt; eine Sperre (zu viele Versuche) wird nur am Seitenende angezeigt, zusammen mit der Anzahl der Minuten;
- Zeilen 162–168: Änderung durch die Geschäftsschicht, die dieselben Regeln wie für ADMIN anwendet (Eindeutigkeit, optimistisches Sperren);
- Zeile 169: Das Token enthält den Benutzernamen und den Anzeigenamen: Nach einer Änderung wird ein neues Token ausgestellt; andernfalls würde die Navigationsleiste den alten Namen behalten;
- Zeilen 172–175: Wird die Änderung von der Geschäftsschicht abgelehnt, wird das Formular neu geladen, wobei die betroffenen Felder rot hervorgehoben sind;
- Zeilen 183–193: Auch das Löschen des Kontos erfordert das aktuelle Passwort. Ein Fehler wird durch eine Pop-up-Meldung auf der Kontoseite angezeigt (PRG);
- Zeilen 194–197: Löschung der Akte, des Kontos und aller Termine (die von ADMIN verwendete Methode der Geschäftsschicht), gefolgt von der Abmeldung: Das Token-Cookie wird gelöscht;
- Zeilen 203–205: der Patient des Tokens;
- Zeilen 208–222: Prüfung des aktuellen Passworts. Die Methode liefert [null] , wenn das Passwort korrekt ist; andernfalls eine Fehlermeldung (eine [Message]: Schlüssel und Parameter). Für das aktuelle Passwort gelten dieselben Beschränkungen wie für die Anmeldung (siehe Beispiel 27): Wer eine offen gebliebene Sitzung vorfindet, kann weder das Passwort ändern noch das Konto löschen noch unbegrenzt Passwörter erraten. Die Prüfung selbst übernimmt [AuthService]; ein Fehlschlag wird als fehlgeschlagene Anmeldung gezählt;
- Zeilen 224–229: das Kontoformular.
11.16.8. controllers/ErrorController.java
| // =========================================================================
// controllers/ErrorController.java
// -------------------------------------------------------------------------
// Die Fehlerseite (400, 403, 404, 405, 500...).
//
// Man gelangt nie über einen Link hierher. Wenn eine Anfrage mit einem Fehler endet
// - eine unbehandelte Ausnahme, ein response.sendError(403), eine
// ResponseStatusException(NOT_FOUND)... -, LEITET der Server (Tomcat) die
// Anfrage an die Adresse /error WEITER, um die Seite aufzubauen, die anstelle
// einer leeren Antwort oder eines Stacktraces zurückgegeben wird (siehe Beispiel 24). Er speichert
// dabei den Fehlercode in einem Attribut der Anfrage.
//
// Spring Boot stellt bereits einen /error-Controller bereit (BasicErrorController, die
// "Whitelabel Error Page"); er tritt zurück, sobald eine Bean das Interface
// ErrorController implementiert, wie diese hier.
//
// @RequestMapping ohne HTTP-Methode: Die Aktion akzeptiert alle Methoden -
// die weitergeleitete Anfrage behält ihre ursprüngliche Methode (ein abgelehnter POST bleibt ein POST).
// =========================================================================
package rdvmedecins.controllers;
import java.util.Map;
// (Das Interface ErrorController von Spring Boot hat den Namen unserer Klasse: unten vollständig ausgeschrieben)
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.RequestMapping;
import jakarta.servlet.RequestDispatcher;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import rdvmedecins.models.ViewModels.ErrorModel;
@Controller
public class ErrorController implements org.springframework.boot.webmvc.error.ErrorController {
private static final Map<Integer, String> MESSAGES = Map.of(
HttpServletResponse.SC_BAD_REQUEST, "ERRORS.BAD_REQUEST",
HttpServletResponse.SC_FORBIDDEN, "ERRORS.FORBIDDEN",
HttpServletResponse.SC_NOT_FOUND, "ERRORS.NOT_FOUND");
@RequestMapping("/error")
public String show(HttpServletRequest request, HttpServletResponse response, Model model) {
// der ursprüngliche Fehlercode, vom Server in der Anfrage gespeichert
Object status = request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE);
int code = status instanceof Integer c ? c : HttpServletResponse.SC_INTERNAL_SERVER_ERROR;
// die Seite behält diesen Code (404 bleibt 404...); ein unerwarteter Code
// (oder ein direkter Aufruf von /error) wird zu einem Fehler 500
if (code < 400 || code > 599) {
code = HttpServletResponse.SC_INTERNAL_SERVER_ERROR;
}
response.setStatus(code);
model.addAttribute("model", new ErrorModel("ERROR_PAGE.TITLE", null, code,
MESSAGES.getOrDefault(code, "ERRORS.SERVER_ERROR")));
return "error";
}
}
|
Dies ist der Controller aus Beispiel 24, mit übersetzten Meldungen:
- Zeilen 6–11: Diese Seite erreicht man nie über einen Link. Endet eine Anfrage mit einem Fehler (eine nicht behandelte Ausnahme, eine [ResponseStatusException], ein [response.sendError(403)] aus dem Ablehnungs-Handler von [Spring Security] ...), leitet der [Tomcat]-Server die Anfrage an die Adresse [/error] weiter, um die zurückzugebende Seite zu erzeugen, anstelle einer leeren Antwort oder eines Aufrufstapels;
- Zeilen 13–15 und Zeilen 34–35: [Spring Boot] stellt bereits einen Controller bereit, [/error] ([BasicErrorController]), der die „Whitelabel Error Page“ erzeugt. Er wird entfernt, sobald eine Bean das Interface [ErrorController] implementiert (importiert in Zeile 24), wie es hier der Fall ist;
- Zeilen 37–40: der Meldungsschlüssel für jeden Fehlercode. [static final]: ein einziges Wörterbuch, das beim Laden der Klasse erstellt und nie ersetzt wird; [Map.of] macht es außerdem schreibgeschützt;
- Zeile 42: [@RequestMapping], das keine HTTP-Methode angibt, akzeptiert alle Methoden: Eine POST-Anfrage, die an [/error] weitergereicht wird (zum Beispiel wenn ein Patient eine Stornierung versucht, die Administratoren vorbehalten ist), bleibt eine POST-Anfrage;
- Zeilen 45–46: der ursprüngliche Fehlercode, den der Server in einem Anfrageattribut mit dem Namen [RequestDispatcher.ERROR_STATUS_CODE] abgelegt hat. Das Attribut hat den Typ [Object]: [status instanceof Integer c] prüft, ob es tatsächlich ein [Integer] ist, und speichert es in diesem Fall in der Variablen [c]. Andernfalls (von Hand eingegebene Adresse [/error]) lautet der Code 500;
- Zeilen 49–51: Ein HTTP-Code, der kein Fehlercode ist, wird in einen 500-Fehler umgewandelt;
- Zeile 52: Die Seite behält den ursprünglichen Fehlercode bei (eine unbekannte Seite bleibt eine 404-Antwort);
- Zeilen 53–55: das Seitenmodell und der Name seiner View. [getOrDefault] liefert den dem Code zugeordneten Schlüssel oder [ERRORS.SERVER_ERROR] für jeden anderen Code (insbesondere 500).
11.17. Views
Die Views werden mit [Thymeleaf] geschrieben (siehe Beispiele 13 bis 16). Rufen wir uns das Konzept in Erinnerung: Eine View ist eine echte HTML-Datei, angereichert mit [th:...]-Attributen, die [Thymeleaf] bei der Erzeugung der Seite ersetzt. Wird eine Datei direkt in einem Browser geöffnet, ohne Server, wird sie dennoch mit ihrem Beispieltext angezeigt („Mme Alice DURAND“, „8:00 – 8:20“): Man spricht dann von „natürlichen Templates“. Die in der Fallstudie verwendeten Attribute sind die aus den Beispielen:
Attribut oder Ausdruck | Funktion |
[th:text="${model.day}"] | ersetzt den Inhalt des Elements durch den Wert, maskiert ([<] wird zu [<]) |
[th:utext] | Wie oben, jedoch ohne Maskierung (nur für das CAPTCHA-Bild) |
[#{SCHEDULE.FREE}] | Eine übersetzte Meldung (siehe Beispiel 22) |
[#{BOOKING_DIALOG.SLOT('time', ${r.time})}] | eine Meldung mit einem Parameter [{time}] |
[#{${error.key}(${error.params})}] | eine Meldung, deren Schlüssel selbst ein Wert ist, mit einem Wörterbuch von Parametern |
[th:if], [th:unless] | das Element wird nur geschrieben, wenn die Bedingung wahr (falsch) ist |
[th:each="row : ${rows}"] | das Element wird für jedes Element der Liste wiederholt |
[th:value], [th:href], [th:action] | ein berechnetes Attribut |
[th:selected], [th:autofocus] | ein boolesches Attribut: wird geschrieben, wenn der Wert wahr ist, andernfalls weggelassen |
[th:classappend] | fügt den Klassen des Attributs [class] eine CSS-Klasse hinzu |
[th:attr="data-confirmation=#{...}"] | ein beliebiges Attribut, berechnet |
[th:with="state=${model.state}"] | eine lokale Variable des Elements |
[th:replace="~{fragments/flash :: flash}"] | ersetzt das Element durch ein Fragment (siehe Beispiel 15) |
[<th:block>] | ein Tag, das keine Spur auf der erzeugten Seite hinterlässt |
[<!--/* ... */-->] | ein Kommentar, der aus der erzeugten Seite entfernt wird |
Die Views müssen fast keine Entscheidungen treffen: Ihr Modell wurde von den Controllern im Abschnitt [record] der Datei [models/ViewModels.java] vorbereitet (welche Schaltflächen anzuzeigen sind, welche URL, welche Übersetzungsschlüssel). Jede View beginnt mit einem Kommentar [<!--/* ... */-->] , der ihre Aufgabe beschreibt; diese Kommentare erscheinen nicht in den an den Browser gesendeten Seiten. Anders als [Razor] kennt [Thymeleaf] den Typ des Modells nicht: Ein Tippfehler in [${model.dayy}] wird nicht zur Kompilierzeit erkannt, sondern erst beim Rendern der Seite und führt zu einer Ausnahme (und damit zu einem 500-Fehler).
Alle Views haben Zugriff auf dieselben Variablen: [model], das vom Controller abgelegte Seitenmodell; [user], [language] und [path] (der angemeldete Benutzer oder [null], die Sprache der Anfrage, der Pfad der angeforderten URL), die dem Modell aller Actions durch die [@ModelAttribute]-Methode von [web/CommonModel.java] hinzugefügt werden; und [flash], etwaige Flash-Meldungen: Nach einer Weiterleitung legt Spring MVC die Flash-Attribute automatisch im Modell der nächsten Anfrage ab.
11.17.1. Das Layout-Template und die Fragmente
11.17.1.1. templates/layout.html
| <!doctype html>
<!--/* =========================================================================
templates/layout.html
-------------------------------------------------------------------------
Das für alle Seiten GEMEINSAME Layout (siehe Beispiel 15): ein Fragment
[page], dessen Parameter [content] der <main>-Block der vom Controller
angeforderten Seite ist (schedule.html, login.html...).
Thymeleaf MASKIERT alles, was es mit th:text anzeigt (die Zeichen
< > & " ' werden zu < >...): Schutz vor HTML-Injection
zum Beispiel durch einen eingegebenen Namen. Um HTML unverändert einzufügen, muss
dies ausdrücklich angefordert werden (th:utext, siehe fragments/captcha.html).
Meldungen: Ein Erfolg wird am ANFANG der Seite angezeigt (Fragment flash), ein
Fehler am ENDE, auf hellrosa Hintergrund (Fragment errors).
Das Layout teilt die Variablen der Seite: [model] (das vom Controller
übergebene View-Modell, siehe models/ViewModels.java), aus dem es den
Titel der Seite liest; [language], [user], [path], die allen
Views von web/CommonModel.java hinzugefügt werden; [flash], die eventuelle Flash-Nachricht.
========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:lang="${language}" th:fragment="page(content)">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<!--/* #{${key}}: die Nachricht, deren Schlüssel der WERT des Ausdrucks ${key} ist */-->
<title th:text="|#{${model.pageTitle}} - #{APP.TITLE}|">RdvMedecins</title>
<link rel="stylesheet" href="/lib/bootstrap/css/bootstrap.min.css">
<link rel="stylesheet" href="/css/styles.css">
</head>
<body>
<div class="container py-4">
<nav th:replace="~{fragments/navbar :: navbar}"></nav>
<div th:replace="~{fragments/flash :: flash}"></div>
<main th:replace="${content}"></main>
<div th:replace="~{fragments/errors :: errors}"></div>
</div>
<!--/* der Dialog "Are you sure?", versteckt, solange er nicht gebraucht wird */-->
<div th:replace="~{fragments/confirmation :: confirmation}"></div>
<script src="/js/app.js"></script>
</body>
</html>
|
Dies ist das Template aus Beispiel 15. Jede Seite der Anwendung beginnt mit [<html th:replace="~{layout :: page(~{::main})}">]: Sie wird ersetzt durch das Fragment [page] dieses Templates, dem sie ihr eigenes Element [<main>] übergibt.
- Zeilen 2–21: ein Kommentar von [Thymeleaf]: [<!--/*] und [*/-->] schließen Text ein, den [Thymeleaf] aus der erzeugten Seite entfernt. Ein Browser, der die Datei ohne Server öffnet, sieht darin einen gewöhnlichen HTML-Kommentar;
- Zeile 22: [th:fragment="page(content)"] macht das gesamte Element [<html>] zu einem Fragment mit dem Namen [page], das einen Parameter [content] erhält. [th:lang] schreibt das Attribut [lang] der Seite: die Sprache der Anfrage ([fr] oder [en]);
- Zeile 27: der übersetzte Titel, zum Beispiel „Terminkalender - RdvMedecins“. Die senkrechten Striche [|...|] begrenzen eine Literalsubstitution: einen Text, in dem Ausdrücke durch ihre Werte ersetzt werden. [#{${model.pageTitle}}] ist die Meldung, deren Schlüssel der Wert von [${model.pageTitle}] ist: Dieser Titel wird vom Controller im Modell jeder Seite geliefert (in Beispiel 15 hat die Seite ihn als Fragmentparameter übergeben);
- Zeilen 28–29: die Stylesheets, die von [Spring Boot] aus dem Ordner [src/main/resources/static] ausgeliefert werden: [Bootstrap] ([static/lib/bootstrap]) und das anwendungsspezifische Stylesheet;
- Zeilen 33–36: die Navigationsleiste, die Erfolgsmeldung (oben), das Element [<main>] der angeforderten Seite ([th:replace="${content}"]: Das Element wird durch das als Parameter erhaltene Fragment ersetzt) und der Fehlerbereich (unten);
- Zeilen 39–40: das Bestätigungsfenster (ausgeblendet) und sein Skript (siehe Beispiel 21), das am Seitenende geladen wird.
Der Anfang der Anmeldeseite, wie ihn der Browser empfängt:
| curl -i http://localhost:8081/login
|
| HTTP/1.1 200
Content-Type: text/html;charset=UTF-8
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Login - RdvMedecins</title>
<link rel="stylesheet" href="/lib/bootstrap/css/bootstrap.min.css">
...
|
Die Kommentare [<!--/* ... */-->] sind verschwunden und haben nur leere Zeilen hinterlassen; auch die Attribute [th:...] sind verschwunden.
11.17.1.2. templates/fragments/navbar.html
| <!--/* =========================================================================
templates/fragments/navbar.html - die Navigationsleiste.
Titel, FR/EN, Rolle, Name, Abmelden - und ein Menü, dessen Einträge
von der Rolle abhängen: "Doctors" und "Patients" erscheinen nur für
den ADMIN. Das ist nur eine Anzeigeerleichterung: Der eigentliche Schutz ist
das @PreAuthorize der Controller (ein USER, der /doctors von Hand eingibt,
erhält eine Seite 403). Ein Patient (USER) hat außerdem sein Menü "Mein Bereich".
Das Menü der aktuellen Seite wird hervorgehoben (Klasse "active"):
[path] ist die angeforderte URL (siehe web/CommonModel.java).
========================================================================= */-->
<nav xmlns:th="http://www.thymeleaf.org" th:fragment="navbar"
class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
<span class="navbar-brand mb-0" th:text="#{APP.TITLE}">RdvMedecins</span>
<ul class="navbar-nav me-auto" th:if="${user != null}">
<li class="nav-item" th:if="${user.isPatient()}">
<a class="nav-link" th:classappend="${#strings.startsWith(path, '/my-')} ? 'active'"
href="/my-area" th:text="#{APP.MENU_MY_AREA}">My area</a>
</li>
<li class="nav-item">
<a class="nav-link" th:classappend="${#strings.startsWith(path, '/schedule')} ? 'active'"
href="/schedule" th:text="#{APP.MENU_SCHEDULE}">Schedule</a>
</li>
<!--/* th:block: ein Thymeleaf-Tag, das keine Spur im HTML hinterlässt */-->
<th:block th:if="${user.isAdmin()}">
<li class="nav-item">
<a class="nav-link" th:classappend="${#strings.startsWith(path, '/doctors')} ? 'active'"
href="/doctors" th:text="#{APP.MENU_DOCTORS}">Doctors</a>
</li>
<li class="nav-item">
<a class="nav-link" th:classappend="${#strings.startsWith(path, '/clients')} ? 'active'"
href="/clients" th:text="#{APP.MENU_PATIENTS}">Patients</a>
</li>
</th:block>
</ul>
<div class="me-auto" th:if="${user == null}"></div>
<div class="d-flex align-items-center gap-2">
<!--/* FR / EN: einfache Links (GET /language/fr), die aktive Sprache hervorgehoben */-->
<div class="btn-group btn-group-sm" role="group" aria-label="FR / EN">
<a class="btn" th:classappend="${language == 'fr'} ? 'btn-light' : 'btn-outline-light'" href="/language/fr">FR</a>
<a class="btn" th:classappend="${language == 'en'} ? 'btn-light' : 'btn-outline-light'" href="/language/en">EN</a>
</div>
<th:block th:if="${user != null}">
<span class="badge text-bg-light text-primary" th:text="${user.role}">ADMIN</span>
<span class="text-white" th:text="${user.name}">name</span>
<!--/* logout ist ein POST: ein auf seine Schaltfläche reduziertes Formular */-->
<form method="post" action="/logout" class="m-0">
<button type="submit" class="btn btn-sm btn-outline-light" th:text="#{APP.LOGOUT}">Log out</button>
</form>
</th:block>
</div>
</nav>
|
- Zeilen 13–14: das Fragment [navbar], das vom Template eingefügt wird;
- Zeile 17: Das Menü wird nur einem angemeldeten Benutzer angezeigt. Auf der Anmeldeseite ist [user] auf [null] gesetzt;
- Zeilen 18–21: „Mein Bereich“, nur für Patienten. [user.isPatient()] ruft eine Methode von [record] [ConnectedUser] auf: Ausdrücke in [Thymeleaf] können Methoden aufrufen;
- Zeile 19: Das Menü der aktuellen Seite wird hervorgehoben (Klasse [active]). [#strings.startsWith] ist eine Funktion des Hilfsobjekts [#strings] von [Thymeleaf] (siehe Beispiel 14). [condition ? 'active'], ergibt ohne „else“-Zweig [null] , wenn die Bedingung falsch ist, und [th:classappend] fügt dann nichts hinzu;
- Zeilen 27–36: „Ärzte“ und „Patienten“, nur für ADMIN. [th:block] fasst die beiden Elemente unter einer einzigen Bedingung zusammen, ohne Tags auf der Seite zu hinterlassen. Dies ist lediglich eine Anzeigeerleichterung: Der eigentliche Schutz kommt von den [@PreAuthorize] der Controller (ein USER, der von Hand [/doctors] eingibt, erhält eine 403-Seite, wie wir gesehen haben);
- Zeile 38: Wenn kein Benutzer angemeldet ist, schiebt ein leeres Element die Schaltflächen FR / EN an den rechten Rand der Leiste, so wie es das Menü tut;
- Zeilen 43–44: Die Schaltflächen FR / EN sind einfach Links zu [/language/fr] and [/language/en]; die der aktiven Sprache wird hervorgehoben ([btn-light]). Hier hat der bedingte Ausdruck beide Zweige;
- Zeilen 48–49: die Rolle und der Name des Benutzers, aus dem Token gelesen;
- Zeilen 51–53: Die Abmeldung ist eine POST-Anfrage (siehe Beispiel 25), die von [Spring Security] verarbeitet wird (siehe [SecurityConfig]): ein Formular, das auf eine einzige Schaltfläche reduziert ist. Ein einfacher Link (GET), der auf einer anderen Website platziert wäre, könnte den Benutzer nicht ohne dessen Wissen abmelden.
11.17.1.3. templates/fragments/flash.html
| <!--/* =========================================================================
templates/fragments/flash.html - die ERFOLGSMELDUNG der vorherigen
Action (Termin gespeichert, Arzt hinzugefügt...), die nur
einmal am Seitenanfang angezeigt wird (siehe web/CookieFlashMapManager.java).
Eine FEHLER-Flash-Nachricht wird am Seitenende von
fragments/errors.html angezeigt.
#{${flash.key}(${flash.params})}: die Meldung, deren Schlüssel
flash.key ist, mit dem Dictionary der Werte von {name},
{login}... als Parameter (siehe web/Translator.java).
========================================================================= */-->
<div xmlns:th="http://www.thymeleaf.org" th:fragment="flash"
th:if="${flash != null and flash.successful()}" class="alert alert-success" role="status"
th:text="#{${flash.key}(${flash.params})}">message</div>
|
- Zeilen 12–14: die Erfolgsmeldung, die von der vorherigen Action vor einer Weiterleitung angezeigt wird. [flash] ist eine [FlashMessage] (siehe [web/FlashMessage.java]): ein Typ (Erfolg oder Fehler), ein Übersetzungsschlüssel und Parameter. Dieses Fragment zeigt nur Erfolgsmeldungen an; Fehler werden vom folgenden Fragment am Seitenende angezeigt. [role="status"] veranlasst Screenreader, die Meldung vorzulesen;
- Zeile 14: [#{${flash.key}(${flash.params})}]: die Meldung mit dem Schlüssel [flash.key], wobei das Wörterbuch [flash.params] ihre Parameter liefert (die Werte von [{name}], [{login}] ...). Der Service [Translator] (siehe „Die Web-Schicht: gemeinsame Services“) ersetzt diese Parameter im Text.
11.17.1.4. templates/fragments/errors.html
| <!--/* =========================================================================
templates/fragments/errors.html - die Fehlerzone am ENDE jeder
Seite, auf hellrosa Hintergrund (Klasse .error-zone, siehe static/css/styles.css).
Sie vereint die beiden möglichen Fehlerquellen:
- model.error: der Fehler der angezeigten Seite (abgelehntes Formular, bereits
verwendeter Login oder Vor- + Nachname, ungültiges Datum, falsches Passwort...);
- eine Fehler-Flash-Nachricht, die von der vorherigen Action vor einer
Umleitung abgelegt wurde (Zeitfenster bereits gebucht, Löschen abgelehnt...).
th:with definiert für das Element lokale Variablen. Es steht auf einem
UMSCHLIESSENDEN th:block: Auf demselben Element wertet Thymeleaf th:if VOR
th:with aus, und die Variablen würden noch nicht existieren. role="alert": ein
Screenreader kündigt die Meldung an, sobald die Seite angezeigt wird, auch wenn sie
am Seitenende steht.
========================================================================= */-->
<th:block xmlns:th="http://www.thymeleaf.org" th:fragment="errors"
th:with="error=${model.error}, flashError=${flash != null and !flash.successful()} ? ${flash}">
<div th:if="${error != null or flashError != null}" class="error-zone" role="alert">
<div th:if="${error != null}" th:text="#{${error.key}(${error.params})}">page error</div>
<div th:if="${flashError != null}" th:text="#{${flashError.key}(${flashError.params})}">flash error</div>
</div>
</th:block>
|
- Zeilen 5–9: Der Fehlerbereich fasst die beiden möglichen Fehlerquellen zusammen: den Seitenfehler ([model.error]) und eine Flash-Fehlermeldung;
- Zeilen 17–18: [th:with] definiert zwei lokale Variablen. [error] ist der Seitenfehler; [flashError] ist die Flash-Meldung, wenn es sich um einen Fehler handelt, andernfalls [null] (ein bedingter Ausdruck ohne „else“-Zweig, wie in der Navigationsleiste). Diese Variablen werden an einem
***[th:block] definiert, der *das Element umschließt, das sie verwendet. Man kann [th:with] und ***[th:if] nicht am selben Element schreiben: [Thymeleaf]* verarbeitet die Attribute eines Elements in einer festen Reihenfolge, die nicht von der Reihenfolge abhängt, in der sie geschrieben sind, und [th:if] wird vor [th:with]** ausgewertet. Die Bedingung würde Variablen verwenden, die noch nicht existieren;
- Zeile 19: Das Feld wird nur geschrieben, wenn mindestens eine Meldung vorliegt. [role="alert"]: Ein Screenreader liest die Meldung vor, sobald die Seite angezeigt wird, auch wenn sie sich am Seitenende befindet;
- Zeilen 20–21: beide Meldungen, übersetzt zusammen mit ihren Parametern.
Für einen Terminkalender, der mit einem ungültigen Datum angefordert wurde ([day=2026-02-30]), enthält das Seitenende beispielsweise:
| <div class="error-zone" role="alert">
<div>The requested date is not valid.</div>
</div>
|
11.17.1.5. templates/fragments/confirmation.html
| <!--/* =========================================================================
templates/fragments/confirmation.html - der modale Dialog "Are you sure?".
Er ersetzt das Fenster window.confirm() des Browsers, das sich weder
gestalten noch übersetzen lässt (seine Schaltflächen bleiben in der Sprache des
Browsers, nicht in der der Seite).
EIN EINZIGER Dialog für die gesamte Seite, anfangs versteckt (d-none). Seine
Beschriftungen werden hier vom Server übersetzt, wie der Rest der Seite;
das kleine Skript static/js/app.js zeigt ihn nur an, setzt die
für das Formular spezifische Meldung ein (Attribut data-confirmation) und sendet
das Formular, wenn der Benutzer bestätigt.
Dieselben Bootstrap-Klassen wie beim Buchungsdialog (fragments/booking.html).
========================================================================= */-->
<div xmlns:th="http://www.thymeleaf.org" th:fragment="confirmation" id="confirmation-modal" class="d-none">
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true"
aria-labelledby="confirmation-modal-title" aria-describedby="confirmation-modal-message">
<div class="modal-dialog modal-dialog-centered">
<div class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="confirmation-modal-title" th:text="#{CONFIRMATION.TITLE}">Confirmation</h5>
<button type="button" class="btn-close" data-action="no" th:attr="aria-label=#{BOOKING_DIALOG.CLOSE_ARIA}"></button>
</div>
<div class="modal-body">
<p class="mb-0" id="confirmation-modal-message"></p>
</div>
<div class="modal-footer">
<!--/* "No, go back" statt "Cancel": Die Frage ist manchmal
"Cancel this appointment?", und eine Schaltfläche "Cancel" wäre zweideutig */-->
<button type="button" class="btn btn-secondary" data-action="no" th:text="#{CONFIRMATION.NO}">No</button>
<button type="button" class="btn btn-danger" data-action="yes" th:text="#{CONFIRMATION.YES}">Yes</button>
</div>
</div>
</div>
</div>
</div>
|
- Zeilen 4–6: Warum gibt es ein Fenster auf der Seite anstelle des Dialogs [window.confirm()] des Browsers (siehe Beispiel 21)?
- Zeile 16: ein einziges Fenster für die gesamte Seite, anfangs ausgeblendet durch die Klasse [d-none] von [Bootstrap] ([display: none]). Das Skript [static/js/app.js] findet es über seine Kennung;
- Zeilen 17–21: die [Bootstrap]-Klassen eines modalen Fensters: der ausgegraute Hintergrund ([modal-backdrop]), dann das Fenster, das sichtbar wird ([show d-block]), sobald die Klasse [d-none] entfernt wird. [role="alertdialog"], [aria-modal], [aria-labelledby] und [aria-describedby] beschreiben das Fenster für Screenreader;
- Zeile 24: die Schaltfläche zum Schließen. Ihre Beschriftung für Screenreader ([aria-label]) ist übersetzt; [th:attr] berechnet ein beliebiges Attribut;
- Zeile 27: die Stelle der formularspezifischen Meldung, die vom Skript dort eingefügt wird;
- Zeilen 30–33: „Nein, zurück“ statt „Abbrechen“: Die Frage lautet mitunter „Diesen Termin stornieren?“. Das Attribut [data-action] teilt dem Skript mit, welche Schaltfläche angeklickt wurde.
11.17.1.6. templates/fragments/captcha.html
| <!--/* =========================================================================
templates/fragments/captcha.html - das CAPTCHA der Authentifizierungsseite
(siehe auth/CaptchaService.java). Es schützt sowohl das Login als auch
den Zugang zum Anlegen eines Kontos (Button "Create a client account").
Parameter: captcha, ein Objekt Captcha (id, svg).
th:utext: Das SVG-Bild wird UNVERÄNDERT in die Seite eingefügt, ohne
Maskierung. Hier ist das unbedenklich, weil dieses SVG vom Server selbst erzeugt wird
und nichts vom Benutzer Stammendes enthält - bei einer Eingabe würde man das
NIEMALS tun.
Das versteckte Feld captchaId teilt dem Server mit, WELCHES CAPTCHA zu prüfen ist; die richtige
Antwort selbst wird nie an den Browser gesendet.
"Another image" lädt einfach die Seite neu ([path] = die aktuelle URL).
========================================================================= */-->
<div xmlns:th="http://www.thymeleaf.org" th:fragment="captcha(captcha)" class="mb-3">
<label class="form-label" for="captcha" th:text="#{CAPTCHA.LABEL}">Copy the characters</label>
<div class="d-flex align-items-center gap-3 mb-2">
<div class="captcha-image" role="img" th:attr="aria-label=#{CAPTCHA.IMAGE_ALT}" th:utext="${captcha.svg}">image</div>
<a class="small" th:href="${path}" th:text="#{CAPTCHA.NEW_IMAGE}">Another image</a>
</div>
<input type="hidden" name="captchaId" th:value="${captcha.id}">
<input id="captcha" name="captcha" type="text" maxlength="10" autocomplete="off" autocapitalize="off"
spellcheck="false" required class="form-control">
<div class="form-text" th:text="#{CAPTCHA.HELP}">help</div>
</div>
|
- Zeile 16: ein parametrisiertes Fragment: Die Seite, die es einfügt, übergibt ihm das Objekt [Captcha] (Kennung und Bild);
- Zeile 19: Das SVG-Bild des CAPTCHA (siehe Beispiel 27) wird unverändert in die Seite eingefügt ([th:utext]), ohne Maskierung. Das ist hier unbedenklich, da dieses SVG vom Server selbst erzeugt wird und nichts vom Benutzer Geliefertes enthält; bei Benutzereingaben würden wir das niemals tun. [role="img"] und [aria-label] beschreiben das Bild für Screenreader;
- Zeile 20: „Anderes Bild“ lädt einfach die Seite neu ([path] ist der Pfad der aktuellen URL): Jeder Aufruf erzeugt ein neues CAPTCHA;
- Zeile 22: Das versteckte Feld [captchaId] teilt dem Server mit, welches CAPTCHA zu prüfen ist; die richtige Antwort wird dagegen nie an den Browser gesendet;
- Zeilen 23–24: die Eingabefelder. [autocomplete="off"], [autocapitalize="off"], und [spellcheck="false"] verhindern, dass der Browser Vorschläge macht, Großschreibung anwendet oder die Eingabe korrigiert.
11.17.1.7. templates/fragments/person-fields.html
| <!--/* =========================================================================
templates/fragments/person-fields.html - die Identitätsfelder (Anrede,
Vorname, Nachname), gemeinsam für drei Formulare: Arzt/Client des ADMIN,
"Client-Konto anlegen" und "Mein Konto verwalten".
Das Fragment liest die Variable [model] der Seite, die es einfügt (eine
FormView, siehe models/ViewModels.java): Werte, Meldung unter
jedem Feld, rot umrandete Felder.
th:selected: ein boolesches Attribut. Thymeleaf schreibt selected="selected",
wenn der Wert true ist, und LÄSST das Attribut WEG, wenn er false ist.
th:classappend: fügt den bereits vorhandenen eine Klasse hinzu - hier
"is-invalid" (rote Bootstrap-Umrandung) für ein abgelehntes Feld, oder nichts.
========================================================================= */-->
<th:block xmlns:th="http://www.thymeleaf.org" th:fragment="fields" th:with="state=${model.state}">
<div class="mb-3">
<label class="form-label" for="title" th:text="#{PERSONS.TITLE_LABEL}">Title</label>
<select id="title" name="title" class="form-select" th:classappend="${state.invalidClass('title')}">
<option th:each="title : ${model.titles()}" th:value="${title.value}"
th:selected="${title.selected}" th:text="${title.value}">Mr</option>
</select>
<div class="invalid-feedback" th:if="${state.errorOf('title') != null}"
th:text="#{${state.errorOf('title')}}">error</div>
</div>
<div class="row g-3 mb-3">
<div class="col-sm-6">
<label class="form-label" for="firstName" th:text="#{PERSONS.FIRSTNAME_LABEL}">First name</label>
<input id="firstName" name="firstName" type="text" maxlength="20" required
class="form-control" th:classappend="${state.invalidClass('firstName')}" th:value="${model.values.firstName}">
<div class="invalid-feedback" th:if="${state.errorOf('firstName') != null}"
th:text="#{${state.errorOf('firstName')}}">error</div>
</div>
<div class="col-sm-6">
<label class="form-label" for="lastName" th:text="#{PERSONS.LASTNAME_LABEL}">Last name</label>
<input id="lastName" name="lastName" type="text" maxlength="20" required
class="form-control" th:classappend="${state.invalidClass('lastName')}" th:value="${model.values.lastName}">
<div class="invalid-feedback" th:if="${state.errorOf('lastName') != null}"
th:text="#{${state.errorOf('lastName')}}">error</div>
</div>
</div>
</th:block>
|
Die Felder für Anrede, Vorname und Nachname sind drei Formularen gemeinsam: dem ADMIN-Formular (für Ärzte und Clients), dem Formular zur Kontoerstellung und dem Formular „Mein Konto verwalten“. Sie werden nur einmal geschrieben, in diesem Fragment.
- Zeile 14: Das Fragment [fields] ist ein [th:block]: Es fügt keine Tags um die Felder hinzu. Es liest die [model]-Variable der Seite, die es einfügt: ein Modell, das das Interface [FormView] implementiert (siehe [models/ViewModels.java]) und das daher Werte ([values]) und einen Zustand ([state]) besitzt. [th:with] speichert den Zustand in einer kürzeren Variablen; an diesem Element steht kein [th:if];
- Zeile 17: [th:classappend] fügt die von [state.invalidClass('title')] gelieferte Klasse hinzu: [is-invalid] (der rote Rand von [Bootstrap]) bei einem abgelehnten Feld, andernfalls eine leere Zeichenfolge;
- Zeilen 18–19: die Anreden ([Mr], [Mme], [Melle]), geliefert von der Methode [titles()] des Modells, einer Default-Methode des Interface [FormView]. Jede Option gibt an, ob sie ausgewählt ist: [th:selected] schreibt [selected="selected"] , wenn der Wert wahr ist, und lässt das Attribut weg, wenn er falsch ist;
- Zeilen 21–22: die Fehlermeldung des Feldes, falls vorhanden. [#{${state.errorOf('title')}}]: die Meldung, deren Schlüssel von [errorOf] geliefert wird. Die Klasse [invalid-feedback] von [Bootstrap] zeigt diese Meldung nur unter einem Feld mit [is-invalid] an;
- Zeilen 25–40: Vorname und Nachname im selben Format, auf einem ausreichend breiten Bildschirm nebeneinander ([col-sm-6]). [th:value] zeigt die Eingabe erneut an; [maxlength] und [required] dienen nur dem Komfort, denn die eigentliche Validierung erfolgt durch den Server.
11.17.1.8. templates/fragments/booking.html
| <!--/* =========================================================================
templates/fragments/booking.html - der Buchungsdialog des
Terminkalenders.
Die ECHTEN Bootstrap-Klassen eines modalen Dialogs (.modal,
.modal-backdrop...), "fest verdrahtet" sichtbar gemacht (show d-block) statt
über das JavaScript von Bootstrap. Der SERVER entscheidet, ihn anzuzeigen
(Parameter &book=... der URL), und ihn zu schließen heißt, einem Link
auf dieselbe Seite ohne diesen Parameter zu folgen.
Das Fragment liest direkt die Variable [model] der Seite, die es einfügt
(ein ScheduleModel).
========================================================================= */-->
<th:block xmlns:th="http://www.thymeleaf.org" th:fragment="booking" th:with="booking=${model.booking}">
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="dialog" aria-modal="true" aria-labelledby="booking-title">
<div class="modal-dialog modal-dialog-centered">
<form method="post" action="/schedule/book" class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="booking-title" th:text="#{BOOKING_DIALOG.TITLE}">Book this slot</h5>
<a class="btn-close" th:href="${model.backUrl}" th:attr="aria-label=#{BOOKING_DIALOG.CLOSE_ARIA}"></a>
</div>
<div class="modal-body">
<p th:text="#{BOOKING_DIALOG.SLOT('time', ${booking.time})}">Slot 8:00 - 8:20</p>
<!--/* was der Server zusätzlich zum gewählten Patienten wissen muss */-->
<input type="hidden" name="doctorId" th:value="${model.doctorId}">
<input type="hidden" name="day" th:value="${model.day}">
<input type="hidden" name="slotId" th:value="${booking.slotId}">
<!--/* ein Patient bucht für sich selbst: keine Liste zur Auswahl
(und der Server ignoriert ein eventuelles clientId ohnehin) */-->
<p class="mb-0" th:if="${booking.patient != null}">
<span th:text="#{BOOKING_DIALOG.PATIENT_LABEL}">Patient</span>:
<strong th:text="${booking.patient}">Mme Alice DURAND</strong>
</p>
<th:block th:if="${booking.patient == null}">
<label class="form-label" for="clientId" th:text="#{BOOKING_DIALOG.PATIENT_LABEL}">Patient</label>
<select id="clientId" name="clientId" class="form-select" required autofocus>
<option value="" th:text="#{BOOKING_DIALOG.CHOOSE_PATIENT}">-- choose a patient --</option>
<option th:each="client : ${booking.clients}" th:value="${client.id}"
th:text="${client.label}">Mme Alice DURAND</option>
</select>
</th:block>
</div>
<div class="modal-footer">
<a class="btn btn-secondary" th:href="${model.backUrl}" th:text="#{BOOKING_DIALOG.CANCEL}">Cancel</a>
<button type="submit" class="btn btn-primary" th:text="#{BOOKING_DIALOG.CONFIRM}">Confirm</button>
</div>
</form>
</div>
</div>
</th:block>
|
- Zeilen 5–9: Das Reservierungsfenster verwendet die echten Klassen eines modalen Fensters von [Bootstrap], das „fest verdrahtet“ sichtbar gemacht wird ([show d-block]), statt über das [JavaScript] von [Bootstrap]. Der Server entscheidet, ob es angezeigt wird;
- Zeile 14: Das Fragment liest das Seitenmodell (ein [ScheduleModel]); [th:with] speichert das Fenster ([model.booking]) in der Variablen [booking];
- Zeile 18: Das Formular sendet die Reservierung per POST an [/schedule/book];
- Zeile 21: Die Schaltfläche zum Schließen ist ein Link zum Terminkalender, ohne den Parameter [book]: Das Schließen des Fensters zeigt einfach die Seite ohne dieses an;
- Zeile 25: „Zeitfenster 8:00 - 8:20“: eine Meldung mit einem Parameter. In [#{BOOKING_DIALOG.SLOT('time', ${booking.time})}] werden die Parameter als Paare (Name, Wert) angegeben: [{time}] wird durch den Wert von [booking.time] ersetzt;
- Zeilen 28–30: versteckte Felder: der Arzt, der Tag (um zum selben Terminkalender zurückzukehren) und das Zeitfenster;
- Zeilen 34–37: Ein Patient reserviert für sich selbst: keine Liste, nur sein Name (der Server ignoriert ein etwaiges [clientId] ohnehin);
- Zeilen 38–45: Ein Administrator wählt einen Patienten aus einer Liste aus – Pflichtangabe ([required]) –, die beim Öffnen der Seite den Fokus erhält ([autofocus]);
- Zeile 49: „Abbrechen“ ist ebenfalls ein Link zur Seite ohne das Pop-up-Fenster.
11.17.2. Die Seiten
11.17.2.1. templates/login.html
| <!doctype html>
<!--/* =========================================================================
templates/login.html - das Login-Formular (siehe AuthController).
Ein gewöhnliches HTML-<form>: Der Browser selbst sendet Login,
Passwort und Antwort auf das CAPTCHA per POST /login, ohne JavaScript. Im Fehlerfall
liefert der Server DIESE Seite zurück, mit dem bereits eingegebenen Login, einem
NEUEN CAPTCHA und dem Fehler, den das Layout am Seitenende anzeigt.
Die gesamte Seite wird durch das Fragment [page] des Layouts ERSETZT, an das wir
den <main>-Block dieser Seite übergeben (~{::main}).
========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main class="row justify-content-center" th:with="loginTyped=${model.login != ''}">
<div class="col-sm-8 col-md-6 col-lg-5">
<div class="card p-4">
<h5 class="card-title mb-3" th:text="#{LOGIN.TITLE}">Login</h5>
<form method="post" action="/login">
<div class="mb-3">
<label class="form-label" for="login" th:text="#{LOGIN.LOGIN_LABEL}">Login</label>
<!--/* th:autofocus: ein boolesches Attribut, geschrieben, wenn der Wert true ist, sonst weggelassen */-->
<input id="login" name="login" type="text" class="form-control" autocomplete="username"
th:value="${model.login}" required th:autofocus="${!loginTyped}">
</div>
<div class="mb-3">
<label class="form-label" for="password" th:text="#{LOGIN.PASSWORD_LABEL}">Password</label>
<input id="password" name="password" type="password" class="form-control"
autocomplete="current-password" required th:autofocus="${loginTyped}">
</div>
<div th:replace="~{fragments/captcha :: captcha(${model.captcha})}"></div>
<button type="submit" class="btn btn-primary w-100" th:text="#{LOGIN.SUBMIT}">Log in</button>
<!--/* noch kein Konto: Ein Patient kann selbst eines erstellen.
Es ist KEIN einfacher Link: Es ist ein zweiter Submit-Button
DIESES Formulars, der an eine andere Adresse geht (formaction). Der
Server prüft dort das obige CAPTCHA, bevor er die Seite zum
Anlegen eines Kontos öffnet (siehe RegistrationController).
formnovalidate: Der Browser verlangt weder Login noch Passwort
(unnötig, um ein Konto anzulegen); der Server prüft
das CAPTCHA. Die Eingabetaste in einem Feld löst immer den ERSTEN
Button des Formulars aus, "Log in". */-->
<button type="submit" class="btn btn-outline-primary w-100 mt-3"
formaction="/register/access" formnovalidate th:text="#{LOGIN.CREATE_ACCOUNT}">Create an account</button>
<div class="form-text text-center" th:text="#{LOGIN.CREATE_ACCOUNT_HELP}">help</div>
</form>
<div class="text-muted small mt-3">
<span th:text="#{LOGIN.DEMO_ACCOUNTS}">Demo accounts</span>
<ul class="mb-0 mt-1">
<li><code>admin</code> - <span th:text="#{LOGIN.DEMO_ADMIN}">ADMIN</span></li>
<li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - <span th:text="#{LOGIN.DEMO_DOCTOR}">DOCTOR</span></li>
<li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - <span th:text="#{LOGIN.DEMO_USER}">USER</span></li>
</ul>
</div>
</div>
</div>
</main>
</body>
</html>
|
- Zeile 12: Die Seite wird durch das Fragment [page] des Templates ersetzt, dem sie ihr Element [<main>] übergibt. [~{::main}] verweist auf das Element [<main>] der aktuellen Datei. Es wird also nur dieses Element verwendet: Die Tags [<html>] und [<body>] dieser Datei dienen nur dazu, sie zu einer vollständigen HTML-Datei zu machen, die in einem Browser geöffnet werden kann;
- Zeile 14: Nach einem fehlgeschlagenen Versuch gibt der Controller diese Seite mit dem bereits eingegebenen Benutzernamen zurück ([model.login]); die Variable [loginTyped] gibt an, ob er bekannt ist;
- Zeile 19: ein standardmäßiges HTML-Formular: Der Browser selbst sendet Benutzernamen, Passwort und CAPTCHA-Antwort ab;
- Zeilen 23–29: [th:autofocus] setzt das boolesche Attribut [autofocus] , wenn der Wert wahr ist, und lässt es andernfalls weg: Nur eines der beiden Felder erhält es. Der Cursor steht im Feld für den Benutzernamen oder im Passwortfeld, wenn der Benutzername bereits bekannt ist. Die Werte von [autocomplete] ([username], [current-password]) unterstützen die Passwortmanager der Browser;
- Zeile 32: das CAPTCHA, ein parametrisiertes Fragment, das das Objekt [model.captcha] erhält;
- Zeilen 45–46: Die zweite Schaltfläche sendet dasselbe Formular an [/register/access] (Attribut [formaction], siehe Beispiel 21): Dort prüft der Server das CAPTCHA, bevor er die Seite zur Kontoerstellung öffnet. [formnovalidate]: Der Browser verlangt keinen Benutzernamen und kein Passwort, da sie zur Kontoerstellung nicht benötigt werden. Das Drücken der Eingabetaste in einem Feld löst immer die erste Schaltfläche des Formulars aus: „Anmelden“;
- Zeilen 50–57: Demokonten (Passwort = Benutzername).
Hier ist das Formular, das für die Adresse [/login?login=martin] erzeugt wurde (das CAPTCHA-Bild wurde zugeschnitten):
| curl http://localhost:8081/login?login=martin
|
| <main class="row justify-content-center">
<div class="col-sm-8 col-md-6 col-lg-5">
<div class="card p-4">
<h5 class="card-title mb-3">Login</h5>
<form method="post" action="/login">
<div class="mb-3">
<label class="form-label" for="login">Login</label>
<input id="login" name="login" type="text" class="form-control" autocomplete="username"
value="martin" required>
</div>
<div class="mb-3">
<label class="form-label" for="password">Password</label>
<input id="password" name="password" type="password" class="form-control"
autocomplete="current-password" required autofocus="autofocus">
</div>
<div class="mb-3">
<label class="form-label" for="captcha">Type the characters shown in the image</label>
<div class="d-flex align-items-center gap-3 mb-2">
<div class="captcha-image" role="img" aria-label="Anti-robot verification image"><svg xmlns="http://www.w3.org/2000/svg" width="150" height="50" ...</svg></div>
<a class="small" href="/login">Another image</a>
</div>
<input type="hidden" name="captchaId" value="7cb0085e-e571-4756-878f-04ca6f429140">
<input id="captcha" name="captcha" type="text" maxlength="10" autocomplete="off" autocapitalize="off"
spellcheck="false" required class="form-control">
<div class="form-text">Upper or lower case, it does not matter.</div>
</div>
<button type="submit" class="btn btn-primary w-100">Log in</button>
|
Da der Benutzername bekannt ist, wurde nur dem Passwortfeld das Attribut [autofocus] zugewiesen. Der Link „Anderes Bild“ verweist auf [/login]: Die Variable [path] enthält nur den Pfad der URL, ohne ihre Parameter.
11.17.2.2. templates/schedule.html
| <!doctype html>
<!--/* =========================================================================
templates/schedule.html - die Hauptseite (siehe ScheduleController).
Drei Blöcke:
1. die Auswahl des Arztes und des Tages;
2. der Terminkalender;
3. der Buchungsdialog (fragments/booking.html).
Ein eventueller Fehler (ungültiges Datum, unbekannter Arzt) wird am
Seitenende vom Layout angezeigt (siehe fragments/errors.html).
========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>
<!--/* 1. Auswahl des Arztes und des Tages: ein GET-Formular, das einfach
mit ?doctorId=...&day=... in der URL neu lädt */-->
<form method="get" action="/schedule" class="card p-3 mb-3">
<div class="row g-2 align-items-end">
<div class="col-sm-5">
<label class="form-label" for="doctorId" th:text="#{DOCTOR_DAY_PICKER.DOCTOR_LABEL}">Doctor</label>
<select id="doctorId" name="doctorId" class="form-select" required>
<option value="" th:text="#{DOCTOR_DAY_PICKER.CHOOSE_DOCTOR}">-- choose --</option>
<option th:each="doctor : ${model.doctors}" th:value="${doctor.id}"
th:selected="${doctor.selected}" th:text="${doctor.label}">Mme Marie PELISSIER</option>
</select>
</div>
<div class="col-sm-4">
<label class="form-label" for="day" th:text="#{DOCTOR_DAY_PICKER.DAY_LABEL}">Day</label>
<input id="day" name="day" type="date" class="form-control" th:value="${model.day}" required>
</div>
<div class="col-sm-3">
<button type="submit" class="btn btn-primary w-100" th:text="#{DOCTOR_DAY_PICKER.VIEW_SCHEDULE}">View the schedule</button>
</div>
</div>
</form>
<!--/* Patient, der bereits einen bevorstehenden Termin hat: warum es keine Schaltfläche "Book" gibt */-->
<div class="alert alert-info" th:if="${model.info != null}">
<span th:text="#{${model.info}}">info</span>
<a href="/my-area" class="alert-link" th:text="#{APP.MENU_MY_AREA}">My area</a>
</div>
<!--/* 2. der Terminkalender; th:object: ${schedule} kann dann als *{...} geschrieben werden */-->
<div class="card p-3" th:if="${model.schedule != null}" th:object="${model.schedule}">
<h5 th:text="|#{SCHEDULE.TITLE_PREFIX} *{day} - *{doctor}|">Schedule of ...</h5>
<table class="table table-hover align-middle" th:unless="*{rows.isEmpty()}">
<thead>
<tr>
<th th:text="#{SCHEDULE.COLUMN_SLOT}">Slot</th>
<th th:text="#{SCHEDULE.COLUMN_STATUS}">Status</th>
<th></th>
</tr>
</thead>
<tbody>
<tr th:each="row : *{rows}" th:classappend="${row.bookable} ? 'free-slot'">
<td th:text="${row.time}">8:00 - 8:20</td>
<td>
<!--/* [patient] wird nur gefüllt, wenn der Benutzer dazu berechtigt ist
sehen darf (ADMIN, DOCTOR oder der Patient bei SEINEM
Termin) - andernfalls einfach "Booked" */-->
<span th:if="${row.free}" class="badge text-bg-success" th:text="#{SCHEDULE.FREE}">Free</span>
<span th:if="${!row.free and row.patient != null}" class="badge"
th:classappend="${row.mine} ? 'text-bg-primary' : 'text-bg-secondary'"
th:text="${row.patient}">Mme Alice DURAND</span>
<span th:if="${!row.free and row.patient == null}" class="badge text-bg-secondary"
th:text="#{SCHEDULE.BOOKED_BY_OTHER}">Booked</span>
</td>
<td>
<!--/* die angezeigten Schaltflächen wurden vom Controller festgelegt
(bookable, appointmentId) je nach Rolle des Benutzers */-->
<!--/* "Book" ist ein einfacher Link: Er öffnet diese Seite erneut
mit dem Buchungsdialog dieses Zeitfensters */-->
<a th:if="${row.bookable}" class="btn btn-sm btn-outline-success"
th:href="${row.bookUrl}" th:text="#{SCHEDULE.BOOK}">Book</a>
<!--/* "Cancel" ÄNDERT Daten: Es ist daher ein POST */-->
<form th:if="${row.appointmentId != null}" method="post" action="/schedule/cancel" class="m-0"
th:attr="data-confirmation=#{SCHEDULE.CANCEL_CONFIRM}">
<input type="hidden" name="appointmentId" th:value="${row.appointmentId}">
<input type="hidden" name="doctorId" th:value="${model.doctorId}">
<input type="hidden" name="day" th:value="${model.day}">
<button type="submit" class="btn btn-sm btn-outline-danger" th:text="#{SCHEDULE.CANCEL_APPOINTMENT}">Cancel</button>
</form>
</td>
</tr>
</tbody>
</table>
<p class="text-muted mb-0" th:if="*{rows.isEmpty()}" th:text="#{SCHEDULE.NO_SLOTS}">No slots.</p>
</div>
<p class="text-muted" th:if="${model.schedule == null}" th:text="#{SCHEDULE.EMPTY_STATE}">Choose a doctor...</p>
<!--/* 3. der Buchungsdialog, nur wenn die URL &book=... enthält */-->
<th:block th:if="${model.booking != null}">
<div th:replace="~{fragments/booking :: booking}"></div>
</th:block>
</main>
</body>
</html>
|
Sehen wir uns diesen Code im Einzelnen an:
- Zeilen 17–35: Auswahl des Arztes und des Tages: ein GET-Formular (siehe Beispiel 17), das die Seite mit [?doctorId=...&day=...] in der URL neu lädt. Jeder Arzt ist ein [OptionView] , der angibt, ob er ausgewählt ist ([th:selected]). Ein Feld [type="date"] sendet das Datum im Format [yyyy-MM-dd] (siehe Beispiel 18);
- Zeilen 38–41: die Meldung für einen Patienten, der bereits einen bevorstehenden Termin hat: Sie erklärt, warum die Schaltflächen „Buchen“ fehlen, und enthält einen Link zu „Mein Bereich“. Der Controller sendet diese Meldung nicht, wenn der Termin des Patienten im angezeigten Terminkalender erscheint (siehe [patientInfo]). [#{${model.info}}]: Der Meldungsschlüssel wird vom Controller geliefert;
- Zeile 44: der Terminkalender, falls angefordert. [th:object] verweist auf ein Auswahlobjekt: Innerhalb des Elements steht [*{day}] für [${model.schedule.day}];
- Zeile 45: der Titel „Terminkalender für Freitag, 25. September 2026 - Mme Marie PELISSIER“ über eine Literalsubstitution;
- Zeile 47: Die Tabelle wird nur geschrieben, wenn der Terminkalender Zeilen enthält ([th:unless]: es sei denn ...);
- Zeile 56: eine Zeile pro Zeitfenster. Ein buchbares Zeitfenster ändert beim Überfahren mit der Maus seine Farbe (Klasse [free-slot], siehe [styles.css]);
- Zeilen 62–67: drei Fälle: frei; gebucht, mit dem Namen des Patienten (blau, wenn es der Termin des angemeldeten Patienten ist, [mine]; andernfalls grau); gebucht ohne sichtbaren Namen, „Belegt“. Der Controller füllt [patient] nur, wenn der Benutzer berechtigt ist, diesen Namen zu sehen;
- Zeilen 74–75: „Buchen“ ist ein Link: Er öffnet diese Seite erneut und zeigt das Reservierungsfenster für dieses Zeitfenster an ([bookUrl], vom Controller vorbereitet);
- Zeilen 77–83: „Stornieren“ verändert Daten: Es ist ein Formular (POST) mit Bestätigung. [th:attr] setzt das Attribut [data-confirmation], das die übersetzte Frage enthält; das Skript [app.js] fängt das Absenden von Formularen ab, die dieses Attribut besitzen (siehe Beispiel 21). Die versteckten Felder [doctorId] und [day] ermöglichen es dem Controller, zum selben Terminkalender weiterzuleiten. In der Schleife verweist [model] immer auf das Seitenmodell;
- Zeilen 88 und 90: ein Arzt ohne verfügbare Zeitfenster oder ein noch nicht angeforderter Terminkalender;
- Zeilen 93–95: das Buchungsfenster, falls der Controller es vorbereitet hat. Die Bedingung steht an einem [th:block] , das Folgendes umschließt: Das Fragment, das [model.booking] liest, wird nur eingefügt, wenn dieses Fenster existiert.
11.17.2.3. templates/persons/list.html
| <!doctype html>
<!--/* =========================================================================
templates/persons/list.html - die Liste der Ärzte ODER der Clients (ADMIN).
Eine einzige View für beide: Die jeweils spezifischen Bezeichnungen kommen in
model.keys an (siehe DoctorsController / ClientsController).
========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>
<div class="d-flex justify-content-between align-items-center mb-3">
<h4 class="mb-0" th:text="#{${model.keys.title}}">Doctors</h4>
<a class="btn btn-primary" th:href="${model.addUrl}" th:text="#{${model.keys.add}}">Add</a>
</div>
<div class="card p-3">
<table class="table table-hover align-middle mb-0" th:unless="${model.persons.isEmpty()}">
<thead>
<tr>
<th th:text="#{PERSONS.COLUMN_TITLE}">Title</th>
<th th:text="#{PERSONS.COLUMN_FIRSTNAME}">First name</th>
<th th:text="#{PERSONS.COLUMN_LASTNAME}">Last name</th>
<th th:text="#{PERSONS.COLUMN_LOGIN}">Login</th>
<th></th>
</tr>
</thead>
<tbody>
<tr th:each="person : ${model.persons}">
<td th:text="${person.title}">Mme</td>
<td th:text="${person.firstName}">Marie</td>
<td th:text="${person.lastName}">PELISSIER</td>
<td><code th:text="${person.login}">pelissier</code></td>
<td class="text-end">
<div class="d-inline-flex gap-2">
<a class="btn btn-sm btn-outline-primary" th:href="${person.editUrl}"
th:text="#{PERSONS.EDIT}">Edit</a>
<!--/* data-confirmation: Ein Bestätigungsdialog wird sich öffnen
bevor das Formular gesendet wird (siehe static/js/app.js) */-->
<form method="post" th:action="${person.deleteUrl}" class="m-0"
th:attr="data-confirmation=#{${model.keys.confirmDelete}}">
<button type="submit" class="btn btn-sm btn-outline-danger" th:text="#{PERSONS.DELETE}">Delete</button>
</form>
</div>
</td>
</tr>
</tbody>
</table>
<p class="text-muted mb-0" th:if="${model.persons.isEmpty()}" th:text="#{${model.keys.empty}}">None.</p>
</div>
</main>
</body>
</html>
|
- Zeilen 11–12: der Titel und die Beschriftung der Schaltfläche zum Hinzufügen: vom Controller gelieferte Übersetzungsschlüssel ([model.keys]), die sich für Ärzte und für Clients unterscheiden;
- Zeilen 16 und 47: die Tabelle oder die Meldung „Keine Ärzte.“ („Keine Patienten.“), wenn die Liste leer ist;
- Zeile 27: eine Zeile pro Person;
- Zeile 31: der Benutzername in einer Festbreitenschrift ([<code>]);
- Zeilen 34–35: „Bearbeiten“ ist ein Link zum Bearbeitungsformular;
- Zeilen 38–41: „Löschen“ verändert Daten: Es ist ein POST-Formular mit Bestätigung. Die Bestätigungsfrage ist ein vom Controller gelieferter Schlüssel: [#{${model.keys.confirmDelete}}]; ebenso seine Adresse ([th:action]).
| <!doctype html>
<!--/* =========================================================================
templates/persons/form.html - Anlegen ODER Bearbeiten eines
Arztes oder Clients (ADMIN). model.creating unterscheidet die beiden Fälle.
Wird die Eingabe abgelehnt (leeres Feld, Login bereits vergeben...),
liefert der Controller DIESE View zurück mit:
- den bereits eingegebenen Werten (model.values);
- den fehlerhaften Feldern rot umrandet (Bootstrap-Klasse "is-invalid");
- unter einem von der Validierung abgelehnten Feld seiner Meldung;
- der Fehlermeldung der Seite, die das
Layout AM SEITENENDE anzeigt (siehe fragments/errors.html).
========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main class="row justify-content-center" th:with="state=${model.state}">
<div class="col-md-8 col-lg-6">
<div class="card p-4">
<h5 class="card-title mb-3" th:text="#{${model.pageTitle}}">Add a doctor</h5>
<!--/* novalidate: Wir lassen den SERVER validieren (er hat das letzte Wort);
die Prüfungen des Browsers (required...) sind nur eine Komfortfunktion,
die ein Benutzer immer umgehen kann */-->
<form method="post" th:action="${model.action}" novalidate>
<input type="hidden" name="version" th:unless="${model.creating}" th:value="${model.values.version}">
<!--/* Anrede, Vorname, Nachname: für drei Formulare gemeinsames Fragment */-->
<th:block th:replace="~{fragments/person-fields :: fields}"></th:block>
<h6 class="mt-4 text-muted" th:text="#{PERSONS.ACCOUNT_SECTION}">User account</h6>
<div class="mb-3">
<label class="form-label" for="login" th:text="#{PERSONS.LOGIN_LABEL}">Login</label>
<input id="login" name="login" type="text" maxlength="30" autocomplete="off"
class="form-control" th:classappend="${state.invalidClass('login')}" th:value="${model.values.login}">
<div class="invalid-feedback" th:if="${state.errorOf('login') != null}"
th:text="#{${state.errorOf('login')}}">error</div>
<div class="form-text" th:if="${state.errorOf('login') == null}"
th:text="${model.creating} ? #{PERSONS.LOGIN_HELP_CREATE} : #{PERSONS.LOGIN_HELP_EDIT}">help</div>
</div>
<div class="mb-4">
<label class="form-label" for="password" th:text="#{PERSONS.PASSWORD_LABEL}">Password</label>
<!--/* nie vorausgefüllt: Das Passwort geht nie an den Browser zurück */-->
<input id="password" name="password" type="password" maxlength="72" autocomplete="new-password"
class="form-control" th:classappend="${state.invalidClass('password')}">
<div class="invalid-feedback" th:if="${state.errorOf('password') != null}"
th:text="#{${state.errorOf('password')}}">error</div>
<div class="form-text" th:if="${state.errorOf('password') == null}"
th:text="${model.creating} ? #{PERSONS.PASSWORD_HELP_CREATE} : #{PERSONS.PASSWORD_HELP_EDIT}">help</div>
</div>
<div class="d-flex gap-2">
<button type="submit" class="btn btn-primary" th:text="#{PERSONS.SAVE}">Save</button>
<a class="btn btn-secondary" th:href="${model.listUrl}" th:text="#{PERSONS.BACK}">Back</a>
</div>
</form>
</div>
</div>
</main>
</body>
</html>
|
- Zeile 16: [state]: der Formularzustand, für den Teil, der nicht im gemeinsamen Fragment enthalten ist;
- Zeile 19: der Titel: „Arzt hinzufügen“, „Patient bearbeiten“ usw.;
- Zeile 24: die Zieladresse des Formulars, vom Controller geliefert. [novalidate]: Der Browser prüft diese Felder nicht selbst ([required], [maxlength]); der Server validiert sie und ist die maßgebliche Instanz (siehe Beispiel 19);
- Zeile 25: die Version der Akte (optimistisches Sperren), nur bei einer Änderung;
- Zeile 28: die Felder für Anrede, Vorname und Nachname, über das gemeinsame Fragment. [th:replace] an einem [th:block]: Das Fragment ersetzt den Block;
- Zeilen 34–39: der Benutzername mit seiner Fehlermeldung oder, falls keine vorliegt, seinem Hilfetext, der vom Modus abhängt: [${model.creating} ? #{...} : #{...}] wählt zwischen zwei Meldungen;
- Zeilen 45–50: das Passwort, das niemals vorausgefüllt wird; es wird nie an den Browser zurückgesendet;
- Zeile 55: Rückkehr zur Liste.
11.17.2.5. templates/registration.html
| <!doctype html>
<!--/* =========================================================================
templates/registration.html - "Client-Konto anlegen" (öffentliche Seite,
siehe RegistrationController). Dieselben Identitätsfelder wie im Formular
des ADMIN (Fragment person-fields), aber Login und Passwort
sind Pflicht, mit Bestätigung.
Hier KEIN CAPTCHA: Man gelangt auf diese Seite erst, nachdem man das
der Authentifizierungsseite abgetippt hat (Button "Create a client account").
#{${key}('min', ${model.passwordMin()})}: die Meldung, deren Schlüssel der
Wert von [key] ist, mit dem Parameter {min} (siehe web/Translator.java).
========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main class="row justify-content-center" th:with="state=${model.state}">
<div class="col-md-8 col-lg-6">
<div class="card p-4">
<h5 class="card-title mb-1" th:text="#{REGISTRATION.TITLE}">Create a client account</h5>
<p class="text-muted small mb-3" th:text="#{REGISTRATION.INTRO}">intro</p>
<form method="post" action="/register" novalidate>
<th:block th:replace="~{fragments/person-fields :: fields}"></th:block>
<h6 class="mt-4 text-muted" th:text="#{PERSONS.ACCOUNT_SECTION}">User account</h6>
<div class="mb-3">
<label class="form-label" for="login" th:text="#{PERSONS.LOGIN_LABEL}">Login</label>
<input id="login" name="login" type="text" maxlength="30" autocomplete="username" required
class="form-control" th:classappend="${state.invalidClass('login')}" th:value="${model.values.login}">
<div class="invalid-feedback" th:if="${state.errorOf('login') != null}"
th:text="#{${state.errorOf('login')}}">error</div>
<div class="form-text" th:if="${state.errorOf('login') == null}" th:text="#{REGISTRATION.LOGIN_HELP}">help</div>
</div>
<div class="row g-3 mb-3">
<div class="col-sm-6">
<label class="form-label" for="password" th:text="#{PERSONS.PASSWORD_LABEL}">Password</label>
<input id="password" name="password" type="password" maxlength="72" autocomplete="new-password" required
class="form-control" th:classappend="${state.invalidClass('password')}">
<div class="invalid-feedback" th:if="${state.errorOf('password') != null}"
th:text="#{${state.errorOf('password')}('min', ${model.passwordMin()})}">error</div>
<div class="form-text" th:if="${state.errorOf('password') == null}"
th:text="#{REGISTRATION.PASSWORD_HELP('min', ${model.passwordMin()})}">help</div>
</div>
<div class="col-sm-6">
<label class="form-label" for="confirmation" th:text="#{ACCOUNT.CONFIRMATION_LABEL}">Confirmation</label>
<input id="confirmation" name="confirmation" type="password" maxlength="72" autocomplete="new-password" required
class="form-control" th:classappend="${state.invalidClass('confirmation')}">
<div class="invalid-feedback" th:if="${state.errorOf('confirmation') != null}"
th:text="#{${state.errorOf('confirmation')}}">error</div>
</div>
</div>
<div class="d-flex gap-2">
<button type="submit" class="btn btn-primary" th:text="#{REGISTRATION.SUBMIT}">Create my account</button>
<a class="btn btn-secondary" href="/login" th:text="#{REGISTRATION.BACK_TO_LOGIN}">Back</a>
</div>
</form>
</div>
</div>
</main>
</body>
</html>
|
- Zeile 21: das Formular, das per POST an [/register] gesendet und vom Server validiert wird ([novalidate]);
- Zeile 22: die Identitätsfelder, die mit denen des ADMIN-Formulars übereinstimmen;
- Zeilen 26–33: der Benutzername, der hier erforderlich ist;
- Zeilen 37–43: das Passwort. Die Fehlermeldung „Das Passwort muss mindestens {min} Zeichen lang sein“ hat einen Parameter: [#{${key}('min', ${model.passwordMin()})}] übergibt sowohl einen berechneten Schlüssel als auch einen Parameter – die in [models/InputRules.java] festgelegte Mindestlänge –, der von einer Methode des Modells gelesen wird;
- Zeilen 46–50: die Passwortbestätigung, die vom Validator verglichen wird;
- Zeile 56: Der Benutzer wird zur Anmeldeseite zurückgeleitet.
11.17.2.6. templates/area.html
| <!doctype html>
<!--/* =========================================================================
templates/area.html - "Mein Bereich": die Startseite des Patienten
(Rolle USER), die direkt nach seinem Login angezeigt wird.
- zwei Optionen: [Manage my account] und [View a schedule];
- sein bevorstehender Termin, falls er einen hat, mit der Möglichkeit, ihn zu stornieren.
========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>
<h4 class="mb-3" th:text="#{AREA.HELLO('name', ${model.patient})}">Hello Mme Alice DURAND</h4>
<div class="row g-3 mb-4">
<div class="col-sm-6">
<a class="card p-4 h-100 text-decoration-none option-card" href="/my-account">
<h5 class="mb-1" th:text="#{AREA.MANAGE_ACCOUNT}">Manage my account</h5>
<span class="text-muted" th:text="#{AREA.MANAGE_ACCOUNT_HELP}">help</span>
</a>
</div>
<div class="col-sm-6">
<a class="card p-4 h-100 text-decoration-none option-card" href="/schedule">
<h5 class="mb-1" th:text="#{AREA.VIEW_SCHEDULE}">View a schedule</h5>
<span class="text-muted" th:text="#{AREA.VIEW_SCHEDULE_HELP}">help</span>
</a>
</div>
</div>
<div class="card p-3">
<h5 th:text="#{AREA.MY_APPOINTMENT}">My appointment</h5>
<!--/* normalerweise nur einer (Regel "ein bevorstehender Termin zur Zeit"),
aber die Seite kann mehrere anzeigen. [status]: eine Iterationsvariable,
die von th:each bereitgestellt wird (status.last: letztes Element?) */-->
<div th:each="appointment, status : ${model.appointments}"
class="d-flex flex-wrap justify-content-between align-items-center gap-2 py-2"
th:classappend="${status.last} ? '' : 'border-bottom'">
<div>
<div class="fw-semibold" th:text="|${appointment.day}, ${appointment.time}|">Wednesday 23 September 2026, 8:00 - 8:20</div>
<div class="text-muted">
<span th:text="${appointment.doctor}">Mme Marie PELISSIER</span> -
<a th:href="${appointment.scheduleUrl}" th:text="#{AREA.SEE_IN_SCHEDULE}">see in the schedule</a>
</div>
</div>
<form method="post" action="/my-area/cancel" class="m-0"
th:attr="data-confirmation=#{SCHEDULE.CANCEL_CONFIRM}">
<input type="hidden" name="appointmentId" th:value="${appointment.id}">
<button type="submit" class="btn btn-outline-danger" th:text="#{AREA.CANCEL_APPOINTMENT}">Cancel</button>
</form>
</div>
<p class="text-muted mb-0" th:if="${model.appointments.isEmpty()}" th:text="#{AREA.NO_APPOINTMENT}">No appointment.</p>
</div>
</main>
</body>
</html>
|
- Zeile 11: „Guten Tag Mr Jean MARTIN“: eine Meldung mit einem Parameter [{name}];
- Zeilen 13–26: die beiden Optionen der Seite, große anklickbare Karten (Links), die auf das Überfahren mit der Maus reagieren (Klasse [option-card], siehe [styles.css]);
- Zeilen 33–35: der bevorstehende Termin. Normalerweise gibt es nur einen (ein bevorstehender Termin pro Patient), doch die Seite kann mehrere anzeigen. [th:each="appointment, status : ..."] deklariert nach der Schleifenvariablen eine Zustandsvariable , die von [Thymeleaf] bereitgestellt wird: [status.last] gibt an, ob das Element das letzte der Liste ist; alle anderen werden durch eine Trennlinie abgesetzt ([border-bottom]);
- Zeile 37: Datum und Uhrzeit, bereits vom Controller formatiert;
- Zeile 40: der Link zum Terminkalender des Arztes für diesen Tag, in dem der Patient seinen Namen sieht;
- Zeilen 43–47: die Stornierung, ein POST-Formular mit Bestätigung;
- Zeile 49: keine bevorstehenden Termine.
11.17.2.7. templates/account.html
| <!doctype html>
<!--/* =========================================================================
templates/account.html - "Mein Konto verwalten" (Rolle USER).
Zwei unabhängige Formulare auf derselben Seite:
1. das Bearbeiten (Identität, Login, optionales neues Passwort);
2. das Löschen des Kontos - wodurch auch seine Termine storniert werden.
Beide erfordern das AKTUELLE Passwort.
========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main class="row justify-content-center" th:with="state=${model.state}">
<div class="col-md-8 col-lg-6">
<!--/* 1. Bearbeitung */-->
<div class="card p-4 mb-4">
<h5 class="card-title mb-3" th:text="#{MY_ACCOUNT.TITLE}">Manage my account</h5>
<form method="post" action="/my-account" novalidate>
<input type="hidden" name="version" th:value="${model.values.version}">
<th:block th:replace="~{fragments/person-fields :: fields}"></th:block>
<h6 class="mt-4 text-muted" th:text="#{PERSONS.ACCOUNT_SECTION}">User account</h6>
<div class="mb-3">
<label class="form-label" for="login" th:text="#{PERSONS.LOGIN_LABEL}">Login</label>
<input id="login" name="login" type="text" maxlength="30" autocomplete="username" required
class="form-control" th:classappend="${state.invalidClass('login')}" th:value="${model.values.login}">
<div class="invalid-feedback" th:if="${state.errorOf('login') != null}"
th:text="#{${state.errorOf('login')}}">error</div>
</div>
<div class="row g-3 mb-3">
<div class="col-sm-6">
<label class="form-label" for="password" th:text="#{MY_ACCOUNT.NEW_PASSWORD_LABEL}">New password</label>
<input id="password" name="password" type="password" maxlength="72" autocomplete="new-password"
class="form-control" th:classappend="${state.invalidClass('password')}">
<div class="invalid-feedback" th:if="${state.errorOf('password') != null}"
th:text="#{${state.errorOf('password')}('min', ${model.passwordMin()})}">error</div>
<div class="form-text" th:if="${state.errorOf('password') == null}"
th:text="#{PERSONS.PASSWORD_HELP_EDIT}">help</div>
</div>
<div class="col-sm-6">
<label class="form-label" for="confirmation" th:text="#{ACCOUNT.CONFIRMATION_LABEL}">Confirmation</label>
<input id="confirmation" name="confirmation" type="password" maxlength="72" autocomplete="new-password"
class="form-control" th:classappend="${state.invalidClass('confirmation')}">
<div class="invalid-feedback" th:if="${state.errorOf('confirmation') != null}"
th:text="#{${state.errorOf('confirmation')}}">error</div>
</div>
</div>
<div class="mb-4">
<label class="form-label" for="currentPassword" th:text="#{MY_ACCOUNT.CURRENT_PASSWORD_LABEL}">Current password</label>
<input id="currentPassword" name="currentPassword" type="password" maxlength="72"
autocomplete="current-password" required
class="form-control" th:classappend="${state.invalidClass('currentPassword')}">
<div class="invalid-feedback" th:if="${state.errorOf('currentPassword') != null}"
th:text="#{${state.errorOf('currentPassword')}}">error</div>
<div class="form-text" th:if="${state.errorOf('currentPassword') == null}"
th:text="#{MY_ACCOUNT.CURRENT_PASSWORD_HELP}">help</div>
</div>
<div class="d-flex gap-2">
<button type="submit" class="btn btn-primary" th:text="#{PERSONS.SAVE}">Save</button>
<a class="btn btn-secondary" href="/my-area" th:text="#{MY_ACCOUNT.BACK}">Back</a>
</div>
</form>
</div>
<!--/* 2. Löschung */-->
<div class="card p-4 border-danger">
<h5 class="card-title text-danger mb-1" th:text="#{MY_ACCOUNT.DELETE_TITLE}">Delete my account</h5>
<p class="text-muted small" th:text="#{MY_ACCOUNT.DELETE_HELP}">help</p>
<form method="post" action="/my-account/delete" class="d-flex flex-wrap gap-2 align-items-end"
th:attr="data-confirmation=#{MY_ACCOUNT.DELETE_CONFIRM}">
<div class="flex-grow-1">
<label class="form-label" for="deletePassword" th:text="#{MY_ACCOUNT.CURRENT_PASSWORD_LABEL}">Current password</label>
<input id="deletePassword" name="deletePassword" type="password" maxlength="72"
autocomplete="current-password" required class="form-control">
</div>
<button type="submit" class="btn btn-danger" th:text="#{MY_ACCOUNT.DELETE_SUBMIT}">Delete my account</button>
</form>
</div>
</div>
</main>
</body>
</html>
|
- Zeilen 15–68: Änderung des Kontos: Identität, Benutzername, neues Passwort (optional) und dessen Bestätigung;
- Zeile 19: die Version der Clientakte (optimistisches Sperren);
- Zeilen 52–61: aktuelles Passwort, für jede Änderung erforderlich;
- Zeilen 71–83: die Löschung, mit Bestätigung. Zwei unabhängige Formulare auf derselben Seite: Jedes sendet nur seine eigenen Felder. Das Passwortfeld hat hier daher einen anderen Namen ([deletePassword]) und eine andere Kennung. Dieses Formular hat nicht das Attribut [novalidate]: Der Browser verlangt das Passwort ([required]) schon vor dem Auslösen des Ereignisses [submit] – also bevor um Bestätigung gebeten wird.
11.17.2.8. templates/error.html
| <!doctype html>
<!--/* =========================================================================
templates/error.html - die Fehlerseite (400, 403, 404, 500...),
vom ErrorController erzeugt.
========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main class="row justify-content-center">
<div class="col-md-8 col-lg-6">
<div class="card p-4 text-center">
<h1 class="display-4 text-danger" th:text="${model.code}">404</h1>
<p class="lead" th:text="#{${model.message}}">This page does not exist.</p>
<div><a class="btn btn-primary" href="/" th:text="#{ERROR_PAGE.BACK}">Back to home</a></div>
</div>
</div>
</main>
</body>
</html>
|
- Zeilen 11–12: Die von [ErrorController] erzeugte Fehlerseite (400, 403, 404, 500): der HTTP-Code und die übersetzte Meldung. Sie verwendet dasselbe Template wie die anderen Seiten: Der Benutzer behält seine Navigationsleiste.
11.18. Die Wörterbücher
Die Wörterbücher sind die der Version [ASP.NET Core MVC], ohne Änderungen: Sie liegen in [src/main/resources/i18n] und werden beim Start vom Service [Translator] gelesen (siehe „Die Web-Schicht: gemeinsame Services“). Dieser Service „flacht“ ihre Struktur ab: Der Text ["TITLE"] aus dem Abschnitt ["LOGIN"] wird zum Meldungsschlüssel [LOGIN.TITLE], der von den Views ([#{LOGIN.TITLE}]) und den Controllern verwendet wird.
11.18.1. i18n/fr.json
| {
"APP": {
"TITLE": "RdvMedecins",
"LOGOUT": "Se déconnecter",
"MENU_SCHEDULE": "Agenda",
"MENU_DOCTORS": "Médecins",
"MENU_PATIENTS": "Clients",
"MENU_MY_AREA": "Mon espace"
},
"LOGIN": {
"TITLE": "Connexion",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Mot de passe",
"SUBMIT": "Se connecter",
"ERROR": "Login ou mot de passe incorrect.",
"DEMO_ACCOUNTS": "Comptes de démonstration (mot de passe = login) :",
"DEMO_ADMIN": "rôle ADMIN : rendez-vous + gestion des médecins et des clients",
"DEMO_DOCTOR": "rôle DOCTOR : prise et annulation de rendez-vous",
"DEMO_USER": "rôle USER (patients) : réservation pour eux-mêmes, gestion de leur compte",
"CREATE_ACCOUNT": "Créer un compte client",
"CREATE_ACCOUNT_HELP": "Pour créer un compte, recopiez d'abord les caractères de l'image."
},
"DOCTOR_DAY_PICKER": {
"DOCTOR_LABEL": "Médecin",
"CHOOSE_DOCTOR": "-- choisir un médecin --",
"DAY_LABEL": "Jour",
"VIEW_SCHEDULE": "Voir l'agenda"
},
"SCHEDULE": {
"PAGE_TITLE": "Agenda",
"TITLE_PREFIX": "Agenda du",
"COLUMN_SLOT": "Créneau",
"COLUMN_STATUS": "Statut",
"FREE": "Libre",
"BOOK": "Réserver",
"CANCEL_APPOINTMENT": "Annuler",
"CANCEL_CONFIRM": "Annuler ce rendez-vous ?",
"EMPTY_STATE": "Choisissez un médecin et un jour, puis cliquez sur « Voir l'agenda ».",
"NO_SLOTS": "Ce médecin n'a aucun créneau horaire.",
"BOOKED": "Rendez-vous enregistré.",
"CANCELLED": "Rendez-vous annulé.",
"BOOKED_BY_OTHER": "Réservé",
"ALREADY_BOOKED_INFO": "Vous avez déjà un rendez-vous à venir : annulez-le pour en prendre un autre."
},
"BOOKING_DIALOG": {
"TITLE": "Réserver ce créneau",
"CLOSE_ARIA": "Fermer",
"SLOT": "Créneau de {time}",
"PATIENT_LABEL": "Patient",
"CHOOSE_PATIENT": "-- choisir un patient --",
"CANCEL": "Annuler",
"CONFIRM": "Confirmer"
},
"PERSONS": {
"COLUMN_TITLE": "Titre",
"COLUMN_FIRSTNAME": "Prénom",
"COLUMN_LASTNAME": "Nom",
"COLUMN_LOGIN": "Login",
"EDIT": "Modifier",
"DELETE": "Supprimer",
"SAVE": "Enregistrer",
"BACK": "Retour à la liste",
"TITLE_LABEL": "Titre",
"FIRSTNAME_LABEL": "Prénom",
"LASTNAME_LABEL": "Nom",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Mot de passe",
"LOGIN_HELP_CREATE": "Facultatif : par défaut, le nom en minuscules.",
"LOGIN_HELP_EDIT": "Laisser vide pour ne pas le changer.",
"PASSWORD_HELP_CREATE": "Facultatif : par défaut, identique au login.",
"PASSWORD_HELP_EDIT": "Laisser vide pour ne pas le changer.",
"ACCOUNT_SECTION": "Compte utilisateur"
},
"DOCTORS": {
"TITLE": "Médecins",
"ADD": "Ajouter un médecin",
"EDIT": "Modifier un médecin",
"EMPTY": "Aucun médecin.",
"DELETE_CONFIRM": "Supprimer ce médecin, ses créneaux horaires et son compte utilisateur ?",
"ADDED": "Le médecin {name} a été ajouté (login : {login}).",
"UPDATED": "Le médecin {name} a été modifié.",
"DELETED": "Le médecin {name} a été supprimé."
},
"CLIENTS": {
"TITLE": "Clients",
"ADD": "Ajouter un client",
"EDIT": "Modifier un client",
"EMPTY": "Aucun client.",
"DELETE_CONFIRM": "Supprimer ce client, son compte utilisateur et tous ses rendez-vous ?",
"ADDED": "Le client {name} a été ajouté (login : {login}).",
"UPDATED": "Le client {name} a été modifié.",
"DELETED": "Le client {name} a été supprimé."
},
"ERROR_PAGE": {
"TITLE": "Erreur",
"BACK": "Retour à l'accueil"
},
"ERRORS": {
"LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
"DOCTOR_ALREADY_EXISTS": "Un médecin portant ce prénom et ce nom existe déjà.",
"PATIENT_ALREADY_EXISTS": "Un client portant ce prénom et ce nom existe déjà.",
"DOCTOR_HAS_APPOINTMENTS": "Ce médecin a des rendez-vous : annulez-les avant de le supprimer.",
"SLOT_ALREADY_BOOKED": "Ce créneau vient d'être réservé par quelqu'un d'autre.",
"CONCURRENT_UPDATE": "Cette fiche a été modifiée entre-temps par un autre utilisateur. Revenez à la liste et rouvrez-la avant de recommencer.",
"DOCTOR_NOT_FOUND": "Ce médecin n'existe pas (ou plus).",
"PATIENT_NOT_FOUND": "Ce client n'existe pas (ou plus).",
"SLOT_NOT_FOUND": "Ce créneau n'existe pas (ou plus).",
"APPOINTMENT_NOT_FOUND": "Ce rendez-vous n'existe pas (ou plus).",
"INVALID_DATE": "La date demandée n'est pas valide.",
"CHOOSE_PATIENT": "Choisissez un patient.",
"INVALID_FORM": "Le formulaire contient des erreurs.",
"INVALID_TITLE": "Choisissez un titre dans la liste.",
"FIRSTNAME_REQUIRED": "Le prénom est obligatoire.",
"FIRSTNAME_TOO_LONG": "Le prénom ne doit pas dépasser 20 caractères.",
"LASTNAME_REQUIRED": "Le nom est obligatoire.",
"LASTNAME_TOO_LONG": "Le nom ne doit pas dépasser 20 caractères.",
"INVALID_LOGIN": "30 caractères au plus : lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
"PASSWORD_TOO_LONG": "Le mot de passe ne doit pas dépasser 72 caractères.",
"SESSION_EXPIRED": "Votre session a expiré : reconnectez-vous.",
"BAD_REQUEST": "La requête est invalide.",
"FORBIDDEN": "Votre rôle ne vous permet pas d'accéder à cette page.",
"NOT_FOUND": "Cette page n'existe pas.",
"SERVER_ERROR": "Une erreur inattendue s'est produite. Réessayez plus tard.",
"TOO_MANY_ATTEMPTS": "Trop de tentatives infructueuses. Réessayez dans {minutes} minute(s).",
"WRONG_CAPTCHA": "Les caractères recopiés ne correspondent pas à l'image. Une nouvelle image vous est proposée.",
"TOO_MANY_ACCOUNTS": "Trop de comptes ont été créés depuis votre connexion. Réessayez dans {minutes} minute(s).",
"LOGIN_REQUIRED": "Le login est obligatoire.",
"PASSWORD_REQUIRED": "Le mot de passe est obligatoire.",
"PASSWORD_TOO_SHORT": "Le mot de passe doit comporter au moins {min} caractères.",
"CONFIRMATION_REQUIRED": "Confirmez le mot de passe.",
"PASSWORDS_DIFFER": "La confirmation ne correspond pas au mot de passe.",
"CURRENT_PASSWORD_REQUIRED": "Saisissez votre mot de passe actuel.",
"WRONG_CURRENT_PASSWORD": "Mot de passe actuel incorrect.",
"PAST_DATE": "On ne peut pas prendre de rendez-vous à une date passée.",
"PATIENT_HAS_UPCOMING_APPOINTMENT": "Ce patient a déjà un rendez-vous à venir : il faut l'annuler avant d'en prendre un autre.",
"CAPTCHA_BEFORE_ACCOUNT": "Pour créer un compte, recopiez d'abord correctement les caractères de l'image, puis cliquez sur « Créer un compte client »."
},
"CAPTCHA": {
"LABEL": "Recopiez les caractères de l'image",
"IMAGE_ALT": "Image de vérification anti-robots",
"NEW_IMAGE": "Autre image",
"HELP": "Majuscules ou minuscules, peu importe."
},
"REGISTRATION": {
"TITLE": "Créer un compte client",
"INTRO": "Ce compte vous permettra de prendre vous-même vos rendez-vous.",
"LOGIN_HELP": "Lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
"PASSWORD_HELP": "Au moins {min} caractères.",
"SUBMIT": "Créer mon compte",
"BACK_TO_LOGIN": "Retour à la connexion",
"DONE": "Votre compte a été créé. Vous pouvez vous connecter avec le login {login}."
},
"ACCOUNT": {
"CONFIRMATION_LABEL": "Confirmation du mot de passe"
},
"AREA": {
"TITLE": "Mon espace",
"HELLO": "Bonjour {name}",
"MANAGE_ACCOUNT": "Gérer mon compte",
"MANAGE_ACCOUNT_HELP": "Modifier mes informations, mon mot de passe, ou supprimer mon compte.",
"VIEW_SCHEDULE": "Voir un agenda",
"VIEW_SCHEDULE_HELP": "Consulter l'agenda d'un médecin et réserver un créneau.",
"MY_APPOINTMENT": "Mon rendez-vous",
"SEE_IN_SCHEDULE": "voir dans l'agenda",
"CANCEL_APPOINTMENT": "Annuler ce rendez-vous",
"NO_APPOINTMENT": "Vous n'avez aucun rendez-vous à venir."
},
"MY_ACCOUNT": {
"TITLE": "Gérer mon compte",
"NEW_PASSWORD_LABEL": "Nouveau mot de passe",
"CURRENT_PASSWORD_LABEL": "Mot de passe actuel",
"CURRENT_PASSWORD_HELP": "Obligatoire pour enregistrer une modification.",
"BACK": "Retour à mon espace",
"DELETE_TITLE": "Supprimer mon compte",
"DELETE_HELP": "Votre compte sera définitivement supprimé, ainsi que tous vos rendez-vous.",
"DELETE_CONFIRM": "Supprimer définitivement votre compte ? Votre rendez-vous éventuel sera annulé.",
"DELETE_SUBMIT": "Supprimer mon compte",
"UPDATED": "Votre compte a été modifié.",
"DELETED": "Votre compte a été supprimé."
},
"CONFIRMATION": {
"TITLE": "Confirmation",
"NO": "Non, revenir",
"YES": "Oui, confirmer"
}
}
|
- Die Abschnitte gruppieren die Texte nach Seite ([LOGIN], [SCHEDULE], [AREA] ...) oder nach Thema ([ERRORS], [CONFIRMATION]). Einige Namen ([DOCTOR_DAY_PICKER], [BOOKING_DIALOG]) stammen aus frühen Versionen der Anwendung, deren Client mit [Angular] geschrieben war;
- Zeile 80: ein Text mit zwei Parametern, [{name}] und [{login}], die bei der Übersetzung ersetzt werden;
- Zeilen 98–137: Fehlermeldungen. Dies sind die Schlüssel, die von der [BusinessException] der Geschäftsschicht, den Validierungsannotationen der Formulare ([@NotBlank(message = "ERRORS.FIRSTNAME_REQUIRED")]), den Controllern und der Fehlerseite verwendet werden. Drei davon haben einen Parameter: [{minutes}] (Zeilen 124 und 126) und [{min}] (Zeile 129).
11.18.2. i18n/en.json
| {
"APP": {
"TITLE": "RdvMedecins",
"LOGOUT": "Log out",
"MENU_SCHEDULE": "Schedule",
"MENU_DOCTORS": "Doctors",
"MENU_PATIENTS": "Patients",
"MENU_MY_AREA": "My area"
},
"LOGIN": {
"TITLE": "Login",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Password",
"SUBMIT": "Log in",
"ERROR": "Incorrect login or password.",
"DEMO_ACCOUNTS": "Demo accounts (password = login):",
"DEMO_ADMIN": "ADMIN role: appointments + doctor and patient management",
"DEMO_DOCTOR": "DOCTOR role: booking and cancelling appointments",
"DEMO_USER": "USER role (patients): booking for themselves, managing their account",
"CREATE_ACCOUNT": "Create a patient account",
"CREATE_ACCOUNT_HELP": "To create an account, first type the characters shown in the image."
},
"DOCTOR_DAY_PICKER": {
"DOCTOR_LABEL": "Doctor",
"CHOOSE_DOCTOR": "-- choose a doctor --",
"DAY_LABEL": "Day",
"VIEW_SCHEDULE": "View schedule"
},
"SCHEDULE": {
"PAGE_TITLE": "Schedule",
"TITLE_PREFIX": "Schedule for",
"COLUMN_SLOT": "Slot",
"COLUMN_STATUS": "Status",
"FREE": "Free",
"BOOK": "Book",
"CANCEL_APPOINTMENT": "Cancel",
"CANCEL_CONFIRM": "Cancel this appointment?",
"EMPTY_STATE": "Choose a doctor and a day, then click \"View schedule\".",
"NO_SLOTS": "This doctor has no time slots.",
"BOOKED": "Appointment booked.",
"CANCELLED": "Appointment cancelled.",
"BOOKED_BY_OTHER": "Booked",
"ALREADY_BOOKED_INFO": "You already have an upcoming appointment: cancel it to book another one."
},
"BOOKING_DIALOG": {
"TITLE": "Book this slot",
"CLOSE_ARIA": "Close",
"SLOT": "Slot {time}",
"PATIENT_LABEL": "Patient",
"CHOOSE_PATIENT": "-- choose a patient --",
"CANCEL": "Cancel",
"CONFIRM": "Confirm"
},
"PERSONS": {
"COLUMN_TITLE": "Title",
"COLUMN_FIRSTNAME": "First name",
"COLUMN_LASTNAME": "Last name",
"COLUMN_LOGIN": "Login",
"EDIT": "Edit",
"DELETE": "Delete",
"SAVE": "Save",
"BACK": "Back to the list",
"TITLE_LABEL": "Title",
"FIRSTNAME_LABEL": "First name",
"LASTNAME_LABEL": "Last name",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Password",
"LOGIN_HELP_CREATE": "Optional: defaults to the last name in lower case.",
"LOGIN_HELP_EDIT": "Leave empty to keep it unchanged.",
"PASSWORD_HELP_CREATE": "Optional: defaults to the login.",
"PASSWORD_HELP_EDIT": "Leave empty to keep it unchanged.",
"ACCOUNT_SECTION": "User account"
},
"DOCTORS": {
"TITLE": "Doctors",
"ADD": "Add a doctor",
"EDIT": "Edit a doctor",
"EMPTY": "No doctors.",
"DELETE_CONFIRM": "Delete this doctor, their time slots and their user account?",
"ADDED": "Doctor {name} has been added (login: {login}).",
"UPDATED": "Doctor {name} has been updated.",
"DELETED": "Doctor {name} has been deleted."
},
"CLIENTS": {
"TITLE": "Patients",
"ADD": "Add a patient",
"EDIT": "Edit a patient",
"EMPTY": "No patients.",
"DELETE_CONFIRM": "Delete this patient, their user account and all their appointments?",
"ADDED": "Patient {name} has been added (login: {login}).",
"UPDATED": "Patient {name} has been updated.",
"DELETED": "Patient {name} has been deleted."
},
"ERROR_PAGE": {
"TITLE": "Error",
"BACK": "Back to the home page"
},
"ERRORS": {
"LOGIN_TAKEN": "This login is already used by another account.",
"DOCTOR_ALREADY_EXISTS": "A doctor with this first and last name already exists.",
"PATIENT_ALREADY_EXISTS": "A patient with this first and last name already exists.",
"DOCTOR_HAS_APPOINTMENTS": "This doctor has appointments: cancel them before deleting the doctor.",
"SLOT_ALREADY_BOOKED": "This slot has just been booked by someone else.",
"CONCURRENT_UPDATE": "This record was changed by another user in the meantime. Go back to the list and reopen it before trying again.",
"DOCTOR_NOT_FOUND": "This doctor does not exist (any more).",
"PATIENT_NOT_FOUND": "This patient does not exist (any more).",
"SLOT_NOT_FOUND": "This slot does not exist (any more).",
"APPOINTMENT_NOT_FOUND": "This appointment does not exist (any more).",
"INVALID_DATE": "The requested date is not valid.",
"CHOOSE_PATIENT": "Choose a patient.",
"INVALID_FORM": "The form contains errors.",
"INVALID_TITLE": "Choose a title from the list.",
"FIRSTNAME_REQUIRED": "The first name is required.",
"FIRSTNAME_TOO_LONG": "The first name must not exceed 20 characters.",
"LASTNAME_REQUIRED": "The last name is required.",
"LASTNAME_TOO_LONG": "The last name must not exceed 20 characters.",
"INVALID_LOGIN": "At most 30 characters: unaccented lower-case letters, digits, dot, hyphen, underscore.",
"PASSWORD_TOO_LONG": "The password must not exceed 72 characters.",
"SESSION_EXPIRED": "Your session has expired: please log in again.",
"BAD_REQUEST": "The request is invalid.",
"FORBIDDEN": "Your role does not allow you to access this page.",
"NOT_FOUND": "This page does not exist.",
"SERVER_ERROR": "An unexpected error occurred. Please try again later.",
"TOO_MANY_ATTEMPTS": "Too many failed attempts. Try again in {minutes} minute(s).",
"WRONG_CAPTCHA": "The characters you typed do not match the image. A new image is shown.",
"TOO_MANY_ACCOUNTS": "Too many accounts have been created from your connection. Try again in {minutes} minute(s).",
"LOGIN_REQUIRED": "The login is required.",
"PASSWORD_REQUIRED": "The password is required.",
"PASSWORD_TOO_SHORT": "The password must be at least {min} characters long.",
"CONFIRMATION_REQUIRED": "Please confirm the password.",
"PASSWORDS_DIFFER": "The confirmation does not match the password.",
"CURRENT_PASSWORD_REQUIRED": "Enter your current password.",
"WRONG_CURRENT_PASSWORD": "Incorrect current password.",
"PAST_DATE": "Appointments cannot be booked for a past date.",
"PATIENT_HAS_UPCOMING_APPOINTMENT": "This patient already has an upcoming appointment: it must be cancelled before booking another one.",
"CAPTCHA_BEFORE_ACCOUNT": "To create an account, first type the characters shown in the image correctly, then click \"Create a patient account\"."
},
"CAPTCHA": {
"LABEL": "Type the characters shown in the image",
"IMAGE_ALT": "Anti-robot verification image",
"NEW_IMAGE": "Another image",
"HELP": "Upper or lower case, it does not matter."
},
"REGISTRATION": {
"TITLE": "Create a patient account",
"INTRO": "With this account you can book your own appointments.",
"LOGIN_HELP": "Unaccented lower-case letters, digits, dot, hyphen, underscore.",
"PASSWORD_HELP": "At least {min} characters.",
"SUBMIT": "Create my account",
"BACK_TO_LOGIN": "Back to login",
"DONE": "Your account has been created. You can now log in with the login {login}."
},
"ACCOUNT": {
"CONFIRMATION_LABEL": "Confirm password"
},
"AREA": {
"TITLE": "My area",
"HELLO": "Hello {name}",
"MANAGE_ACCOUNT": "Manage my account",
"MANAGE_ACCOUNT_HELP": "Change my details or password, or delete my account.",
"VIEW_SCHEDULE": "View a schedule",
"VIEW_SCHEDULE_HELP": "See a doctor's schedule and book a slot.",
"MY_APPOINTMENT": "My appointment",
"SEE_IN_SCHEDULE": "see in the schedule",
"CANCEL_APPOINTMENT": "Cancel this appointment",
"NO_APPOINTMENT": "You have no upcoming appointment."
},
"MY_ACCOUNT": {
"TITLE": "Manage my account",
"NEW_PASSWORD_LABEL": "New password",
"CURRENT_PASSWORD_LABEL": "Current password",
"CURRENT_PASSWORD_HELP": "Required to save any change.",
"BACK": "Back to my area",
"DELETE_TITLE": "Delete my account",
"DELETE_HELP": "Your account will be permanently deleted, together with all your appointments.",
"DELETE_CONFIRM": "Permanently delete your account? Any appointment you have will be cancelled.",
"DELETE_SUBMIT": "Delete my account",
"UPDATED": "Your account has been updated.",
"DELETED": "Your account has been deleted."
},
"CONFIRMATION": {
"TITLE": "Confirmation",
"NO": "No, go back",
"YES": "Yes, confirm"
}
}
|
Das englische Wörterbuch hat exakt dieselben Schlüssel in denselben Zeilen.
11.19. Die statischen Dateien
[Spring Boot] liefert die Dateien des Ordners [src/main/resources/static] unverändert aus (siehe Beispiel 15): [static/css/styles.css] wird unter der Adresse [/css/styles.css] ausgeliefert. Diese Adressen sind in [SecurityConfig] als öffentlich deklariert, damit die Anmeldeseite ihre Stile erhält. Der Ordner [static/lib/bootstrap] enthält [Bootstrap] (sein Stylesheet [css/bootstrap.min.css] und seine Lizenz), das hier nicht angezeigt wird.
11.19.1. static/css/styles.css
| /* =========================================================================
static/css/styles.css - einige Einstellungen zusätzlich zu Bootstrap
(dieselben wie in der ASP.NET-Core-MVC-Version dieser Anwendung).
========================================================================= */
body {
background-color: #f5f7fa;
}
.free-slot:hover {
background-color: #e9f7ef;
}
/* ─────────────────────────────────────────────────────────────────────────
.error-zone: die Fehlermeldungen am Seitenende auf hellrosa Hintergrund
(siehe templates/fragments/errors.html).
position: sticky + bottom: Ist die Seite höher als das Fenster (ein
Terminkalender mit 12 Zeitfenstern zum Beispiel), bleibt die Zone am unteren Rand des
Fensters haften, statt unterhalb des sichtbaren Bereichs zu verschwinden - ohne je
den Inhalt zu verdecken, wenn die Seite niedrig ist.
z-index: über dem grauen Hintergrund des Buchungsdialogs (.modal-backdrop).
───────────────────────────────────────────────────────────────────────── */
.error-zone {
position: sticky;
bottom: 1rem;
z-index: 1060;
margin-top: 1.5rem;
padding: 0.75rem 1rem;
background-color: #fdecef; /* hellrosa */
border: 1px solid #f5c2c7;
border-radius: 0.375rem;
color: #842029;
}
/* die beiden großen Optionen der Seite "My area" des Patienten */
.option-card {
transition: border-color 0.15s, box-shadow 0.15s;
}
.option-card:hover {
border-color: #0d6efd;
box-shadow: 0 0.25rem 0.75rem rgba(13, 110, 253, 0.15);
}
/* das CAPTCHA-Bild (SVG, 150 x 50 Pixel) */
.captcha-image svg {
display: block;
border: 1px solid #dee2e6;
border-radius: 0.375rem;
}
|
- Zeilen 10–12: Ein buchbares Zeitfenster ändert beim Überfahren mit der Maus seine Farbe;
- Zeilen 23–33: der Fehlerbereich auf hellrosa Hintergrund. [position: sticky] und [bottom: 1rem]: Ist die Seite höher als das Fenster, bleibt der Bereich am unteren Fensterrand, statt aus dem Bildschirm zu verschwinden; [z-index] platziert ihn über dem ausgegrauten Hintergrund des Buchungsfensters;
- Zeilen 36–43: Die beiden Optionen von „Mein Bereich“ reagieren auf das Überfahren mit der Maus;
- Zeilen 46–50: der Rahmen des CAPTCHA-Bildes.
11.19.2. static/js/app.js
| // =========================================================================
// static/js/app.js - das EINZIGE JavaScript der Anwendung.
// -------------------------------------------------------------------------
// Die gesamte Anwendung funktioniert ohne JavaScript. Dieses Skript fügt eine
// Komfortfunktion hinzu: Vor dem Senden eines Formulars mit dem Attribut
// data-confirmation="..." fragt ein modaler Dialog "Are you sure?"
// (der Dialog selbst steht in der Seite: templates/fragments/confirmation.html).
// Ist JavaScript deaktiviert, wird das Formular einfach ohne
// Bestätigung gesendet - nichts geht kaputt (Prinzip "Progressive Enhancement").
//
// Warum nicht window.confirm()? Sein Fenster lässt sich nicht gestalten, und seine
// Schaltflächen bleiben in der Sprache des Browsers, nicht in der der Seite.
// =========================================================================
(() => {
const modal = document.getElementById('confirmation-modal');
if (!modal) {
return;
}
const message = document.getElementById('confirmation-modal-message');
const noButton = modal.querySelector('.modal-footer [data-action="no"]');
let pendingForm = null; // das Formular, das gesendet wird, wenn der Benutzer bestätigt
let previousFocus = null; // das Element, das beim Schließen den Fokus zurückerhält
function open(form) {
pendingForm = form;
previousFocus = document.activeElement;
// textContent (und nicht innerHTML): Die Nachricht wird als TEXT angezeigt,
// nie als HTML interpretiert
message.textContent = form.dataset.confirmation;
modal.classList.remove('d-none');
// der Fokus geht auf "No": Ein unbedachtes Drücken der Eingabetaste löscht nichts
noButton.focus();
}
function close() {
modal.classList.add('d-none');
pendingForm = null;
if (previousFocus) {
previousFocus.focus();
}
}
// 1. wir fangen das Senden der zu bestätigenden Formulare ab
document.querySelectorAll('form[data-confirmation]').forEach((form) => {
form.addEventListener('submit', (event) => {
event.preventDefault();
open(form);
});
});
// 2. die Schaltflächen des Dialogs (Yes / No / Schließen-Kreuz)
modal.addEventListener('click', (event) => {
const action = event.target.closest('[data-action]')?.dataset.action;
if (action === 'yes') {
const form = pendingForm;
close();
// form.submit() sendet das Formular, OHNE das Ereignis
// 'submit' erneut auszulösen: keine neue Bestätigungsabfrage
form.submit();
} else if (action === 'no') {
close();
} else if (event.target.classList.contains('modal')) {
close(); // Klick auf den grauen Hintergrund, außerhalb des Dialogs
}
});
// 3. Tastatur: Escape schließt den Dialog; Tab bleibt IM Dialog
// (sonst würde der Fokus auf die ausgegraute Seite dahinter gehen)
modal.addEventListener('keydown', (event) => {
if (event.key === 'Escape') {
close();
} else if (event.key === 'Tab') {
const buttons = [...modal.querySelectorAll('button')];
const first = buttons[0];
const last = buttons[buttons.length - 1];
if (event.shiftKey && document.activeElement === first) {
event.preventDefault();
last.focus();
} else if (!event.shiftKey && document.activeElement === last) {
event.preventDefault();
first.focus();
}
}
});
})();
|
Das Skript für das Bestätigungsfenster aus Beispiel 21, erweitert um die Tastaturbedienung. Es folgt demselben Prinzip der progressiven Erweiterung: Ohne [JavaScript] werden die Formulare ohne Bestätigung abgesendet, und die Anwendung funktioniert weiterhin.
- Zeile 15: Das gesamte Skript ist in eine Funktion eingeschlossen, die sofort aufgerufen wird ([(() => { ... })()]): Ihre Variablen sind für andere Skripte der Seite nicht sichtbar;
- Zeilen 16–19: Eine Seite ohne Bestätigungsfenster hat nichts zu tun;
- Zeile 24: das Element, das vor dem Öffnen des Fensters den Tastatur-Fokus hatte (das Element, das die Tastatureingaben empfängt): Beim Schließen des Fensters erhält es den Fokus zurück;
- Zeilen 26–35: Das Fenster öffnet sich mit der formularspezifischen Meldung ([form.dataset.confirmation] ist der Wert seines Attributs [data-confirmation]); der Fokus wird auf „Nein, zurück“ gesetzt: Ein versehentliches Drücken der Eingabetaste löscht nichts;
- Zeilen 37–43: Das Fenster wird ausgeblendet und der Fokus wiederhergestellt;
- Zeilen 46–51: Das Absenden von Formularen mit dem Attribut [data-confirmation] wird abgefangen, wie in Beispiel 21;
- Zeilen 54–67: „Ja“, „Nein“, die Schaltfläche zum Schließen und ein Klick außerhalb des Fensters. [closest('[data-action]')] findet das Element mit dem Attribut, auch wenn auf ein darin enthaltenes Element geklickt wurde. Der Operator [?.] liefert [undefined] , statt zu scheitern, wenn kein Element gefunden wird;
- Zeilen 71–86: Die Esc-Taste schließt das Fenster; die Tab-Taste (und Umschalt+Tab) lässt den Fokus zwischen den Schaltflächen des Fensters kreisen, statt ihn auf die ausgegraute Seite dahinter wandern zu lassen.