...

Introduktion

Formål

Formålet med dette dokument er at beskrive, hvordan et udviklingsmiljø til videreudvikling af NXRG kan sættes op, samt hvordan koden bygges, deployes og testes.

...

Kodestrukturen, kodemæssige afhængigheder til tredjeparts moduler og de forskellige servicemodulers ansvar og design beskrives sidst i dette dokument sammen med testdesign.

Sammenhæng med øvrige dokumenter

Dette dokument er en del af den samlede dokumentation for NXRG.

Dokumentets relation til de øvrige dokumenter er beskrevet i dokumentationsoversigten for NXRG.

Læsevejledning

Læser forventes at have kendskab til Java softwareudvikling med anvendelse af Maven og WildFly. Derudover forventes kendskab til Docker samt docker-compose.

Hvor der i teksten er angivet <component base> refereres til topniveaufolderen for kildekoden for komponenten.

Dokument Historik

Introduktion til NXRG

Alle NXRG services udstiller en SOAP service. Snitfladen er defineret i en WSDL fil og en række XSD filer. 

...

Design og arkitektur er beskrevet: NXRG - Design- og arkitekturbeskrivelse.

Opsætning af udviklingsmiljø

I det følgende antages at koden er hentet fra SVN: https://svn.nspop.dk/svn/components/nxrg.

Krav til software

NXRG deployeres vha. docker, hvorfor de alle baserer sig på NSP platformens base image, hvori der findes nødvendigt software til afvikling.

...

• Maven 3.0.3 eller højere anvendes.
• docker-compose version 3.4 eller højere

Bygge WAR filer

Man skal bruge Maven til at bygge NXRG, hvilket gøres ved at køre kommandoen

...

Afvikling

Der henvises til installationsvejledningen for nærmere instrukser.

Udviklers workstation

Når man udvikler kan det være praktisk at foretage lokal deployment.

...

• HelbredsURL: Se NXRG - Driftsvejledning
• Services: Se NXRG - Guide til anvendere

Beskrivelse af systemdesign

Systemdesign er beskrevet i NXRG - Design- og arkitekturbeskrivelse.

Beskrivelse af kildekodens strukturering og design

Kode strukturering

Kildekoden bygges vha Maven, og kildekoden er struktureret som Maven moduler. NXRG består af følgende moduler:

Dato og tidshåndtering

Datoer og tidspunkter anvendes på følgende måde i NXRG:

Dato og tidshåndtering

Datoer og tidspunkter anvendes på følgende måde i NXRG:

• RIM formattet er en streng, og requst og response forventes at være i UTC tid.
• IHE frameworket anvender joda time (DateTime) og klasser, der interagerer med dette framework anvender derfor joda time.
• Ved "indgang" til servicene tjekkes at tidspunkterne i IHE modellen er UTC tid (UtcDateTimeTransformer og UtcDateTimeQueryTransformer)
• Tidspunkter fra metadata, som gemmes i databasen er UTC tid
• RIM formattet er en streng, og requst og response forventes at være i UTC tid.
• IHE frameworket anvender joda time (DateTime) og klasser, der interagerer med dette framework anvender derfor joda time.
• Ved "indgang" til servicene tjekkes at tidspunkterne i IHE modellen er UTC tid (UtcDateTimeTransformer og UtcDateTimeQueryTransformer)
• Tidspunkter fra metadata, som gemmes i databasen er UTC tid
• Øvrig håndtering af tid foregår vha java.time.Instant og foregår i UTC tid
• Klassen DateTimeUtils anvendes som utility til at håndtere dato og tid

Databaseændringer

Databasemodellen styres ved hjælp af Liquibase. Det betyder at når der skal laves ændringer til databasemodellen, så må man ikke rette i de eksisterende skemafiler. I stedet skal der laves nye filer der beskriver ændringerne.

Skemaændringer

Skal der tilføjes f.eks. en ny kolonne eller en ny tabel skal nedenstående gøres.

1. Der oprettes en ny fil i folderen compose/configuration/database/ddl. Filen skal navngives liquibase-changelog-x.y.z.xml hvor x, y og z er det versionsnummer du forventer at release komponenten som. Filen skal beskrive ændringen der skal laves. Hvis man anvender liquibase SQL syntaxen får man typisk automatisk "rollback" med. Man kan også referere til rå SQL filer.
2. Filen fra punkt 1 tilføjes compose/database/liquibase-changelog-master.xml.
3. Done

Testdata

Opstår der en situation hvor der skal tilføjes yderlige testdata for at integrationstesten kan afvikles skal nedenstående udføres.

1. Der oprettes en ny fil i folderen compose/configuration/database/test. Filen skal navngives liquibase-changelog-test-x.y.z.xml hvor x, y og z er det versionsnummer du forventer at release komponenten som. Filen skal beskrive ændringen der skal laves. Hvis man avender liquibase SQL syntaxen får man typisk automatisk "rollback" med. Man kan også referere til rå SQL filer.
2. Filen fra punk 1 tilføjes compose/database/liquibase-changelog-test.xml
3. Done

Migrering

 Adgang til database script

NXRG udgiver sine database scripts i et liquibase docker image: nxrg-liquibase. Ønsker man at starte NXRG fra et docker image, kan man med fordel anvende det tilhørende liquibase image, til at få lagt den tilhørende database på en mariadatabase.

Eksempel på anvendelse vha. docker compose:

networks:
  nsp_net:
    external: true
  nxrg_net:  

volumes:
  shared-data-db:

services:
  mysql-nxrg:
    image: mariadb:10.3.16
    networks:
      - nxrg_net
    environment:
      - MYSQL_ROOT_PASSWORD=rootroot
      - MYSQL_DATABASE=nxrg
      - MYSQL_USER=nxrg
      - MYSQL_PASSWORD=nxrg
    ports:
      - "3306:3306"
    healthcheck:
      test: "/usr/bin/mysql --user=$$MYSQL_USER --password=$$MYSQL_PASSWORD $$MYSQL_DATABASE --execute \"SELECT count(table_name) > 0 FROM information_schema.tables;\""
      start_period: 5s
      interval: 2s
      timeout: 10s
      retries: 10

  nxrg-liquibase:
    image: nxrg-liquibase:latest
    depends_on:
      mysql-nxrg:
        condition: service_healthy
    networks:
      - nxrg_net
    command: >
      --defaultsFile /liquibase/configuration/liquibase.properties update

Når ovenstående docker-compose fil startes op, startes en mariadb og efterfølgende vil liquibase opdatere med med NXRG database script (NB. eksemplet ovenfor er foreløbigt da nxrg-liquibase image ikke er publiceret endnu.

Migrering

Kildekoden, som håndterede migreringen fra OpenText registyr, samt dets hjælpe værktøjer til kontrol af migreringen (også benævnt: Migreringstool, Migreringsverifikationstool, Replaytool og Datareperationstool), er taget ud af svn i revision r10379.

Felt migrering

NXRG har sin egen service til migrering af eksisterende metadata til søgbare felter. Detaljerne er beskrevet i "NXRG - driftvejledning til felt migrering" om, hvordan dette køres.

Source koden består af 3 klasser, med følgende formål:

1. ComplexFieldMigration: har ansvaret for håndtering af fieldMigrationStatus
2. ComplexDocumentEntryFieldMigration: har ansvar for håndtering af documentEntry
3. AddRepositoryUniqueId: har ansvar for håndtering af migrering af det specifikke felt. Her RepositoryUniqueId.
4. Et sql script der i første version opretter fieldmigrationstatus og eftefølgende tilføjer en record per migrering

Skal denne funktionalitet udvides med nye felter, gøres det på følgende måde:

• Er der tale om et felt, der logisk hører til på documentEntry:
  • der laves en ny klasse i stil med AddRepositoryUniqueId, som på samme vis, nedarver fra ComplexDocumentEntryFieldMigration
• Er der tale om et felt, der logisk hører til på assocation eller  submissionset:
  • der laves en ny klasse i stil med ComplexDocumentEntryFieldMigration, som håndterer f.eks. association istedet.
  • en ny klasse i stil med AddRepositoryUniqueId, som nedarver fra den nye klasse istedet for ComplexDocumentEntryFieldMigration
• Der oprettes et sql script, der indsætter en record i fieldmigrationstatus

Samtidig med at ovenstående laves, skal også håndtering i selve NXRG laves. Sådan at nye registreringer af dokumenter, selv gemmer feltet som søgbart felt. Drejer det sig om et felt til documentEntry rettes følgende klasser:

1. DocumentEntryTO
2. DocumentEntryDaoImpl.createDocumentEntry
3. XdsObjectMapper.mapDocumentEntry
4. DocumentEntryDaoImplTest

Reel anvendels af det nye felt, må først ske i en senere version af NXRG, sådan at data grundlaget i de kørende systemer er blevet migreret og data tilgængeligKildekoden, som håndterede migreringen, samt dets hjælpe værktøjer til kontrol af migreringen (også benævnt: Migreringstool, Migreringsverifikationstool, Replaytool og Datareperationstool), er taget ud af svn i revision r10379.

Beskrivelse af testsetup

Unittests (JUnit)

JUnit anvendes til implementering af unit tests. Der er kontinuert gennemført unit tests på alle komponenter i projektet.

...

Hvis der derimod laves en verify, så vil der også blive genereret code coverage, hvor fremkommende rapport kan ses i testreport/target/site/jacoco-aggregate/index.html

Integrationstests

Integrationstests ligger i modulet nxrg-qa og kan afvikles med:

...

Hvis man ønsker af afvikle testen op mod en andet miljø f.eks. test1 eller test2 henvises til NXRG - Testvejledning.

Integrationstesten sender een notifiation til NAS. Denne kan findes via DRG. På Test1 kan det gøres med getMessages vha. pull point: http://test1.ekstern-test.nspop.dk:8080/nas2/pullpoint/service/080d09f8-48af-405c-b55f-f821a773c9c1

Performance test

Performance testen foregår vha. et test framework udviklet af Arosii.

...

I det følgende antages at koden er hentet ned fra SVN: https://svn.nspop.dk/svn/components/performance/trunk/  samt at man har docker installeret i sit udviklingsmiljø. JMeter skal også være tilgængelig.

Kildekodens struktur

Kildekoden indeholder også performance test til andre services, men i nedestående er NXRG vigtigste dele trukket frem.

...

tests: indeholder de generede test filer

• distributioner
• planer

Versionskontrol

Test versionen styres vha. af revision i trunk. I dokumentet "testvejledning" afsnit performance test angives, hvilken version af performance testen der anvendes med en given version af NXRG.

Udvikling af test

NXRGs  performance test består af ovennævnte java sourcer. Disse vedligeholdes i takt med at NXRG snitflader ændres/udvides og skal performance testes.

Lokal test kan gøres ved at bygge projektet og starte JMeter op.

Generering af testfiler

Når man har udviklet og bygget test projektet, startes JMeter. Herefter kan en eksisterende performance test åbnes og køres herfra. Eller en ny kan laves. 

...