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

• JAVA_PROJECT_SETUP_GUIDE.md - Komplett oppsetts- og bruksveiledning
• docs/DATABASE_SCHEMA.md - Database-skjema og migrasjoner
• .github/copilot-instructions.md - Kode-retningslinjer for AI-assistanse

Tekniske Detaljer

• PACKAGE_CONSOLIDATION_FIX.md - 🎯 KRITISK FIX - Unified WSDL package-løsning
• STORESERVICE_SOLUTION.md - ⭐ Optimal filtrert nedlasting med StoreService

Lisens

Dette prosjektet er utviklet for integrasjon med Kartverkets Matrikkel API.