Basisprojekt
Hier folgen Erklärungen des neuen Basisprojekts. Es wird um die folgenden Themen gehen:
- Basisprojekt mit IntelliJ einrichten
- Kurzer Blick ins Basisprojekt
- Kommunikation Client --> Server
- OpenAPI
- Maven und OpenAPI
- Erweiterung der REST-Schnittstelle
Basisprojekt mit IntelliJ einrichten
Clone
Auf anderen Branch wechseln (hier development)
Initialer Build (Generierung)
Lombok Plugin
Lombok Plugin installiert? Wenn nein jetzt machen
Hinweis: Wenn man schon hier ist, kann man auch das Spring-(Boot)-Plugin installieren
Server laufen lassen
... und ggf. Lombok aktivieren (Man wird nach dem Start der Anwendung gefragt)
Logging umstellen
Development Profil aktivieren
damit dann user1 - user9 angelegt werden und man nicht jedesmal neu registrieren muss
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
Client starten
Mehrere Instanzen des Clients ermöglichen
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.
Kurzer Blick ins Basisprojekt
Screenshots
Kommunikation Client --> Server
Der Server verwendet das REST-Protokoll und als Austauschformat JSON
OpenAPI
(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)
- Paths: Endpunkte der API (z.B. /users, /lobbies).
- Operations: Spezifikation von Methoden wie GET, POST.
- Definitions: Detaillierte Beschreibung von Eingabe- und Ausgabestrukturen.
- Security: Authentifizierungsmechanismen.
Kann JSON oder YAML (Yet Another Markup Language) verwenden YAML ist wie JSON nur mit weniger Klammern
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 sich die REST-Schnittstellen generieren zu lassen. Diese Erzeugung erfolgt mit dem OpenAPI Generator https://github.com/OpenAPITools/openapi-generator
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 Client werden die Apache Http Bibliothek verwendet.
Server
Im Server wird Spring (Boot) verwendet
TODO: Weitere Informationen zu
- Lombok
- Dependency Injection
- Spring (Boot), siehe auch 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.
In diesem Beispiel soll die aktuelle Schnittstelle um die Möglichkeit erweitert werden, alle Lobbies vom Server zu bekommen.
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.
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.
Wie bekommt man dann aber nun die Funktionalität rein?
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)
*ApiController implements *Api (Für Spring) (z.B. LobbiesApiController)
*ApiDelegate (z.B. LobbiesApiDelegate): Macht die eigentliche Arbeit und muss im eigenen Code-Bereich erweitert werden!
Schritt 2: Erweiterung auf Server-Seite
Da es schon Funktionen für die Lobbies gibt, gibt es auch bereits eine Implementierung, die LobbiesApiDelegate überschreibt
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.
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