Skip to Content

Changes for page Basisprojekt

Last modified by Carl Welsch on 2026/10/23 16:19
From version 78.4
edited by Carl Welsch
on 2026/10/23 12:39
Change comment: Auto-saved during real-time collaboration
To version 62.1
edited by Marco Grawunder
on 2025/10/16 11:59
Change comment: There is no comment for this version

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.cwelsch
1 +XWiki.mgrawunder
Content
... ... @@ -1,13 +1,7 @@
1 1  [[image:Main.Organisatorisches.WebHome@softwareprojekt_logo_transparent.png||alt="SoftwareprojektLogo.png" data-xwiki-image-style-alignment="end" height="136" width="309"]]
2 2  
3 -{{info}}
4 -**Worum geht es auf dieser Seite?**
3 +Hier folgen Erklärungen des neuen Basisprojekts. Es wird um die folgenden Themen gehen:
5 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.
9 -{{/info}}
10 -
11 11  {{toc/}}
12 12  
13 13  
... ... @@ -15,11 +15,9 @@
15 15  
16 16  [[image:1755245956916-184.png]]
17 17  
18 -== Repository klonen ==
12 +== Clone ==
19 19  
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}}
14 +Achtung! In dem Screenshot wird das globale Basisprojekt verwendet. Für jede Gruppe existiert bereits ein eigenes Repository, welches verwendet werden sollte,
23 23  
24 24  Sie finden die Clone-URL wie folgt:
25 25  
... ... @@ -35,50 +35,29 @@
35 35  
36 36  == Access Token ==
37 37  
38 -{{expandable summary="Schritt-für-Schritt: Access Token einrichten"}}
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**.
30 +Beim ersten Mal clonen müssen Sie Ihre Gitlab-Zugangsdaten verwenden. Statt Name und Passwort ist es sinnvoll, einen Access-Token zu definieren. Das können Sie machen, in dem Sie auf ihre Profilbild klicken (auf der linken Seite) und dort "Edit Profile" auswählen. In dem nun folgenden Menü gibt es den Punkt Access tokens.
40 40  
41 -[[image:1792748594897-686.png||height="305" width="258"]]
32 +[[image:1757398899497-714.png||height="246" width="278"]]
42 42  
43 -Unter dem Bereich **Access** finden Sie den Unterbereich **Personal access token**.
34 +Dort können Sie mit [[image:1757398947128-748.png||height="89" width="197"]] ein neues Token anlegen.
44 44  
45 -[[image:1792748661578-664.png||height="594" width="259"]]
36 +Als Namen können Sie z.B. IntelliJ verwenden. Wichtig! Das Token ist aus Sicherheitsgründen nur eine bestimmte Zeit gültig. In diesem Gitlab kann dies maximal ein Jahr sein, standardmäßig ist ist hier aber ein Monat gewählt. Sie sollten also das Feld anpassen.
46 46  
47 -Dort können Sie mit **Generate token** ein neues Token anlegen. Wählen Sie hier **Generate fine-grained token **aus.
38 +[[image:1757399088336-273.png||height="92" width="547"]]
48 48  
49 -[[image:1792749012547-899.png||height="77" width="637"]]
40 +Bei den Scopes sollten die beiden Rechte "read_repository" und "write_repository" gewählt werden.
50 50  
51 -Als Namen für den Token kann z. B. `IntelliJ` verwendet werden. Außerdem muss eine Beschreibung für den Token angelegt werden, wie bspw. "SWP Laptop Verbindung", welcher später zur Identifizierung des Tokes dient. Access Tokens sind aus Sicherheitsgründen zeitlich begrenzt. Wählen Sie ein Ablaufdatum, das zum Projektzeitraum passt. Anschließend wählen Sie unter **Group and project access **den Punkt **Only specific groups or projects I have access to** und wählen Ihre SWP-Gruppe aus.
52 -
53 -[[image:1792751550136-821.png||height="567" width="638"]]
54 -
55 -Bei **Resource access** sollten unter **Repository** "Code" und "Repository" gewählt werden.
56 -
57 -[[image:1792751165237-439.png||height="568" width="369"]]
58 -
59 -Anschließend müssen Sie bei den Permissions setzen. Dafür wählen Sie bei Code "Download", Push und Read. Für Repository wählen Sie Create
60 -
61 -[[image:1792751732971-755.png||height="471" width="610"]]
62 -
63 63  Danach wird das Access Token generiert
64 64  
65 65  [[image:1757399184270-348.png||height="99" width="978"]]
66 66  
67 -{{warning}}
68 -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.**
69 -{{/warning}}
46 +Jetzt ist es wichtig, dass Sie sich das Token sichern!
70 70  
71 -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.
72 -{{/expandable}}
48 +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.
73 73  
74 -== SSH ==
75 75  
76 -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:
51 +== Nach dem Clonen ==
77 77  
78 -[[image:1792324965203-193.png]]
79 -
80 -== Nach dem Klonen ==
81 -
82 82  sollten Sie einen Bildschirm ähnlich zu dem folgenden sehen:
83 83  
84 84  [[image:1755245980026-164.png]]
... ... @@ -87,9 +87,10 @@
87 87  
88 88  [[image:1755245996886-733.png]]
89 89  
90 -== Initialer Maven-Build und Codegenerierung ==
61 +== Initialer Build (Generierung) ==
91 91  
92 -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.
63 +Dem neuen Code fehlen einige generierte Dateien. Diese werden wie folgt erzeugt. 
64 +Hinweis: Immer, wenn an dem OpenAPI-Dokument etwas geändert wird oder neue Abhängigkeiten für Maven definiert werden, muss diese Aktion durchgeführt werden.
93 93  
94 94  [[image:1755246008466-477.png]]
95 95  
... ... @@ -97,47 +97,24 @@
97 97  [[image:1755246018789-616.png]]
98 98  
99 99  
100 -== Lombok-Plugin ==
72 +== Lombok Plugin ==
101 101  
102 -Falls das Lombok-Plugin noch nicht installiert ist, installieren bzw. aktivieren Sie es in IntelliJ.
74 +**Lombok Plugin installiert? Wenn nein jetzt machen**
103 103  
104 104  [[image:1755248508652-523.png]]
105 105  
106 -Je nach IntelliJ-Edition kann zusätzlich das Spring-/Spring-Boot-Plugin hilfreich sein.
78 +**Hinweis: Wenn man schon hier ist, kann man auch das Spring-(Boot)-Plugin **installieren
107 107  
108 108  [[image:1756886220468-891.png]]
109 109  
110 -== Probleme mit Maven oder IntelliJ ==
82 +== Server laufen lassen ==
111 111  
112 -Falls IntelliJ nach dem Klonen des Repositories nicht alle Abhängigkeiten oder Klassen erkennt, überprüfen Sie bitte folgende Punkte:
113 -
114 -1. **Java-Version:** Das Basisprojekt benötigt mindestens Java 21. Kontrollieren Sie mit java -version und mvn -version, welche Versionen verwendet werden.
115 -1. **IntelliJ-Projekt:** Öffnen Sie das gesamte Projekt mit der übergeordneten pom.xml, nicht nur das Server- oder Client-Verzeichnis.
116 -1. **Maven-Konfiguration:** Überprüfen Sie unter //Settings → Build Tools → Maven//, ob Maven mit einem passenden JDK ausgeführt wird.
117 -1. **Maven aktualisieren:** Öffnen Sie das Maven-Toolfenster und wählen Sie //Reload All Maven Projects//.
118 -1. (((
119 -**Projekt bauen:** Öffnen Sie ein Terminal im Hauptverzeichnis des Projekts und führen Sie folgenden Befehl aus:
120 -
121 -mvn -U clean install -DskipTests
122 -)))
123 -1. **Generierte Klassen:** Stellen Sie sicher, dass die durch OpenAPI generierten Java-Klassen unter target/generated-sources vorhanden sind und von IntelliJ erkannt werden.
124 -1. **Lombok:** Prüfen Sie, ob das Lombok-Plugin aktiviert ist und Annotation Processing korrekt funktioniert.
125 -1. **Server starten:** Starten Sie die Klasse ServerApp im Server-Modul. Überprüfen Sie bei Problemen die Java-Version und die Startkonfiguration.
126 -
127 -**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.
128 -
129 -Man kann auch versuchen, die Caches von IntelliJ einmal zu löschen: File → Invalidate Caches → Invalidate and Restart
130 -
131 -Falls es immer noch Problem gibt: Es gibt eine erweiterte Checkliste: [[Basisprojekt Checkliste>>doc:.Basisprojekt Checkliste.WebHome]]
132 -
133 -== Server starten ==
134 -
135 135  Den Serverbereich aufklappen und dort auf die Datei ServerApp mit der rechten Maustaste klicken.
136 136  
137 137  [[image:1755246035428-328.png]]
138 138  
139 139  
140 -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.
89 +... und ggf. Lombok aktivieren (Man wird nach dem Start der Anwendung gefragt). WICHTIG! Wenn das Lombok-Plugin nicht installiert und die folgende Funktion nicht aktiviert ist, muss jede Änderung mit Hilfe von Maven passieren.
141 141  
142 142  [[image:1755246072443-191.png]]
143 143  
... ... @@ -147,7 +147,6 @@
147 147  
148 148  == Logging umstellen ==
149 149  
150 -{{expandable summary="Schritt-für-Schritt: Logging konfigurieren"}}
151 151  Wenn man möchte, kann man das Logging umstellen.
152 152  
153 153  [[image:1755246135109-325.png]]
... ... @@ -157,12 +157,10 @@
157 157  
158 158  
159 159  [[image:1755246162330-595.png]]
160 -{{/expandable}}
161 161  
162 -== Development-Profil aktivieren ==
109 +== Development Profil aktivieren ==
163 163  
164 -{{expandable summary="Schritt-für-Schritt: Development-Profil aktivieren"}}
165 -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.
111 +Damit das Testen einfacher geht, gibt es ein spezielles Spring-Profil. In diesem werden automatisch user1-user9 mit jeweils dem identischen Passwort angelegt und man spart sich die Registierung.
166 166  
167 167  Wenn man die Anwendung einmal gestartet hat, kann man dies Configuration anpassen:
168 168  
... ... @@ -171,7 +171,7 @@
171 171  [[image:1755246173415-934.png]]
172 172  
173 173  
174 -Wenn die verwendete IntelliJ-Version keine Spring-Unterstützung bietet, kann das Profil über eine Umgebungsvariable in der Server-Konfiguration gesetzt werden:
120 +**Wenn man IntelliJ nicht in der Pro-Version verwendet bzw. das Spring Boot Plugin nicht installiert hat, muss kann man ein Spring-Profil über eine Umgebungsvariable in der Konfiguration des Servers setzen: **
175 175  
176 176  **SPRING_PROFILES_ACTIVE=dev**
177 177  
... ... @@ -178,15 +178,12 @@
178 178  [[image:1755248752596-839.png]]
179 179  
180 180  Danach muss man den Server neu starten!
181 -{{/expandable}}
182 182  
183 183  == Client starten ==
184 184  
185 185  Wenn der Server gestartet ist, kann man mehrere Clients starten. Dafür auf jeden Fall die Klasse Main verwenden.
186 186  
187 -{{warning}}
188 -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.
189 -{{/warning}}
132 +**Sollte es nun Problem geben, schauen Sie bitte, ob Sie noch eine alte Java-Version auf ihrem System installiert haben. Wir brauchen mindestens Java 21!**
190 190  
191 191  [[image:1755246257400-525.png]]
192 192  
... ... @@ -199,19 +199,18 @@
199 199  
200 200  === Mehrere Instanzen des Clients ermöglichen ===
201 201  
202 -{{expandable summary="Schritt-für-Schritt: mehrere Client-Instanzen starten"}}
203 203  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.
204 204  
205 205  [[image:1755246233218-893.png]]
206 206  
207 207  
208 -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.
150 +Wenn folgendes kommt, ist entweder das "dev" Profil nicht aktiviert, der Nutzer wurde nicht angelegt. Wenn der Server nicht läuft, gibt es eine andere Fehlermeldung.
209 209  
210 210  [[image:1755246292057-581.png]]
211 -{{/expandable}}
212 212  
213 -= Überblick über das Basisprojekt =
214 214  
155 += Kurzer Blick ins Basisprojekt =
156 +
215 215  [[image:1755249096987-249.png]]
216 216  
217 217  
... ... @@ -218,27 +218,21 @@
218 218  [[image:1755249136156-419.png]]
219 219  
220 220  
221 -== Projektstruktur ==
163 +== Screenshots ==
222 222  
223 223  [[image:1755249228556-469.png]]
224 224  
225 225  
226 -= Kommunikation vom Client zum Server: REST =
168 += Kommunikation Client ~-~-> Server =
227 227  
228 228  [[image:1755249285866-367.png]]
229 229  
230 -Für klassische Request/Response-Operationen verwendet das Basisprojekt **REST über HTTP**. Als Austauschformat wird **JSON** verwendet. Die zentrale Spiellogik verbleibt auf dem Server.
172 +Der Server verwendet das REST-Protokoll und als Austauschformat JSON
231 231  
232 232  = OpenAPI =
233 233  
234 -{{info}}
235 -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.
236 -{{/info}}
176 +(Hinweis: Ich bin nicht sicher, ob IntelliJ diese Darstellung auch hat, wenn man nicht die Ultimate Version verwendet. Ggf. muss man das OpenAPI-Plugin installieren)
237 237  
238 -{{info}}
239 -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
240 -{{/info}}
241 -
242 242  [[image:1755250026156-269.png]]
243 243  
244 244  [[image:1755250050031-304.png]]
... ... @@ -245,12 +245,12 @@
245 245  
246 246  * **Paths**: Endpunkte der API (z.B. /users, /lobbies).
247 247  * **Operations**: Spezifikation von Methoden wie GET, POST.
248 -* **Schemas**: Beschreibung der Datenstrukturen für Ein- und Ausgaben.
184 +* **Definitions**: Detaillierte Beschreibung von Eingabe- und Ausgabestrukturen.
249 249  * **Security**: Authentifizierungsmechanismen.
250 250  
251 251  [[image:1755250061990-172.png]]
252 252  
253 -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.
189 +Kann JSON oder YAML (Yet Another Markup Language) verwenden YAML ist wie JSON nur mit weniger Klammern
254 254  
255 255  [[image:1755250157536-746.png]]
256 256  
... ... @@ -261,15 +261,15 @@
261 261  
262 262  = Maven und OpenAPI =
263 263  
264 -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]]
200 +Die OpenAPI Datei kann verwendet werden, um sich die [[REST-Schnittstellen>>doc:||anchor="HErweiterungderREST-Schnittstelle"]] generieren  zu lassen. Diese Erzeugung erfolgt mit dem OpenAPI Generator [[https:~~/~~/github.com/OpenAPITools/openapi-generator>>https://github.com/OpenAPITools/openapi-generator]]
265 265  
266 -Die Generierung kann über die Kommandozeile erfolgen; im Basisprojekt ist sie bereits in den Maven-Build integriert.
202 +Man kann dabei jetzt einen Kommandozeilenaufruf verwenden oder man setzt auf das im Basisprojekt vorhandene MVN ()
267 267  
268 268  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:
269 269  
270 270  == Client ==
271 271  
272 -Im Java-Client wird ein HTTP-Client für den Zugriff auf die generierte API verwendet.
208 +Im Client werden die Apache Http Bibliothek verwendet.
273 273  
274 274  
275 275  [[image:1756887005209-855.png]]
... ... @@ -276,24 +276,27 @@
276 276  
277 277  == Server ==
278 278  
279 -Auf der Serverseite werden Spring-/Spring-Boot-kompatible Schnittstellen und Controller-Strukturen generiert.
215 +Im Server wird Spring (Boot) verwendet
280 280  
281 281  [[image:1756887037619-847.png]]
282 282  
283 -{{info}}
284 -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]].
285 -{{/info}}
219 +TODO: Weitere Informationen zu
286 286  
221 +- Lombok
287 287  
223 +- Dependency Injection
288 288  
225 +- Spring (Boot), siehe auch [[https:~~/~~/www.marcobehler.com/guides/spring-framework>>https://www.marcobehler.com/guides/spring-framework]]
226 +
227 +
228 +
289 289  = Erweiterung der REST-Schnittstelle =
290 290  
291 -{{expandable summary="Ausführliches Beispiel: REST-Schnittstelle erweitern"}}
292 292  In diesem Beispiel wird einmal gezeigt, wie die REST-Schnittstelle des Basisprojektes einfach erweitert werden kann.
293 293  
294 294  In diesem Beispiel soll die aktuelle Schnittstelle um die Möglichkeit erweitert werden, alle Lobbies vom Server zu bekommen.
295 295  
296 -== Schritt 1: OpenAPI-Dokument erweitern ==
235 +== Schritt 1: Erweitere das OpenAPI-Dokument ==
297 297  
298 298  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.
299 299  
... ... @@ -327,9 +327,9 @@
327 327  
328 328  Hinweis: Niemals Änderungen unterhalb des target-Ordners machen. Das wird von Maven bei clean gelöscht.
329 329  
330 -=== Wo wird die eigentliche Funktionalität implementiert? ===
269 +=== Wie bekommt man dann aber nun die Funktionalität rein? ===
331 331  
332 -Für jeden API-Bereich (z. B. `lobbies` und `users`) werden serverseitig typischerweise mehrere Schnittstellen bzw. Klassen generiert:
271 +Für jeden Endpunkt (also aktuell lobbies und users) werden drei Interfaces/Klassen erzeugt:
333 333  
334 334  * *Api (z.B, LobbiesApi): Beschreibung der REST-Methoden, vor allem auch das Mapping von z.B. /lobbies/join auf die Methode lobbyJoin(String)
335 335  * (((
... ... @@ -336,7 +336,7 @@
336 336  *ApiController implements *Api (Für Spring) (z.B. LobbiesApiController)
337 337  )))
338 338  * (((
339 -* `*ApiDelegate` (z. B. `LobbiesApiDelegate`): Delegationsschnittstelle. Die fachliche Implementierung erfolgt **im eigenen, nicht generierten Code**.
278 +*ApiDelegate (z.B. LobbiesApiDelegate): Macht die eigentliche Arbeit und muss** im eigenen Code-Bereich** erweitert werden!
340 340  )))
341 341  
342 342  
... ... @@ -347,7 +347,7 @@
347 347  
348 348  [[image:1756888762381-912.png||height="48" width="789"]]
349 349  
350 -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.
289 +Wenn man einen neuen Endpunkt definiert, muss man auch einen neuen Service definieren. (Hinweis: Der Service muss eine Spring Komponenten sein, damit sie in den Spring Context aufgenommen wird).
351 351  
352 352  In der Klasse muss man dann die neue Methode lobbyList aus der API überschreiben.
353 353  
... ... @@ -371,7 +371,7 @@
371 371  
372 372  === LobbyMapping ===
373 373  
374 -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.
313 +Da man relativ oft Server-Objekt in DTO umwandeln muss gibt es im Basisprojekt MapStruct. Damit muss man nur die DTO-Klasse anlegen (i.d.R. über OpenAPI!!)
375 375  
376 376  Also z.B.
377 377  
... ... @@ -385,9 +385,7 @@
385 385  
386 386  == Schritt 3: Erweiterung auf Client-Seite (Java) ==
387 387  
388 -{{info}}
389 -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.
390 -{{/info}}
327 +Hinweis: Das Beispiel bezieht sich hier auf eine Client mit Java. Für andere Clients wie Angular ist das Vorgehen anders.
391 391  
392 392  Auf der Client-Seite wird die komplette Kommunikation mit dem Server in der generierten Klasse DefaultApi gekapselt.
393 393  
... ... @@ -408,13 +408,13 @@
408 408  [[image:1756890010118-149.png||height="116" width="972"]]
409 409  
410 410  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.
411 -{{/expandable}}
412 412  
413 -= Asynchrone Kommunikation zum Client: WebSockets =
414 414  
350 += Kommunikation: Server ~-~-> Client (WebSockets) =
351 +
415 415  [[image:1756890800817-370.png||height="604" width="1121"]]
416 416  
417 -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.
354 +Da man mit REST nicht Nachrichten vom Server an den Client schicken kann, werden im Basisprojekt dafür WebSockets verwendet.
418 418  
419 419  Spring bietet eine native Unterstützung von WebSockets. Für eigene Funktionen kann man sich in die Kommunikation über die Serverklasse WebSocketHandler einklinken
420 420  
... ... @@ -441,25 +441,47 @@
441 441  
442 442  == STOMP ==
443 443  
444 -WebSocket stellt einen bidirektionalen Kommunikationskanal bereit. Für eine strukturierte Nachrichtenkommunikation verwendet das Basisprojekt darüber **STOMP (Streaming Text Oriented Messaging Protocol)**.
381 +WebSockets haben kein Protokoll (wie z.B. http)
445 445  
446 -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.
383 +Es können entweder binäre oder textuelle Daten verarbeitet werden (die jeweiligen Gegenstellen müssen das wissen!)
447 447  
385 +Wenn man jetzt mehr als nur Text verschicken möchte, muss man sich überlegen, wie man Objekte z.B. mit JSON serialisiert (analog zu REST)
448 448  
449 -Veröffentlicht der Server eine Nachricht auf einem Topic, erhalten sie die dafür registrierten Clients. Dieses Modell entspricht dem **Publish/Subscribe-Pattern**.
387 +STOMP: Streaming Text Oriented Messaging Protocol
450 450  
389 +Definiert ein einfaches Protokoll, welches es erlaubt, sinnvoll über WebSockets zu kommunizieren
390 +
391 +Ist ein Teil von Spring
392 +
393 +Methoden sind z.B. CONNECT, SEND oder SUBSCRIBE
394 +
395 +STOMP arbeitet mit Topics
396 +
397 +Ein Client registriert (SUBSCRIBE) sich für bestimmte Ereignistypen
398 +
399 +
400 +§Wenn auf der Server-Seite dieser Typ veröffentlich wird dann wird dies an die jeweils interessierten Clients geschickt
401 +
402 +Publish/Subscribe-Pattern
403 +
451 451  [[https:~~/~~/docs.spring.io/spring-framework/reference/web/websocket/stomp.html>>url:https://docs.spring.io/spring-framework/reference/web/websocket/stomp.html]]
452 452  
453 453  
454 -Der Server definiert je nach fachlichem Bereich unterschiedliche Topics. Für das Nutzermanagement sind beispielsweise vorgesehen:
407 +§Der Server definiert unterschiedliche Topics (je nach Modul)
455 455  
456 -* `/topic/users/loggedIn`: Ein Nutzer hat sich angemeldet.
457 -* `/topic/users/loggedOut`: Ein Nutzer hat sich ausgeloggt.
409 +§Beim Nutzermanagement aktuell:
458 458  
411 +§/topic/users/loggedIn: Es hat sich ein neuer Nutzer angemeldet
412 +
413 +§/topic/users/loggedOut: Ein Nutzer hat sich ausgeloggt
414 +
415 +
459 459  [[image:1756891125969-748.png||height="317" width="726"]]
460 460  
461 -Topic-Namen sind Strings, sollten aber einem konsistenten fachlichen Namensschema folgen. Für Lobby-Ereignisse bietet sich entsprechend `/topic/lobbies/...` an.
418 +§Topic-Namen sind Strings, sollte aber Aufbau von oben entsprechen
462 462  
420 +§In der Lobby würde es stattdessen /topic/lobbies/* heißen
421 +
463 463  == WebSockets: Versenden von Nachrichten ==
464 464  
465 465  [[image:1756891180516-843.png||height="426" width="801"]]
... ... @@ -471,28 +471,27 @@
471 471  [[image:1756891254830-647.png||height="101" width="777"]]
472 472  
473 473  * message kann grundsätzlich alles sein, was serialisiert werden kann
474 -* Technisch könnte Java-Serialisierung verwendet werden; das alte Basisprojekt hat dies teilweise getan.
433 +* Man könnte nun einfach die Java-Serialisierung verwenden (im alten Basisprojekt ist das auch so)
475 475  * Das hat aber eine Reihe von Nachteilen
476 476  ** 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
477 477  ** Es gibt eine Reihe von Sicherheitsproblemen
478 -* Besser ist ein technologieunabhängigeres Austauschformat. Im Basisprojekt wird deshalb JSON verwendet.
437 +* Besser: Definiere ein gemeinsames Austauschformat, was viele verstehen ~-~-> Im Basisprojekt (und in vielen anderen Projekten auch) JSON verwenden
479 479  * Insbesondere Web-Clients (JavaScript) bieten hervorragende Möglichkeiten, an JSON zu verarbeiten
480 480  * Client und Server haben sich damit auf Format für den Austausch geeinigt
481 481  ** Topic: Strings
482 482  ** Message: JSON
483 483  
484 -Auch über WebSockets werden an Clients nur geeignete DTOs übertragen; interne Serverobjekte bleiben serverintern.
443 +An den Clilent werden auch bei WebSockets nur DTOs verschickt! (userMapping)
485 485  
486 486  [[image:1756891375095-158.png||height="266" width="775"]]
487 487  
488 488  == Wie verbindet sich ein Client mit dem Server? ==
489 489  
490 -{{expandable summary="Technische Details zum Verbindungsaufbau"}}
491 -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.
449 +UserService bietet eine Methode zum Login an. Diese ruft nun aber keine REST-Endpunkt auf (da man sich sowieso bei JEDEM Aufruf authentifizieren muss, macht so ein Endpunkt kein Sinn). Stattdessen wird die Verbindung mit dem WebSocket hergestellt und dort Nama und Passwort überprüft.
492 492  
493 493  [[image:1756891512330-186.png||height="170" width="820"]]
494 494  
495 -=== Auf Client-Seite: WebSocketConnectionManager ===
453 +=== Auf Server Seite (WebSocketConnectionManager): ===
496 496  
497 497  [[image:1756891551794-161.png||height="387" width="1019"]]
498 498  
... ... @@ -504,7 +504,7 @@
504 504  
505 505  4) Jackson als Mapper definieren (DTO-Object <-> JSON)
506 506  
507 -[[image:1756891617399-232.png||height="289" width="1006"]]
465 +=== [[image:1756891617399-232.png||height="289" width="1006"]] ===
508 508  
509 509  
510 510  1) Asynchron die Verbindung zum Server aufbauen
... ... @@ -514,13 +514,3 @@
514 514  3) Über den Kontext ein Event pushen LoggedInEvent
515 515  
516 516  4) Jede Serververbindung hat eine Session
517 -{{/expandable}}
518 -
519 -= Siehe auch =
520 -
521 -* [[Stichwortverzeichnis>>doc:Main.Index.WebHome]]
522 -* [[Glossar>>doc:Main.Glossar.WebHome]]
523 -* [[Basisprojekt FAQ>>doc:Main.Basisprojekt.Basisprojekt FAQ.WebHome]]
524 -* (((
525 -[[Basisprojekt Checkliste>>doc:.Basisprojekt Checkliste.WebHome]]
526 -)))
1792324965203-193.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.mgrawunder
Size
... ... @@ -1,1 +1,0 @@
1 -29.6 KB
Content
1792748594897-686.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.cwelsch
Size
... ... @@ -1,1 +1,0 @@
1 -44.4 KB
Content
1792748661578-664.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.cwelsch
Size
... ... @@ -1,1 +1,0 @@
1 -92.0 KB
Content
1792749012547-899.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.cwelsch
Size
... ... @@ -1,1 +1,0 @@
1 -46.3 KB
Content
1792750917132-904.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.cwelsch
Size
... ... @@ -1,1 +1,0 @@
1 -232.1 KB
Content
1792751165237-439.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.cwelsch
Size
... ... @@ -1,1 +1,0 @@
1 -164.3 KB
Content
1792751550136-821.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.cwelsch
Size
... ... @@ -1,1 +1,0 @@
1 -241.6 KB
Content
1792751732971-755.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.cwelsch
Size
... ... @@ -1,1 +1,0 @@
1 -144.2 KB
Content