Wiki source code of Basisprojekt

Version 77.2 by Carl Welsch on 2026/10/23 12:34

Manage
- Copy
Actions
- Export
- Print Preview
Viewers
- Source
- Children
- Content
- Comments
- Attachments (72)
- History
- Information
- Likes

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

Wiki source code of Basisprojekt

Applications

Navigation