...

Formål

Nærværende dokument er en guide til nye udviklere af stamdataservicen på BackOfficeNSP. Guiden gennemgår på overordnet plan de aktiviteter, der er nødvendige for at kunne videreudvikle stamdataservicen.

...

Metode og rapportens opbygning

Efter nærværende introduktion vil dokumentet gennemgå de væsentligste dele af opsætningen af et lokalt udviklingsmiljø og afvikling af test/performancetest.

Dokumentet forudsætter, at læseren har grundig kendskab til Java udvikling, webservices og , Maven samt Docker-compose. Kendskab til JBoss Wildfly applikationsserver 7 vil yderligere hjælpe læseren, men er ikke en forudsætning.

I dokumentet benyttes følgende notationer:

Markering af scripts og kommandoer.

Markering af advarsler

Markering af referencer til filer.

...

Målgruppe og læsevejledning

Den primære målgruppe for dokumentet er systemudviklere.toc

...

System design

Stamdata importerne består af en kerne komponent (sdm4-core), og en række importer specifikke komponenter – alle deployes på BackOffice og har udelukkende til formål at populere data i en database (kan godt være forskellige databaser for hver komponent), se [DESIGN] for yderligere information vedrørende BackOffice. 

Komponenter på BackOffice:

BackOffice applikationerne er en række selvstændigt kørende applikationer, til overvågning af indkomne data filer, der kan være i forskellige formater (XML, fastlængde, csv, m.v). Indkomne filer indlæses, valideres og gemmes herefter i DoDi’ens database.

Hver NSP komponent er designet som en Servlet 2.4 web-applikation og benytter Guice til dependency injection.

Servlet paths, filters, osv. konfigureres direkte i koden og ikke i web.xml.

Hvert modul indeholder en ApplicationContextListener.java fil Hvert komponent indeholder en implementation af et Parser interface der fungerer som entry-point til applikationen. Det anbefales, at man som ny udvikler på projektet kigger koden igennem med denne fil som udgangspunkt.

2.1     Properties

Stamdata importerne styres af java properties filer. Hver stamdata importer har en default konfigurations fil (default-config.properties) som er deployet sammen med war filen, denne kan overstyres med en properties fil lagt i jboss uden for war filen (config.properties) – se installations guiden for detaljer

.

Seal

Stamdataservicen benytter Seal.java til håndtering af forespørgsler og svar i webservice snitfladen.

Derudover er XercesImpl også fjernet, da den på tilsvarende måde konflikter med Wildfly[1].

Properties

Stamdataservicen benytter Guice til konfigurationsstyring. Konfiguration styres via filen config.properties, der pakkes sammen med WAR-filen.

Importeren styres af historiske årsager stadig via en statisk klasse (Configuration.java).

...

Opsætning af udviklingsmiljø

Opsætningen af udviklingsmiljøet for stamdataservicen forudsætter, at følgende elementer allerede er installeret på udviklerens maskine:

• Java Developer Kit 6.0_x(JDK 8)
• Et passende udviklingsmiljø
• Maven 3.x
• Virtualbox version 4.1.18
• Vagrant version 1.0.3
• MySQL database 5.1.x
• JBoss AS7 (bliver sat op via Puppet scripts)

...

• Docker 18.x (testet med 18.09.7)

Kildekode

Kildekoden er placeret i to forskellige github-repositories:

3.1.1      BackOffice

Kildekoden er placeret her:

SVN:

Core modul: https://svn.nspop.dk/svn/triforkcomponents/sdm4-coresdm/trunk/

Maven-plugin: https://github.com/trifork/sdm4-vagrant-maven-plugin/

Test-utils: https://svn.nspop.dk/svn/trifork/sdm4-testutils/trunk/

Parent-modul inkl. Test-environment: https://svn.nspop.dk/svn/trifork/sdm4-parent/trunk/

Importer moduler

https://svn.nspop.dk/svn/trifork/sdm4-autorisationimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-bemyndigelseimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-cprimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-doseringimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-lprimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-refhostimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-sikredeimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-sksimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-sorimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-sorrelationimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-takstimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-testdataimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-tilskudsblanketimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-vaccinationimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-vitaminimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-ydelseimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-yderimporter/trunk/

Koden checkes ud på følgende måde:

% svn co <kode-url> <sdm4-navn>

3.2     Byggemiljø

 Byggemiljø

Stamdataprojektet anvender Maven som byggesystem [MAVEN]. Strukturen følger de generelle anbefalinger for Maven projekter, og er struktureret med en parent pom.xml og en projekt pom.xml fil for hvert underprojekt.

Subprojekterne er opbygget efter Maven layout konventionen.

For at bygge en importer, skal man gøre følgende:

Check Core-modul ud og kør mvn install

Check Maven-plugin ud og kør mvn install

CheckTest-utils ud og kør mvn install

Check parent-modul ud og kør mvn install

Herefter er du klar til at bygge et importer-modul.

Importmodulets integrationstest er afhængig af at ligge som et subdirectory til parent-modulet, så du skal checke det ud som sådan et.

Hvis du ønsker at checke alle importermoduler ud, ligger der i roden af parent-modulet et script, checkout-importermodules.sh, som udfører checkout af alle importermoduler samt maven-plugin og test-utils.

3.2.1      Dependencies

For at kunne hente NSI-specifikke dependencies (SEAL, nsp-util) osv. i binær form i stedet for at skulle bygge dem allesammen lokalt, indeholder pom’erne for alle importmoduler en reference til nexus.trifork.com, som er et artefaktrepository der er placeret hos Trifork. Binære releases af alle moduler inkl. core, maven-plugin, test-utils og parent findes også i nexus.trifork.com.

Repository’et bør snarest muligt udskiftes med et repository der er driftet hos NSI. Når et sådant er etableret, vil alle SDM4-moduler skifte til at bruge dette.

3.3     Database setup

3.3.1      BackOffice

BackOffice-projekterne anvender Vagrant+Ansible til at opsætte udviklingsmiljøet.

For at få bootet og opsat en udviklingsmaskine, køres følgende

% vagrant up

Fra roden af et importermodul eller fra parent-modulet.

Når vagrant har bygget den virtuelle maskine, er den sat op med den korrekte version af Wildfly samt en MariaDB der er konfigureret til at have en root-bruger med password papkasse og en sdm4-bruger med password sdm4.

Der er også automatisk oprettet en tom database med standard-navnet for databasen, (sdm_warehouse) og en datasource i JBoss med det JNDI-navn, som applikationen som default forventer at kunne slå datasource op.

Applikationen kører ved opstart automatisk databaseskema på databasen.

Der er forwardet følgende porte ind i den virtuelle maskine, så man kan tilgå Wildfly og MariaDB fra sin lokale maskine

8080 -> 8080 (dvs. at man kan tilgå http://localhost:8080/)

3307 -> 3306 (dvs. at man kan have en urelateret mysql kørende lokalt og tilgå SDM-mysql’en på den virtuelle maskine på url localhost:3307)

...

Projektet bygges (og tests afvikles) med følgende kommando:

mvn clean install

Database setup

Som en del af docker-compose setuppet for projektet, startes en MariaDB container op, og en database initialiseres.

For at starte projektet inkl. MariaDB-containeren køres følgende fra projektroden:

Det kan tage op til et minut, før databaseserveren er klar. Kig efter følgende linje i outputtet:

Bemærk at der ved afvikling af tests anvendes en in-memory H2-database, og til dette er det derfor ikke nødvendigt at starte en lokal database op. 

Autogenereret kode

Start med at køre følgende:

Stamdataprojektet benytter JAX-WS i webservice snitfladerne i CPR-WS projektet.

Snitfladekoden er autogeneret og skal ved opdatering af de associererede WSDL filer opdateres med kommandoen:

Som bagvedliggende implementering af JAX-WS benyttes Oracle’s reference implementering. Denne kan konfigureres ved at ændre i filen

Unit Tests

Installationen kan verificeres ved at eksekvere stamdataservicens test suite.

Stamdataservicen benytter JUnit, Mockito og Mockito Undertow til test.

Testkoden er for hvert modul lokaliseret i:

Test suiten afvikles ved at udføre følgende kommando i projektroden:

(Denne metode afvikler ikke testene PersonInformationIT, DetGodeCPROpslag104IT og DetGodeCPROpslag1041aIDWSIT, hvilket verify nedenfor gør)

Kommandoen kan også udføres under de individuelle moduler, hvorved kun undermodulets test udføres.

Installationen kan yderligere verificeres ved at udføre kommandoen:

Denne kommando validerer code coverage og kode konventionerne for projektet.

Kode konventionerne følger reglerne defineret i filen:

...

Som en del af testen bliver den servicen startet i en indlejret Undertow servlet-container, som der testes mod. Dette gør at noget af unit testen kører som en slags integrationstest.

 IDE

Stamdataservicen kan principielt udvikles i enhver Java IDE, der forstår Maven projekters opbygning.

I dette dokument beskrives kort opsætning for to af de pt. mest udbredte Java IDE’er: Eclipse og IntelliJ.

...

     Eclipse

Eclipse er ikke født med Maven support, og det anbefales derfor, at man installerer m2eclipse inden stamdataservicen hentes ind i Eclipse:

Herefter importeres projekterne i Eclipse via ”import”:

Image RemovedImage Added

Alternativt kan man importere projektet ved at udføre følgende kommando:

Og herefter importere projektet på normal vis i Eclipse.

Kommandoen genererer Eclipse projektfilerne (.project og .classpath) for roden og hvert undermodul.  Denne metode kræver dog, at kommandoen udføres hver gang man ændrer i pom filerne.

...

     IntelliJ Idea IDE

IntelliJ Idea er født med Maven support, og stamdataservicen kan derfor direkte importeres. Projektet importeres i IntelliJ ved under ”Create new project” at vælge ”Import project from external model”. Herefter udvælges roden af stamdataservicen, hvorefter projektet importeres.

...

Alternativt kan man importere projektet ved at udføre følgende kommando:

Herefter kan projektet importeres på normal vis i IntelliJ.

...

Obs! Denne metode kræver dog, at kommandoen udføres hver gang man ændrer i pom filerne.

...

Distribution

Stamdataservicen kan bygges til distribution eller lokal test ved at udføre:

% mvn package

4     Tips og tricks

I de følgende beskrives problemer og deres løsninger:

4.1     JBoss out of memory

4.1.1      Beskrivelse

I JBoss’s boot.log:

$JBOSS_HOME/server/default/log/boot.log

Logger JBoss noget i stil med ”out of memory” og nævner “permgenspace”

4.1.2      Løsning

Forøg JBoss permgen space ved at ændre linien indeholdende:

JAVA_OPTS="-Xms2048m -Xmx2048m -XX:MaxPermSize=256m -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000"

i filen

$JBOSS_HOME/bin/run.conf

til

 JAVA_OPTS="-Xms2048m -Xmx2048m -XX:MaxPermSize=512m -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000"

5    Ændringslog

Nyeste udgave af dette dokument kan erhverves ved henvendelse til NSP-operatøren.

Mavens release plugin anvendes til at lave releases:

mvn org.apache.maven.plugins:maven-release-plugin:2.5.3:prepare

Referencer og kilder

...

[1] Fra Seal.java 2.1.2 er XercesImpl ikke længere inkluderet i Seal.java.

[2] Root password til mysql sættes med følgende kommando: