Page History
Navitabs | ||||
---|---|---|---|---|
| ||||
Anchortoc | _Toc40578283 | _Toc40578283 |
---|
Anchor | _Toc292960798 | _Toc292960798 |
Anchor | _Toc327798371 | _Toc327798371 |
Anchor | _Toc277248668 | _Toc277248668 |
Anchor | _Toc44403513 | _Toc44403513 |
1 Introduktion
1.1 Formål
1.2 Læsevejledning
1.3 Dokumenthistorik
1.4 Definitioner og referencer
2 Opsætning af udviklingsmiljø
2.1 Krav til software
2.2 Tilpasning af miljø
2.3 Bygge War filen
2.4 Deployering til WildFly
2.5 Afvikling af integrationstests mod WildFly
2.6 Samtidig deployering og afvikling af integrationstests
3 Deployment på WildFly
3.1 Udviklers workstation
4 Beskrivelse af systemdesign
5 Beskrivelse af kildekodens strukturering og design
5.1 Kode-strukturering
5.2 Generelt design af Svareksponeringsservice XDS-adaptere
5.3 Svareksponeringsservice XDS Registry Adapter
5.4 Svareksponeringsservice XDS Repository Adapter
6 Beskrivelse af test-setup
6.1 Unittests (JUnit)
6.2 Integrationstests (Failsafe)
6.2.1 Krævet test setup
6.2.2 Afvikling af integrationstests
6.3 Code coverage
6.3.1 Code coverage for unittests
6.3.2 Code coverage for unittests og integrationstests
...
|
Introduktion
Formål
...
Formålet med dette dokument er at beskrive
...
, hvordan et udviklingsmiljø til videreudvikling
...
af SXA (Labsvar) Adaptere, kan sættes op, samt hvordan koden bygges,
...
deployes og testes.
...
Først beskrives de softwaremæssige krav, der er til udviklingsmiljøet, herunder hvordan kode hentes og bygges. Dernæst beskrives deploymentmiljøet.
...
Læsevejledning
Læser forventes at have kendskab til Java softwareudvikling med anvendelse af Maven
...
, Docker og docker-compose.
Hvor der i teksten er angivet <component base> refereres til topniveaufolderen for kildekoden for komponenten
...
Version
...
Dato
...
Ansvarlig
...
Beskrivelse
...
0.9
...
24.08.2016
...
Systematic
...
Første udgave
...
1.0
...
.
...
Systematic
...
...
Definition | Beskrivelse |
---|---|
DGWS | Den Gode WebService 1.0.1 |
NSI | National Sundheds-IT |
NSP | Den nationale service platform (inden for sundheds-IT) |
SXA | Svareksponeringsservice XDS-adaptere |
XDS | Cross-Enterprise Document Sharing |
...
Alias
...
Beskrivelse
...
Svareksponeringsservice XDS-adaptere – Design og Arkitektur, (SSE/11734/SDD/0014)
...
Installationsvejledning Svareksponeringsservice XDS-adaptere, (SSE/11734/INS/0011)
...
Konfiguration af Svareksponeringsservice XDS-adaptere, (SSE/11734/NOT/0056)
...
Opsætning af udviklingsmiljø
I det følgende antages at koden er hentet
...
fra SVN: https://svn.nspop.dk/svn/components/labsvar/
Krav til software
SXA Adaptere 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.
WildFly (se \[Installationsvejledning\])
...
Ved deployering vha. Maven-scripts og kørsel af integrationstests beskrevet i det efterfølgende gøres brug af property-filer, der beskriver placering af WildFly og endpoints for eksterne systemer mm.
Disse property-filer ligger i:
- <component base>/environment.properties
- <component base>/integrationtest/src/test/resources/testclient.properties
...
Code Block |
---|
-Denvironment-property-file=<sti til tilpasset environment.properties>
-Dtestclient-property-file=<sti til tilpasset testclient.properties> |
...
Gennemfør følgende steps for at bygge komponenterne til Svareksponeringsservice XDS-adaptere.
- For at bygge projektet uden deployering til WildFly eller kørsel af integrationstest foretages følgende kommando fra <component base>:
Code Block |
---|
mvn clean install \
-Denvironment-property-file=<sti til tilpasset environment.properties> |
...
For at etablere og deployere properties til WildFly foretages følgende kommando fra <component base>:
Code Block |
---|
mvn install –Pdeploy-ds-appserver \
-Denvironment-property-file=<sti til tilpasset environment.properties> |
...
- Property-filer deployeres til WildFly (hvilket kræver skriverettighed i default/conf)
...
- docker-compose version 3.4 eller højere.
Kildekodens struktur og design
Modulopbygning
Kildekoden bygges vha Apache Maven, og kildekoden er struktureret som Maven moduler. Følgende moduler findes i SXA Adaptere:
Modul | Beskrivelse |
---|---|
SXA Lab Report Service Stub | Stub til at emulere en Svareksponeringsservice backend. Pakkes som en Wildfly applikation (WAR) |
AO Appointment Stub Integration Test | Integrationstests til AO Appointments Provider Stub |
AO Provider Common | Fælleskode, der benyttes både af AO Document Metadata Provider og AO Document Provider |
AO Provider Cache | Kode til at gemme/hente/slette AO XDS Adapters aftaledokumenter i database |
AO Document Metadata Provider | Modul til implementation af dokumentsøgning (ITI-18) - dvs "registry-delen" af AO XDS Adaptere. Modulet har til ansvar at fremfinde |
Code Block |
---|
mvn install –Pdeploy-to-appserver \
-Denvironment-property-file=<sti til tilpasset environment.properties> |
...
- Service-filer deployeres til WildFly (hvilket kræver skriverettighed i Wildfly/standalone/deployments)
...
For at afvikle integrationstests mod den deployerede instans på WildFly udføres kommandoen:
Code Block |
---|
mvn verify –Pexternal-test \
-Dtestclient-property-file={_}<sti til tilpasset testclient.properties> |
Bemærk, at afvikling af integrationstests kræver, at Dokumentdelingsservicen er deployeret (med sine afhængigheder) og konfigureret til at anvende Svareksponeringsservice XDS-adapterne, som beskrevet i \[Konfiguration\].
...
For at lette afvikling af integrationstests ifm. udvikling, kan deployering af war/ears til WildFly og afvikling af integrationstests udføres med kommandoen:
Code Block |
---|
mvn install -Ddev \
-Denvironment-property-file=<sti til tilpasset environment.properties> -Dtestclient-property-file=<sti til tilpasset testclient.properties> |
...
Der henvises til installationsvejledningen \[Installationsvejledning\] for nærmere instrukser.
...
Når man udvikler kan det være praktisk at foretage deploy til en lokal WildFly.
...
Det overordnede design for Svareksponeringsservice XDS-adapterne er beskrevet i \[Design og Arkitektur\].
...
dokumentmetadata og reagerer på søgeparametre givet ved forespørgsel på dokumentmetadata. |
...
Modulet har yderligere til opgave at danne de konkrete dokumenter svarende til de fremsøgte metadata og gemmer disse dokumenter i AO Provider Cache. | |
AO Document Metadata Provider War | Pakker AO Document Providere som en Wildfly applikation (WAR) |
AO Document Metadata Provider Integration Test | Integrationstests til AO Document Metadata Provider. Modulet har til ansvar at fremfinde dokumenter i AO Provider Cache |
...
og reagerer på søgeparametre givet ved forespørgsel på dokumenter. |
...
Der er afhængigheder til forskellige Maven-artefakter, hvoraf følgende er skabt i regi af NSI:
- documentsharing/* – moduler der indeholder abstraktioner over IHE XDS dokumentmetadata, forespørgsel og indhentning af dokumenter.
- hsuid/ - modul der indeholder implementering af OIO attributter til identifikation af sundhedsfaglige personer, der er fælles for webservicekomponenter, der anvender DGWS
- dgws/consumer - modul der indeholder implementering af DGWS consumer funktionalitet, der anvendes af komponenter der anvender DGWS i rollen som web service consumer.
- dds/client-types – moduler der indeholder IHE wsdl og xsd filer for "Registry Stored Query Transaction", samt JAXB-generede typer fra disse filer.
...
De to Java-webservices Svareksponeringsservice XDS Registry Adapter og Svareksponeringsservice XDS Repository Adapter er implementeret ved brug af komponenter fra documentsharing og Dokumentdelingsservices.
JAX-WS er anvendt på baggrund af artefakter fra DDS skabt ved kodegenerering ud fra WSDL-filer og XSD-filer.
...
Servicen består af en række Maven-moduler, der findes under xdswrappers/:
- documentmetadataprovider: Indeholder forretningslogik
- documentmetadataprovider-war: Konfigurerer webservicen og bygger war-filen, der skal deployeres
- documentmetadataprovider-integrationtest: Indeholder integrationstests af webservicen
...
Servicen består af en række Maven-moduler, der findes under xdswrappers/:
- documentprovider: Indeholder forretningslogik
- documentprovider-war: Konfigurerer webservicen og bygger war-filen, der skal deployeres
- documentprovider-integrationtest: Indeholder integrationstests af webservicen
...
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:
Code Block |
---|
mvn test |
...
Maven Failsafe plugin anvendes til gennemførelse af integrationstests i projektet.
...
Integrationstests forudsætter at Dokumentdelingsservicen (DDS) og dennes afhængigheder er deployeret til WildFly. Desuden kræves at DDS'en er konfigureret til at kende både Svareksponeringsservice XDS Registry Adapter og Svareksponeringsservice XDS Repository Adapter, samt at disses konfigurationer er i overensstemmelse (fx skal samme repositoryUniqueId være anvendt i deres konfigurationer).
...
Integrationstests kan afvikles ved at køre:
Code Block |
---|
mvn verify –Pexternal-test |
...
Code coverage analyse er foretaget i projektet med anvendelse af Maven Cobertura plugin.
...
Code coverage-rapport omfattende alene unittests genereres ved at gennemføre følgende trin:
- I kommandoprompt i SXA hovedfolder (folderen med parent pom) udføres:
Code Block |
---|
mvn clean site cobertura:cobertura |
- Genereret code coverage-rapport kan nu læses i folderen target/site/cobertura
...
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.
...
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
...
- Download fra fx sourceforge (https://sourceforge.net/projects/cobertura/) og udpakning
- Kildekode hentes fra https://github.com/cobertura/cobertura/releases og bygges
...
- Download fra http://archive.apache.org/dist/ant/binaries/apache-ant-1.9.4-bin.tar.gz
Kopier følgende afhængigheder til Ant's lib folder
Jar
Kilde
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
...
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/
...
Code Block |
---|
<?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:
Code Block |
---|
net.sourceforge.cobertura.datafile=<sti>/cobertura.ser |
For at få Cobertura til at skrive coverage af integrationstests, er der to muligheder:
AO Document Provider | Modul til implementation af dokumenthentning (ITI-43) - dvs "repository-delen" af AO XDS Adaptere. |
AO Document Provider War | Pakker AO Document Provider som en Wildfly applikation (WAR) |
AO Document Provider Integration Test | Integrationstests til AO Document Provider |
AO Document Sharing Integration Test | Integrationstests for RN og RM udgaver af AO XDS Adaptere. Tester fremsøgning af dokumentreferencer (ITI-18) samt afhentning af dokumenter (ITI-43) |
Services
Ovenstående modulliste opsumerer kodens struktur.
Tre af modulerne producerer installerbare services (WAR filer).
Det drejer sig om følgende:
- AO Appointments Provider Stub: Denne service anvendes kun til udvikling og emulerer en bookplan backend til levering af aftaledata.
- AO Document Metadata Provider War: Denne service implementerer "registry-delen" af AO XDS Adaptere. Dette er et generelt modul, der kan konfigureres til hhv. Region Nord (RN) og Region Midt (RM) ved hjælp af konfigurationsfiler.
- AO Document Provider War: Denne service implementerer "repository-delen" af AO XDS Adaptere. Dette er et generelt modul, der kan konfigureres til hhv. Region Nord (RN) og Region Midt (RM) ved hjælp af konfigurationsfiler.
Byg af AO XDS Adaptere
Man skal bruge Apache Maven til at bygge NAS, hvilket gøres ved at køre kommandoen
|
Efter byg kan WAR filer findes her:
|
Disse tre WAR filer svarer til de beskrevne services i forgående afsnit.
Deployering af AO XDS Adaptere
Efter byg kan det være nyttigt at lave en deployering af de genererede services (WAR).
Til udviklingsformål er der udarbejdet en mængde docker-compose setups. Disse ligger i
|
conf angiver, hviklen konfiguration man ønsker at starte (rn = Region Nord, rm = Region Midt).
apd-version angiver, hvilken version af Medcoms profilering af aftaledokumenter (se), der skal anvendes (v11 = version 1.1, v20 = version 2.0).
Det relevante docker-compose setup startes med følgende kommando:
|
Docker-compose setup'et startere både AO XDS Adapter services samt bagvedliggende database service og mock Bookplan service. Når alle services er startet kan WSDL for de deployede AO XDS Adapter services nåes på følgende URL'er:
|
Test af AO XDS Adaptere
Der er udviklet både unit tests og integrationstests til AO XDS Adaptere. Struktur og afvikling af disse beskrives i det følgende.
Unit tests
Der er udviklet en række unit tests til de forskellige moduler i AO XDS Adaptere.
Maven sørger for afvikling af unit tests som en del af byg af AO XDS Adaptere.
Unit tests kan også køres efter et byg med kommandoen:
|
Hvis man ønsker at få opsamlet testresultaterne (og beregnede test coverage) i en samlet rapport vha Maven plugin'et jacoco, kan følgende kommando anvendes:
|
Denne kommando afvikler unit tests og opsamler test coverage rapporten i følgende directory:
|
Rapporten kan med fordel åbnes i en browser, da den er genereret i både xml og html format.
Integrations tests
Der er udviklet en række integrationstests til AO XDS Adapter.
Disse kan være nyttige at afvikle på udviklermaskinen.
Afviklingen forudsætter, at AO XDS Adaptere er bygget og deployeret (ved opstart af relevant docker-compose setup) som beskrevet ovenfor.
TODO
...
Metode
...
Installation og brug
...
coberturaFlush.war servicen
...
- coberturaFlush.war er at finde i Cobertura-2.1.1-bin-tar
- Før kopiering til <WildFly>/standalone/deployments skal følgende linje tilføjes til coberturaFlush.war/META-INF/MANIFEST.MF:
Code Block |
---|
Dependencies: net.sourceforge.cobertura |
- Efter ændring deployeres coberturaFlush.war og servicen udstiller ”<host>/coberturaFlush/flushCobertura”. Kald til denne service ved f.eks. Curl får Cobertura til at skrive coverage filen. (Se trin 3.3).
...
- Cobertura skriver automatisk coverage fil ved genstart af WildFly
- Denne mulighed kræver følgende ændring i <wildfly folder>/bin/standalone.conf med tilføjelse af:
Code Block |
---|
JAVA_OPTS="$JAVA_OPTS -Djboss.shutdown.forceHalt=false" |
...
- Genstart af WildFly
...
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 SXA-projektets hovedfolder.
- Coberturas instrumentering af koden sker ved udførsel af følgende i kommandoprompt i SXA-projektets hovedfolder (folderen med parent pom):
Code Block |
---|
mvn clean install -Dcobertura-build \
-Pdeploy-to-appserver \
-Denvironment-property-file=<sti til tilpasset environment.properties> |
...
- Gen-deployer SXA-projektets services på WildFly
- I samme folder udføres integrationstestene ved:
Code Block |
---|
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 SXA hovedfolder at udføre:
Code Block |
---|
cd cobertura/target/coberturaReporting-coberturaReporting
ant –f cobertura.xml create-report |
...