Wiki source code of Basisprojekt

Version 39.1 by mgrawunder on 2025/09/03 11:01

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
	14	[[image:1755245971657-468.png]]
	15
	16
	17	[[image:1755245980026-164.png]]
	18
	19	Auf anderen Branch wechseln (hier development)
	20
	21	[[image:1755245996886-733.png]]
	22
24.2	23	== Initialer Build (Generierung) ==
7.2	24
10.2	25	[[image:1755246008466-477.png]]
7.2	26
	27
10.2	28	[[image:1755246018789-616.png]]
	29
	30
24.2	31	== Lombok Plugin ==
	32
23.1	33	Lombok Plugin installiert? Wenn nein jetzt machen
	34
25.2	35	[[image:1755248508652-523.png]]
24.2	36
37.2	37	Hinweis: Wenn man schon hier ist, kann man auch das Spring-(Boot)-Plugin installieren
23.1	38
37.2	39	[[image:1756886220468-891.png]]
36.2	40
25.2	41	== Server laufen lassen ==
23.1	42
10.2	43	[[image:1755246035428-328.png]]
	44
	45
25.3	46	... und ggf. Lombok aktivieren (Man wird nach dem Start der Anwendung gefragt)
10.2	47
23.1	48	[[image:1755246072443-191.png]]
10.2	49
	50
23.1	51	[[image:1755246118807-452.png]]
10.2	52
2.2	53
25.3	54	== Logging umstellen ==
3.1	55
23.1	56	[[image:1755246135109-325.png]]
	57
	58
	59	[[image:1755246147827-679.png]]
	60
	61
	62	[[image:1755246162330-595.png]]
	63
25.3	64	== Development Profil aktivieren ==
23.1	65
25.3	66	damit dann user1 - user9 angelegt werden und man nicht jedesmal neu registrieren muss
	67
23.1	68	[[image:1755246173415-934.png]]
	69
	70
37.3	71	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	72
	73	SPRING_PROFILES_ACTIVE=dev
	74
26.2	75	[[image:1755248752596-839.png]]
	76
	77
	78	== Client starten ==
	79
23.1	80	[[image:1755246257400-525.png]]
	81
	82
	83	[[image:1755246212916-883.png]]
	84
	85
	86	[[image:1755246223246-834.png]]
	87
	88
26.2	89	=== Mehrere Instanzen des Clients ermöglichen ===
	90
23.1	91	[[image:1755246233218-893.png]]
	92
	93
27.1	94	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	95
23.1	96	[[image:1755246292057-581.png]]
	97
30.2	98
	99	= Kurzer Blick ins Basisprojekt =
	100
	101	[[image:1755249096987-249.png]]
	102
	103
	104	[[image:1755249136156-419.png]]
33.1	105
	106
	107	== Screenshots ==
	108
	109	[[image:1755249228556-469.png]]
	110
	111
	112	= Kommunikation Client ~-~-> Server =
	113
	114	[[image:1755249285866-367.png]]
	115
34.1	116	Der Server verwendet das REST-Protokoll und als Austauschformat JSON
	117
	118	= OpenAPI =
	119
37.3	120	(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)
	121
34.1	122	[[image:1755250026156-269.png]]
	123
	124	[[image:1755250050031-304.png]]
	125
	126	* Paths: Endpunkte der API (z.B. /users, /lobbies).
	127	* Operations: Spezifikation von Methoden wie GET, POST.
	128	* Definitions: Detaillierte Beschreibung von Eingabe- und Ausgabestrukturen.
	129	* Security: Authentifizierungsmechanismen.
	130
	131	[[image:1755250061990-172.png]]
36.1	132
	133	Kann JSON oder YAML (Yet Another Markup Language) verwenden YAML ist wie JSON nur mit weniger Klammern
	134
	135	[[image:1755250157536-746.png]]
37.3	136
	137	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]]
	138
	139	Dort wird die Datei auch grafisch dargestellt.
	140
	141
37.4	142	= Maven und OpenAPI =
	143
38.2	144	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	145
38.2	146	Man kann dabei jetzt einen Kommandozeilenaufruf verwenden oder man setzt auf das im Basisprojekt vorhandene MVN ()
37.4	147
38.2	148	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	149
38.2	150	== Client ==
38.1	151
38.2	152	Im Client werden die Apache Http Bibliothek verwendet.
	153
	154
	155	[[image:1756887005209-855.png]]
	156
	157	== Server ==
	158
	159	Im Server wird Spring (Boot) verwendet
	160
	161	[[image:1756887037619-847.png]]
	162
	163	TODO: Weitere Informationen zu
	164
	165	- Lombok
	166
	167	- Dependency Injection
	168
	169	- Spring (Boot), siehe auch [[https:~~/~~/www.marcobehler.com/guides/spring-framework>>https://www.marcobehler.com/guides/spring-framework]]
	170
	171
	172
38.1	173	= Erweiterung der REST-Schnittstelle =
	174
38.2	175	In diesem Beispiel wird einmal gezeigt, wie die REST-Schnittstelle des Basisprojektes einfach erweitert werden kann.
	176
	177	In diesem Beispiel soll die aktuelle Schnittstelle um die Möglichkeit erweitert werden, alle Lobbies vom Server zu bekommen.
	178
	179	== Schritt 1: Erweitere das OpenAPI-Dokument ==
	180
	181	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.
	182
	183	Die Funktion soll sehr einfach sein und keine Parameter verlangen. Dafür bietet sich die GET-Funktion an.
	184
	185	Im folgenden Bild sind alle Anpassungen zu sehen:
	186
	187	[[image:1756887436525-790.png\|\|height="355" width="974"]]
	188
	189
	190	Nach dem Speichern, sollte das OpenAPI-Dokument wie folgt aussehen
	191
	192	[[image:1756887488020-376.png\|\|height="642" width="904"]]
	193
	194
38.3	195	Jetzt kann man entweder in IntelliJ
38.2	196
38.3	197	[[image:1756888245896-845.png\|\|height="347" width="620"]]
	198
	199	oder im Terminal (z.B. auch in IntelliJ)
	200
	201	[[image:1756888279902-777.png\|\|height="637" width="1053"]]
	202
	203	Wobei hier auch clean compile reichen würde.
	204
	205	ACHTUNG! Falls maven Problem macht, kann das auch an einer falschen Java-Version im System liegen (siehe auch [[FAQ>>doc:.Basisprojekt FAQ.WebHome]])
	206
	207	Es werden durch den Aufruf neue Inhalte generiert (bzw. die alten überschrieben).
	208
	209	[[image:1756888428042-802.png\|\|height="538" width="1077"]]
	210
	211	Hinweis: Niemals Änderungen unterhalb des target-Ordners machen. Das wird von Maven bei clean gelöscht.
	212
	213	=== Wie bekommt man dann aber nun die Funktionalität rein? ===
	214
	215	Für jeden Endpunkt (also aktuell lobbies und users) werden drei Interfaces/Klassen erzeugt:
	216
	217	* *Api (z.B, LobbiesApi): Beschreibung der REST-Methoden, vor allem auch das Mapping von z.B. /lobbies/join auf die Methode lobbyJoin(String)
	218	* (((
	219	ApiController implements Api (Für Spring) (z.B. LobbiesApiController)
	220	)))
	221	* (((
	222	ApiDelegate (z.B. LobbiesApiDelegate): Macht die eigentliche Arbeit und muss* im eigenen Code-Bereich** erweitert werden!
	223	)))
	224
	225
	226
	227	== Schritt 2: Erweiterung auf Server-Seite ==
	228
	229	Da es schon Funktionen für die Lobbies gibt, gibt es auch bereits eine Implementierung, die LobbiesApiDelegate überschreibt
	230
	231	[[image:1756888762381-912.png\|\|height="48" width="789"]]
	232
	233	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).
	234
	235	In der Klasse muss man dann die neue Methode lobbyList aus der API überschreiben.
	236
	237	[[image:1756888929507-312.png\|\|height="156" width="1161"]]
	238
	239	Dabei wird folgendes gemacht:
	240
	241	1. Es wird ein Rückgabeobjekt vom Typ Liste erzeugt
	242	1. Es wird über alles Lobbies auf dem Server gegangen (lobbyManagement.getLobbies())
	243	1. Da der Client u.U. nicht die vollständigen Informationen über die Lobbies bekommen soll, gibt es zwei unterschiedliche Klassen: ServerLobby und LobbyDTO.
	244	1. Die Foreach-Schleife sorgt dafür, dass in das Rückgabeobjekt nur die LobbyDTOs eingefügt werden.
	245	1. Dafür wird eine Funktion mit dem Namen lobbyMapping verwendet
	246	1. Schließlich wird am Ende gesagt, dass alles ok ist und eine Antwort ResponseEntity.ok mit dem Rückgabeobjekt (lobbies) gesendet.
	247
38.4	248	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	249
	250	Auf Server-Seite fehlt jetzt noch die Methode getLobbies im LobbyManagement
	251
	252	[[image:1756889590500-656.png\|\|height="81" width="518"]]
	253
	254
	255	=== LobbyMapping ===
	256
	257	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!!)
	258
	259	Also z.B.
	260
	261	[[image:1756889440395-856.png]]
	262
	263	und definiert ein Interface mit einer Annotation
	264
	265	[[image:1756889472103-847.png]]
	266
	267	und damit kann man die Funktion aufrufen. Hinweis: Der Mapper ist im LobbyService über die Spring Dependency Injection gebunden.
39.1	268
	269	== Schritt 3: Erweiterung auf Client-Seite (Java) ==
	270
	271	Hinweis: Das Beispiel bezieht sich hier auf eine Client mit Java. Für andere Clients wie Angular ist das Vorgehen anders.
	272
	273	Auf der Client-Seite wird die komplette Kommunikation mit dem Server in der generierten Klasse DefaultApi gekapselt.
	274
	275	[[image:1756889795622-530.png]]
	276
	277	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
	278
	279	Im Client gibt es auch eine Klasse LobbyService. Dort ist die DefaultApi Klasse über Dependency Injection gebunden.
	280
	281	[[image:1756889917681-650.png]]
	282
	283	Dort kann man nun eine neue Methode getLobbies() integrieren:
	284
	285	[[image:1756889979252-910.png]]
	286
	287	Und das Ganze dann z.B. im MainMenuPresenter verwenden:
	288
	289	[[image:1756890010118-149.png\|\|height="116" width="972"]]
	290
	291	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.
	292
	293

Wiki source code of Basisprojekt

Applications

Navigation