Introduktion

Formål

Formålet med dette dokument er at beskrive hvordan et udviklingsmiljø, til videreudvikling af NAS services, kan sættes op, samt hvordan koden bygges, deployes og testes.

Først beskrives de softwaremæssige krav, der er til miljøet, samt hvordan kode hentes og bygges. Dernæst beskrives deploymentmiljøet.

Kodestrukturen, kodemæssige afhængigheder til tredjeparts moduler og de forskellige servicemodulers ansvar og design beskrives sidst i dette dokument sammen med testdesign.

Sammenhæng med øvrige dokumenter

Dette dokument er en del af den samlede dokumentation for NAS.

Dokumentets relation til de øvrige dokumenter er beskrevet i dokumentationsoversigten for projektet NAS Service.

Læsevejledning

Læser forventes at have kendskab til Java softwareudvikling med anvendelse af Maven og WildFly. Derudover forventes kendskab til docker-compose.

Hvor der i teksten er angivet <component base> refereres til topniveaufolderen for kildekoden for komponenten.

Introduktion til NAS services

Alle NAS services udstiller en SOAP service. Snitfladen er defineret i en WSDL fil og en række XSD filer. 

Alle NAS services er Java baserede komponenter, der baserer sig på Java 8 og Spring frameworket. Derudover anvendes NSP Kafka klienten. Den udstillede SOAP snitflader er implementeret direkte oven på Java Servlets.

Design og arkitektur er beskrevet: NAS Design og Arkitekturbeskrivelse.

Opsætning af udviklingsmiljø

I det følgende antages at koden er hentet fra SVN: https://svn.nspop.dk/svn/components/nas.

Krav til software

Alle NAS services deployeres vha. docker, hvorfor de alle baserer sig på NSP platformens base image, hvori der findes nødvendigt software til afvikling.

Derudover er der krav til de anvendte udviklingsværktøjer:

• Maven 3.0.3 eller højere anvendes.
• docker-compose version 3.4 eller højere

Bygge WAR filer

Man skal bruge Apache Maven til at bygge NAS, hvilket gøres ved at køre kommandoen

mvn package

Efter byg kan WAR filer findes her:

./services/subscriptionmanager/target/subscriptionmanager.war
./services/notificationbroker/target/notificationbroker.war
./services/pullpoint/target/pullpoint.war
./services/idlist/target/idlist.war
./services/pullpointfactory/target/pullpointfactory.war
./services/cleanup/target/cleanup.war
./services/administration/target/administration.war

Afvikling

Der henvises til installationsvejledningen NAS Driftsvejledning for nærmere instrukser.

Udviklers workstation

Når man udvikler kan det være praktisk at foretage deploy. Dette kan gøres vha. docker-compose:

docker-compose -f compose/development/docker-compose.yml up --bulid

Individuelle services kan også startes hvormed kun deres afhængigheder starter. Til udvikling vil der blive startet en mariadb container samt kafka og zookeeper containere, når der er behov herfor.

Når alle services er startet er de at finde på følgende port:

pullpointfactory

pullpoint

idlist

subscriptionmanager

notificationbroker

Deres endpoints findes på følgende måde: http://<navn>:<port>/<navn>. Alternativt kan alle services tilgås via en HTTP reverse proxy på port 8090. En service kan så tilgås via adressen http://<navn>:8090/<navn>.

Beskrivelse af systemdesign

Systemdesign er beskrevet i NAS Design og Arkitekturbeskrivelse

Beskrivelse af kildekodens strukturering og design

Kode strukturering

Kildekoden bygges vha Apache Maven, og kildekoden er struktureret som Maven moduler. Følgende moduler er support moduler, som inkluderes efter behov:

Derudover findes alle services som moduler under services.

Database navnekonvention

For at sikre en ensartet navngivning af tabeller, kolonner osv. er nedenstående navnekonvention indført i forhold til databasen. 

1. Tabelnavne er i snake case og der anvendes kun små bogstaver. 
2. Kolonner er i snake case og der anvendes kun små bogstaver. 
3. Navngivngning af indexer, constraints osv. er tabelnavn_kolonner_postfix. Hvor postfix er pk for primary key, uc for unique constraint, fk for foreign key og idx for index.

Databaseændringer

Databasemodel styres ved hjælp af liquibase. Det betyder at når der skal laves ændringer til databasemodellen så må man ikke rette i de eksisterende skemafiler. I stedet skal der laves nye filer der beskriver ændringerne.

Skemaændringer

Skal der tilføjes f.eks. en ny kolonne eller en ny tabel skal nedenstående gøres.

1. Der oprettes en ny fil i folderen compose/database/ddl. Filen skal navngives liquibase-changelog-x.y.z.xml hvor x, y og z er det versionsnummer du forventer at release komponenten som. Filen skal beskrive ændringen der skal laves. Hvis man anvender liquibase SQL syntaxen får man typisk automatisk "rollback" med. Man kan også referere til rå SQL filer.
2. Filen fra punkt 1 tilføjes compose/database/liquibase-changelog-master.xml.
3. Done

Testdata

Opstår der en situation hvor der skal tilføjes yderlige testdata for at integrationstesten kan afvikles skal nedenstående udføres.

1. Der oprettes en ny fil i folderen compose/database/test. Filen skal navngives liquibase-changelog-test-x.y.z.xml hvor x, y og z er det versionsnummer du forventer at release komponenten som. Filen skal beskrive ændringen der skal laves. Hvis man avender liquibase SQL syntaxen får man typisk automatisk "rollback" med. Man kan også referere til rå SQL filer.
2. Filen fra punk 1 tilføjes compose/database/liquibase-changelog-test.xml
3. Done

Beskrivelse af testsetup

Unittests (JUnit)

JUnit anvendes til implementering af unit tests. Der er kontinuert gennemført unit tests på alle komponenter i projektet.

Unit tests afvikling under byg, men kan separat afvikles ved at køre:

mvn test

Hvis der derimod laves en verify, så vil der også blive genereret code coverage, hvor fremkommende rapport kan ses i testreport/target/site/jacoco-aggregate/index.html

Integrationstests

Integrationstests kan afvikles ved at køre følgende under integration-test modulet:

mvn test

Dette afvikles op mod indlejrede udgaver af alle NAS services. Hvis man derimod ønsker at afvikle testen op mod det kørende udviklingsmiljø (docker-compose setup), så kan man bruge development profilen:

mvn -Pdevelopment test

Dette forudsætter at alle services er startet som angivet i udviklet docker-compose setuppet. Hvis man ønsker af afvikle testen op mod en andet miljø, skal en række projekt variable defineres (se pom.xml-filen herom)

Udvikling af performance test

Performance testen foregår vha. et test framework udviklet af Arosii (version 2.0.0).

Performance testen består af 2 dele:

1. Udvikling af selve testen. Dette foregår i JMeter og kræver både java udvikling og efterfølgende opsætning i JMeter.
2. Udførsel af testen. Dette foregår vha. en række shell scripts på en master og flere slave maskiner. 

Udvikling og opsæt er beskrevet i nærværende dokument, mens den faktiske udførsel af testen er beskrevet i NAS Testvejledning.

Performance testen skal passe til NAS servicens snitflade for Notification Broker og Pullpoint. Ændres disse er det også nødvendigt at ændre performance testen.

I det følgende antages at koden er hentet ned fra SVN: https://svn.nspop.dk/svn/components/performance/trunk/  samt at man har docker installeret i sit udviklingsmiljø. JMeter skal også være tilgængelig.

Kildekodens struktur

Kildekoden indeholder også performance test til andre services, men i nedestående er NAS servicens dele trukket frem.

modules: indeholder kildekoden til de forskellige test

• NotificationBrokerBackgroundJob anvendes til baggrundsbelastning under pullpoint testen. Det startes og stoppes med start.sh og stop.sh der findes under "tests" under performance testens afvikling.
• GUI klasserne anvendes til indtastning  af test parametre (CreateIDListRequestSamplerGui anvendes ikke i den nuværende performance test, men gemmes til evt. fremtidig brug)
• Sampler klasserne anvendes til at lave det faktiske web service kald (CreateIDListRequestSampler anvendes ikke i den nuværende performance test, men gemmes til evt. fremtidig brug)
• GenerateTestdataSql anvendes til at skabe et sql script, som kan anvendes til at lave baggrundsdata til pullpoint testen
• pullpoint.txt er en eksempel fil, skulle man i en fremtidig test gøre brug af fil import muligheden

tests: indeholder de generede test filer

• distributioner
• planer
• baggrundsbelastning  start.sh og stop.sh. (Testframeworket tjekker under testkørslen for om disse script findes, og gør de det, udføres de.)

Versionskontrol

Test versionen styres vha. af revision i trunk. I dokumentet "testvejledning" afsnit performance test angives, hvilken version af performance testen der anvendes med en given version af NAS servicen.

Udvikling af test

NAS servicens performance test består af ovennævnte java sourcer. Disse vedligeholdes i takt med at NAS servicens snitflader for notification broker og pullpoint ændres og skal performance testes.

Lokal test kan gøres ved at bygge projektet og starte JMeter op.

Baggrundsbelastningenjobbet (NotificationBrokerBackgroundJob) testes ved at køre fra eksempelvis eclipse. Eksempel på parametre: http://localhost:8090/notificationbroker TESTNAS-TOPIC-PERFORMANCE-01 idtype01 40 1000 3000

Baggrundsdata klassen testes og anvendes ved at køre fra eksempelvis eclipse. Eksempel på parametre: pullPoint 1000 3000 idtype01 TESTNAS-TOPIC-PERFORMANCE-01 30808460SOSITEST 

Generering af testfiler

Når man har udviklet og bygget test projektet, startes JMeter. Herefter kan en eksisterende performance test åbnes og køres herfra. Eller en ny kan laves. 

Det følgende skærmbillede viser den skærm, som er udviklet i NotificationBrokerRequestSamplerGui med data hentet fra en gemt test:

Skærmbilledet for PullPointRequestSamplerGui ser følgende ud:

Når man starter testen (den grønne pil) aktiveres et kald mod den service, der er konfigureret under 'Host configuration' og hermed aktiveres koden fra NotificationBrokerRequestSampler eller PullPointRequestSampler respektivt.

Resultatet kan ses under 'View Result Tree',  hvor både kald og svar kan ses.

Den endelige kørsel af performance testen skal bruge en test plan (skabes når ovenstående test gemmes) samt en distribution, der indeholder 'Distribution' delen af ovenstående. De gemmes henholdsvis i tests/nas/src/test/jmeter/templates/testplans og tests/nas/src/test/jmeter/templates/distributions

Start.sh scriptet opdateres med korrekt parametre liste til baggrundsbelastningsjobbet.

Tredje parts moduler og software stack

Løsningen er udviklet i Java og de udstillede WebServices er implementeret som Servlet 3 og anvender JAXB til serialisering og de-serialisering af beskeder. 

Til håndtering af dependency injection, database transaktioner og databaser anvendes Spring. 

Nedenstående liste er en liste af 3. parts moduler vi direkte afhænger af. Det vil sige dem der er listet i POM filerne. Udover det anvendes der også en række biblioteker der stilles til rådighed af platformen. Disse er ikke listet her. 

commons-pool:commons-pool:jar:1.6
com.sun.xml.bind:jaxb-core:jar:2.2.11
com.sun.xml.bind:jaxb-impl:jar:2.2.11
dk.sdsd.nsp:nsp-util:jar:1.0.11
org.springframework:spring-context:jar:5.1.5.RELEASE
rg.springframework:spring-core:jar:5.1.5.RELEASE
org.springframework:spring-jdbc:jar:5.1.5.RELEASE
org.springframework:spring-web:jar:5.1.5.RELEASE
log4j:log4j:jar:1.2.17

Nedenstående er en liste over de biblioteker der anvendes i forbindelse med test. Det vil sige dem der er angivet i POM filerne med scope test. 

org.apache.kafka:kafka_2.11:jar:1.1.0:test
org.apache.kafka:kafka_2.11:jar:test:1.1.0:test
org.apache.kafka:kafka-clients:jar:1.1.0:test
org.glassfish:javax.json:jar:1.0.3:test
org.jboss.resteasy:resteasy-client:jar:3.0.19.Final:test
org.mockito:mockito-all:jar:1.9.5:test
org.springframework.kafka:spring-kafka:jar:2.1.12.RELEASE:test
org.springframework.kafka:spring-kafka-test:jar:2.1.12.RELEASE:test
org.springframework:spring-test:jar:5.1.5.RELEASE:test
dk.sds.nsp.kafka:kafka-clients:jar:1.1.0:test
dk.sosi.seal:seal:jar:2.4.5:test
io.undertow:undertow-core:jar:1.4.26.Final:test
io.undertow:undertow-servlet:jar:1.4.26.Final:test
javax:javaee-api:jar:7.0:test
javax.servlet:javax.servlet-api:jar:3.1.0:test
junit:junit:jar:4.12:test
com.h2database:h2:jar:1.4.197:test