Dette er en foreløbig beskrivelse, med rettelser på vej. 

KOPIERET FRA NAS:

Introduktion

Formål

Formålet med dette dokument er at beskrive hvordan et udviklingsmiljø til videreudvikling af Nationalt eCPR-servicen, 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.

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 eCPR-servicen

eCPR-servicen udstiller en SOAP service, der følger DGWS. Snitfladen er defineret i en række WSDL filer, der er grupperet i hver sin mappe (prod, prodtest, stage, test1, test2, udd) samt 5 wsdl filer i wsdl-mappen placeret i ~ecpr2-schemas\src\main\resources\wsdl. 

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

eCPR-servicen er en Java baseret komponent, der for nuværende baserer sig på Java 8 og Springboot frameworket, men senere vil SpringBoot blive fjernet. Den overordnede arkitektur og design er beskrevet i eCPR - Design- og Arkitekturbeskrivelse.

Opsætning af udviklingsmiljø

I det følgende antages at koden er hentet fra git: https://git.nspop.dk/projects/COM

Krav til software

eCPR-servicen deployeres vha. docker, og 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 version?
• docker-compose version 3.6 eller højere

Bygge WAR filer

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

mvn clean install -D maven.test.skip=true -e

Efter byg kan WAR filen findes under ecpr2-service/target/ecpr2-service-1.28.18

Afvikling

For at bygge docker-imaget udføres kommandoen

docker-compose -f compose/development/docker-compose.yml up -d --build

som både bygger og starter en lokal database og selve servicen ecpr2. Herefter kan eCPR findes på port 8380 (Eller 8080?, se docker-compose i development linje 14-16).
Endpointet kan findes på http://??

Beskrivelse af systemdesign

Systemarkitekturen er beskrevet i eCPR - Design- og Arkitekturbeskrivelse. Nedenfor beskrives systemdesignet vha. sekvensdiagrammer, der viser flowet gennem systemet. 
Hvor mange? Af hvilke kald? Skal der laves et designdiagram? 

Beskrivelse af kildekodens strukturering og design

Kode strukturering

Kildekoden bygges vha Apache Maven. Overordnet består kildekoden af 5 Maven moduler, et parent modul (ecpr2) og 4 øvrige moduler, som kort beskrives nedenfor: 

Når systemet bygges med kommandoen

mvn clean install -D maven.test.skip=true -e

er bygge orderen 

1. eCPR2
2. ecpr2-schemas
3. ecpr2-server-api
4. ecpr2-service
5. ecpr2-test

ecpr2-service kodestrukturering

Selve eCPR-servicens kodestruktur er uddybet nedenfor, hvor hver mappe under ecpr-service → src → main → java → dk.sds.ecpr2 er beskrevet:

_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_

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:

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:

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:

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