Basisprojekt
- Basisprojekt mit IntelliJ einrichten
- Überblick über das Basisprojekt
- Kommunikation vom Client zum Server: REST
- OpenAPI
- Maven und OpenAPI
- Erweiterung der REST-Schnittstelle
- Asynchrone Kommunikation zum Client: WebSockets
Basisprojekt mit IntelliJ einrichten
Repository klonen
Sie finden die Clone-URL wie folgt:
- Loggen Sie sich auf https://gitlab.swl.informatik.uni-oldenburg.de/ ein
- Falls nicht vorausgewählt, wählen Sie auf der linken Seite "Projects"
- Da Sie bisher noch nichts gemacht haben, ist diese Seite leer. Wechseln Sie auf den Reiter Member
- Dort sollte ihr Repository zu finden sein.
- Oben rechts gibt es einen Button Code. Kopieren Sie dort die URL, die hinter "Clone with HTTPS" steht.
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.
Dort können Sie mit 
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.
Bei den Scopes sollten die beiden Rechte "read_repository" und "write_repository" gewählt werden.
Danach wird das Access Token generiert
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
sollten Sie einen Bildschirm ähnlich zu dem folgenden sehen:
Auf dem main-Branch (master) kann keine Änderung gemacht werden, deswegen muss auf einen anderen Branch gewechselt werden. Im Beispiel development.
Initialer Maven-Build und Codegenerierung
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.
Lombok-Plugin
Falls das Lombok-Plugin noch nicht installiert ist, installieren bzw. aktivieren Sie es in IntelliJ.
Je nach IntelliJ-Edition kann zusätzlich das Spring-/Spring-Boot-Plugin hilfreich sein.
Server starten
Den Serverbereich aufklappen und dort auf die Datei ServerApp mit der rechten Maustaste klicken.
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.
Logging umstellen
Wenn man möchte, kann man das Logging umstellen.
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.
Wenn man die Anwendung einmal gestartet hat, kann man dies Configuration anpassen:
Wenn die verwendete IntelliJ-Version keine Spring-Unterstützung bietet, kann das Profil über eine Umgebungsvariable in der Server-Konfiguration gesetzt werden:
SPRING_PROFILES_ACTIVE=dev
Danach muss man den Server neu starten!
Client starten
Wenn der Server gestartet ist, kann man mehrere Clients starten. Dafür auf jeden Fall die Klasse Main verwenden.
Mehrere Instanzen des Clients ermöglichen
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.
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.
Überblick über das Basisprojekt
Projektstruktur
Kommunikation vom Client zum Server: REST
Für klassische Request/Response-Operationen verwendet das Basisprojekt REST über HTTP. Als Austauschformat wird JSON verwendet. Die zentrale Spiellogik verbleibt auf dem Server.
OpenAPI
- Paths: Endpunkte der API (z.B. /users, /lobbies).
- Operations: Spezifikation von Methoden wie GET, POST.
- Schemas: Beschreibung der Datenstrukturen für Ein- und Ausgaben.
- Security: Authentifizierungsmechanismen.
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.
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
Dort wird die Datei auch grafisch dargestellt.
Maven und OpenAPI
Die OpenAPI-Datei kann verwendet werden, um Teile der REST-Schnittstelle zu generieren. Dafür wird der OpenAPI Generator eingesetzt https://github.com/OpenAPITools/openapi-generator
Die Generierung kann über die Kommandozeile erfolgen; im Basisprojekt ist sie bereits in den Maven-Build integriert.
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.
Server
Auf der Serverseite werden Spring-/Spring-Boot-kompatible Schnittstellen und Controller-Strukturen generiert.
Erweiterung der REST-Schnittstelle
In diesem Beispiel wird einmal gezeigt, wie die REST-Schnittstelle des Basisprojektes einfach erweitert werden kann.
In diesem Beispiel soll die aktuelle Schnittstelle um die Möglichkeit erweitert werden, alle Lobbies vom Server zu bekommen.
Schritt 1: OpenAPI-Dokument erweitern
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.
Die Funktion soll sehr einfach sein und keine Parameter verlangen. Dafür bietet sich die GET-Funktion an.
Im folgenden Bild sind alle Anpassungen zu sehen:
Nach dem Speichern, sollte das OpenAPI-Dokument wie folgt aussehen
Jetzt kann man entweder in IntelliJ
oder im Terminal (z.B. auch in IntelliJ)
Wobei hier auch clean compile reichen würde.
ACHTUNG! Falls maven Problem macht, kann das auch an einer falschen Java-Version im System liegen (siehe auch FAQ)
Es werden durch den Aufruf neue Inhalte generiert (bzw. die alten überschrieben).
Hinweis: Niemals Änderungen unterhalb des target-Ordners machen. Das wird von Maven bei clean gelöscht.
Wo wird die eigentliche Funktionalität implementiert?
Für jeden API-Bereich (z. B. `lobbies` und `users`) werden serverseitig typischerweise mehrere Schnittstellen bzw. Klassen generiert:
- *Api (z.B, LobbiesApi): Beschreibung der REST-Methoden, vor allem auch das Mapping von z.B. /lobbies/join auf die Methode lobbyJoin(String)
*ApiController implements *Api (Für Spring) (z.B. LobbiesApiController)
- `*ApiDelegate` (z. B. `LobbiesApiDelegate`): Delegationsschnittstelle. Die fachliche Implementierung erfolgt im eigenen, nicht generierten Code.
Schritt 2: Erweiterung auf Server-Seite
Da es schon Funktionen für die Lobbies gibt, gibt es auch bereits eine Implementierung, die LobbiesApiDelegate überschreibt
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.
In der Klasse muss man dann die neue Methode lobbyList aus der API überschreiben.
Dabei wird folgendes gemacht:
- Es wird ein Rückgabeobjekt vom Typ Liste erzeugt
- Es wird über alles Lobbies auf dem Server gegangen (lobbyManagement.getLobbies())
- Da der Client u.U. nicht die vollständigen Informationen über die Lobbies bekommen soll, gibt es zwei unterschiedliche Klassen: ServerLobby und LobbyDTO.
- Die Foreach-Schleife sorgt dafür, dass in das Rückgabeobjekt nur die LobbyDTOs eingefügt werden.
- Dafür wird eine Funktion mit dem Namen lobbyMapping verwendet
- Schließlich wird am Ende gesagt, dass alles ok ist und eine Antwort ResponseEntity.ok mit dem Rückgabeobjekt (lobbies) gesendet.
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
Auf Server-Seite fehlt jetzt noch die Methode getLobbies im LobbyManagement
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.
Also z.B.
und definiert ein Interface mit einer Annotation
und damit kann man die Funktion aufrufen. Hinweis: Der Mapper ist im LobbyService über die Spring Dependency Injection gebunden.
Schritt 3: Erweiterung auf Client-Seite (Java)
Auf der Client-Seite wird die komplette Kommunikation mit dem Server in der generierten Klasse DefaultApi gekapselt.
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
Im Client gibt es auch eine Klasse LobbyService. Dort ist die DefaultApi Klasse über Dependency Injection gebunden.
Dort kann man nun eine neue Methode getLobbies() integrieren:
Und das Ganze dann z.B. im MainMenuPresenter verwenden:
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
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.
Spring bietet eine native Unterstützung von WebSockets. Für eigene Funktionen kann man sich in die Kommunikation über die Serverklasse WebSocketHandler einklinken
Sobald sich jemand beim Server für WebSockets angemeldet hat wird von Spring ein org.springframework.web.socket.messaging.SessionConnectedEvent
geworfen, welches in der folgenden Methode (im WebSocketHandler) aufgefangen wird
Die Methode ist Observer für das Event SessionConnectedEvent
Der WebSocketServer kennt die Nutzer und erlaubt das Einloggen nur, wenn Login und Passwort stimmen (durch Spring Security)
1)Aus dem Event kann der Nutzer gelesen werden (der sollte nie leer sein)
2) Dann wird sich aus dem Repository (später mehr) der Nutzer geholt, der durch den Namen identifiziert ist (z.B. „test1“)
3) Schließlich werden allen anderen darüber informiert, dass ein neuer Nutzer da ist
STOMP
WebSocket stellt einen bidirektionalen Kommunikationskanal bereit. Für eine strukturierte Nachrichtenkommunikation verwendet das Basisprojekt darüber STOMP (Streaming Text Oriented Messaging Protocol).
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.
Veröffentlicht der Server eine Nachricht auf einem Topic, erhalten sie die dafür registrierten Clients. Dieses Modell entspricht dem Publish/Subscribe-Pattern.
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:
- `/topic/users/loggedIn`: Ein Nutzer hat sich angemeldet.
- `/topic/users/loggedOut`: Ein Nutzer hat sich ausgeloggt.
Topic-Namen sind Strings, sollten aber einem konsistenten fachlichen Namensschema folgen. Für Lobby-Ereignisse bietet sich entsprechend `/topic/lobbies/...` an.
WebSockets: Versenden von Nachrichten
Nachrichteninhalt
- message kann grundsätzlich alles sein, was serialisiert werden kann
- Technisch könnte Java-Serialisierung verwendet werden; das alte Basisprojekt hat dies teilweise getan.
- 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.
- 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.
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.
Auf Client-Seite: WebSocketConnectionManager
1) Variablen definieren
2) WebSocketClient erzeugen
3) Daraus WebSocketStompClient machen
4) Jackson als Mapper definieren (DTO-Object <-> JSON)
1) Asynchron die Verbindung zum Server aufbauen
2) Wenn erfolgreich in das Hauptmenü wechseln (showScene à später mehr)
3) Über den Kontext ein Event pushen LoggedInEvent
4) Jede Serververbindung hat eine Session