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

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

I dokumentet benyttes følgende notationer:

Markering af scripts og kommandoer.

Markering af advarsler

Markering af referencer til filer.

     Målgruppe og læsevejledning

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

2       System design

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 der fungerer som entry-point til applikationen. Det anbefales, at man som ny udvikler på projektet kigger koden igennem med denne fil som udgangspunkt.

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

     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       Opsætning af udviklingsmiljø

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


     Kildekode

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 indeholder et docker-compose setup, der starter en MariaDB container op og initialiserer en database.

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

% docker-compose -f compose/development/docker-compose.yml up

Det kan tage op til et minut, før databaseserveren er klar. Kig efter følgende linje i outputtet:

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 ændringer i konfigurationsfilerne har systemmæssige konsekvenser, og derfor bør kun velovervejede ændringer committes.


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


    Test

Installationen kan verificeres ved at eksekvere stamdataservicens test suite.

Stamdataservicen benytter JUnit og Mockito til test.

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


En del af testsuiten består af integrationstests, som kan afvikles mod forskellige miljøer. Miljøerne er konfigureret i profiler, således at man f.eks. kan teste mod test1-miljøet med følgende kommando:

% mvn verify -Ptest1

Profilerne kan ses i pom-filen. Der er pt. følgende profiler:

NavnBeskrivelse
developmentUnder denne profil bliver den testede service startet i en indlejret Undertow servlet-container, som der testes mod. Denne profil er aktiv som default, og bruges altså, hvis man ikke specifikt angiver en anden profil.
localUnder denne profil startes ingen Undertow-container, i stedet forventes den testede service at køre på localhost. Formålet med dette er at kunne teste mod et lokalt docker-compose setup.
test1Som 'local', men mod test1.
test2Som 'local', men mod test2.

Bemærk: I skrivende stund er det kun development-profilen der virker, da testklasserne selv opretter testdata i en lokalt kørende database. Der udestår et arbejde med at adskille oprettelsen af testdata fra udførsel af tests.

   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.

     Eclipse

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

http://www.eclipse.org/m2e/


Herefter importeres projekterne i Eclipse via ”import”:

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

% mvn eclipse:eclipse


Og herefter importere projektet på normal vis i Eclipse.

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.

     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.

Det anbefales i den sammenhæng, at man krydser af i ”Import Maven projects automatically”, hvorefter IntelliJ selv detekterer nye moduler i projektet.

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.

     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.

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.

Æ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

1.529/10-2020Fjernet afsnit omkring performance testKIT



8       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



[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