Skip to Content

Wiki source code of Basisprojekt

Version 75.1 by Carl Welsch on 2026/10/23 12:21
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"}}
Carl Welsch 71.2 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 finden Sie in der Spalte links den Bereich **Access tokens**.
Marco Grawunder 62.1 40
Carl Welsch 73.3 41 [[image:1792748594897-686.png||height="305" width="258"]]
Carl Welsch 71.2 42
Carl Welsch 74.2 43 Unter dem Bereich **Access** finden Sie den Unterbereich **Personal access token**.
Marco Grawunder 62.1 44
Carl Welsch 73.3 45 [[image:1792748661578-664.png||height="594" width="259"]]
46
Carl Welsch 74.3 47 Dort können Sie mit **Generate token** ein neues Token anlegen. Wählen Sie hier **Generate fine-grained token **aus.
Marco Grawunder 62.1 48
Carl Welsch 74.2 49 [[image:1792749012547-899.png||height="77" width="637"]]
50
Carl Welsch 74.3 51 Als Namen für den Token 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 52
53 [[image:1757399088336-273.png||height="92" width="547"]]
54
55 Bei den Scopes sollten die beiden Rechte "read_repository" und "write_repository" gewählt werden.
56
57 Danach wird das Access Token generiert
58
59 [[image:1757399184270-348.png||height="99" width="978"]]
60
Marco Grawunder 63.1 61 {{warning}}
62 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 63 {{/warning}}
Marco Grawunder 62.1 64
Marco Grawunder 64.1 65 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.
66 {{/expandable}}
Marco Grawunder 62.1 67
Marco Grawunder 66.2 68 == SSH ==
69
70 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:
71
Marco Grawunder 68.1 72 [[image:1792324965203-193.png]]
73
Marco Grawunder 63.1 74 == Nach dem Klonen ==
Marco Grawunder 62.1 75
76 sollten Sie einen Bildschirm ähnlich zu dem folgenden sehen:
77
78 [[image:1755245980026-164.png]]
79
80 Auf dem main-Branch (master) kann keine Änderung gemacht werden, deswegen muss auf einen anderen Branch gewechselt werden. Im Beispiel development.
81
82 [[image:1755245996886-733.png]]
83
Marco Grawunder 63.1 84 == Initialer Maven-Build und Codegenerierung ==
Marco Grawunder 62.1 85
Marco Grawunder 63.1 86 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 87
88 [[image:1755246008466-477.png]]
89
90
91 [[image:1755246018789-616.png]]
92
93
Marco Grawunder 63.1 94 == Lombok-Plugin ==
Marco Grawunder 62.1 95
Marco Grawunder 63.1 96 Falls das Lombok-Plugin noch nicht installiert ist, installieren bzw. aktivieren Sie es in IntelliJ.
Marco Grawunder 62.1 97
98 [[image:1755248508652-523.png]]
99
Marco Grawunder 63.1 100 Je nach IntelliJ-Edition kann zusätzlich das Spring-/Spring-Boot-Plugin hilfreich sein.
Marco Grawunder 62.1 101
102 [[image:1756886220468-891.png]]
103
Marco Grawunder 69.1 104 == Probleme mit Maven oder IntelliJ ==
105
106 Falls IntelliJ nach dem Klonen des Repositories nicht alle Abhängigkeiten oder Klassen erkennt, überprüfen Sie bitte folgende Punkte:
107
108 1. **Java-Version:** Das Basisprojekt benötigt mindestens Java 21. Kontrollieren Sie mit java -version und mvn -version, welche Versionen verwendet werden.
109 1. **IntelliJ-Projekt:** Öffnen Sie das gesamte Projekt mit der übergeordneten pom.xml, nicht nur das Server- oder Client-Verzeichnis.
110 1. **Maven-Konfiguration:** Überprüfen Sie unter //Settings → Build Tools → Maven//, ob Maven mit einem passenden JDK ausgeführt wird.
111 1. **Maven aktualisieren:** Öffnen Sie das Maven-Toolfenster und wählen Sie //Reload All Maven Projects//.
112 1. (((
113 **Projekt bauen:** Öffnen Sie ein Terminal im Hauptverzeichnis des Projekts und führen Sie folgenden Befehl aus:
114
115 mvn -U clean install -DskipTests
116 )))
117 1. **Generierte Klassen:** Stellen Sie sicher, dass die durch OpenAPI generierten Java-Klassen unter target/generated-sources vorhanden sind und von IntelliJ erkannt werden.
118 1. **Lombok:** Prüfen Sie, ob das Lombok-Plugin aktiviert ist und Annotation Processing korrekt funktioniert.
119 1. **Server starten:** Starten Sie die Klasse ServerApp im Server-Modul. Überprüfen Sie bei Problemen die Java-Version und die Startkonfiguration.
120
121 **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.
122
Marco Grawunder 70.1 123 Man kann auch versuchen, die Caches von IntelliJ einmal zu löschen: File → Invalidate Caches → Invalidate and Restart
124
Marco Grawunder 70.2 125 Falls es immer noch Problem gibt: Es gibt eine erweiterte Checkliste: [[Basisprojekt Checkliste>>doc:.Basisprojekt Checkliste.WebHome]]
Marco Grawunder 69.1 126
Marco Grawunder 63.1 127 == Server starten ==
Marco Grawunder 62.1 128
129 Den Serverbereich aufklappen und dort auf die Datei ServerApp mit der rechten Maustaste klicken.
130
131 [[image:1755246035428-328.png]]
132
133
Marco Grawunder 63.1 134 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 135
136 [[image:1755246072443-191.png]]
137
138
139 [[image:1755246118807-452.png]]
140
141
142 == Logging umstellen ==
143
Marco Grawunder 64.1 144 {{expandable summary="Schritt-für-Schritt: Logging konfigurieren"}}
Marco Grawunder 62.1 145 Wenn man möchte, kann man das Logging umstellen.
146
147 [[image:1755246135109-325.png]]
148
149
150 [[image:1755246147827-679.png]]
151
152
153 [[image:1755246162330-595.png]]
Marco Grawunder 64.1 154 {{/expandable}}
Marco Grawunder 62.1 155
Marco Grawunder 63.1 156 == Development-Profil aktivieren ==
Marco Grawunder 62.1 157
Marco Grawunder 64.1 158 {{expandable summary="Schritt-für-Schritt: Development-Profil aktivieren"}}
Marco Grawunder 63.1 159 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 160
161 Wenn man die Anwendung einmal gestartet hat, kann man dies Configuration anpassen:
162
163 [[image:1757399848941-253.png||height="209" width="558"]]
164
165 [[image:1755246173415-934.png]]
166
167
Marco Grawunder 63.1 168 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 169
170 **SPRING_PROFILES_ACTIVE=dev**
171
172 [[image:1755248752596-839.png]]
173
174 Danach muss man den Server neu starten!
Marco Grawunder 64.1 175 {{/expandable}}
Marco Grawunder 62.1 176
177 == Client starten ==
178
179 Wenn der Server gestartet ist, kann man mehrere Clients starten. Dafür auf jeden Fall die Klasse Main verwenden.
180
Marco Grawunder 63.1 181 {{warning}}
182 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.
183 {{/warning}}
Marco Grawunder 62.1 184
185 [[image:1755246257400-525.png]]
186
187
188 [[image:1755246212916-883.png]]
189
190
191 [[image:1755246223246-834.png]]
192
193
194 === Mehrere Instanzen des Clients ermöglichen ===
195
Marco Grawunder 64.1 196 {{expandable summary="Schritt-für-Schritt: mehrere Client-Instanzen starten"}}
Marco Grawunder 62.1 197 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.
198
199 [[image:1755246233218-893.png]]
200
201
Marco Grawunder 63.1 202 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 203
204 [[image:1755246292057-581.png]]
Marco Grawunder 64.1 205 {{/expandable}}
Marco Grawunder 62.1 206
Marco Grawunder 63.1 207 = Überblick über das Basisprojekt =
Marco Grawunder 62.1 208
209 [[image:1755249096987-249.png]]
210
211
212 [[image:1755249136156-419.png]]
213
214
Marco Grawunder 63.1 215 == Projektstruktur ==
Marco Grawunder 62.1 216
217 [[image:1755249228556-469.png]]
218
219
Marco Grawunder 63.1 220 = Kommunikation vom Client zum Server: REST =
Marco Grawunder 62.1 221
222 [[image:1755249285866-367.png]]
223
Marco Grawunder 63.1 224 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 225
226 = OpenAPI =
227
Marco Grawunder 63.1 228 {{info}}
229 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.
230 {{/info}}
Marco Grawunder 62.1 231
Marco Grawunder 66.1 232 {{info}}
233 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
234 {{/info}}
235
Marco Grawunder 62.1 236 [[image:1755250026156-269.png]]
237
238 [[image:1755250050031-304.png]]
239
240 * **Paths**: Endpunkte der API (z.B. /users, /lobbies).
241 * **Operations**: Spezifikation von Methoden wie GET, POST.
Marco Grawunder 63.1 242 * **Schemas**: Beschreibung der Datenstrukturen für Ein- und Ausgaben.
Marco Grawunder 62.1 243 * **Security**: Authentifizierungsmechanismen.
244
245 [[image:1755250061990-172.png]]
246
Marco Grawunder 63.1 247 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 248
249 [[image:1755250157536-746.png]]
250
251 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]]
252
253 Dort wird die Datei auch grafisch dargestellt.
254
255
256 = Maven und OpenAPI =
257
Marco Grawunder 63.1 258 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 259
Marco Grawunder 63.1 260 Die Generierung kann über die Kommandozeile erfolgen; im Basisprojekt ist sie bereits in den Maven-Build integriert.
Marco Grawunder 62.1 261
262 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:
263
264 == Client ==
265
Marco Grawunder 63.1 266 Im Java-Client wird ein HTTP-Client für den Zugriff auf die generierte API verwendet.
Marco Grawunder 62.1 267
268
269 [[image:1756887005209-855.png]]
270
271 == Server ==
272
Marco Grawunder 63.1 273 Auf der Serverseite werden Spring-/Spring-Boot-kompatible Schnittstellen und Controller-Strukturen generiert.
Marco Grawunder 62.1 274
275 [[image:1756887037619-847.png]]
276
Marco Grawunder 63.1 277 {{info}}
278 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]].
279 {{/info}}
Marco Grawunder 62.1 280
281
282
283 = Erweiterung der REST-Schnittstelle =
284
Marco Grawunder 64.1 285 {{expandable summary="Ausführliches Beispiel: REST-Schnittstelle erweitern"}}
Marco Grawunder 62.1 286 In diesem Beispiel wird einmal gezeigt, wie die REST-Schnittstelle des Basisprojektes einfach erweitert werden kann.
287
288 In diesem Beispiel soll die aktuelle Schnittstelle um die Möglichkeit erweitert werden, alle Lobbies vom Server zu bekommen.
289
Marco Grawunder 63.1 290 == Schritt 1: OpenAPI-Dokument erweitern ==
Marco Grawunder 62.1 291
292 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.
293
294 Die Funktion soll sehr einfach sein und keine Parameter verlangen. Dafür bietet sich die GET-Funktion an.
295
296 Im folgenden Bild sind alle Anpassungen zu sehen:
297
298 [[image:1756887436525-790.png||height="355" width="974"]]
299
300
301 Nach dem Speichern, sollte das OpenAPI-Dokument wie folgt aussehen
302
303 [[image:1756887488020-376.png||height="642" width="904"]]
304
305
306 Jetzt kann man entweder in IntelliJ
307
308 [[image:1756888245896-845.png||height="347" width="620"]]
309
310 oder im Terminal (z.B. auch in IntelliJ)
311
312 [[image:1756888279902-777.png||height="637" width="1053"]]
313
314 Wobei hier auch clean compile reichen würde.
315
316 **ACHTUNG! Falls maven Problem macht, kann das auch an einer falschen Java-Version im System liegen (siehe auch [[FAQ>>doc:.Basisprojekt FAQ.WebHome]])**
317
318 Es werden durch den Aufruf neue Inhalte generiert (bzw. die alten überschrieben).
319
320 [[image:1756888428042-802.png||height="538" width="1077"]]
321
322 Hinweis: Niemals Änderungen unterhalb des target-Ordners machen. Das wird von Maven bei clean gelöscht.
323
Marco Grawunder 63.1 324 === Wo wird die eigentliche Funktionalität implementiert? ===
Marco Grawunder 62.1 325
Marco Grawunder 63.1 326 Für jeden API-Bereich (z. B. `lobbies` und `users`) werden serverseitig typischerweise mehrere Schnittstellen bzw. Klassen generiert:
Marco Grawunder 62.1 327
328 * *Api (z.B, LobbiesApi): Beschreibung der REST-Methoden, vor allem auch das Mapping von z.B. /lobbies/join auf die Methode lobbyJoin(String)
329 * (((
330 *ApiController implements *Api (Für Spring) (z.B. LobbiesApiController)
331 )))
332 * (((
Marco Grawunder 63.1 333 * `*ApiDelegate` (z. B. `LobbiesApiDelegate`): Delegationsschnittstelle. Die fachliche Implementierung erfolgt **im eigenen, nicht generierten Code**.
Marco Grawunder 62.1 334 )))
335
336
337
338 == Schritt 2: Erweiterung auf Server-Seite ==
339
340 Da es schon Funktionen für die Lobbies gibt, gibt es auch bereits eine Implementierung, die LobbiesApiDelegate überschreibt
341
342 [[image:1756888762381-912.png||height="48" width="789"]]
343
Marco Grawunder 63.1 344 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 345
346 In der Klasse muss man dann die neue Methode lobbyList aus der API überschreiben.
347
348 [[image:1756888929507-312.png||height="156" width="1161"]]
349
350 Dabei wird folgendes gemacht:
351
352 1. Es wird ein Rückgabeobjekt vom Typ Liste erzeugt
353 1. Es wird über alles Lobbies auf dem Server gegangen (lobbyManagement.getLobbies())
354 1. Da der Client u.U. nicht die vollständigen Informationen über die Lobbies bekommen soll, gibt es zwei unterschiedliche Klassen: ServerLobby und LobbyDTO.
355 1. Die Foreach-Schleife sorgt dafür, dass in das Rückgabeobjekt nur die LobbyDTOs eingefügt werden.
356 1. Dafür wird eine Funktion mit dem Namen lobbyMapping verwendet
357 1. Schließlich wird am Ende gesagt, dass alles ok ist und eine Antwort ResponseEntity.ok mit dem Rückgabeobjekt (lobbies) gesendet.
358
359 **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
360
361 Auf Server-Seite fehlt jetzt noch die Methode getLobbies im LobbyManagement
362
363 [[image:1756889590500-656.png||height="81" width="518"]]
364
365
366 === LobbyMapping ===
367
Marco Grawunder 63.1 368 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 369
370 Also z.B.
371
372 [[image:1756889440395-856.png]]
373
374 und definiert ein Interface mit einer Annotation
375
376 [[image:1756889472103-847.png]]
377
378 und damit kann man die Funktion aufrufen. Hinweis: Der Mapper ist im LobbyService über die Spring Dependency Injection gebunden.
379
380 == Schritt 3: Erweiterung auf Client-Seite (Java) ==
381
Marco Grawunder 63.1 382 {{info}}
383 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.
384 {{/info}}
Marco Grawunder 62.1 385
386 Auf der Client-Seite wird die komplette Kommunikation mit dem Server in der generierten Klasse DefaultApi gekapselt.
387
388 [[image:1756889795622-530.png]]
389
390 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
391
392 Im Client gibt es auch eine Klasse LobbyService. Dort ist die DefaultApi Klasse über Dependency Injection gebunden.
393
394 [[image:1756889917681-650.png]]
395
396 Dort kann man nun eine neue Methode getLobbies() integrieren:
397
398 [[image:1756889979252-910.png]]
399
400 Und das Ganze dann z.B. im MainMenuPresenter verwenden:
401
402 [[image:1756890010118-149.png||height="116" width="972"]]
403
404 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 405 {{/expandable}}
Marco Grawunder 62.1 406
Marco Grawunder 63.1 407 = Asynchrone Kommunikation zum Client: WebSockets =
Marco Grawunder 62.1 408
409 [[image:1756890800817-370.png||height="604" width="1121"]]
410
Marco Grawunder 63.1 411 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 412
413 Spring bietet eine native Unterstützung von WebSockets. Für eigene Funktionen kann man sich in die Kommunikation über die Serverklasse WebSocketHandler einklinken
414
415
416 [[image:1756890924024-346.png||height="377" width="1092"]]
417
418
419 Sobald sich jemand beim Server für WebSockets angemeldet hat wird von Spring ein org.springframework.web.socket.messaging.SessionConnectedEvent
420 geworfen, welches in der folgenden Methode (im WebSocketHandler) aufgefangen wird
421
422 [[image:1756890958794-603.png||height="373" width="1087"]]
423
424 Die Methode ist Observer für das Event SessionConnectedEvent
425
426 Der WebSocketServer kennt die Nutzer und erlaubt das Einloggen nur, wenn Login und Passwort stimmen (durch Spring Security)
427
428 [[image:1756891019715-621.png]]
429
430 1)Aus dem Event kann der Nutzer gelesen werden (der sollte nie leer sein)
431
432 2) Dann wird sich aus dem Repository (später mehr) der Nutzer geholt, der durch den Namen identifiziert ist (z.B. „test1“)
433
434 3) Schließlich werden allen anderen darüber informiert, dass ein neuer Nutzer da ist
435
436 == STOMP ==
437
Marco Grawunder 63.1 438 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 439
Marco Grawunder 63.1 440 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 441
442
Marco Grawunder 63.1 443 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 444
445 [[https:~~/~~/docs.spring.io/spring-framework/reference/web/websocket/stomp.html>>url:https://docs.spring.io/spring-framework/reference/web/websocket/stomp.html]]
446
447
Marco Grawunder 63.1 448 Der Server definiert je nach fachlichem Bereich unterschiedliche Topics. Für das Nutzermanagement sind beispielsweise vorgesehen:
Marco Grawunder 62.1 449
Marco Grawunder 63.1 450 * `/topic/users/loggedIn`: Ein Nutzer hat sich angemeldet.
451 * `/topic/users/loggedOut`: Ein Nutzer hat sich ausgeloggt.
Marco Grawunder 62.1 452
453 [[image:1756891125969-748.png||height="317" width="726"]]
454
Marco Grawunder 63.1 455 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 456
457 == WebSockets: Versenden von Nachrichten ==
458
459 [[image:1756891180516-843.png||height="426" width="801"]]
460
461 [[image:1756891216134-578.png||height="428" width="699"]]
462
463 == Nachrichteninhalt ==
464
465 [[image:1756891254830-647.png||height="101" width="777"]]
466
467 * message kann grundsätzlich alles sein, was serialisiert werden kann
Marco Grawunder 63.1 468 * Technisch könnte Java-Serialisierung verwendet werden; das alte Basisprojekt hat dies teilweise getan.
Marco Grawunder 62.1 469 * Das hat aber eine Reihe von Nachteilen
470 ** 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
471 ** Es gibt eine Reihe von Sicherheitsproblemen
Marco Grawunder 63.1 472 * Besser ist ein technologieunabhängigeres Austauschformat. Im Basisprojekt wird deshalb JSON verwendet.
Marco Grawunder 62.1 473 * Insbesondere Web-Clients (JavaScript) bieten hervorragende Möglichkeiten, an JSON zu verarbeiten
474 * Client und Server haben sich damit auf Format für den Austausch geeinigt
475 ** Topic: Strings
476 ** Message: JSON
477
Marco Grawunder 63.1 478 Auch über WebSockets werden an Clients nur geeignete DTOs übertragen; interne Serverobjekte bleiben serverintern.
Marco Grawunder 62.1 479
480 [[image:1756891375095-158.png||height="266" width="775"]]
481
482 == Wie verbindet sich ein Client mit dem Server? ==
483
Marco Grawunder 64.1 484 {{expandable summary="Technische Details zum Verbindungsaufbau"}}
Marco Grawunder 63.1 485 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 486
487 [[image:1756891512330-186.png||height="170" width="820"]]
488
Marco Grawunder 63.1 489 === Auf Client-Seite: WebSocketConnectionManager ===
Marco Grawunder 62.1 490
491 [[image:1756891551794-161.png||height="387" width="1019"]]
492
493 1) Variablen definieren
494
495 2) WebSocketClient erzeugen
496
497 3) Daraus WebSocketStompClient machen
498
499 4) Jackson als Mapper definieren (DTO-Object <-> JSON)
500
Marco Grawunder 63.1 501 [[image:1756891617399-232.png||height="289" width="1006"]]
Marco Grawunder 62.1 502
503
504 1) Asynchron die Verbindung zum Server aufbauen
505
506 2) Wenn erfolgreich in das Hauptmenü wechseln (showScene à später mehr)
507
508 3) Über den Kontext ein Event pushen LoggedInEvent
509
510 4) Jede Serververbindung hat eine Session
Marco Grawunder 64.1 511 {{/expandable}}
512
Marco Grawunder 65.1 513 = Siehe auch =
Marco Grawunder 64.1 514
Marco Grawunder 65.1 515 * [[Stichwortverzeichnis>>doc:Main.Index.WebHome]]
516 * [[Glossar>>doc:Main.Glossar.WebHome]]
517 * [[Basisprojekt FAQ>>doc:Main.Basisprojekt.Basisprojekt FAQ.WebHome]]
Marco Grawunder 71.1 518 * (((
519 [[Basisprojekt Checkliste>>doc:.Basisprojekt Checkliste.WebHome]]
520 )))