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.
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æ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.
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.
I det følgende antages at koden er hentet fra SVN: https://svn.nspop.dk/svn/components/nas.
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:
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 |
Der henvises til installationsvejledningen NAS Driftsvejledning for nærmere instrukser.
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:
Service | port |
---|---|
pullpointfactory | 8080 |
pullpoint | 8081 |
idlist | 8082 |
subscriptionmanager | 8083 |
notificationbroker | 8084 |
cleanup | 8085 |
administration | 8086 |
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>.
Systemdesign er beskrevet i NAS Design og Arkitekturbeskrivelse
Kildekoden bygges vha Apache Maven, og kildekoden er struktureret som Maven moduler. Følgende moduler er support moduler, som inkluderes efter behov:
Modul | Beskrivelse |
---|---|
config | Hjælpekode til håndtering af konfiguration. |
database | Her ligger modellering og adgang mod databasen. |
kafka | Alt adgang til Kafka findes her. De primære interfaces er Publisher og Streamer . |
log | Opsætning af generel log findes her samt hjælpekode til SLA logning. |
security | Heri ligger kode til håndtering af DGWS. |
testutilities | Hjælpekode til testafvikling. |
util | Enkelte klasser der anvendes på tværs af flere moduler og som ikke har været komplexe nok til at retfærdiggøre et selvstændigt modul. |
Derudover findes alle services som moduler under services.
For at sikre en ensartet navngivning af tabeller, kolonner osv. er nedenstående navnekonvention indført i forhold til databasen.
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.
Skal der tilføjes f.eks. en ny kolonne eller en ny tabel skal nedenstående gøres.
Opstår der en situation hvor der skal tilføjes yderlige testdata for at integrationstesten kan afvikles skal nedenstående udføres.
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 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)
Performance testen foregår vha. et test framework udviklet af Arosii (version 2.0.0).
Performance testen består af 2 dele:
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.
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
tests: indeholder de generede test filer
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.
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
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.
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