Svareksponeringsservice XDS-adaptere
Guide til Udviklere
Indhold
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
Svareksponeringsservice-dokumentdeling består af to Java-baserede webservices og Svareksponeringsservice XDS Registry Adapter og Svareksponeringsservice XDS Repository Adapter. Ved konfiguration af Dokumentdelingsservices (DDS) på National Service Platform (NSP) kan anvendere af DDS lave opslag og udtræk af laboratoriesvarsdokumenter udstillet med Svareksponeringsservice-dokumentdelingens webservices.
Formålet med dette dokument er at beskrive opsætning og anvendelse af et udviklingsmiljø til videreudvikling af Svareksponeringsservice XDS-adapterne. Herunder hvordan koden bygges, deployeres og testes.
Læser forventes at have kendskab til Java softwareudvikling med anvendelse af Maven og WildFly applikationsserver.
Hvor der i teksten er angivet <component base> refereres til topniveaufolderen for kildekoden for komponenten.
I afsnit 2 beskrives de softwaremæssige krav, der er til miljøet, samt hvordan kode bygges. I afsnit 3 beskrives deployment-miljøet, mens beskrivelse af design fremgår af afsnit 4.
Kodestrukturen, kodemæssige afhængigheder til tredjepartsmoduler og de forskellige servicemodulers ansvar og design beskrives i afsnit 5.
Testdesign findes i afsnit 6.
Version | Dato | Ansvarlig | Beskrivelse |
---|---|---|---|
0.9 | 24.08.2016 | Systematic | Første udgave |
1.0 | 13.08.2016 | Systematic | Klar til release |
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 |
---|---|
Design og Arkitektur | Svareksponeringsservice XDS-adaptere – Design og Arkitektur, (SSE/11734/SDD/0014) |
Installations-vejledning | Installationsvejledning Svareksponeringsservice XDS-adaptere, (SSE/11734/INS/0011) |
Konfiguration | Konfiguration af Svareksponeringsservice XDS-adaptere, (SSE/11734/NOT/0056) |
I det følgende antages at koden er hentet ned fra softwarebørsen el.lign.
Krav til applikationsserveren og operativsystemet 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: |
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:
Disse kan kopieres og tilpasses til aktuelt miljø. Efterfølgende Maven-kommandoer gør brug af de tilpassede property-filer gennem argumenterne:
-Denvironment-property-file=<sti til tilpasset environment.properties>
-Dtestclient-property-file=<sti til tilpasset testclient.properties>
Er disse argumenter ikke anført benytter Maven-scripts de oprindelige property-filer.
Gennemfør følgende steps for at bygge komponenterne til Svareksponeringsservice XDS-adaptere.
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>:
mvn install –Pdeploy-ds-appserver \
-Denvironment-property-file=<sti til tilpasset environment.properties>
Bemærk, at dette afstedkommer deployering til WildFly, herunder at:
For at deployere war og ear filer til WildFly foretages følgende kommando fra <component base>:
mvn install –Pdeploy-to-appserver \
-Denvironment-property-file=<sti til tilpasset environment.properties>
Bemærk, at dette afstedkommer deployering til WildFly, herunder at:
For at afvikle integrationstests mod den deployerede instans på WildFly udføres kommandoen: mvn verify –Pexternal-test \ -Dtestclient-property-file={_}<sti til tilpasset testclient.properties>_ <ac:structured-macro ac:name="anchor" ac:schema-version="1" ac:macro-id="c775b123-2ddc-47bd-a869-357f1f05cea1"><ac:parameter ac:name="">_Toc305606314</ac:parameter></ac:structured-macro>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:
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.
<ac:structured-macro ac:name="anchor" ac:schema-version="1" ac:macro-id="aeda00bf-034c-401d-b0aa-34e1c03c42ec"><ac:parameter ac:name="">_Toc305606317</ac:parameter></ac:structured-macro>Det overordnede design for Svareksponeringsservice XDS-adapterne er beskrevet i \[Design og Arkitektur\]. |
Koden for Svareksponeringsservice XDS-adapterne er samlet i et Maven-projekt kaldet SXA.
SXA-projektet er delt i følgende moduler:
Der er afhængigheder til forskellige Maven-artefakter, hvoraf følgende er skabt i regi af NSI:
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/:
Servicen består af en række Maven-moduler, der findes under xdswrappers/:
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
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:
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:
mvn clean site cobertura: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:
Trin:
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/ |
<?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>
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 |
|
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).|
Genstart af WildFly |
|
Code coverage-rapport omfattende både unittests og integrationstests genereres ved at gennemføre følgende trin:
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.
mvn verify –Pexternal-test __
-Denvironment-property-file=<sti til tilpasset environment.properties> \
-Dtestclient-property-file=<sti til tilpasset testclient.properties>
cd cobertura/target/coberturaReporting-coberturaReporting
ant –f cobertura.xml create-report