Skip to Content

Wiki source code of Basisprojekt

Version 69.1 by Marco Grawunder on 2026/10/19 15:33
Hide last authors
Marco Grawunder 62.1 1 [[image:Main.Organisatorisches.WebHome@softwareprojekt_logo_transparent.png||alt="SoftwareprojektLogo.png" data-xwiki-image-style-alignment="end" height="136" width="309"]]
2
Marco Grawunder 63.1 3 {{info}}
Marco Grawunder 65.1 4 **Worum geht es auf dieser Seite?**
5
6 Diese Seite erklärt den **Einstieg in das bereitgestellte Basisprojekt** und die darin verwendete Client-Server-Kommunikation. Behandelt werden insbesondere Einrichtung und Build, Spring, REST/OpenAPI, DTOs sowie WebSockets/STOMP.
7
8 Das Basisprojekt verwendet mindestens **Java 21**. Screenshots können sich bei neueren Versionen optisch unterscheiden.
Marco Grawunder 63.1 9 {{/info}}
Marco Grawunder 62.1 10
11 {{toc/}}
12
13
14 = Basisprojekt mit IntelliJ einrichten =
15
16 [[image:1755245956916-184.png]]
17
Marco Grawunder 63.1 18 == Repository klonen ==
Marco Grawunder 62.1 19
Marco Grawunder 63.1 20 {{warning}}
21 Im Screenshot wird teilweise das globale Basisprojekt gezeigt. **Verwenden Sie für die Arbeit das bereits für Ihre Gruppe angelegte Repository.**
22 {{/warning}}
Marco Grawunder 62.1 23
24 Sie finden die Clone-URL wie folgt:
25
26 * Loggen Sie sich auf [[https:~~/~~/gitlab.swl.informatik.uni-oldenburg.de/>>https://gitlab.swl.informatik.uni-oldenburg.de/]] ein
27 * Falls nicht vorausgewählt, wählen Sie auf der linken Seite "Projects"
28 [[image:1757398628416-879.png||height="119" width="541"]]
29 * Da Sie bisher noch nichts gemacht haben, ist diese Seite leer. Wechseln Sie auf den Reiter Member
30 * Dort sollte ihr Repository zu finden sein.
31 * Oben rechts gibt es einen Button Code. Kopieren Sie dort die URL, die hinter "Clone with HTTPS" steht.
32 [[image:1757398731084-704.png||height="454" width="323"]]
33
34 [[image:1755245971657-468.png]]
35
36 == Access Token ==
37
Marco Grawunder 64.1 38 {{expandable summary="Schritt-für-Schritt: Access Token einrichten"}}
Marco Grawunder 63.1 39 Beim ersten Git-Zugriff über HTTPS werden Zugangsdaten benötigt. Statt des normalen Passworts sollte ein persönlicher **Access Token** verwendet werden. Öffnen Sie dazu Ihr Profilbild, wählen Sie **Edit profile** und anschließend **Access tokens**.
Marco Grawunder 62.1 40
41 [[image:1757398899497-714.png||height="246" width="278"]]
42
43 Dort können Sie mit [[image:1757398947128-748.png||height="89" width="197"]] ein neues Token anlegen.
44
Marco Grawunder 63.1 45 Als Namen kann z. B. `IntelliJ` verwendet werden. Access Tokens sind aus Sicherheitsgründen zeitlich begrenzt. Wählen Sie ein Ablaufdatum, das zum Projektzeitraum passt.
Marco Grawunder 62.1 46
47 [[image:1757399088336-273.png||height="92" width="547"]]
48
49 Bei den Scopes sollten die beiden Rechte "read_repository" und "write_repository" gewählt werden.
50
51 Danach wird das Access Token generiert
52
53 [[image:1757399184270-348.png||height="99" width="978"]]
54
Marco Grawunder 63.1 55 {{warning}}
56 Kopieren und speichern Sie das erzeugte Token unmittelbar. Es wird nach der Erstellung nicht erneut vollständig angezeigt. **Tokens dürfen niemals in das Repository eingecheckt werden.**
Marco Grawunder 66.1 57 {{/warning}}
Marco Grawunder 62.1 58
Marco Grawunder 64.1 59 Beim **Einloggen **(Achtung! Gemeint ist hier, wenn Intellij (bzw. git) nach den Account-Daten beim Clonen fragt. Man kann auch einen Gitlab-Account hinterlegen (der dann aber parallel existiert). Hier für ist es wichtig, dass noch "api" und "read_user" als Recht vergeben wird.) in IntelliJ können Sie dieses Token im Passwort-Feld verwenden. Geben Sie ihren Account bei Name ein.
60 {{/expandable}}
Marco Grawunder 62.1 61
Marco Grawunder 66.2 62 == SSH ==
63
64 Hinweis: Man kann jetzt auch mit SSH clonen. Da gitlab aber hinter einem Reverseproxy liegt, geht das nur mit der direkten Adresse des Host:  vmisdata07.uni-oldenburg.de. Ist nun auch in Gitlab zu konfiguriert:
65
Marco Grawunder 68.1 66 [[image:1792324965203-193.png]]
67
Marco Grawunder 63.1 68 == Nach dem Klonen ==
Marco Grawunder 62.1 69
70 sollten Sie einen Bildschirm ähnlich zu dem folgenden sehen:
71
72 [[image:1755245980026-164.png]]
73
74 Auf dem main-Branch (master) kann keine Änderung gemacht werden, deswegen muss auf einen anderen Branch gewechselt werden. Im Beispiel development.
75
76 [[image:1755245996886-733.png]]
77
Marco Grawunder 63.1 78 == Initialer Maven-Build und Codegenerierung ==
Marco Grawunder 62.1 79
Marco Grawunder 63.1 80 Nach einem frischen Checkout fehlen zunächst generierte Quellen. Führen Sie deshalb einen Maven-Build aus. Eine erneute Generierung ist insbesondere notwendig, wenn die OpenAPI-Beschreibung geändert wurde oder generierte Quellen fehlen.
Marco Grawunder 62.1 81
82 [[image:1755246008466-477.png]]
83
84
85 [[image:1755246018789-616.png]]
86
87
Marco Grawunder 63.1 88 == Lombok-Plugin ==
Marco Grawunder 62.1 89
Marco Grawunder 63.1 90 Falls das Lombok-Plugin noch nicht installiert ist, installieren bzw. aktivieren Sie es in IntelliJ.
Marco Grawunder 62.1 91
92 [[image:1755248508652-523.png]]
93
Marco Grawunder 63.1 94 Je nach IntelliJ-Edition kann zusätzlich das Spring-/Spring-Boot-Plugin hilfreich sein.
Marco Grawunder 62.1 95
96 [[image:1756886220468-891.png]]
97
Marco Grawunder 69.1 98 == Probleme mit Maven oder IntelliJ ==
99
100 Falls IntelliJ nach dem Klonen des Repositories nicht alle Abhängigkeiten oder Klassen erkennt, überprüfen Sie bitte folgende Punkte:
101
102 1. **Java-Version:** Das Basisprojekt benötigt mindestens Java 21. Kontrollieren Sie mit java -version und mvn -version, welche Versionen verwendet werden.
103 1. **IntelliJ-Projekt:** Öffnen Sie das gesamte Projekt mit der übergeordneten pom.xml, nicht nur das Server- oder Client-Verzeichnis.
104 1. **Maven-Konfiguration:** Überprüfen Sie unter //Settings → Build Tools → Maven//, ob Maven mit einem passenden JDK ausgeführt wird.
105 1. **Maven aktualisieren:** Öffnen Sie das Maven-Toolfenster und wählen Sie //Reload All Maven Projects//.
106 1. (((
107 **Projekt bauen:** Öffnen Sie ein Terminal im Hauptverzeichnis des Projekts und führen Sie folgenden Befehl aus:
108
109 mvn -U clean install -DskipTests
110 )))
111 1. **Generierte Klassen:** Stellen Sie sicher, dass die durch OpenAPI generierten Java-Klassen unter target/generated-sources vorhanden sind und von IntelliJ erkannt werden.
112 1. **Lombok:** Prüfen Sie, ob das Lombok-Plugin aktiviert ist und Annotation Processing korrekt funktioniert.
113 1. **Server starten:** Starten Sie die Klasse ServerApp im Server-Modul. Überprüfen Sie bei Problemen die Java-Version und die Startkonfiguration.
114
115 **Hinweis:** Wenn Maven im Terminal erfolgreich durchläuft, IntelliJ aber weiterhin Fehler anzeigt, liegt das Problem häufig an der IntelliJ-Projektkonfiguration und nicht an den Abhängigkeiten selbst.
116
117 Sollte der Server anschließend weiterhin nicht starten, teilen Sie bitte die erste aussagekräftige Fehlermeldung aus dem Run-Fenster beziehungsweise den ersten relevanten Caused by-Eintrag mit.
118
Marco Grawunder 63.1 119 == Server starten ==
Marco Grawunder 62.1 120
121 Den Serverbereich aufklappen und dort auf die Datei ServerApp mit der rechten Maustaste klicken.
122
123 [[image:1755246035428-328.png]]
124
125
Marco Grawunder 63.1 126 Falls IntelliJ nach dem Start Annotation Processing für Lombok anbietet, aktivieren Sie es. Ohne korrekt eingerichtetes Lombok bzw. Annotation Processing werden Änderungen gegebenenfalls erst nach einem erneuten Maven-Build korrekt erkannt.
Marco Grawunder 62.1 127
128 [[image:1755246072443-191.png]]
129
130
131 [[image:1755246118807-452.png]]
132
133
134 == Logging umstellen ==
135
Marco Grawunder 64.1 136 {{expandable summary="Schritt-für-Schritt: Logging konfigurieren"}}
Marco Grawunder 62.1 137 Wenn man möchte, kann man das Logging umstellen.
138
139 [[image:1755246135109-325.png]]
140
141
142 [[image:1755246147827-679.png]]
143
144
145 [[image:1755246162330-595.png]]
Marco Grawunder 64.1 146 {{/expandable}}
Marco Grawunder 62.1 147
Marco Grawunder 63.1 148 == Development-Profil aktivieren ==
Marco Grawunder 62.1 149
Marco Grawunder 64.1 150 {{expandable summary="Schritt-für-Schritt: Development-Profil aktivieren"}}
Marco Grawunder 63.1 151 Für lokale Tests existiert das Spring-Profil `dev`. Darin werden automatisch vorbereitete Testnutzer (`user1` bis `user9`) angelegt, sodass nicht für jeden Testlauf neue Konten registriert werden müssen.
Marco Grawunder 62.1 152
153 Wenn man die Anwendung einmal gestartet hat, kann man dies Configuration anpassen:
154
155 [[image:1757399848941-253.png||height="209" width="558"]]
156
157 [[image:1755246173415-934.png]]
158
159
Marco Grawunder 63.1 160 Wenn die verwendete IntelliJ-Version keine Spring-Unterstützung bietet, kann das Profil über eine Umgebungsvariable in der Server-Konfiguration gesetzt werden:
Marco Grawunder 62.1 161
162 **SPRING_PROFILES_ACTIVE=dev**
163
164 [[image:1755248752596-839.png]]
165
166 Danach muss man den Server neu starten!
Marco Grawunder 64.1 167 {{/expandable}}
Marco Grawunder 62.1 168
169 == Client starten ==
170
171 Wenn der Server gestartet ist, kann man mehrere Clients starten. Dafür auf jeden Fall die Klasse Main verwenden.
172
Marco Grawunder 63.1 173 {{warning}}
174 Falls der Start fehlschlägt, prüfen Sie insbesondere die tatsächlich verwendete Java-Version. Für das Basisprojekt wird mindestens **Java 21** benötigt.
175 {{/warning}}
Marco Grawunder 62.1 176
177 [[image:1755246257400-525.png]]
178
179
180 [[image:1755246212916-883.png]]
181
182
183 [[image:1755246223246-834.png]]
184
185
186 === Mehrere Instanzen des Clients ermöglichen ===
187
Marco Grawunder 64.1 188 {{expandable summary="Schritt-für-Schritt: mehrere Client-Instanzen starten"}}
Marco Grawunder 62.1 189 Standardmäßig erlaubt IntelliJ nicht das Starten mehrerer Clients. Man könnte nun mehrere Configurations für den Client anlegen. Man kann aber auch in der Konfiguration unter "Modify options" den Haken bei "Allow multiple instances" setzen. Dann kann eine beliebige Anzahl von Clients gestartet werden.
190
191 [[image:1755246233218-893.png]]
192
193
Marco Grawunder 63.1 194 Falls die Anmeldung eines vorbereiteten Testnutzers fehlschlägt, prüfen Sie insbesondere, ob das `dev`-Profil aktiv ist und der Benutzer angelegt wurde. Läuft der Server nicht, erscheint in der Regel eine andere Fehlermeldung.
Marco Grawunder 62.1 195
196 [[image:1755246292057-581.png]]
Marco Grawunder 64.1 197 {{/expandable}}
Marco Grawunder 62.1 198
Marco Grawunder 63.1 199 = Überblick über das Basisprojekt =
Marco Grawunder 62.1 200
201 [[image:1755249096987-249.png]]
202
203
204 [[image:1755249136156-419.png]]
205
206
Marco Grawunder 63.1 207 == Projektstruktur ==
Marco Grawunder 62.1 208
209 [[image:1755249228556-469.png]]
210
211
Marco Grawunder 63.1 212 = Kommunikation vom Client zum Server: REST =
Marco Grawunder 62.1 213
214 [[image:1755249285866-367.png]]
215
Marco Grawunder 63.1 216 Für klassische Request/Response-Operationen verwendet das Basisprojekt **REST über HTTP**. Als Austauschformat wird **JSON** verwendet. Die zentrale Spiellogik verbleibt auf dem Server.
Marco Grawunder 62.1 217
218 = OpenAPI =
219
Marco Grawunder 63.1 220 {{info}}
221 Die grafische OpenAPI-Darstellung hängt von der verwendeten IntelliJ-Edition und den installierten Plugins ab. Falls sie nicht verfügbar ist, kann ein geeignetes OpenAPI-Plugin installiert werden.
222 {{/info}}
Marco Grawunder 62.1 223
Marco Grawunder 66.1 224 {{info}}
225 Es gibt (als Beta-Version) ein Plugin für IntelliJ mit dem die Berbeitung, gerade zu Anfang hoffentlich etwas einfacher funktioniert. Zu finden ist das Plugin hier: https://swl.informatik.uni-oldenburg.de/swp/downloads/openapi/ (Achtung! Muss von der Platte installiert werden. Siehe https://www.jetbrains.com/help/idea/managing-plugins.html#install_plugin_from_disk
226 {{/info}}
227
Marco Grawunder 62.1 228 [[image:1755250026156-269.png]]
229
230 [[image:1755250050031-304.png]]
231
232 * **Paths**: Endpunkte der API (z.B. /users, /lobbies).
233 * **Operations**: Spezifikation von Methoden wie GET, POST.
Marco Grawunder 63.1 234 * **Schemas**: Beschreibung der Datenstrukturen für Ein- und Ausgaben.
Marco Grawunder 62.1 235 * **Security**: Authentifizierungsmechanismen.
236
237 [[image:1755250061990-172.png]]
238
Marco Grawunder 63.1 239 OpenAPI-Dokumente können in JSON oder YAML formuliert werden. **YAML** steht heute rekursiv für „YAML Ain't Markup Language“ und ist für menschenlesbare Konfigurations- und Beschreibungsdateien häufig kompakter als JSON.
Marco Grawunder 62.1 240
241 [[image:1755250157536-746.png]]
242
243 Die aktuelle Version des OpenAPI Dokumentes findet sich im Basisprojekt 2 [[https:~~/~~/gitlab.swl.informatik.uni-oldenburg.de/SPB/SWPBasisprojekt2/-/blob/master/openapi.yaml?ref_type=heads>>https://gitlab.swl.informatik.uni-oldenburg.de/SPB/SWPBasisprojekt2/-/blob/master/openapi.yaml?ref_type=heads]]
244
245 Dort wird die Datei auch grafisch dargestellt.
246
247
248 = Maven und OpenAPI =
249
Marco Grawunder 63.1 250 Die OpenAPI-Datei kann verwendet werden, um Teile der [[REST-Schnittstelle>>doc:Main.Basisprojekt.WebHome||anchor="HErweiterungderREST-Schnittstelle"]] zu generieren. Dafür wird der OpenAPI Generator eingesetzt [[https:~~/~~/github.com/OpenAPITools/openapi-generator>>https://github.com/OpenAPITools/openapi-generator]]
Marco Grawunder 62.1 251
Marco Grawunder 63.1 252 Die Generierung kann über die Kommandozeile erfolgen; im Basisprojekt ist sie bereits in den Maven-Build integriert.
Marco Grawunder 62.1 253
254 Dafür ist in den Maven-Dateien bereits das OpenAPI Generator Plugin integriert. Da im Client und im Server unterschiedliche Arten verwendet werden, erfolgt die Konfiguration im Client und im Server unterschiedlich:
255
256 == Client ==
257
Marco Grawunder 63.1 258 Im Java-Client wird ein HTTP-Client für den Zugriff auf die generierte API verwendet.
Marco Grawunder 62.1 259
260
261 [[image:1756887005209-855.png]]
262
263 == Server ==
264
Marco Grawunder 63.1 265 Auf der Serverseite werden Spring-/Spring-Boot-kompatible Schnittstellen und Controller-Strukturen generiert.
Marco Grawunder 62.1 266
267 [[image:1756887037619-847.png]]
268
Marco Grawunder 63.1 269 {{info}}
270 Weiterführende technische Konzepte des Basisprojekts sind insbesondere **Lombok**, **Dependency Injection** und **Spring Boot**. Für Spring bietet z. B. der folgende Leitfaden eine ausführlichere Einführung: [[Spring Framework Guide>>url:https://www.marcobehler.com/guides/spring-framework]].
271 {{/info}}
Marco Grawunder 62.1 272
273
274
275 = Erweiterung der REST-Schnittstelle =
276
Marco Grawunder 64.1 277 {{expandable summary="Ausführliches Beispiel: REST-Schnittstelle erweitern"}}
Marco Grawunder 62.1 278 In diesem Beispiel wird einmal gezeigt, wie die REST-Schnittstelle des Basisprojektes einfach erweitert werden kann.
279
280 In diesem Beispiel soll die aktuelle Schnittstelle um die Möglichkeit erweitert werden, alle Lobbies vom Server zu bekommen.
281
Marco Grawunder 63.1 282 == Schritt 1: OpenAPI-Dokument erweitern ==
Marco Grawunder 62.1 283
284 Um diese neue Funktion sowohl im Client als auch im Server verwenden zu können, ist es notwendig, diese neue Funktion im OpenAPI-Dokument zu definieren.
285
286 Die Funktion soll sehr einfach sein und keine Parameter verlangen. Dafür bietet sich die GET-Funktion an.
287
288 Im folgenden Bild sind alle Anpassungen zu sehen:
289
290 [[image:1756887436525-790.png||height="355" width="974"]]
291
292
293 Nach dem Speichern, sollte das OpenAPI-Dokument wie folgt aussehen
294
295 [[image:1756887488020-376.png||height="642" width="904"]]
296
297
298 Jetzt kann man entweder in IntelliJ
299
300 [[image:1756888245896-845.png||height="347" width="620"]]
301
302 oder im Terminal (z.B. auch in IntelliJ)
303
304 [[image:1756888279902-777.png||height="637" width="1053"]]
305
306 Wobei hier auch clean compile reichen würde.
307
308 **ACHTUNG! Falls maven Problem macht, kann das auch an einer falschen Java-Version im System liegen (siehe auch [[FAQ>>doc:.Basisprojekt FAQ.WebHome]])**
309
310 Es werden durch den Aufruf neue Inhalte generiert (bzw. die alten überschrieben).
311
312 [[image:1756888428042-802.png||height="538" width="1077"]]
313
314 Hinweis: Niemals Änderungen unterhalb des target-Ordners machen. Das wird von Maven bei clean gelöscht.
315
Marco Grawunder 63.1 316 === Wo wird die eigentliche Funktionalität implementiert? ===
Marco Grawunder 62.1 317
Marco Grawunder 63.1 318 Für jeden API-Bereich (z. B. `lobbies` und `users`) werden serverseitig typischerweise mehrere Schnittstellen bzw. Klassen generiert:
Marco Grawunder 62.1 319
320 * *Api (z.B, LobbiesApi): Beschreibung der REST-Methoden, vor allem auch das Mapping von z.B. /lobbies/join auf die Methode lobbyJoin(String)
321 * (((
322 *ApiController implements *Api (Für Spring) (z.B. LobbiesApiController)
323 )))
324 * (((
Marco Grawunder 63.1 325 * `*ApiDelegate` (z. B. `LobbiesApiDelegate`): Delegationsschnittstelle. Die fachliche Implementierung erfolgt **im eigenen, nicht generierten Code**.
Marco Grawunder 62.1 326 )))
327
328
329
330 == Schritt 2: Erweiterung auf Server-Seite ==
331
332 Da es schon Funktionen für die Lobbies gibt, gibt es auch bereits eine Implementierung, die LobbiesApiDelegate überschreibt
333
334 [[image:1756888762381-912.png||height="48" width="789"]]
335
Marco Grawunder 63.1 336 Für die fachliche Umsetzung wird ein eigener Service bzw. eine passende Delegate-Implementierung verwendet. Soll die Klasse von Spring verwaltet werden, muss sie als Spring-Komponente im Application Context registriert sein.
Marco Grawunder 62.1 337
338 In der Klasse muss man dann die neue Methode lobbyList aus der API überschreiben.
339
340 [[image:1756888929507-312.png||height="156" width="1161"]]
341
342 Dabei wird folgendes gemacht:
343
344 1. Es wird ein Rückgabeobjekt vom Typ Liste erzeugt
345 1. Es wird über alles Lobbies auf dem Server gegangen (lobbyManagement.getLobbies())
346 1. Da der Client u.U. nicht die vollständigen Informationen über die Lobbies bekommen soll, gibt es zwei unterschiedliche Klassen: ServerLobby und LobbyDTO.
347 1. Die Foreach-Schleife sorgt dafür, dass in das Rückgabeobjekt nur die LobbyDTOs eingefügt werden.
348 1. Dafür wird eine Funktion mit dem Namen lobbyMapping verwendet
349 1. Schließlich wird am Ende gesagt, dass alles ok ist und eine Antwort ResponseEntity.ok mit dem Rückgabeobjekt (lobbies) gesendet.
350
351 **Anmerkung**: Das Basisprojekt ist aktuell so eingerichtet, dass Spring Exceptions auffängt und entsprechend an den Client leitet. Diese findet in der Klasse  GlobalExceptionHandler statt
352
353 Auf Server-Seite fehlt jetzt noch die Methode getLobbies im LobbyManagement
354
355 [[image:1756889590500-656.png||height="81" width="518"]]
356
357
358 === LobbyMapping ===
359
Marco Grawunder 63.1 360 Da interne Serverobjekte häufig in DTOs überführt werden müssen, verwendet das Basisprojekt **MapStruct**. Die DTOs werden in der Regel aus der OpenAPI-Beschreibung generiert; das Mapping zwischen internem Modell und DTO wird im eigenen Code definiert.
Marco Grawunder 62.1 361
362 Also z.B.
363
364 [[image:1756889440395-856.png]]
365
366 und definiert ein Interface mit einer Annotation
367
368 [[image:1756889472103-847.png]]
369
370 und damit kann man die Funktion aufrufen. Hinweis: Der Mapper ist im LobbyService über die Spring Dependency Injection gebunden.
371
372 == Schritt 3: Erweiterung auf Client-Seite (Java) ==
373
Marco Grawunder 63.1 374 {{info}}
375 Dieses Beispiel bezieht sich auf den Java-Client. Bei Web-Clients, z. B. mit Angular oder React, unterscheidet sich die konkrete technische Integration; der OpenAPI-Vertrag bleibt jedoch derselbe.
376 {{/info}}
Marco Grawunder 62.1 377
378 Auf der Client-Seite wird die komplette Kommunikation mit dem Server in der generierten Klasse DefaultApi gekapselt.
379
380 [[image:1756889795622-530.png]]
381
382 Dort gibt es eine neue Methode lobbyList. Die sorgt dafür, dass der REST-Aufruf auf die Server-Seite geht und liefert das passende Objekt List<LobbyDTO> zurück
383
384 Im Client gibt es auch eine Klasse LobbyService. Dort ist die DefaultApi Klasse über Dependency Injection gebunden.
385
386 [[image:1756889917681-650.png]]
387
388 Dort kann man nun eine neue Methode getLobbies() integrieren:
389
390 [[image:1756889979252-910.png]]
391
392 Und das Ganze dann z.B. im MainMenuPresenter verwenden:
393
394 [[image:1756890010118-149.png||height="116" width="972"]]
395
396 Anmerkung: Obwohl DefaultApi alle Funktionen zum Server kapselt, sollte man im Client spezifische Services für bestimmte Bereich haben, die diese Klasse verwenden.  Das führt zu einer besseren Trennung von Funktionalitäten im Code.
Marco Grawunder 64.1 397 {{/expandable}}
Marco Grawunder 62.1 398
Marco Grawunder 63.1 399 = Asynchrone Kommunikation zum Client: WebSockets =
Marco Grawunder 62.1 400
401 [[image:1756890800817-370.png||height="604" width="1121"]]
402
Marco Grawunder 63.1 403 Für klassische REST-Aufrufe initiiert der Client die Anfrage. Muss der Server Clients **asynchron über Ereignisse oder Zustandsänderungen informieren**, verwendet das Basisprojekt WebSockets.
Marco Grawunder 62.1 404
405 Spring bietet eine native Unterstützung von WebSockets. Für eigene Funktionen kann man sich in die Kommunikation über die Serverklasse WebSocketHandler einklinken
406
407
408 [[image:1756890924024-346.png||height="377" width="1092"]]
409
410
411 Sobald sich jemand beim Server für WebSockets angemeldet hat wird von Spring ein org.springframework.web.socket.messaging.SessionConnectedEvent
412 geworfen, welches in der folgenden Methode (im WebSocketHandler) aufgefangen wird
413
414 [[image:1756890958794-603.png||height="373" width="1087"]]
415
416 Die Methode ist Observer für das Event SessionConnectedEvent
417
418 Der WebSocketServer kennt die Nutzer und erlaubt das Einloggen nur, wenn Login und Passwort stimmen (durch Spring Security)
419
420 [[image:1756891019715-621.png]]
421
422 1)Aus dem Event kann der Nutzer gelesen werden (der sollte nie leer sein)
423
424 2) Dann wird sich aus dem Repository (später mehr) der Nutzer geholt, der durch den Namen identifiziert ist (z.B. „test1“)
425
426 3) Schließlich werden allen anderen darüber informiert, dass ein neuer Nutzer da ist
427
428 == STOMP ==
429
Marco Grawunder 63.1 430 WebSocket stellt einen bidirektionalen Kommunikationskanal bereit. Für eine strukturierte Nachrichtenkommunikation verwendet das Basisprojekt darüber **STOMP (Streaming Text Oriented Messaging Protocol)**.
Marco Grawunder 62.1 431
Marco Grawunder 63.1 432 STOMP definiert u. a. Operationen wie `CONNECT`, `SEND` und `SUBSCRIBE` und arbeitet mit Topics. Ein Client kann ein Topic abonnieren und erhält anschließend Nachrichten, die der Server auf diesem Topic veröffentlicht.
Marco Grawunder 62.1 433
434
Marco Grawunder 63.1 435 Veröffentlicht der Server eine Nachricht auf einem Topic, erhalten sie die dafür registrierten Clients. Dieses Modell entspricht dem **Publish/Subscribe-Pattern**.
Marco Grawunder 62.1 436
437 [[https:~~/~~/docs.spring.io/spring-framework/reference/web/websocket/stomp.html>>url:https://docs.spring.io/spring-framework/reference/web/websocket/stomp.html]]
438
439
Marco Grawunder 63.1 440 Der Server definiert je nach fachlichem Bereich unterschiedliche Topics. Für das Nutzermanagement sind beispielsweise vorgesehen:
Marco Grawunder 62.1 441
Marco Grawunder 63.1 442 * `/topic/users/loggedIn`: Ein Nutzer hat sich angemeldet.
443 * `/topic/users/loggedOut`: Ein Nutzer hat sich ausgeloggt.
Marco Grawunder 62.1 444
445 [[image:1756891125969-748.png||height="317" width="726"]]
446
Marco Grawunder 63.1 447 Topic-Namen sind Strings, sollten aber einem konsistenten fachlichen Namensschema folgen. Für Lobby-Ereignisse bietet sich entsprechend `/topic/lobbies/...` an.
Marco Grawunder 62.1 448
449 == WebSockets: Versenden von Nachrichten ==
450
451 [[image:1756891180516-843.png||height="426" width="801"]]
452
453 [[image:1756891216134-578.png||height="428" width="699"]]
454
455 == Nachrichteninhalt ==
456
457 [[image:1756891254830-647.png||height="101" width="777"]]
458
459 * message kann grundsätzlich alles sein, was serialisiert werden kann
Marco Grawunder 63.1 460 * Technisch könnte Java-Serialisierung verwendet werden; das alte Basisprojekt hat dies teilweise getan.
Marco Grawunder 62.1 461 * Das hat aber eine Reihe von Nachteilen
462 ** Der Empfänger muss dafür unbedingt auch ein Java-Client sein und er muss exakt dieselbe Klasse bei sich haben, damit der das Objekt wieder zurück in ein Java-Objekt umwandeln kann
463 ** Es gibt eine Reihe von Sicherheitsproblemen
Marco Grawunder 63.1 464 * Besser ist ein technologieunabhängigeres Austauschformat. Im Basisprojekt wird deshalb JSON verwendet.
Marco Grawunder 62.1 465 * Insbesondere Web-Clients (JavaScript) bieten hervorragende Möglichkeiten, an JSON zu verarbeiten
466 * Client und Server haben sich damit auf Format für den Austausch geeinigt
467 ** Topic: Strings
468 ** Message: JSON
469
Marco Grawunder 63.1 470 Auch über WebSockets werden an Clients nur geeignete DTOs übertragen; interne Serverobjekte bleiben serverintern.
Marco Grawunder 62.1 471
472 [[image:1756891375095-158.png||height="266" width="775"]]
473
474 == Wie verbindet sich ein Client mit dem Server? ==
475
Marco Grawunder 64.1 476 {{expandable summary="Technische Details zum Verbindungsaufbau"}}
Marco Grawunder 63.1 477 Der `UserService` bietet die Anmeldung an. Im Basisprojekt erfolgt sie beim Aufbau der WebSocket-/STOMP-Verbindung; die Zugangsdaten werden dabei über die bestehende Sicherheitskonfiguration geprüft.
Marco Grawunder 62.1 478
479 [[image:1756891512330-186.png||height="170" width="820"]]
480
Marco Grawunder 63.1 481 === Auf Client-Seite: WebSocketConnectionManager ===
Marco Grawunder 62.1 482
483 [[image:1756891551794-161.png||height="387" width="1019"]]
484
485 1) Variablen definieren
486
487 2) WebSocketClient erzeugen
488
489 3) Daraus WebSocketStompClient machen
490
491 4) Jackson als Mapper definieren (DTO-Object <-> JSON)
492
Marco Grawunder 63.1 493 [[image:1756891617399-232.png||height="289" width="1006"]]
Marco Grawunder 62.1 494
495
496 1) Asynchron die Verbindung zum Server aufbauen
497
498 2) Wenn erfolgreich in das Hauptmenü wechseln (showScene à später mehr)
499
500 3) Über den Kontext ein Event pushen LoggedInEvent
501
502 4) Jede Serververbindung hat eine Session
Marco Grawunder 64.1 503 {{/expandable}}
504
Marco Grawunder 65.1 505 = Siehe auch =
Marco Grawunder 64.1 506
Marco Grawunder 65.1 507 * [[Stichwortverzeichnis>>doc:Main.Index.WebHome]]
508 * [[Glossar>>doc:Main.Glossar.WebHome]]
509 * [[Basisprojekt FAQ>>doc:Main.Basisprojekt.Basisprojekt FAQ.WebHome]]