Wiki source code of Basisprojekt

Last modified by mgrawunder on 2025/09/09 08:42

version	line-number	content
2.1	1	[[image:Main.Organisatorisches.WebHome@softwareprojekt_logo_transparent.png\|\|alt="SoftwareprojektLogo.png" data-xwiki-image-style-alignment="end" height="136" width="309"]]
	2
28.1	3	Hier folgen Erklärungen des neuen Basisprojekts. Es wird um die folgenden Themen gehen:
	4
24.1	5	{{toc/}}
23.2	6
2.2	7
7.2	8	= Basisprojekt mit IntelliJ einrichten =
	9
	10	[[image:1755245956916-184.png]]
	11
24.2	12	== Clone ==
7.2	13
60.1	14	Achtung! In dem Screenshot wird das globale Basisprojekt verwendet. Für jede Gruppe existiert bereits ein eigenes Repository, welches verwendet werden sollte,
52.2	15
60.1	16	Sie finden die Clone-URL wie folgt:
	17
	18	* Loggen Sie sich auf [[https:~~/~~/gitlab.swl.informatik.uni-oldenburg.de/>>https://gitlab.swl.informatik.uni-oldenburg.de/]] ein
	19	* Falls nicht vorausgewählt, wählen Sie auf der linken Seite "Projects"
	20	[[image:1757398628416-879.png\|\|height="119" width="541"]]
	21	* Da Sie bisher noch nichts gemacht haben, ist diese Seite leer. Wechseln Sie auf den Reiter Member
	22	* Dort sollte ihr Repository zu finden sein.
	23	* Oben rechts gibt es einen Button Code. Kopieren Sie dort die URL, die hinter "Clone with HTTPS" steht.
	24	[[image:1757398731084-704.png\|\|height="454" width="323"]]
	25
7.2	26	[[image:1755245971657-468.png]]
	27
60.1	28	== Access Token ==
7.2	29
60.1	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.
52.2	31
60.1	32	[[image:1757398899497-714.png\|\|height="246" width="278"]]
	33
	34	Dort können Sie mit [[image:1757398947128-748.png\|\|height="89" width="197"]] ein neues Token anlegen.
	35
	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.
	37
	38	[[image:1757399088336-273.png\|\|height="92" width="547"]]
	39
	40	Bei den Scopes sollten die beiden Rechte "read_repository" und "write_repository" gewählt werden.
	41
	42	Danach wird das Access Token generiert
	43
	44	[[image:1757399184270-348.png\|\|height="99" width="978"]]
	45
	46	Jetzt ist es wichtig, dass Sie sich das Token sichern!
	47
	48	Beim Einloggen in IntelliJ können Sie dieses Token im Passwort-Feld verwenden. Geben Sie ihren Account bei Name ein.
	49
	50	== Nach dem Clonen ==
	51
	52	sollten Sie einen Bildschirm ähnlich zu dem folgenden sehen:
	53
7.2	54	[[image:1755245980026-164.png]]
	55
60.1	56	Auf dem main-Branch (master) kann keine Änderung gemacht werden, deswegen muss auf einen anderen Branch gewechselt werden. Im Beispiel development.
7.2	57
	58	[[image:1755245996886-733.png]]
	59
24.2	60	== Initialer Build (Generierung) ==
7.2	61
60.1	62	Dem neuen Code fehlen einige generierte Dateien. Diese werden wie folgt erzeugt.
	63	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.
	64
10.2	65	[[image:1755246008466-477.png]]
7.2	66
	67
10.2	68	[[image:1755246018789-616.png]]
	69
	70
24.2	71	== Lombok Plugin ==
	72
23.1	73	Lombok Plugin installiert? Wenn nein jetzt machen
	74
25.2	75	[[image:1755248508652-523.png]]
24.2	76
37.2	77	Hinweis: Wenn man schon hier ist, kann man auch das Spring-(Boot)-Plugin installieren
23.1	78
37.2	79	[[image:1756886220468-891.png]]
36.2	80
25.2	81	== Server laufen lassen ==
23.1	82
60.1	83	Den Serverbereich aufklappen und dort auf die Datei ServerApp mit der rechten Maustaste klicken.
	84
10.2	85	[[image:1755246035428-328.png]]
	86
	87
60.1	88	... 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.
10.2	89
23.1	90	[[image:1755246072443-191.png]]
10.2	91
	92
23.1	93	[[image:1755246118807-452.png]]
10.2	94
2.2	95
25.3	96	== Logging umstellen ==
3.1	97
60.1	98	Wenn man möchte, kann man das Logging umstellen.
	99
23.1	100	[[image:1755246135109-325.png]]
	101
	102
	103	[[image:1755246147827-679.png]]
	104
	105
	106	[[image:1755246162330-595.png]]
	107
25.3	108	== Development Profil aktivieren ==
23.1	109
60.1	110	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.
25.3	111
60.1	112	Wenn man die Anwendung einmal gestartet hat, kann man dies Configuration anpassen:
	113
	114	[[image:1757399848941-253.png\|\|height="209" width="558"]]
	115
23.1	116	[[image:1755246173415-934.png]]
	117
	118
37.3	119	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:
23.1	120
	121	SPRING_PROFILES_ACTIVE=dev
	122
26.2	123	[[image:1755248752596-839.png]]
	124
60.1	125	Danach muss man den Server neu starten!
26.2	126
	127	== Client starten ==
	128
60.1	129	Wenn der Server gestartet ist, kann man mehrere Clients starten. Dafür auf jeden Fall die Klasse Main verwenden.
	130
	131	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!
	132
23.1	133	[[image:1755246257400-525.png]]
	134
	135
	136	[[image:1755246212916-883.png]]
	137
	138
	139	[[image:1755246223246-834.png]]
	140
	141
26.2	142	=== Mehrere Instanzen des Clients ermöglichen ===
	143
60.1	144	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.
	145
23.1	146	[[image:1755246233218-893.png]]
	147
	148
27.1	149	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.
26.2	150
23.1	151	[[image:1755246292057-581.png]]
	152
30.2	153
	154	= Kurzer Blick ins Basisprojekt =
	155
	156	[[image:1755249096987-249.png]]
	157
	158
	159	[[image:1755249136156-419.png]]
33.1	160
	161
	162	== Screenshots ==
	163
	164	[[image:1755249228556-469.png]]
	165
	166
	167	= Kommunikation Client ~-~-> Server =
	168
	169	[[image:1755249285866-367.png]]
	170
34.1	171	Der Server verwendet das REST-Protokoll und als Austauschformat JSON
	172
	173	= OpenAPI =
	174
37.3	175	(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)
	176
34.1	177	[[image:1755250026156-269.png]]
	178
	179	[[image:1755250050031-304.png]]
	180
	181	* Paths: Endpunkte der API (z.B. /users, /lobbies).
	182	* Operations: Spezifikation von Methoden wie GET, POST.
	183	* Definitions: Detaillierte Beschreibung von Eingabe- und Ausgabestrukturen.
	184	* Security: Authentifizierungsmechanismen.
	185
	186	[[image:1755250061990-172.png]]
36.1	187
	188	Kann JSON oder YAML (Yet Another Markup Language) verwenden YAML ist wie JSON nur mit weniger Klammern
	189
	190	[[image:1755250157536-746.png]]
37.3	191
	192	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]]
	193
	194	Dort wird die Datei auch grafisch dargestellt.
	195
	196
37.4	197	= Maven und OpenAPI =
	198
38.2	199	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]]
37.4	200
38.2	201	Man kann dabei jetzt einen Kommandozeilenaufruf verwenden oder man setzt auf das im Basisprojekt vorhandene MVN ()
37.4	202
38.2	203	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:
37.4	204
38.2	205	== Client ==
38.1	206
38.2	207	Im Client werden die Apache Http Bibliothek verwendet.
	208
	209
	210	[[image:1756887005209-855.png]]
	211
	212	== Server ==
	213
	214	Im Server wird Spring (Boot) verwendet
	215
	216	[[image:1756887037619-847.png]]
	217
	218	TODO: Weitere Informationen zu
	219
	220	- Lombok
	221
	222	- Dependency Injection
	223
	224	- Spring (Boot), siehe auch [[https:~~/~~/www.marcobehler.com/guides/spring-framework>>https://www.marcobehler.com/guides/spring-framework]]
	225
	226
	227
38.1	228	= Erweiterung der REST-Schnittstelle =
	229
38.2	230	In diesem Beispiel wird einmal gezeigt, wie die REST-Schnittstelle des Basisprojektes einfach erweitert werden kann.
	231
	232	In diesem Beispiel soll die aktuelle Schnittstelle um die Möglichkeit erweitert werden, alle Lobbies vom Server zu bekommen.
	233
	234	== Schritt 1: Erweitere das OpenAPI-Dokument ==
	235
	236	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.
	237
	238	Die Funktion soll sehr einfach sein und keine Parameter verlangen. Dafür bietet sich die GET-Funktion an.
	239
	240	Im folgenden Bild sind alle Anpassungen zu sehen:
	241
	242	[[image:1756887436525-790.png\|\|height="355" width="974"]]
	243
	244
	245	Nach dem Speichern, sollte das OpenAPI-Dokument wie folgt aussehen
	246
	247	[[image:1756887488020-376.png\|\|height="642" width="904"]]
	248
	249
38.3	250	Jetzt kann man entweder in IntelliJ
38.2	251
38.3	252	[[image:1756888245896-845.png\|\|height="347" width="620"]]
	253
	254	oder im Terminal (z.B. auch in IntelliJ)
	255
	256	[[image:1756888279902-777.png\|\|height="637" width="1053"]]
	257
	258	Wobei hier auch clean compile reichen würde.
	259
	260	ACHTUNG! Falls maven Problem macht, kann das auch an einer falschen Java-Version im System liegen (siehe auch [[FAQ>>doc:.Basisprojekt FAQ.WebHome]])
	261
	262	Es werden durch den Aufruf neue Inhalte generiert (bzw. die alten überschrieben).
	263
	264	[[image:1756888428042-802.png\|\|height="538" width="1077"]]
	265
	266	Hinweis: Niemals Änderungen unterhalb des target-Ordners machen. Das wird von Maven bei clean gelöscht.
	267
	268	=== Wie bekommt man dann aber nun die Funktionalität rein? ===
	269
	270	Für jeden Endpunkt (also aktuell lobbies und users) werden drei Interfaces/Klassen erzeugt:
	271
	272	* *Api (z.B, LobbiesApi): Beschreibung der REST-Methoden, vor allem auch das Mapping von z.B. /lobbies/join auf die Methode lobbyJoin(String)
	273	* (((
	274	ApiController implements Api (Für Spring) (z.B. LobbiesApiController)
	275	)))
	276	* (((
40.2	277	ApiDelegate (z.B. LobbiesApiDelegate): Macht die eigentliche Arbeit und muss* im eigenen Code-Bereich** erweitert werden!
38.3	278	)))
	279
	280
	281
	282	== Schritt 2: Erweiterung auf Server-Seite ==
	283
	284	Da es schon Funktionen für die Lobbies gibt, gibt es auch bereits eine Implementierung, die LobbiesApiDelegate überschreibt
	285
	286	[[image:1756888762381-912.png\|\|height="48" width="789"]]
	287
	288	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).
	289
	290	In der Klasse muss man dann die neue Methode lobbyList aus der API überschreiben.
	291
	292	[[image:1756888929507-312.png\|\|height="156" width="1161"]]
	293
	294	Dabei wird folgendes gemacht:
	295
	296	1. Es wird ein Rückgabeobjekt vom Typ Liste erzeugt
	297	1. Es wird über alles Lobbies auf dem Server gegangen (lobbyManagement.getLobbies())
	298	1. Da der Client u.U. nicht die vollständigen Informationen über die Lobbies bekommen soll, gibt es zwei unterschiedliche Klassen: ServerLobby und LobbyDTO.
	299	1. Die Foreach-Schleife sorgt dafür, dass in das Rückgabeobjekt nur die LobbyDTOs eingefügt werden.
	300	1. Dafür wird eine Funktion mit dem Namen lobbyMapping verwendet
	301	1. Schließlich wird am Ende gesagt, dass alles ok ist und eine Antwort ResponseEntity.ok mit dem Rückgabeobjekt (lobbies) gesendet.
	302
38.4	303	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
38.5	304
	305	Auf Server-Seite fehlt jetzt noch die Methode getLobbies im LobbyManagement
	306
	307	[[image:1756889590500-656.png\|\|height="81" width="518"]]
	308
	309
	310	=== LobbyMapping ===
	311
	312	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!!)
	313
	314	Also z.B.
	315
	316	[[image:1756889440395-856.png]]
	317
	318	und definiert ein Interface mit einer Annotation
	319
	320	[[image:1756889472103-847.png]]
	321
	322	und damit kann man die Funktion aufrufen. Hinweis: Der Mapper ist im LobbyService über die Spring Dependency Injection gebunden.
39.1	323
	324	== Schritt 3: Erweiterung auf Client-Seite (Java) ==
	325
	326	Hinweis: Das Beispiel bezieht sich hier auf eine Client mit Java. Für andere Clients wie Angular ist das Vorgehen anders.
	327
	328	Auf der Client-Seite wird die komplette Kommunikation mit dem Server in der generierten Klasse DefaultApi gekapselt.
	329
	330	[[image:1756889795622-530.png]]
	331
	332	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
	333
	334	Im Client gibt es auch eine Klasse LobbyService. Dort ist die DefaultApi Klasse über Dependency Injection gebunden.
	335
	336	[[image:1756889917681-650.png]]
	337
	338	Dort kann man nun eine neue Methode getLobbies() integrieren:
	339
	340	[[image:1756889979252-910.png]]
	341
	342	Und das Ganze dann z.B. im MainMenuPresenter verwenden:
	343
	344	[[image:1756890010118-149.png\|\|height="116" width="972"]]
	345
	346	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.
	347
40.2	348
	349	= Kommunikation: Server ~-~-> Client (WebSockets) =
	350
	351	[[image:1756890800817-370.png\|\|height="604" width="1121"]]
	352
51.2	353	Da man mit REST nicht Nachrichten vom Server an den Client schicken kann, werden im Basisprojekt dafür WebSockets verwendet.
	354
	355	Spring bietet eine native Unterstützung von WebSockets. Für eigene Funktionen kann man sich in die Kommunikation über die Serverklasse WebSocketHandler einklinken
	356
	357
	358	[[image:1756890924024-346.png\|\|height="377" width="1092"]]
	359
	360
	361	Sobald sich jemand beim Server für WebSockets angemeldet hat wird von Spring ein org.springframework.web.socket.messaging.SessionConnectedEvent
	362	geworfen, welches in der folgenden Methode (im WebSocketHandler) aufgefangen wird
	363
	364	[[image:1756890958794-603.png\|\|height="373" width="1087"]]
	365
	366	Die Methode ist Observer für das Event SessionConnectedEvent
	367
	368	Der WebSocketServer kennt die Nutzer und erlaubt das Einloggen nur, wenn Login und Passwort stimmen (durch Spring Security)
	369
	370	[[image:1756891019715-621.png]]
	371
	372	1)Aus dem Event kann der Nutzer gelesen werden (der sollte nie leer sein)
	373
	374	2) Dann wird sich aus dem Repository (später mehr) der Nutzer geholt, der durch den Namen identifiziert ist (z.B. „test1“)
	375
	376	3) Schließlich werden allen anderen darüber informiert, dass ein neuer Nutzer da ist
	377
	378	== STOMP ==
	379
	380	WebSockets haben kein Protokoll (wie z.B. http)
	381
	382	Es können entweder binäre oder textuelle Daten verarbeitet werden (die jeweiligen Gegenstellen müssen das wissen!)
	383
	384	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)
	385
	386	STOMP: Streaming Text Oriented Messaging Protocol
	387
	388	Definiert ein einfaches Protokoll, welches es erlaubt, sinnvoll über WebSockets zu kommunizieren
	389
	390	Ist ein Teil von Spring
	391
	392	Methoden sind z.B. CONNECT, SEND oder SUBSCRIBE
	393
	394	STOMP arbeitet mit Topics
	395
	396	Ein Client registriert (SUBSCRIBE) sich für bestimmte Ereignistypen
	397
	398
	399	§Wenn auf der Server-Seite dieser Typ veröffentlich wird dann wird dies an die jeweils interessierten Clients geschickt
	400
	401	Publish/Subscribe-Pattern
	402
	403	[[https:~~/~~/docs.spring.io/spring-framework/reference/web/websocket/stomp.html>>url:https://docs.spring.io/spring-framework/reference/web/websocket/stomp.html]]
	404
	405
	406	§Der Server definiert unterschiedliche Topics (je nach Modul)
	407
	408	§Beim Nutzermanagement aktuell:
	409
	410	§/topic/users/loggedIn: Es hat sich ein neuer Nutzer angemeldet
	411
	412	§/topic/users/loggedOut: Ein Nutzer hat sich ausgeloggt
	413
	414
	415	[[image:1756891125969-748.png\|\|height="317" width="726"]]
	416
	417	§Topic-Namen sind Strings, sollte aber Aufbau von oben entsprechen
	418
	419	§In der Lobby würde es stattdessen /topic/lobbies/* heißen
	420
	421	== WebSockets: Versenden von Nachrichten ==
	422
	423	[[image:1756891180516-843.png\|\|height="426" width="801"]]
	424
	425	[[image:1756891216134-578.png\|\|height="428" width="699"]]
	426
	427	== Nachrichteninhalt ==
	428
	429	[[image:1756891254830-647.png\|\|height="101" width="777"]]
	430
	431	* message kann grundsätzlich alles sein, was serialisiert werden kann
	432	* Man könnte nun einfach die Java-Serialisierung verwenden (im alten Basisprojekt ist das auch so)
	433	* Das hat aber eine Reihe von Nachteilen
	434	** 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
	435	** Es gibt eine Reihe von Sicherheitsproblemen
	436	* Besser: Definiere ein gemeinsames Austauschformat, was viele verstehen ~-~-> Im Basisprojekt (und in vielen anderen Projekten auch) JSON verwenden
	437	* Insbesondere Web-Clients (JavaScript) bieten hervorragende Möglichkeiten, an JSON zu verarbeiten
	438	* Client und Server haben sich damit auf Format für den Austausch geeinigt
	439	** Topic: Strings
	440	** Message: JSON
	441
	442	An den Clilent werden auch bei WebSockets nur DTOs verschickt! (userMapping)
	443
	444	[[image:1756891375095-158.png\|\|height="266" width="775"]]
	445
	446	== Wie verbindet sich ein Client mit dem Server? ==
	447
	448	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.
	449
	450	[[image:1756891512330-186.png\|\|height="170" width="820"]]
	451
	452	=== Auf Server Seite (WebSocketConnectionManager): ===
	453
	454	[[image:1756891551794-161.png\|\|height="387" width="1019"]]
	455
	456	1) Variablen definieren
	457
	458	2) WebSocketClient erzeugen
	459
	460	3) Daraus WebSocketStompClient machen
	461
	462	4) Jackson als Mapper definieren (DTO-Object <-> JSON)
	463
	464	=== [[image:1756891617399-232.png\|\|height="289" width="1006"]] ===
	465
	466
	467	1) Asynchron die Verbindung zum Server aufbauen
	468
	469	2) Wenn erfolgreich in das Hauptmenü wechseln (showScene à später mehr)
	470
	471	3) Über den Kontext ein Event pushen LoggedInEvent
	472
	473	4) Jede Serververbindung hat eine Session

Wiki source code of Basisprojekt

Applications

Navigation