Skip to content

README.md

Latest commit

 

History

History
240 lines (177 loc) · 8.09 KB

README.md

File metadata and controls

240 lines (177 loc) · 8.09 KB

Matrikkel API Integration

En generisk Java Spring Boot-applikasjon for integrasjon med norsk Matrikkel SOAP API. Applikasjonen kan laste ned og lagre matrikkeldata fra hvilken som helst norsk kommune til PostgreSQL database.

Teknisk Stack

  • Java 21 - Moderne LTS-versjon
  • Spring Boot 3.4.0 - Latest stable release
  • PostgreSQL 17 - Database med full støtte for matrikkeldata
  • Flyway 10.20.1 - Database migrasjoner med baseline-strategi
  • JAX-WS 4.0.0 - Automatisk SOAP XML serialisering
  • Maven 3.9+ - Build management

Funksjoner

  • ✅ Generisk & Kommune-uavhengig - Fungerer med alle norske kommuner ved å oppgi kommunenummer
  • ✅ SOAP Client - Automatisk generert fra WSDL med JAX-WS
  • ✅ Cursor-basert Paginering - Effektiv bulk-nedlasting med MatrikkelBubbleId
  • ✅ Server-side Filtrering - Filtrer på personnummer/organisasjonsnummer (99% reduksjon i dataoverføring!)
  • ✅ To-stegs API-pattern - MatrikkelenhetService → StoreService for optimal ytelse
  • ✅ PostgreSQL Lagring - Spring Data JPA med Hibernate
  • ✅ Eierforhold - Håndterer personer, juridiske personer og matrikkelenhet-eiere
  • ✅ Database Migrasjoner - Flyway med baseline-strategi for nye installasjoner
  • ✅ CLI Interface - Kommandolinje-verktøy for import
  • ✅ Batch Processing - Konfigurerbare batch-størrelser (standard 500)

Rask Start

Forutsetninger

  1. Java 21 JDK installert
  2. PostgreSQL 17 database kjørende
  3. Maven 3.9+ installert
  4. .env-fil med database- og API-credentials (se eksempel under)

Environment Setup

Opprett .env-fil i prosjektets rot:

# Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_NAME=matrikkel2
DB_USERNAME=your_username
DB_PASSWORD=your_password

# Matrikkel API credentials (test environment)
MATRIKKEL_USERNAME=your_kommune_test
MATRIKKEL_PASSWORD=your_password

# Spring Configuration
SPRING_PROFILES_ACTIVE=dev

Database Setup

# Last inn environment variables
export $(grep -v '^#' .env | xargs)

# Kjør Flyway baseline migration (første gang)
mvn flyway:migrate

# Verifiser at 14 tabeller ble opprettet
psql -h $DB_HOST -p $DB_PORT -U $DB_USERNAME -d $DB_NAME -c "\dt"

Tabeller som opprettes:

  • matrikkel_matrikkelenheter - Matrikkelenheter (grunndata)
  • matrikkel_personer - Personer (base-tabell)
  • matrikkel_fysiske_personer - Fysiske personer
  • matrikkel_juridiske_personer - Juridiske personer
  • matrikkel_eierforhold - Eierforhold (kobling mellom matrikkelenhet og eier)
  • matrikkel_bygninger - Bygninger
  • matrikkel_bruksenheter - Bruksenheter
  • matrikkel_veger - Veger/gater
  • matrikkel_adresser - Adresser (base-tabell)
  • matrikkel_vegadresser - Vegadresser
  • flyway_schema_history - Flyway migrasjonshistorikk

Import-strategier

Applikasjonen støtter to hovedstrategier optimalisert for ulike bruksområder:

Strategi 1: Filtrert Import (Anbefalt ✨)

Last ned kun data for spesifikke personer/organisasjoner - alt i én operasjon:

# Last ned matrikkelenheter + personer + bygninger + adresser for spesifikt personnummer
export $(grep -v '^#' .env | xargs) && mvn spring-boot:run \
  -Dspring-boot.run.arguments="--import --kommune=1103 --personnummer=964965226"

# Eller for organisasjon
export $(grep -v '^#' .env | xargs) && mvn spring-boot:run \
  -Dspring-boot.run.arguments="--import --kommune=4601 --organisasjonsnummer=964338531"

Slik fungerer det:

  1. 🔍 MatrikkelenhetService.findMatrikkelenheter(): Server-side filter returnerer IDer (f.eks. 4,744 IDer på ~1 sek)
  2. 📦 StoreService.getObjects(): Batch-hent komplette objekter (10 batches × 500 = ~12 sek)
  3. 👥 Person-data: Laster eierforhold for alle matrikkelenheter
  4. 🏢 Bygninger/Bruksenheter: API-filtrert nedlasting (BruksenhetService.findBruksenheterForMatrikkelenheter)
  5. 🏠 Adresser: API-filtrert nedlasting (AdresseService.findAdresserForMatrikkelenheter)

Ytelse: 99% reduksjon i dataoverføring (4,744 vs ~15,000 objekter for kommune 1103)

Strategi 2: To-fase Import

Nyttig når du vil ha basis-data først, deretter legge til detaljer selektivt:

Fase 1: Base Import (--base-import)

# Last ned matrikkelenheter + personer KUN (hopp over bygninger/adresser)
export $(grep -v '^#' .env | xargs) && mvn spring-boot:run \
  -Dspring-boot.run.arguments="--import --kommune=1103 --personnummer=964965226 --base-import"

Fase 2: Selektiv Detalj-import (--filter-existing)

# Last fra database, filtrer på person/org, hent bygninger/adresser
export $(grep -v '^#' .env | xargs) && mvn spring-boot:run \
  -Dspring-boot.run.arguments="--filter-existing --kommune=1103 --personnummer=964965226"

Bulk Import (Uten Filter)

# Import ALLE matrikkelenheter fra en kommune - TREG for store kommuner!
export $(grep -v '^#' .env | xargs) && mvn spring-boot:run \
  -Dspring-boot.run.arguments="--import --kommune=4601 --limit=1000"

⚠️ Merknad: Bulk import uten filter laster ALL data for kommunen (ikke anbefalt for store kommuner som Bergen, Oslo)

Teknisk Implementasjon

To-stegs Pattern (Server-Side Filtering)

Når du bruker --personnummer eller --organisasjonsnummer filter, bruker systemet en optimalisert to-stegs tilnærming:

Steg 1: MatrikkelenhetService.findMatrikkelenheter()

// Server-side filtrering - returnerer kun IDer
MatrikkelenhetsokModel model = new MatrikkelenhetsokModel();
model.setKommunenummer(kommunenummer);
model.setNummerForPerson(personnummer);
MatrikkelenhetIdList idList = matrikkelenhetService.findMatrikkelenheter(model, context);
// Resultat: [123, 456, 789, ...] - 4,744 IDer på ~1 sekund

Steg 2: StoreService.getObjects()

// Batch-hent komplette objekter basert på ID
MatrikkelBubbleIdList bubbleIdList = convertToMatrikkelBubbleIdList(ids);
MatrikkelBubbleObjectList objects = storeService.getObjects(bubbleIdList, context);
// Resultat: 4,744 komplette Matrikkelenhet-objekter på ~12 sekunder (10 batches × 500)

Fordeler:

  • ✅ Server-side filtrering (API gjør jobben)
  • ✅ 99% reduksjon i dataoverføring
  • ✅ Type-safe etter package-konsolidering (nedlastning package)
  • ✅ Batch processing (500 objekter per batch)

Package Consolidation (Kritisk!)

Alle WSDL-tjenester som deler XSD-schemas MÅ bruke samme package-navn:

<!-- pom.xml -->
<execution>
    <id>wsimport-store</id>
    <configuration>
        <packageName>no.matrikkel.client.generated.nedlastning</packageName>
    </configuration>
</execution>

Hvorfor? StoreService og NedlastningService deler samme XSD schema. Forskjellige package-navn gir ClassCastException runtime, selv om klassene er identiske!

Se PACKAGE_CONSOLIDATION_FIX.md for full forklaring.

Utviklingsverktøy

Maven Tasks

# Kompiler prosjekt og generer SOAP-klienter fra WSDL
mvn clean compile

# Kjør tester
mvn test

# Package til JAR (skip tests)
mvn clean package -DskipTests

# Flyway: Vis migrasjons-status
mvn flyway:info

# Flyway: Kjør migrasjoner
mvn flyway:migrate

Database-verktøy

# Koble til database
export $(grep -v '^#' .env | xargs)
psql -h $DB_HOST -p $DB_PORT -U $DB_USERNAME -d $DB_NAME

# Vis alle tabeller
\dt

# Tell matrikkelenheter
SELECT COUNT(*) FROM matrikkel_matrikkelenheter;

# Se eierforhold for en matrikkelenhet
SELECT * FROM matrikkel_eierforhold WHERE matrikkelenhet_id = 123;

Dokumentasjon

Viktig Dokumentasjon

Tekniske Detaljer

Lisens

Dette prosjektet er utviklet for integrasjon med Kartverkets Matrikkel API.