Changes for page Basisprojekt

Last modified by Marco Grawunder on 2026/09/08 10:20

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

From 64.1 to 63.1

From version 63.1

edited by Marco Grawunder
on 2026/08/25 15:36

Change comment: There is no comment for this version

To version 62.1

edited by Marco Grawunder
on 2025/10/16 11:59

Change comment: There is no comment for this version

Raw
Rendered

Summary

Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

@@ -1,8 +1,6 @@
  [[image:Main.Organisatorisches.WebHome@softwareprojekt_logo_transparent.png||alt="SoftwareprojektLogo.png" data-xwiki-image-style-alignment="end" height="136" width="309"]]
--{{info}}
--Diese Seite erklärt den Einstieg in das bereitgestellte Basisprojekt und die darin verwendete Client-Server-Kommunikation. Das Basisprojekt verwendet mindestens **Java 21**. Screenshots der IDE oder von GitLab können sich bei neueren Versionen optisch unterscheiden; die beschriebenen Arbeitsschritte bleiben davon in der Regel unberührt.
--{{/info}}
++Hier folgen Erklärungen des neuen Basisprojekts. Es wird um die folgenden Themen gehen:
  {{toc/}}
@@ -11,11 +11,9 @@
  [[image:1755245956916-184.png]]
--== Repository klonen ==
++== Clone ==
--{{warning}}
--Im Screenshot wird teilweise das globale Basisprojekt gezeigt. **Verwenden Sie für die Arbeit das bereits für Ihre Gruppe angelegte Repository.**
--{{/warning}}
++Achtung! In dem Screenshot wird das globale Basisprojekt verwendet. Für jede Gruppe existiert bereits ein eigenes Repository, welches verwendet werden sollte,
  Sie finden die Clone-URL wie folgt:
@@ -31,13 +31,13 @@
  == Access Token ==
--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 anschließend **Access tokens**.
++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.
  [[image:1757398899497-714.png||height="246" width="278"]]
  Dort können Sie mit [[image:1757398947128-748.png||height="89" width="197"]] ein neues Token anlegen.
--Als Namen kann z. B. `IntelliJ` verwendet werden. Access Tokens sind aus Sicherheitsgründen zeitlich begrenzt. Wählen Sie ein Ablaufdatum, das zum Projektzeitraum passt.
++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.
  [[image:1757399088336-273.png||height="92" width="547"]]
@@ -47,14 +47,12 @@
  [[image:1757399184270-348.png||height="99" width="978"]]
--{{warning}}
--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.**
--{{/warning}}
++Jetzt ist es wichtig, dass Sie sich das Token sichern!
  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.
--== Nach dem Klonen ==
++== Nach dem Clonen ==
  sollten Sie einen Bildschirm ähnlich zu dem folgenden sehen:
@@ -64,9 +64,10 @@
  [[image:1755245996886-733.png]]
--== Initialer Maven-Build und Codegenerierung ==
++== Initialer Build (Generierung) ==
--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.
++Dem neuen Code fehlen einige generierte Dateien. Diese werden wie folgt erzeugt.
++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.
  [[image:1755246008466-477.png]]
@@ -74,17 +74,17 @@
  [[image:1755246018789-616.png]]
--== Lombok-Plugin ==
++== Lombok Plugin ==
--Falls das Lombok-Plugin noch nicht installiert ist, installieren bzw. aktivieren Sie es in IntelliJ.
++**Lombok Plugin installiert? Wenn nein jetzt machen**
  [[image:1755248508652-523.png]]
--Je nach IntelliJ-Edition kann zusätzlich das Spring-/Spring-Boot-Plugin hilfreich sein.
++**Hinweis: Wenn man schon hier ist, kann man auch das Spring-(Boot)-Plugin **installieren
  [[image:1756886220468-891.png]]
--== Server starten ==
++== Server laufen lassen ==
  Den Serverbereich aufklappen und dort auf die Datei ServerApp mit der rechten Maustaste klicken.
@@ -91,7 +91,7 @@
  [[image:1755246035428-328.png]]
--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.
++... 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.
  [[image:1755246072443-191.png]]
@@ -111,9 +111,9 @@
  [[image:1755246162330-595.png]]
--== Development-Profil aktivieren ==
++== Development Profil aktivieren ==
--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.
++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.
  Wenn man die Anwendung einmal gestartet hat, kann man dies Configuration anpassen:
@@ -122,7 +122,7 @@
  [[image:1755246173415-934.png]]
--Wenn die verwendete IntelliJ-Version keine Spring-Unterstützung bietet, kann das Profil über eine Umgebungsvariable in der Server-Konfiguration gesetzt werden:
++**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: **
  **SPRING_PROFILES_ACTIVE=dev**
@@ -134,9 +134,7 @@
  Wenn der Server gestartet ist, kann man mehrere Clients starten. Dafür auf jeden Fall die Klasse Main verwenden.
--{{warning}}
--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.
--{{/warning}}
++**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!**
  [[image:1755246257400-525.png]]
@@ -154,12 +154,12 @@
  [[image:1755246233218-893.png]]
--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.
++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.
  [[image:1755246292057-581.png]]
--= Überblick über das Basisprojekt =
++= Kurzer Blick ins Basisprojekt =
  [[image:1755249096987-249.png]]
@@ -167,22 +167,20 @@
  [[image:1755249136156-419.png]]
--== Projektstruktur ==
++== Screenshots ==
  [[image:1755249228556-469.png]]
--= Kommunikation vom Client zum Server: REST =
++= Kommunikation Client ~-~-> Server =
  [[image:1755249285866-367.png]]
--Für klassische Request/Response-Operationen verwendet das Basisprojekt **REST über HTTP**. Als Austauschformat wird **JSON** verwendet. Die zentrale Spiellogik verbleibt auf dem Server.
++Der Server verwendet das REST-Protokoll und als Austauschformat JSON
  = OpenAPI =
--{{info}}
--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.
--{{/info}}
++(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)
  [[image:1755250026156-269.png]]
@@ -190,12 +190,12 @@
  * **Paths**: Endpunkte der API (z.B. /users, /lobbies).
  * **Operations**: Spezifikation von Methoden wie GET, POST.
--* **Schemas**: Beschreibung der Datenstrukturen für Ein- und Ausgaben.
++* **Definitions**: Detaillierte Beschreibung von Eingabe- und Ausgabestrukturen.
  * **Security**: Authentifizierungsmechanismen.
  [[image:1755250061990-172.png]]
--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.
++Kann JSON oder YAML (Yet Another Markup Language) verwenden YAML ist wie JSON nur mit weniger Klammern
  [[image:1755250157536-746.png]]
@@ -206,15 +206,15 @@
  = Maven und OpenAPI =
--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]]
++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]]
--Die Generierung kann über die Kommandozeile erfolgen; im Basisprojekt ist sie bereits in den Maven-Build integriert.
++Man kann dabei jetzt einen Kommandozeilenaufruf verwenden oder man setzt auf das im Basisprojekt vorhandene MVN ()
  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:
  == Client ==
--Im Java-Client wird ein HTTP-Client für den Zugriff auf die generierte API verwendet.
++Im Client werden die Apache Http Bibliothek verwendet.
  [[image:1756887005209-855.png]]
@@ -221,16 +221,20 @@
  == Server ==
--Auf der Serverseite werden Spring-/Spring-Boot-kompatible Schnittstellen und Controller-Strukturen generiert.
++Im Server wird Spring (Boot) verwendet
  [[image:1756887037619-847.png]]
--{{info}}
--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]].
--{{/info}}
++TODO: Weitere Informationen zu
++- Lombok
++- Dependency Injection
++- Spring (Boot), siehe auch [[https:~~/~~/www.marcobehler.com/guides/spring-framework>>https://www.marcobehler.com/guides/spring-framework]]
++
++
++
  = Erweiterung der REST-Schnittstelle =
  In diesem Beispiel wird einmal gezeigt, wie die REST-Schnittstelle des Basisprojektes einfach erweitert werden kann.
@@ -237,7 +237,7 @@
  In diesem Beispiel soll die aktuelle Schnittstelle um die Möglichkeit erweitert werden, alle Lobbies vom Server zu bekommen.
--== Schritt 1: OpenAPI-Dokument erweitern ==
++== Schritt 1: Erweitere das OpenAPI-Dokument ==
  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.
@@ -271,9 +271,9 @@
  Hinweis: Niemals Änderungen unterhalb des target-Ordners machen. Das wird von Maven bei clean gelöscht.
--=== Wo wird die eigentliche Funktionalität implementiert? ===
++=== Wie bekommt man dann aber nun die Funktionalität rein? ===
--Für jeden API-Bereich (z. B. `lobbies` und `users`) werden serverseitig typischerweise mehrere Schnittstellen bzw. Klassen generiert:
++Für jeden Endpunkt (also aktuell lobbies und users) werden drei Interfaces/Klassen erzeugt:
  * *Api (z.B, LobbiesApi): Beschreibung der REST-Methoden, vor allem auch das Mapping von z.B. /lobbies/join auf die Methode lobbyJoin(String)
  * (((
@@ -280,7 +280,7 @@
  *ApiController implements *Api (Für Spring) (z.B. LobbiesApiController)
  )))
  * (((
--* `*ApiDelegate` (z. B. `LobbiesApiDelegate`): Delegationsschnittstelle. Die fachliche Implementierung erfolgt **im eigenen, nicht generierten Code**.
++*ApiDelegate (z.B. LobbiesApiDelegate): Macht die eigentliche Arbeit und muss** im eigenen Code-Bereich** erweitert werden!
  )))
@@ -291,7 +291,7 @@
  [[image:1756888762381-912.png||height="48" width="789"]]
--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.
++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).
  In der Klasse muss man dann die neue Methode lobbyList aus der API überschreiben.
@@ -315,7 +315,7 @@
  === LobbyMapping ===
--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.
++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!!)
  Also z.B.
@@ -329,9 +329,7 @@
  == Schritt 3: Erweiterung auf Client-Seite (Java) ==
--{{info}}
--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.
--{{/info}}
++Hinweis: Das Beispiel bezieht sich hier auf eine Client mit Java. Für andere Clients wie Angular ist das Vorgehen anders.
  Auf der Client-Seite wird die komplette Kommunikation mit dem Server in der generierten Klasse DefaultApi gekapselt.
@@ -354,11 +354,11 @@
  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.
--= Asynchrone Kommunikation zum Client: WebSockets =
++= Kommunikation: Server ~-~-> Client (WebSockets) =
  [[image:1756890800817-370.png||height="604" width="1121"]]
--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.
++Da man mit REST nicht Nachrichten vom Server an den Client schicken kann, werden im Basisprojekt dafür WebSockets verwendet.
  Spring bietet eine native Unterstützung von WebSockets. Für eigene Funktionen kann man sich in die Kommunikation über die Serverklasse WebSocketHandler einklinken
@@ -385,26 +385,47 @@
  == STOMP ==
--WebSocket stellt einen bidirektionalen Kommunikationskanal bereit. Für eine strukturierte Nachrichtenkommunikation verwendet das Basisprojekt darüber **STOMP (Streaming Text Oriented Messaging Protocol)**.
++WebSockets haben kein Protokoll (wie z.B. http)
--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.
++Es können entweder binäre oder textuelle Daten verarbeitet werden (die jeweiligen Gegenstellen müssen das wissen!)
++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)
--Veröffentlicht der Server eine Nachricht auf einem Topic, erhalten sie die dafür registrierten Clients. Dieses Modell entspricht dem **Publish/Subscribe-Pattern**.
++STOMP: Streaming Text Oriented Messaging Protocol
++Definiert ein einfaches Protokoll, welches es erlaubt, sinnvoll über WebSockets zu kommunizieren
++
++Ist ein Teil von Spring
++
++Methoden sind z.B. CONNECT, SEND oder SUBSCRIBE
++
++STOMP arbeitet mit Topics
++
++Ein Client registriert (SUBSCRIBE) sich für bestimmte Ereignistypen
++
++
++§Wenn auf der Server-Seite dieser Typ veröffentlich wird dann wird dies an die jeweils interessierten Clients geschickt
++
++Publish/Subscribe-Pattern
++
  [[https:~~/~~/docs.spring.io/spring-framework/reference/web/websocket/stomp.html>>url:https://docs.spring.io/spring-framework/reference/web/websocket/stomp.html]]
--Der Server definiert je nach fachlichem Bereich unterschiedliche Topics. Für das Nutzermanagement sind beispielsweise vorgesehen:
++§Der Server definiert unterschiedliche Topics (je nach Modul)
--* `/topic/users/loggedIn`: Ein Nutzer hat sich angemeldet.
--* `/topic/users/loggedOut`: Ein Nutzer hat sich ausgeloggt.
++§Beim Nutzermanagement aktuell:
++§/topic/users/loggedIn: Es hat sich ein neuer Nutzer angemeldet
++§/topic/users/loggedOut: Ein Nutzer hat sich ausgeloggt
++
++
  [[image:1756891125969-748.png||height="317" width="726"]]
--Topic-Namen sind Strings, sollten aber einem konsistenten fachlichen Namensschema folgen. Für Lobby-Ereignisse bietet sich entsprechend `/topic/lobbies/...` an.
++§Topic-Namen sind Strings, sollte aber Aufbau von oben entsprechen
++§In der Lobby würde es stattdessen /topic/lobbies/* heißen
++
  == WebSockets: Versenden von Nachrichten ==
  [[image:1756891180516-843.png||height="426" width="801"]]
@@ -416,27 +416,27 @@
  [[image:1756891254830-647.png||height="101" width="777"]]
  * message kann grundsätzlich alles sein, was serialisiert werden kann
--* Technisch könnte Java-Serialisierung verwendet werden; das alte Basisprojekt hat dies teilweise getan.
++* Man könnte nun einfach die Java-Serialisierung verwenden (im alten Basisprojekt ist das auch so)
  * Das hat aber eine Reihe von Nachteilen
  ** 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
  ** Es gibt eine Reihe von Sicherheitsproblemen
--* Besser ist ein technologieunabhängigeres Austauschformat. Im Basisprojekt wird deshalb JSON verwendet.
++* Besser: Definiere ein gemeinsames Austauschformat, was viele verstehen ~-~-> Im Basisprojekt (und in vielen anderen Projekten auch) JSON verwenden
  * Insbesondere Web-Clients (JavaScript) bieten hervorragende Möglichkeiten, an JSON zu verarbeiten
  * Client und Server haben sich damit auf Format für den Austausch geeinigt
  ** Topic: Strings
  ** Message: JSON
--Auch über WebSockets werden an Clients nur geeignete DTOs übertragen; interne Serverobjekte bleiben serverintern.
++An den Clilent werden auch bei WebSockets nur DTOs verschickt! (userMapping)
  [[image:1756891375095-158.png||height="266" width="775"]]
  == Wie verbindet sich ein Client mit dem Server? ==
--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.
++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.
  [[image:1756891512330-186.png||height="170" width="820"]]
--=== Auf Client-Seite: WebSocketConnectionManager ===
++=== Auf Server Seite (WebSocketConnectionManager): ===
  [[image:1756891551794-161.png||height="387" width="1019"]]
@@ -448,7 +448,7 @@
 ) Jackson als Mapper definieren (DTO-Object <-> JSON)
--[[image:1756891617399-232.png||height="289" width="1006"]]
++=== [[image:1756891617399-232.png||height="289" width="1006"]] ===
 ) Asynchron die Verbindung zum Server aufbauen

Changes for page Basisprojekt

Summary

Details

Applications

Navigation