Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Navitabs
rootStamdatamodul (SDM)
firsttabRegisterudtrækservices (SDM)
includeroottrue

...


Table of Contents

Formål

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

     Metode Metode og rapportens opbygning

Efter nærværende introduktion vil dokumentet gennemgå de væsentligste dele af opsætningen af et lokalt udviklingsmiljø og afvikling af test/performancetest.

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

...

Markering af referencer til filer.

     Målgruppe Målgruppe og læsevejledning

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

Table of Contents

...


System design

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

...

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

     SealSeal

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 AS6Wildfly[1].

     PropertiesProperties

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).

...

Opsætning af udviklingsmiljø

Opsætningen af udviklingsmiljøet for stamdataservicen forudsætter, at følgende elementer allerede er installeret på udviklerens maskine:


  • Java Developer Kit 6.0_x(JDK 8)
  • Et passende udviklingsmiljø
  • Maven 3.x
  • Docker 18.x (testet med 18.09.7)
  • JBoss AS6

     KildekodeKildekode

Kildekoden er placeret i SVN:

https://svn.nspop.dk/svn/components/sdm/


     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.

 

    Database setup

Projektet bygges (og tests afvikles) med følgende kommando:

mvn clean install

Database setup

Som en del af docker-compose setuppet for projektet, startes For at køre projektets tests skal der køre en lokal MariaDB. Projektet indeholder et docker-compose setup, der starter en MariaDB container op, og initialiserer en database initialiseres.

For at starte projektet inkl. MariaDB-containeren køres følgende fra projektroden:

...

mariadb_1 | 2020-01-13 09:27:51+00:00 [Note] [Entrypoint]: Creating database sdm_warehouse

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 der ved afvikling af tests anvendes en in-memory H2-database, og til dette er det derfor ikke nødvendigt at starte en lokal database op. 

Autogenereret      Autogenereret kode

Start med at køre følgende:

...

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

...


Unit Tests

Installationen kan verificeres ved at eksekvere stamdataservicens test suite.

Stamdataservicen benytter JUnit, Mockito og Mockito Undertow til test.

Testkoden er for hvert modul lokaliseret i:

...

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

% mvn test

(Denne metode afvikler ikke testene PersonInformationIT, DetGodeCPROpslag104IT og DetGodeCPROpslag1041aIDWSIT, hvilket verify nedenfor gør)


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

...

Kode konventionerne følger reglerne defineret i filen:

config/checkstyle.xml


Som en del af testen bliver den servicen startet i en indlejret Undertow servlet-container, som der testes mod. Dette gør at noget af unit testen kører som en slags integrationstest.

   IDE

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

...

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

     Distribution

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

...

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.

   Krav

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

...

Krav

...

Installation og test

...

Stamdatas kildekode er checket ud.

...

%git clone https://github.com/trifork/sdm/ git clone https://github.com/trifork/sdm/

...

Maven3 installereret

...

Se maven.org for installation

% mvn –v (i prompt)

...

Adgang til internettet

...

-

...

Adgang til Test STS’en (dvs. være på et netværk hvor den er tilgængelig.)

...

Check at

http://niab01.nsp-test.netic.dk:8080/sts/services/SecurityTokenService?wsdl viser wsdl i browser. Udskift evt. niab01.nsp-test.netic.dk:8080 men den Test STS host og port du anvender.

...

NSP in a box (NIAB) kørende via vmware’s vmplayer

...

Følg vejledningen i [niab] og gennemfør smoketesten for at checke at den fungerer.

     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.

     Konfiguration

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

...

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

     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”.

     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>.

     Testrapporter

HTML-rapporter bliver lagt i

...

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).

     Krav

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

...

Krav

...

Installation og test

...

Stamdatas kildekode er checket ud.

...

%git clone https://github.com/trifork/sdm/ git clone https://github.com/trifork/sdm/

...

Maven3 installereret

...

Se maven.org for installation

% mvn –v (i prompt)

...

Adgang til internettet

...

-

...

Adgang til Test STS’en (dvs. være på et netværk hvor den er tilgængelig.)

...

Check at

http://niab01.nsp-test.netic.dk:8080/sts/services/SecurityTokenService?wsdl viser wsdl i browser. Udskift evt. niab01.nsp-test.netic.dk:8080 men den Test STS host og port du anvender.

...

NSP in a box (NIAB) kørende via vmware’s vmplayer

...

Følg vejledningen i [niab] og gennemfør smoketesten for at checke at den fungerer.

...

CPRABBS servicen deployeret (på NIAB)

...

I dette dokument er der en miniguide hertil men det anbefales at konsultere dokumenterne

[BRS-guide til anvendere] og [BRS-driftvejledning]

     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/

     Performance testdata

Filen

...

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.

     Forudsætninger

     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/

     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.

     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

     CPRABBS-service konfiguration

Fra kildekoden skal

...

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

omdøbes til :

...

brs.properties

...

$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

     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

Distribution

Mavens release plugin anvendes til at lave releases:

mvn org.apache.maven.plugins:maven-release-plugin:2.5.3:prepare

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

     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:

...

Property

...

Beskrivelse

...

numberOfIterations

...

hvor mange loops skal hver tråd køre

...

numberOfThreads

...

hvor mange tråde skal der startes

...

Hostname

...

på hvilken host kører StamdataPersonLookup-servicen

...

Port

...

på hvilken port kører StamdataPersonLookup-servicen

     Testrapporter

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

...

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:

     JBoss out of memory

     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”

     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"

     JBoss kan ikke skrive til “trancsaction.log”        

     Beskrivelse

I JBoss’s boot.log:

...

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

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

     Løsning

Ignorér denne fejl.

7       Ændringslog

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

...

Version

...

Dato

...

Ændring

...

Ansvarlig

...

1.0

...

28/4-2011

...

Initielt Dokument

...

Trifork

...

1.1

...

6/10-2011

...

Opdateret med CPR tjenester

...

Trifork

...

1.2

...

8/12-2011

...

Kvalitetssikret af Lakeside

...

Lakeside

...

1.3

...

22/12-2011

...

Opdateret bla. med performance test af autorisationsservicen og kopi-register-servicen

...

Trifork

...

1.4

...

14/5-2013

...

Opdateret afsnit omkring oprettelse af database

...

Trifork

...

Referencer og kilder

Reference-id

Indhold / Overskrift

Henvisning

[MAVEN]

Welcome to Apache Maven

http://maven.apache.org/

[NIAB]

NSP in a box

Kan rekvireres ved henvendelse til operatøren inklusiv vejledning i anvendelse og konfiguration.

[BRS-guide til anvendere]

Guide til anvendere

Ligger i doc bibliotek i en BRS release

[BRS-driftvejledning]

Driftvejledning

Ligger i doc bibliotek i en BRS release

...