Dit document bevat informatie die nodig is om aan de slag te gaan met verdere ontwikkeling van Klukkluk, en bevat instructies over het opzetten van de werkomgeving en informatie over libraries die gebruikt zijn om de applicatie te ontwikkelen.

Java

Voor het ontwikkelen van de applicatie is Java 17 vereist, evenals de JavaFX 17 SDK. Configuratie van Java staat in de installatiehandleiding beschreven.

Git

Om een repository te kunnen klonen moet Git op de computer gedownload zijn. Git is een systeem dat gebruikt wordt om veranderingen in bestanden bij te houden. Het is vooral handig voor mensen die samenwerken aan projecten, zoals softwareontwikkeling, maar het kan ook voor andere soorten projecten gebruikt worden. Git kun je downloaden vanaf de volgende pagina https://www.git-scm.com/downloads

Het opstellen van het project

Om aan de slag te kunnen met Klukkluk dient men de volgende stappen te doorlopen:

1. Voeg het project toe aan git via git clone <repo>.
2. Start IntelliJ.
3. Open de pom.xml als project en laad alle dependencies.
4. Zoek in de repository het bestand JaVaFo.jar. Druk met de rechtermuisknop hierop en klik op "Add as library", druk in het pop-upmenu op "ok".
5. Controleer in module-info.java of van de twee regels die JaVaFo bevatten, degene onder de system scope in gebruik is. Dit staat in het bestand met comments aangegeven. Zie hoofdstuk 8 voor verdere toelichting.
6. Controleer in de pom.xml of bij de JaVaFo dependency de system scope met bijbehorende filepath aanwezig zijn.
7. Run Mainwrapper.class of KlukklukApplication.class om de applicatie te compileren. De applicatie zal nu opstarten.

Als de applicatie opstart zal deze een aantal waarschuwingen naar de console printen:

Deze hinderen de werking van het programma niet en kunnen genegeerd worden.

Projectstructuur

De package-structuur van de applicatie staat beschreven in het SDD. Hiernaast bevat de repository nog een aantal extra bestanden waarmee verder gewerkt kan worden.

• CREATE.sql, het script waarmee de database aangemaakt kan worden. Mochten er ooit aanpassingen moeten plaatsvinden in de database, dan kunnen die via dit bestand ingevoerd worden. (Zorg er naderhand voor dat de Entity-klassen bijgewerkt worden)
• JaVaFo.jar, De externe library gebruikt voor de indelingen voor periodecompetities via zwitsers. Hierover later nog meer informatie.

JPA

Voor verbinding met de database maakt Klukkluk gebruik van de Jakarta Persistence API. Om data uit de database te benaderen dient gebruik te worden gemaakt van de Repository en Entity-klassen, waarbij de repositories de functie van een DAO uitvoeren en een Entity een java-klasse is die een database tabel representeert. In de repositories kunnen queries op de database uitgevoerd worden in een speciaal dialect genaamd JPQL (Jakarta Persistence Query Language). Het resultaat van een query is altijd ofwel één ofwel een List van Entities. Deze entities kunnen vervolgens via mappers omgezet worden naar DTO's.

Indien er ooit een verandering aan de database moet worden doorgevoerd dienen de Entity-klassen mee aangepast te worden. Evenals als er ooit een nieuwe tabel wordt ingevoerd dient deze een corresponderende Entity-klasse te krijgen en toegevoegd te worden aan het persistence.xml bestand dat staat opgeslagen onder resources/META-INF.

module-info.java gebruiken

Klukkluk maakt gebruik van Java-modules. Deze worden gedefinieerd in het bestand module-info.java, waarin beschreven staat welke modules vereist zijn voor de werking van de applicatie, welke modules geopend worden, waarnaartoe deze worden geopend (indien toepasselijk) en welke modules geëxporteerd worden (en waarnaartoe indien van toepassing).

Voor versie 0.4 ziet het bestand er als volgt uit:

Bepaalde modules zijn verplicht naar de JavaFX module geëxporteerd te worden, zodat deze kunnen worden gebruikt met de JavaFX frontend, hierover later meer informatie.

Belangrijk, binnen de repository-klassen wordt gebruik gemaakt van Jakarta Persistence functies. Deze worden door IntelliJ rood aangegeven, IntelliJ wil deze immers van de jakarta.jakartaee.api module uitlezen. Deze functies worden al uitgelezen uit aanwezige modules. Het toevoegen van de jakarta.jakartaee.api module zorgt ervoor dat de applicatie niet zal builden.

JaVaFo

In het bestand zijn twee verschillende variaties van JaVaFo aanwezig. Welke van de twee van toepassing is hangt af van de manier waarop het project gepackaged wordt. Gedurende de ontwikkelingsperiode is gebruik gemaakt van online tooling om de codekwaliteit en stabiliteit van de builds te controleren, hiervoor moest JaVaFo in de system scope gedefinieerd worden, zodat de tooling deze via de Bitbucket repository kon inladen. Wanneer de applicatie via mvn package of mvn clean package wordt gepackaged dient gebruik te worden gemaakt van een local maven dependency via mvn install:install-file.

Om de dependency lokaal te installeren dienen de instructies in de comments van module-info.java gevolgd te worden. Hierna kunnen de JaVaFo modules omgewisseld worden en kan in pom.xml de system scope en filepath uitgecomment worden. Voor een lokale maven dependency zijn deze immers niet van toepassing.

JavaFX

JavaFX is over het algemeen vrij gemakkelijk te gebruiken, wel zijn er een paar belangrijke dingen die een ontwikkelaar moet weten om goed met JavaFX te kunnen werken. 
JavaFX werkt met FXML bestanden. Dit zijn eigenlijk een soort HTML bestanden die het raamwerk van de front-end bevatten. Er kan met CSS bestanden styling gegeven worden aan deze bestanden. Er zijn wel een paar belangrijke regels voor deze FXML bestanden. Zet deze bestanden in een folder genaamd resources die zich bevindt in de src/main van het project. FXML is niet heel lastig om mee te werken door de scene builder, voordat we hiermee beginnen moeten we echter wel eerst een controller linken aan het bestand en andere instellingen instellen. Anders zal het programma niet opstarten. 

Zoals te zien is in de bovenstaande screenshot in het rode vakje worden er meerdere dingen aangewezen aan een soort variabelen. Sommige van deze dingen genereert JavaFX zelf met het gebruik van de Scene Builder. Een paar dingen ook niet. Bijvoorbeeld de stylesheets tag bevat de link naar de stylesheet voor het bestand. De styleClass tag bevat een CSS klasse met styling en de fx:controller tag bevat een link naar de controller klasse van deze pagina. De controller bevat al het gedrag van de pagina en maakt gebruik van de fx:id's die aan verschillende velden en objecten meegegeven worden om het gedrag daarover te beheren. 

Als er op deze knop wordt gedrukt, de Scene Builder knop, wordt de Scene Builder geopend. De Scene Builder is een drag & drop interface waar buttons en andere elementen van JavaFX op de pagina gezet kunnen worden. Dit kan ook direct in de code en daar is dan ook de text knop voor. In de screenshot is de huidige pagina de text pagina. 

In de Scene Builder zijn verschillende blokken met verschillende velden en functionaliteiten. Ik heb deze voor het gemak even onderverdeeld in cijfers waar ik vanaf nu naar zal refereren. 

Blok 1 (linksboven) bevat alle elementen die in de pagina gesleept kunnen worden. Dit zijn bijvoorbeeld buttons, grafieken, een menu, tabellen en nog veel meer. Als er iets geslepen wordt in het veld in het midden (de pagina) gebeuren er twee belangrijke dingen. Één is dat er op de achtergrond in het text tabje de FXML code voor het object wordt aangemaakt. Nummer twee is dat er in vak 2 (linksonder) een nieuw object erbij komt. Het object dat net in het vak is gesleept. Vak 2 is dan ook de navigator waar alle objecten die vanuit blok 1 op de pagina gesleept worden in hiërarchische volgorde worden weergeven. Als laatste is er nog vak 3 (rechts). Dit vak bevat alle instellingen voor het object uit vak 1. Selecteer een object op de pagina en alle opties komen omhoog die aangepast kunnen worden aan dat object. Een hoop van deze instellingen kunnen ook in de text tab aangepast worden en dat is vaak ook makkelijker. 

In de bovenstaande button worden een paar belangrijke handelingen gedaan. Allereerst wordt er met fx:id een variabele naam gegeven aan de button die in de controller gebruikt kan worden. Later komt hier meer informatie over. Disable zorgt ervoor dat de knop unclickable wordt. mnemonicParsing wordt automatisch aangemaakt bij het gebruik van de Scene Builder en hoeft niet aangepast te worden. onAction is misschien wel een van de belangrijkste tag's op deze pagina. Naast onAction zijn er meerdere soortgelijke tags die onder andere staan in het kopje "Properties inherited from class javafx.scene.Node". Het is verstandig om deze API documentatie van JavaFX ook nog even goed door te lezen aangezien hier erg handige methodes in beschreven staan. De eerder genoemde onAction en andere tags die daarbij horen triggeren een actie als er een bepaalde interactie met de knop wordt gedaan. onAction activeert in dit geval de methode onDeleteButton die in de controller staat als er op de knop geklikt wordt. De hashtag voor de methode is verplicht. Als laatste is er nog de styleClass tag en deze is hetzelfde als bij de borderPane in een eerder voorbeeld. Hiermee kan een styling klasse gebonden worden aan deze button. 

In de controller zijn er een hoop van deze @FXML tags te vinden. Deze binden het FXML object aan een Java object waar de controller gebruik van kan maken. JavaFX kan deze zelf genereren als er een nieuwe fx:id gegeven wordt aan bijvoorbeeld een button door over het gele lijntje dat verschijnt te klikken en op generate in controller te klikken. Ditzelfde kan ook voor methodes en is ook aangeraden aangezien verschillende trigger tags verschillende parameters hebben. 

Dit waren zo een beetje de belangrijkste dingen voor het gebruik van JavaFX. Als laatste is er nog de stylesheet maar deze verandert niet heel veel van normaal CSS. Het is wel belangrijk dat de gebruiker een value assigned aan een CSS functie die begint met -fx. Dit zijn de ingebouwde functies van JavaFX en andere functies die niet beginnen met -fx werken af en toe, maar zijn niet heel betrouwbaar. 

Packaging via Maven

Klukkluk is een maven project, hierdoor kan de applicatie gemakkelijk gepackaged worden als een enkele .jar. Dit gebeurt door middel van de Maven Shade plugin:

De configuratie gebruikt door Klukkluk is vrij standaard en hoeft verder niet gewijzigd te worden.

De Maven Shade plugin haakt direct in de gebruikelijke maven commando's, de applicatie kan dus via mvn (clean) package gepackaged worden. Na het uitvoeren van dit commando worden er twee .jar bestanden gegenereerd: een original versie van de .jar (original-klukkluk-0.X.jar), en een zogeheten shaded .jar, genaamd klukkluk-0.X.jar. De shaded .jar bevat alle maven dependencies die nodig zijn om Klukkluk op te starten, waaronder alle onderdelen van JavaFX voor de front end van de applicatie. De original .jar heeft dit niet en zal dus niet opstarten. Deze .jar runnen via java -jar .\original-klukkluk-0.X.jar zal in de opdrachtprompt of terminal de volgende error geven:

Noot: Het betreft een ClassNotFoundException, deze wordt veroorzaakt door het ontbreken van module javafx.application.Application. Een klasse vereist door JavaFX om de applicatie te kunnen starten.

jpackage

Om de applicatie als een .msi te packagen kan gebruik worden gemaakt van jpackage. Jpackage werkt via een command line die in de Windows Opdrachtprompt of MacOS Terminal kan worden uitgevoerd. Dit ziet er als volgt uit:

jpackage --name Klukkluk --input "<path\to\main\jar\directory>" --type "msi" --app-version "0.X" --main-jar "klukkluk-0.X.jar" --win-dir-chooser --dest "<path\to\destination>" --win-shortcut --icon "<path\to\klukkluk.ico>"

In dit voorbeeld zitten een aantal opties, die naar wens kunnen worden ingesteld:

• --name: De naam van het bestand.
• --input: Het absolute pad waar de te packagen .jar staat. (Alleen de .jar mag hierin staan!)
• --dest: Het absolute pad waar de het te maken bestand wordt opgeslagen. (Deze kan leeggelaten worden, het bestand wordt in dit geval in de input directory opgeslagen)
• --type: Het type bestand om te packagen. (Let op: Dit is OS-specifiek! Een MacOS systeem mag geen .exe of .msi packagen, en een Windows systeem mag geen .pkg of .dmg aanmaken!)
• --app-version: De versie van de applicatie.
• --main-jar: de .jar die in het bestand verwerkt wordt.
• --icon: Het absolute pad naar het bestand wat als icoon voor het programma gebruikt wordt.

(Optioneel, OS-Specifiek)

• --win-dir-chooser: Geeft de gebruiker de mogelijkheid om te kiezen waar deze de applicatie wil installeren.
• --win-shortcut: maakt een snelkoppeling aan op het bureaublad.

Meer informatie over jpackage, samen met meer OS-specifieke opties, is te vinden in de documentatie van Oracle.