1. Introduktion
1.1. Formål
Formålet med dette dokument er at beskrive hvordan et udviklingsmiljø, til videreudvikling af DDS Repository, kan sættes op, samt hvordan koden bygges, deployes og testes.
I afsnit 3 beskrives de softwaremæssige krav der er til miljøet samt hvordan kode bygges. I afsnit 4 beskrives deployment-miljøet.
Kodestrukturen, kodemæssige afhængigheder til tredjeparts moduler og de forskellige servicemodulers ansvar og design beskrives i afsnit 6.
Testdesign findes i afsnit 7.
1.2. Sammenhæng med øvrige dokumenter
Dette dokument er en del af den samlede dokumentation for DDS projektet: Dokumentdelingsservice (DDS).
1.3. Læsevejledning
Læser forventes at have kendskab til Java softwareudvikling med anvendelse af Maven, WildFly applikationsserver og MySQL.
Hvor der i teksten er angivet <component base> refereres til topniveaufolderen for kildekoden for komponenten.
1.4. Dokumenthistorik
Version | Dato | Ansvarlig | Beskrivelse |
1.0 | 24.01.2013 | Systematic | Initiel udgave |
1.0a | 19.04.2013 | Systematic | Udgave til Release Candidate 1 |
1.1 | 19.06.2013 | Systematic | Kvalitetssikret |
1.2 | 23.05.2014 | Systematic | Rettelser som konsekvens af opsplitning af tidl. NPI-mavenprojekt i selvstændige komponenter. |
1.3 | 28.11.2014 | Systematic | Referencer til Nationalt Patientindeks (NPI) fjernet |
1.4 | 14.01.2015 | Systematic | Nye kommandoer til maven og ændring af npi og npiservices til dds |
1.5 | 30.03.2015 | Systematic | Opdatering af afhængigheder i 6.1 Tilføjet afsnit 3.3 Beskrivelse af afhængigheden til eksterne database scripts og datasources |
1.6 | 02.02.2016 | Systematic | Kodereferencer er opdaterede pga. navneskifte fra NPI til DDS Opgradering til WildFly Forbedret codecoverage beskrivelse |
1.7 | 16.12.2016 | Systematic | BRS stub nu påkrævet (3.3) Cobertura modul beskrevet i 6.1 Performancetest fjernet da disse er beskrevet i separat dokument |
1.8 | 13.06.2018 | Systematic | Migreret til NSPOP SVN |
1.9 | 14.11.2018 | KvalitetsIT | Lagt dokumentation ind i Confluence |
1.10 | 23.07.2020 | KvalitetsIT | Opdateret byggevejledning. |
1.5. Definitioner og referencer
Definition | Beskrivelse |
NSI | National Sundheds-IT |
NSP | Den nationale service platform (inden for sundheds-IT) |
SHAK | Sygehusafdelingsklassifikation |
SOR | Sundhedsvæsenets organisationsregister |
STS | Security Token Service |
BRS | Behandlingsrelationsservicen |
HS | Healthshare Document Registry |
Alias | Beskrivelse |
DGWS | Den Gode WebService 1.0.1 |
Design | DDS Repository Design og Arkitektur (SSE/11734/SDD/0006) |
Installationsvejledning | Installationsvejledning DDS Repository (SSE/11734/INS/0005) |
Min-log | Design og Arkitektur Min-log Service (SSE/11734/SDD/0002) |
SAM | Design og Arkitektur Samtykke Service (SSE/11734/SDD/0003) |
SAM-guide | Guide til udviklere Samtykke Service (SSE/11734/PHB/0007) |
Minlog-guide | Guide til udviklere Min Log Service (SSE/11734/PHB/0004) |
2. Introduktion til DDS Repository
Realisering af DDS Repository består af en Java-baseret webservice.
Webservicen tillader anvendersystemer at foretage udtræk af patient specifikke dokumenter fra XDS dokument kildesystemer.
Servicen filtrerer dokumenter baseret på borgerens generelle samtykker mod den sundhedsfaglige person foretager udtrækket
Servicen validerer brugerens rettigheder, kalder behandlingsrelationsservicen og gemmer eventuelle relevante oplysninger i borgerens Min-log.
For en dybere introduktion til servicen og baggrunden bag, se [Design].
3. Opsætning af udviklingsmiljø
I det følgende antages at koden er hentet ned fra softwarebørsen el.lign.
3.1. Krav til software
Krav til applikationsserveren, operativsystemet og databasen er de samme som til produktionsmiljøet. De specifikke krav kan ses i [Installationsvejledning] afsnit 2.
Derudover er der en række krav til de anvendte udviklingsværktøjer:
Krav til Maven
Maven 3.0.3 eller højere anvendes.
Krav til Docker
Docker 18.x eller højere anvendes.
3.2. Bygge komponenten
Udfør følgende kommando for at bygge komponenten:
mvn clean install
Det tager lidt tid, da der skal genereres kode ud fra et større antal wsdl-filer.
3.3. Integrationstest
For at køre integrationstesten gøres følgende:
Byg DDS, som beskrevet ovenfor
Udfør følgende kommandoer:
cd compose/development
docker-compose up --build
Vent på at setuppet kommer op.
cd integrationstest
mvn verify -Plocal,integration-tests
Det er muligt at ramme andre miljøer end det lokale ved at udskifte local med test1 eller test2.
3.4. Byg af teststubbe til eksterne services
Der er udviklet to teststubbe til at hjælpe i udviklingen og test af denne service. De to stubbe erstatter de to eksterne afhængigheder, som servicen har; BRS og HS repository. For begge stubbe gælder, at for at benytte stubben skal wsdl.location/ service.location for den tilsvarende service rettes i DDSRepository.properties, så den peger på lokationen, hvor stubben er deployet.
BRS-stubben er placeret i et separat modul under folderen dds/brs-stub. Fra denne folder bygges og deployeres til WildFly med standard Maven-kommandoen:
mvn clean install
BRS-stubben logger kaldet, men foretager sig intet derudover.
XDS-repository-stubben er tilsvarende placeret i et separat modul, blot under folderen dds/xds-repository-stub. Fra denne folder bygges og deployeres der automatisk til WildFly når DDSRepository bygges med kommandoen:
mvn clean install -Ddev -Denvironment-property-file=<sti til tilpasset environment.properties> -Dtestclient-property-file=<sti til tilpasset testclient.properties>
Ønsker man et separat byg af xds-repository-stubben kan standard Maven-kommandoen benyttes:
mvn clean install
XDS-repository-stub returnerer de data, der er nødvendige for at afvikle integrationstestene.
4. Beskrivelse af systemdesign
Systemdesign er beskrevet i [Design].
5. Beskrivelse af kildekodens struktur og design
5.1. Kodestruktur
Projektet er delt i følgende moduler:
dds/common – modul der indeholder de java-komponenter, de to webservices (DDS registry & repository) deler.
dds/brs-client – modul der indeholder en webserviceklient til kommunikation med BRS.
dds/ddsregistry – modul der indeholder webservice til filtrerede opslag i healthshare (denne service).
dds/ddsrepository – modul der indeholder webservice til at hente dokumenter vedrørende specifikke patienter fra healthshare
dds/types – modul der indeholder wsdl’er og xml-skemafiler i SOAP 1.2 version. Disse bruges af webservicen, til at snakke med healthshare.
dds/integrationtest-util – modul der indeholder java-komponenter, som flere integrationtests deler.
dds/client-types - modul der indeholder wsdl’er og xml-skemafiler i SOAP 1.1 version. Disse skal bruges til at lave en klient der kan kontakte DDS repository.
dds/cobertura – modul der indeholder komponenter til instrumentering af kode til generering af code coverage rapport.
dds/xds-repository-stub – modul der indeholder en stub der kan køres tests imod.
dds/ddsregistry-proxy – modul der indeholder en proxy til udviklingsbrug. Proxyen sikrer at der kun bliver gemt data på testpatienter.
Der er afhængigheder til forskellige maven-artefakter, hvoraf følgende er skabt i regi af NSI:
dk.nsi,services-common:services-common – modul der indeholder de dele af koden der er fælles for alle komponenterne, herunder interface til opslag i SOR register, DGWS fejlkoder, samt utilities til logning med mere.
dk.nsi.services-common:remote-test-resources – Modulet indeholder SQL-scripts og datasource konfigurationer til Stamdata database. Scripts opretter Stamdata databasen og tabellerne med initielt test data.
dk.nsi.hsuid:hsuid – modul der indeholder implementering af OIO attributter til identifikation af sundhedsfaglige personer, der er fælles for webservicekomponenter, der anvender DGWS.
dk.nsi.dgws:dgws-common – modul der indeholder implementering af DGWS fælles funktionalitet til håndtering af DGWS header og fejlkoder.
dk.nsi.dgws:provider – modul der indeholder implementering af DGWS provider funktionalitet, der anvendes af alle komponenter der anvender DGWS i rollen som web service provider.
dk.nsi.dgws:remote-test-resources – Modulet indeholder SQL-script og datasource konfiguration til whitelist databasen. Script opretter whitelist databasen med initielt test indhold.
dk.nsi.dgws:consumer – modul der indeholder implementering af DGWS consumer funktionalitet, der anvendes af komponenter der anvender DGWS i rollen som web service consumer (aktuelt ConsentAdministration, der kalder Min-log-registration webservicen).
dk.nsi.consentservices.verification:consent-verification-client – modul der indeholder funktionalitet til kald af webservice til verifikation af samtykker.
dk.nsi.minlog.registration:minlog-registration-client – modul der indeholder funktionalitet til kald af webservice til registrering af hændelser i en borgers Minlog.
5.2. Generelt design af DDS Repository
Servicen består af en række Maven-moduler, der findes under dds/ddsrepository:
application: Indeholder webservice og forretningslogik
war: Bygger war-filen der skal deployes
integrationtest: Indeholder integrationstests af webservicen
Derudover er der en række generelle designvalg for servicen:
Servicen er implementeret ved brug af Den Gode Webservice [DGWS], hvor Seal.Java er anvendt til at håndtere sikkerhed og DGWS headers.
JAX-WS er anvendt til kodegenerering ud fra WSDL-filer og JAXB er anvendt til kodegenerering ud fra XSD-filer.
Servicen er implementeret som en Java-webservice.
6. Beskrivelse af testsetup
6.1. Unittests
JUnit anvendes til implementering af unit tests. Der er kontinuert gennemført unit tests på alle komponenter i projektet.
Unit tests kan afvikles ved at køre:
mvn test
6.2. Integrationstests (Failsafe)
Maven Failsafe plugin anvendes til gennemførelse af integrationstests af DDS Repository.
Integrationstestene af DDS Repository er afhængige af at MinLogRegistration-servicen og samtykkeverifikationsservicen er deployeret, samt at BRS og HS er tilgængelige (eller evt. stubbene, se afsnit 3.4).
Det nødvendige testdata læses automatisk på af maven-scriptet, inden integrationstestene afvikles.
Integrationstests kan afvikles ved at køre:
mvn verify –Pexternal-test
Bemærk at dette forudsætter, at service(s) etc. er deployeret på WildFly-serveren, da integrationstestene afvikles imod kørende service(s).
6.3. Code coverage
Code coverage analyse er foretaget i projektet med anvendelse af Maven Cobertura plugin.
6.3.1. Code coverage for unittests og integrationstests
En samlet code coverage-rapport omfattende både unittests og integrationstests kan genereres ved forberedelse og gennemførsel af trin beskrevet i det efterfølgende.
6.3.1.1. Forberedelse
Cobertura skal installeres på WildFly og Ant installeres mhp. anvendelse ved fletning af code coverage-rapporter fra unittest og integrationstests.
De anvendte versioner er:
Cobertura 2.1.1
Ant 1.9.4
Trin:
Cobertura etableres, ved enten:
Download fra fx sourceforge (https://sourceforge.net/projects/cobertura/) og udpakning
Kildekode hentes fra https://github.com/cobertura/cobertura/releases og bygges
Ant installeres
Download fra http://archive.apache.org/dist/ant/binaries/apache-ant-1.9.4-bin.tar.gz
I Ant’s lib folder bør følgende jars være tilgængelige
Jar | Fremskaffelse |
asm-5.0.1.jar | Indeholdende i Cobertura-2.1.1-bin-tar |
asm-analysis-5.0.1.jar | Indeholdende i Cobertura-2.1.1-bin-tar |
asm-commons-5.0.1.jar | Indeholdende i Cobertura-2.1.1-bin-tar |
asm-tree-5.0.1.jar | Indeholdende i Cobertura-2.1.1-bin-tar |
asm-util-5.0.1.jar | Indeholdende i Cobertura-2.1.1-bin-tar |
cobertura-2.1.1.jar | Indeholdende i Cobertura-2.1.1-bin-tar |
commons-lang3-3.3.2.jar | Indeholdende i Cobertura-2.1.1-bin-tar |
oro-2.0.8.jar | Indeholdende i Cobertura-2.1.1-bin-tar |
slf4j-api-1.7.5.jar | Indeholdende i Cobertura-2.1.1-bin-tar |
slf4j-log4j12-1.6.4.jar | Bør være i lokal m2 folder |
log4j-1.2.16.jar | Bør være i lokal m2 folder |
Installation af Cobertura modul på WildFly:
Følgende Cobertura afhængigheder kopieres fra cobertura-2.1.1-bin.tar.gz til <wildfly folder>/modules/net/sourceforge/cobertura/main
Jar
Destination
<arkiv>/cobertura-2.1.1.jar
<modul-main>/
<arkiv>/lib/asm-tree-5.0.1.jar
<modul-main>/lib/
<arkiv>/lib/asm-commons-5.0.1.jar
<modul-main>/lib/
<arkiv>/lib/asm-util-5.0.1.jar
<modul-main>/lib/
<arkiv>/lib/asm-analysis-5.0.1.jar
<modul-main>/lib/
<arkiv>/lib/oro-2.0.8.jar
<modul-main>/lib/
En module.xml fil skabes i samme main mappe med følgende indhold:
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.1" name="net.sourceforge.cobertura">
<resources>
<resource-root path="."/>
<resource-root path="cobertura-2.1.1.jar"/>
<resource-root path="lib/asm-tree-5.0.1.jar"/>
<resource-root path="lib/asm-commons-5.0.1.jar"/>
<resource-root path="lib/asm-util-5.0.1.jar"/>
<resource-root path="lib/asm-analysis-5.0.1.jar"/>
<resource-root path="lib/oro-2.0.8.jar"/>
</resources>
<dependencies>
<module name="asm.asm" />
<module name="javax.servlet.api" />
<module name="org.slf4j" />
</dependencies>
</module>
Default udskrives coveragefilen (cobertura.ser) i <wildfly folder>/bin mappen. Ønskes filen udskrevet til en anden mappe skabes filen cobertura.properties i main mappen med indeholdet:
net.sourceforge.cobertura.datafile=<sti>/cobertura.ser
For at få Cobertura til at skrive coverage af integrationstests, er der to muligheder:
Metode | Installation og brug |
coberturaFlush.war servicen |
Dependencies: net.sourceforge.cobertura
|
Genstart af WildFly |
|
Bemærk at når WildFly startes med instrumenteret kode, da startes ”optagelse” af code coverage. Ved kald til coberturaFlush servicen skabes et billede af hvordan coverage ser ud nu. Dette billede skrives til cobertura.ser, hvor filen bliver additivt opdateret, hvis filen findes i forvejen, eller skabes, hvis den ikke findes. ”Optagelse” af code coverage bliver først reset ved genstart af WildFly og fjernelse af cobertura.ser.
Genstart af WildFly
6.3.1.2. Gennemførelse
Code coverage-rapport omfattende både unittests og integrationstests genereres ved at gennemføre følgende trin:
Kontroller, at wildfly bruger-account kan skrive cobertura.ser filen i output folderen (Standard <wildfly>/bin/cobertura.ser eller bestemmes i cobertura.properties)
Kontroller, at stien til cobertura.ser er korrekt i filen cobertura/src/main/coberturaScripts/cobertura.properties under DDS-projektets hovedfolder.
Coberturas instrumentering af koden sker ved udførsel af følgende i kommandoprompt i DDS-projektets hovedfolder (folderen med parent pom):
mvn clean install -Dcobertura-build -Pdeploy-to-appserver -Denvironment-property-file=<sti til tilpasset environment.properties>
Bemærk, at argumentet –Pdeploy-to-appserver aktiverer en maven-profil, der kopierer ear/war-filer til WildFly deployment folder vha. properties. Som alternativ til dette argument kan ear/war-filer deployeres manuelt.
Gen-deployer DDS-projektets services på WildFly
I samme folder udføres integrationstestene ved:
mvn verify –Pexternal-test -Denvironment-property-file=<sti til tilpasset environment.properties> -Dtestclient-property-file=<sti til tilpasset testclient.properties>
Afslutning af coberturas optagelse gennemføres ved enten:
Shutdown af WildFly, eller
At åbne siden http://<host:port>/coberturaFlush/flushCobertura (fx via curl eller i browser. Bemærk at dette forudsætter at filen coberturaFlush.war blev kopieret og deployeret)
Flet code coverage-rapporter ved i kommandoprompt i DDS hovedfolder at udføre:
cd cobertura/target/coberturaReporting-coberturaReporting
ant –f cobertura.xml create-report
Genereret code coverage-rapport kan nu læses i folderen cobertura/target/coberturaReporting-coberturaReporting/report