1      1       Formål

Nærværende dokument er en guide til nye udviklere af stamdataservicen på BackOfficeNSP. Guiden gennemgår på overordnet plan de aktiviteter, der er nødvendige for at kunne videreudvikle stamdataservicen.

...

Dokumentet forudsætter, at læseren har grundig kendskab til Java udvikling, webservices og Maven. Kendskab til JBoss applikationsserver 7 vil yderligere hjælpe læseren, men er ikke en forudsætning.

...

Den primære målgruppe for dokumentet er systemudviklere.

2      2       System design

Stamdata importerne består af en kerne komponent (sdm4-core), og en række importer specifikke komponenter – alle deployes på BackOffice og har udelukkende til formål at populere data i en database (kan godt være forskellige databaser for hver komponent), se [DESIGN] for yderligere information vedrørende BackOffice. 

Komponenter på BackOffice:

BackOffice applikationerne er en række selvstændigt kørende applikationer, til overvågning af indkomne data filer, der kan være i forskellige formater (XML, fastlængde, csv, m.v). Indkomne filer indlæses, valideres og gemmes herefter i DoDi’ens database.

Hver NSP komponent er designet som en Servlet 2.4 web-applikation og benytter Guice til dependency injection.

Servlet paths, filters, osv. konfigureres direkte i koden og ikke i web.xml.

Hvert modul indeholder en ApplicationContextListener.java fil Hvert komponent indeholder en implementation af et Parser interface der fungerer som entry-point til applikationen. Det anbefales, at man som ny udvikler på projektet kigger koden igennem med denne fil som udgangspunkt.

2.1    

...

Stamdata importerne styres af java properties filer. Hver stamdata importer har en default konfigurations fil (default-config.properties) som er deployet sammen med war filen, denne kan overstyres med en properties fil lagt i jboss uden for war filen (config.properties) – se installations guiden for detaljer

Seal

Stamdataservicen benytter Seal.java til håndtering af forespørgsler og svar i webservice snitfladen.

Seal.java bygger i nuværende version (2.1.x) på commons-logging, hvilket konflikter med JBoss AS6. I pom.xml filerne er commons-logging derfor fjernet, og erstattet med en slf4j commons-logging proxy.

Derudover er XercesImpl også fjernet, da den på tilsvarende måde konflikter med JBoss AS6[1].

2.2     Properties

Stamdataservicen benytter Guice til konfigurationsstyring. Konfiguration styres via filen config.properties, der pakkes sammen med WAR-filen.

Importeren styres af historiske årsager stadig via en statisk klasse (Configuration.java).

3       3      Opsætning af udviklingsmiljø

...

• Java Developer Kit 6.0_x
• Et passende udviklingsmiljø
• Maven 3.x
• Virtualbox version 4.1.18
• Vagrant version 1.0.3
• MySQL database 5.1.x
• JBoss AS7 (bliver sat op via Puppet scripts)AS6

3.1     Kildekode

Kildekoden er placeret i to forskellige et github-repositoriesrepository:

3.1.1      BackOffice

Kildekoden er placeret her:

Core modul: https://svn.nspop.dk/svn/trifork/sdm4-core/trunk/Maven-plugin: https://github.com/trifork/sdm4-vagrant-maven-plugin/

Test-utils: https://svn.nspop.dk/svn/trifork/sdm4-testutils/trunk/

sdm/

Koden checkes ud på følgende måde:

% git clone Parent-modul inkl. Test-environment: https://svn.nspop.dk/svn/trifork/sdm4-parent/trunk/

Importer moduler

https://svn.nspop.dk/svn/trifork/sdm4-autorisationimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-bemyndigelseimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-cprimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-doseringimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-lprimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-refhostimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-sikredeimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-sksimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-sorimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-sorrelationimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-takstimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-testdataimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-tilskudsblanketimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-vaccinationimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-vitaminimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-ydelseimporter/trunk/

https://svn.nspop.dk/svn/trifork/sdm4-yderimporter/trunk/

Koden checkes ud på følgende måde:

% svn co <kode-url> <sdm4-navn>

github.com/trifork/sdm/

3.2     Byggemiljø

Stamdataprojektet anvender Maven som byggesystem [MAVEN]. Strukturen følger de generelle anbefalinger for Maven projekter, og er struktureret med en parent pom.xml og en projekt pom.xml fil for hvert underprojekt.

Subprojekterne er opbygget efter Maven layout konventionen.

For at bygge en importer, skal man gøre følgende:

Check Core-modul ud og kør mvn install

Check Maven-plugin ud og kør mvn install

CheckTest-utils ud og kør mvn install

Check parent-modul ud og kør mvn install

Herefter er du klar til at bygge et importer-modul.

Importmodulets integrationstest er afhængig af at ligge som et subdirectory til parent-modulet, så du skal checke det ud som sådan et.

Hvis du ønsker at checke alle importermoduler ud, ligger der i roden af parent-modulet et script, checkout-importermodules.sh, som udfører checkout af alle importermoduler samt maven-plugin og test-utils.

3.2.1      Dependencies

For at kunne hente NSI-specifikke dependencies (SEAL, nsp-util) osv. i binær form i stedet for at skulle bygge dem allesammen lokalt, indeholder pom’erne for alle importmoduler en reference til nexus.trifork.com, som er et artefaktrepository der er placeret hos Trifork. Binære releases af alle moduler inkl. core, maven-plugin, test-utils og parent findes også i nexus.trifork.com.

Repository’et bør snarest muligt udskiftes med et repository der er driftet hos NSI. Når et sådant er etableret, vil alle SDM4-moduler skifte til at bruge dette.

3.3     Database setup

3.3.1      BackOffice

BackOffice-projekterne anvender Vagrant+Ansible til at opsætte udviklingsmiljøet.

For at få bootet og opsat en udviklingsmaskine, køres følgende

% vagrant up

Fra roden af et importermodul eller fra parent-modulet.

Når vagrant har bygget den virtuelle maskine, er den sat op med den korrekte version af Wildfly samt en MariaDB der er konfigureret til at have en root-bruger med password papkasse og en sdm4-bruger med password sdm4.

Der er også automatisk oprettet en tom database med standard-navnet for databasen, (sdm_warehouse) og en datasource i JBoss med det JNDI-navn, som applikationen som default forventer at kunne slå datasource op.

Applikationen kører ved opstart automatisk databaseskema på databasen.

Der er forwardet følgende porte ind i den virtuelle maskine, så man kan tilgå Wildfly og MariaDB fra sin lokale maskine

8080 -> 8080 (dvs. at man kan tilgå http://localhost:8080/)

3307 -> 3306 (dvs. at man kan have en urelateret mysql kørende lokalt og tilgå SDM-mysql’en på den virtuelle maskine på url localhost:3307)

...

3.3     Database setup

Tester man med en ”NSP in a box” (NIAB) skal mysql databasen som udgangspunkt konfigureres i på NIAB hosten. (Se [NIAB] for konfiguration af NIAB)

Opret en bruger i mysql databasen med bruger navn ”sdm” og password ”papkasse”:

% mysql -uroot -p

Enter password: <root password til mysql>[2]

mysql> CREATE USER 'sdm'@'localhost' IDENTIFIED BY 'papkasse';

Stamdataservicens database og tabeller oprettes via:

db/schema.sql

db/batch_copy

db/dynamic_views.sql

Sql filerne eksekveres på følgende måde:

% mysqladmin -u root create sdm_warehouse -p

% mysql -u root -p

Enter password: <root password til mysql>

mysql> grant all privileges on sdm_warehouse.* to sdm@localhost identified by 'papkasse' with grant option;

mysql> exit

% mysql -u sdm sdm_warehouse < db/schema.sql -p

Enter password: papkasse 

% mysql -u sdm sdm_warehouse < db/batch_copy.sql -p

Enter password: papkasse 

% mysql -u sdm sdm_warehouse < db/dynamic_views.sql -p

Enter password: papkasse 

Det anbefales, at den nuværende navngivning af databasen bibeholdes. Ønsker man at etablere en database med et alternativt navn, skal dette tilrettes i modulernes konfigurationsfiler.

Bemærk, at ændringer i konfigurationsfilerne har systemmæssige konsekvenser, og derfor bør kun velovervejede ændringer committes.

3.4     Autogenereret kode

Start med at køre følgende:

% mvn clean install

Stamdataprojektet benytter JAX-WS i webservice snitfladerne i CPR-WS projektet.

Snitfladekoden er autogeneret og skal ved opdatering af de associererede WSDL filer opdateres med kommandoen:

% mvn generate-sources

Som bagvedliggende implementering af JAX-WS benyttes Oracle’s reference implementering. Denne kan konfigureres ved at ændre i filen

<CPR-modul>/…/WEB-INF/sun-jaxws.properties

3.5     Test

Installationen kan verificeres ved at eksekvere stamdataservicens test suite.

...

Testkoden er for hvert modul lokaliseret i:

src/test/java

Test suiten afvikles ved at udføre følgende kommando i projektroden:

% mvn test

Kommandoen kan også udføres under de individuelle moduler, hvorved kun undermodulets test udføres.

...

Installationen kan yderligere verificeres ved at udføre kommandoen:

% mvn verify

Denne kommando validerer code coverage og kode konventionerne for projektet.

...

Kode konventionerne følger reglerne defineret i filen:

config/checkstyle.xml

3.

...

6     IDE

Stamdataservicen kan principielt udvikles i enhver Java IDE, der forstår Maven projekters opbygning.

...

I dette dokument beskrives kort opsætning for to af de pt. mest udbredte Java IDE’er: Eclipse og IntelliJ.

3.

...

6.

...

1     Eclipse

Eclipse er ikke født med Maven support, og det anbefales derfor, at man installerer m2eclipse inden stamdataservicen hentes ind i Eclipse:

...

Herefter importeres projekterne i Eclipse via ”import”:

Image Removed

Alternativt kan man importere projektet ved at udføre følgende kommando:

...

Kommandoen genererer Eclipse projektfilerne (.project og .classpath) for roden og hvert undermodul.  Denne metode kræver dog, at kommandoen udføres hver gang man ændrer i pom filerne.

3.

...

7     IntelliJ Idea IDE

IntelliJ Idea er født med Maven support, og stamdataservicen kan derfor direkte importeres. Projektet importeres i IntelliJ ved under ”Create new project” at vælge ”Import project from external model”. Herefter udvælges roden af stamdataservicen, hvorefter projektet importeres.

...

Alternativt kan man importere projektet ved at udføre følgende kommando:

% mvn idea:idea

Herefter kan projektet importeres på normal vis i IntelliJ.

...

Obs! Denne metode kræver dog, at kommandoen udføres hver gang man ændrer i pom filerne.

3.

...

8     Distribution

Stamdataservicen kan bygges til distribution eller lokal test ved at udføre:

% mvn package

...

Dette generer en række WAR filer, der efterfølgende kan deployeres lokalt eller i produktion.

Kodeord til serverne og databaserne skal indhentes hos NSP-operatøren.

4       Performance test af autorisationsservicen og kopi-register-servicen

Dette afsnit beskriver hvordan man kører performance af autorisationsservicen og kopi-register-servicen.

4.1     Krav

For at køre performance test på Stamdata Projektet er det nødvendigt at have:

4.1.1     Deployment

Fra Netic kan man downloade et vmware image der er opsat til at kunne afvikle NSP. Dette kaldes ”NSP in a box” (NIAB). Dette image kan rekvireres ved henvendelse hos operatøren.

4.1.2     Konfiguration

Inden man kører test skal man konfigurere stamdata komponenterne til at køre i development mode. Fra kildekoden skal

/nsp/authorization-lookup-ws/src/test/resources/test-config.properties

omdøbes til

stamdata-authorization-lookup-ws.properties

og lægges i

$JBOSS_HOME/server/default/conf/

På samme måde skal

/nsp/batch-copy-ws/src/test/resources/test-config.properties

omdøbes til

stamdata-batch-copy-ws.properties

og lægges i

$JBOSS_HOME/server/default/conf/

Check at følgende property:

security=dgwsTest

er sat i

stamdata-batch-copy-ws.properties

Dette gør, at komponenterne godkender requests med ID Kort underskrevet af Test STS’en.

Når filerne er ændret skal JBoss genstartes:

% sudo /etc/init.d/jboss restart

4.1.3     Konfiguration af database

Det CVR-nummer der bliver brugt til tests skal være oprettet i stamdatatabellerne ”Client” og ”Client_permissions”. Dette gøres på følgende måde:

1. I tabellen ”Client” oprettes et element med:
   1. ”name” sat til ”Region Syd” og
   2. ”subjectSerialNumber ” sat til ”CVR:19343634-UID:1234”
   3. Aflæs det generede id og opret i tabellen ”Client_permission” en indgang med
      1. ”client_id” sat til det genererede i tabellen ”Client”
      2. ”permission” sat til ”cpr/person/v1”.

4.1.4     Kørsel

Performance tests køres ved at køre følgende kommandoer fra folderen ”common/performance” i stamdata’s kildekode:

% mvn -Pperformancetest integration-test site -Dhostname=<host> -Dport=<port>

Hvor <host> er adressen på nsp-serveren, hvor Stamdataservice er deployet. Hvis du kører mod NIAB så anvend dens IP-adresse som <host> og anvend 8080 som <port>.

4.2     Testrapporter

HTML-rapporter bliver lagt i

common/performance/target/site/

når alle tests er færdige.

Her ligger performancerapporter fra kørsel mod autorisationsservicen (authorization-ws-test-report.html) og kopi-register-servicen (replication-ws-report.html).

5       Performancetest af CPR-services

Test køres med current dir i

nsp/cpr-ws

For StamdataPersonLookup testes den case, hvor request indeholder fornavn+efternavn, og der søges efter personer der matcher dette. Denne case er udvalgt, fordi den vurderes at belaste serveren mest (i forhold til fx casen med opslag ud fra cpr-numre).

5.1     Krav

For at køre performance test på Stamdata Projektet er det nødvendigt at have:

5.1.1     Konfiguration

Inden man kører test, skal man konfigurere stamdata komponenterne til at køre i development mode. Fra kildekoden skal

/nsp/cpr-ws/src/test/resources/test-config.properties

omdøbes til

stamdata-cpr-ws.properties

og lægges i (anvend sudo)

$JBOSS_HOME/server/default/conf/

5.2     Performance testdata

Filen

nsp/cpr-ws/src/test/resources/getPersonDetailsQueryParameters.csv

indeholder komma-separerede par af fornavn, efternavn der benyttes til kaldene til StamdataPersonLookup-servicen.

Der skal rettes i denne fil, så der angives mere end to fornavn, efternavn-par.

Alle fornavn, efternavn-par skal vælges så de hver giver mindst ét hit i den database der køres med. Fornavn, efternavn par som ikke giver et hit markeres som fejlede af JMeter-sampleren.

På samme måde indeholder filen

nsp/cpr-ws/src/test/resources/ getSubscribedPersonDetailsQueryParameters.csv

et cvr-nummer pr. linie. Disse cvr-numre benyttes til kaldene til StamdataPersonLookupWithSubscription-servicen.

Der skal rettes i denne fil, så der angives det ønskede antal cvr-numre.

De cvr der angives, behøver ikke nødvendigvis alle give hits (men nogle af dem skal). Sampleren markerer kun requests hvor samtlige person-opslag lykkedes.

Cvr-numre giver hits, første gang der kaldes for dem, givet at det angivne cpr-nummer i Cpr subscription-servicen er angivet til at have abonnement på mindst ét cvr-nummer, der findes i databasen.

5.3     Forudsætninger

5.3.1     CPR-WS Konfiguration

Inden man kører test skal man konfigurere stamdata komponenterne til at køre i development mode. Fra kildekoden skal

/nsp/cpr-ws/src/test/resources/test-config.properties

omdøbes til

stamdata-cpr-ws.properties

og lægges i (anvend sudo)

$JBOSS_HOME/server/default/conf/

5.3.2     CPR-WS database opsætning

For at kunne køre testen igennem med de leverede input-parametre, skal dette script indlæses i Stamdatas database:

src/test/resources/data_needed_for_performancetests.sql

f.eks. ved at køre (på NIAB hvis det er det man har valgt)

% mysql -usdm -p < nsp/cpr-ws/src/test/resources/data_needed_for_performancetests.sql

Password: papkasse

indeholder eksempeldata for henholdsvis cpr-abonnementer og ændrede cpr-numre til cprabbs-servicen.

For at give et realistisk dataload, skal der indsættes en væsentligt større mængde data i begge tabeller. Disse data skal matche data i Stamdatas person-tabel.

Både Stamdata og cprabbs-servicen skal være konfigureret til at acceptere Id-kort udstedt af SOSI test-STS’en. Se vejledning til anvendere [BRS-guide til anvendere] og [BRS-driftvejledning] for detaljer og afsnit 5.4 for en miniguide.

5.4     CPRABBS-Service miniguide

Der skal være adgang til en kørende cprabbs-service. Dette kan f.eks. opnås ved at deploye cpr-abbs war filen i på NIAB fra seneste BRS release. Denne cpr-abbs war fil ligger i et BRS release her:

<versions-nr>/cprabbs-war-<versions-nr>.war

5.4.1     CPRABBS-service konfiguration

Fra kildekoden skal

/brs/common/src/main/resources/brs.local-deploy.properties

omdøbes til :

brs.properties

og lægges i (anvend sudo):

$JBOSS_HOME/server/default/conf/

I Stamdatas konfiguration skal property

cprabbs.service.endpoint.host

cprabbs.service.endpoint.port

cprabbs.service.endpoint.path

sættes til cprabbs-servicens endpoint, fx værdierne

cprabbs.service.endpoint.host=localhost

cprabbs.service.endpoint.port=8080

cprabbs.service.endpoint.path=/cprabbs/service/cprabbs

5.4.2     CPRABBS-service databaseopsætning

Opret og tilpas CPRABBS notifikationsdatabasen:

$ mysql -f -uroot -p < init-mysql-nsp_reg_notification.sql

(ignorér fejl)

$ mysql --database=nsp_reg_noti -uroot -p < create-cprsubscription-tables.sql

$ mysql --database=nsp_reg_noti -uroot -p < mysql-cprsubscription-alter-tables.sql

Opret og tilpas testdatabase over personer med CPR-nummer opdateringer i stamdata databasen:

$ mysql -f -uroot -p < init-mysql-nsp_stamdata.sql

$ mysql --database=nsp_stamdata -uroot -p < create-test-stamdata-tables.sql

$ mysql --database=nsp_stamdata -uroot -p < mysql-test-stamdata-alter-tables.sql

Fyld data i CPRABBS notifikationsdatabasen:

$ mysql --database=nsp_stamdata -uroot -p < src/test/resources/cprabbs_data_needed_for_performancetests_nsp_stamdata.sql

Opret og tilpas testdatabase over personer med CPR-nummer opdateringer i stamdata databasen:

$ mysql --database=nsp_reg_noti -uroot -p < src/test/resources/cprabbs_data_needed_for_performancetests_nsp_reg_noti.sql

5.5     Udførsel

Man udfører testen ved at køre følgende (som én linie, uden liniebrud):

rm -rf target/chronos/&& mvn integration-test site -Pperformancetest -DskipTests -DnumberOfIterations=5 -DnumberOfThreads=10 -Dhostname=localhost -Dport=8080

(rm-delen sørger for, at Chronos-pluginn’et kører testen igen, selvom der ligger et resultat fra tidligere).

Værdierne af de 4 properties til sidst kan rettes. De betyder følgende:

5.6     Testrapporter

Når kommandoen har kørt, er testrapporter tilgængelige i

target/site

Denne html fil:

StamdataPersonLookupGetPersonDetails-report.html

Viser resultatet af den test, der forespørger på personer via fornavn, efternavn par. Resultater af den performancetest, der er abonnements (altså afhænger cpprabs-servicen) forefindes i

StamdataPersonLookupWithSubscriptionGetSubscribedPersonDetails-report.html

6       Tips og tricks

I de følgende beskrives problemer og deres løsninger:

...

6.1     JBoss out of memory

...

6.1.

...

1     Beskrivelse

...

I JBoss’s boot.log: 

$JBOSS_HOME/server/default/log/boot.log

...

Logger JBoss noget i stil med ”out of memory” og nævner “permgenspace”

...

6.1.

...

2     Løsning

Forøg JBoss permgen space ved at ændre linien indeholdende: 

JAVA_OPTS="-Xms2048m -Xmx2048m -XX:MaxPermSize=256m -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000"

...

i filen 

$JBOSS_HOME/bin/run.conf

til 

JAVA_OPTS="-Xms2048m -Xmx2048m -XX:MaxPermSize=512m -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000"

...

6.2     JBoss kan ikke skrive til “trancsaction.log”        

6.2.1     Beskrivelse

I JBoss’s boot.log:

$JBOSS_HOME/server/default/log/boot.log

Logger JBoss noget i stil med ”transaction.log” og ”cannot write”

6.2.2     Løsning

Ignorér denne fejl.

7      

...

Ændringslog

Nyeste udgave af dette dokument kan erhverves ved henvendelse til NSP-operatøren. 

8       Referencer og kilder

...

[1] Fra Seal.java 2.1.2 er XercesImpl ikke længere inkluderet i Seal.java.

[2] Root password til mysql sættes med følgende kommando:

% mysqladmin -u root password NEWPASSWORD