Gå til hovedinnhold

Spesielle tjenester

Spesielle tjenester​

StoreService​

Denne tjenesten tilbyr metoder for å hente ut en eller flere bobler basert på deres id. Denne er primærmåten å navigere gjennom boblemodellen og for å hente ut boblene.

RapportService​

Matrikkelen tilbyr en del predefinerte rapporter og denne tjenesten brukes for å bestille og hente disse. Bruksmønsteret er at man benytter en metode for å bestille en rapport. Man får da tilbake et rapport-objekt som peker til et Jobb-objekt som man kan hente ut for å få status for bestillingen. Når rapporten er ferdig kan man hente denne ut over HTTPS som en filnedlasting.

Eksempel​

Følgende eksempel viser hvordan vi kan bestille og hente ut en rapport. Bruker rapporten "Samlet rapport for matrikkelenhet" som eksempel.

// Finner først matrikkelenheten vi vil ha rapport for
MatrikkelenhetService matrikkelenhetService;
MatrikkelenhetId matrikkelenhetId = matrikkelenhetService.findMatrikkelenhetIdForIdent(new MatrikkelenhetIdent(...));

// Bestiller så rapporten
RapportService rapportService;
OfflineMatrikkelRapport r = rapportService.createSamletRapportForMatrikkelenhet(
    matrikkelenhetId, ExportTypeId.PDF, true
);

// Henter rapporten ut og finner URL for filen.
MatrikkelRapport rapport = rapportService.hentRapport(r.getJobbId()); // Dette kallet feiler hvis rapporten ikke er klar.

String urlForRapport = rapport.getURL(); // Kan så bruke denne for å hente rapporten over https

KodelisteService​

API-et tilbyr en tjeneste for å hente ut alt av koder i systemet. Dette kan da brukes for å cache opp kodeverdier i lokal klient. Da det i utgangspunktet kan komme til nye kodeverdier når som helst bør man i klient benytte seg av denne tjenesten ofte for å være sikker på at man ikke ender opp med å få bobler fra StoreService som refererer til kodeverdier man ikke vet om.

Metoden getKodelister på tjenesten tar inn et tidspunkt, men dette bør ikke benyttes med mindre man vet at man ikke ønsker kodelister på nåværende tidspunkt. Dette krever spesielle rettigheter så man bør nok benytte seg av "nåtid" i de fleste tilfeller.

NedlastningService​

Det kan være tilfeller der man ønsker å hente ut store datamengder. NedlastningService tilbyr to metoder for å kunne gjøre dette. De to metodene har samme signatur men forskjellige returtyper. Den ene metoden gir tilbake id-er og den andre gir oss boblene. Det er opp til brukeren å bestemme hvilke av disse som er mest hensiktsmessige. Hvis man allerede har en lokal kopi av matrikkelen og vil sjekke om man har alle id-er vil det være unødvendig å hente ut alle objekter. Under følger eksempel på bruk av tjenesten.

Eksempel​

NedlastningService service;
 
String filter = "{kommunefilter: [\"1201\"]}";
List<VegId> alleIds = new ArrayList<>();
List<VegId> idsEtterId;
VegId sisteId = null;
do {
	idsEtterId = service.findIdsEtterId(sisteId, Veg.class, filter, 10000);
	alleIds.addAll(idsEtterId);
	sisteId = alleIds.get(alleIds.size() - 1);
} while(idsEtterId.size() > 0);
 
return alleIds;

Eksemplet henter ut alle veger i kommune med kommunenummer "1201". Se beskrivelsen av tjenesten for mer informasjon rundt de forskjellige parametrene.

Tjenesten kan man da bruke for å hente ut data for en eller flere kommuner (eller hele landet) og man kan så koble dette sammen med endringsloggstjenester for å bygge opp en lokal kopi av matrikkeldata.

EndringsloggService​

EndringsloggService kan brukes for å hente en instans av Endringer, som igjen inneholder en liste av Endring. En Endring representerer en Nyoppretting, Oppdatering, Sletting eller en Typeendring for ett bobleobjekt. Legg merke til at en endring inneholder ikke hva som eventuelt har blitt endret i bobleobjektet, om man oppgir ReturnerBobler. Alltid som parameter til endringsloggstjenesten vil man få tilbake boblen i nåværende tillstand (dvs. ikke tilstanden boblen hadde da endringen ble utført).

Brukstilfelle for denne tjenesten kan være å holde et system synkronisert med matrikkelen. For å etablere en lokal kopi vil man måtte bruke endringsloggtjenesten sammen med nedlastningservice beskrevet over. Man kan da hente ut siste endring fra endringsloggservice først, før man så benytter nedlastningservice for å hente ut alle objekter for typene man vil ha i lokal kopi. Etter at man har fått ut alle objekter kan man lese endringer som har foregått i løpet av perioden man lastet ned data.

Man kan ikke etablere en lokal kopi ved å kun benytte endringsloggstjenesten. Denne vil bare gi ut endringer for det siste året. Man må da basere seg på å først hente ut data med *nedlastningserviceÆ, før man kan bruke endringsloggen som beskrevet under for å holde kopien ved like.

Eksempel som går igjennom alle endringer​

EndringsloggService endringsloggService;
StoreService storeService;

Map<BubbleId<?>, BubbleObject> boblerForHenting = new HashMap<>();
Set<BubbleId<?>> leggesTil = new LinkedHashSet<>();
Set<BubbleId<?>> oppdateres = new LinkedHashSet<>();
Set<BubbleId<?>> slettes = new LinkedHashSet<>();

String filter = "{kommunefilter: [\"1201\"]}";
MatrikkelEndringId forsteEndringsId = null; // bruk f.eks. id fra siste endring hentet med nedlastingstjenesten
Endringer<MatrikkelEndring<?, ?>> endringer;
do {
   endringer = endringsloggService.findEndringer(
         forsteEndringsId,             // returner endringsobjekter fra og med oppgitt endringsID.
         MatrikkelBubbleObject.class,  // returner endringer for alle typer i matrikkelen
         filter,                       // begrens til endringer for en gitt kommune
         ReturnerBobler.Aldri,         // ikke returner bobleobjektene endringen gjelder for(dvs. kun endringsobjektet)
         10000);                       // returner maksimalt 10000 endring

   // Samle opp id for alle bobleobjekter som er lagt til eller oppdatert, slik at de kan hentes i ett store service kall
   for (MatrikkelEndring<?, ?> endring : endringer.getEndringList()) {
      switch (endring.getEndringstype()) {
         case Nyoppretting:
            leggesTil.add(endring.getEndretBubbleId());
            boblerForHenting.put(endring.getEndretBubbleId(), null);
            break;
         case Typeendring:
         case Oppdatering:
            oppdateres.add(endring.getEndretBubbleId());
            boblerForHenting.put(endring.getEndretBubbleId(), null);
            break;
         case Sletting:
            slettes.add(endring.getEndretBubbleId());
            leggesTil.remove(endring.getEndretBubbleId());
            oppdateres.remove(endring.getEndretBubbleId());
            break;
      }
   }

   // hent alle nye og oppdaterte bobler med store service
   for (BubbleObject bubbleObject : storeService.getObjectsIgnoreMissing(boblerForHenting.keySet())) {
      boblerForHenting.put(bubbleObject.getId(), bubbleObject);
   }
} while (!endringer.isAlleEndringerFunnet());

for (BubbleId<?> bubbleId : leggesTil) {
   BubbleObject bubbleObject = boblerForHenting.get(bubbleId);
   // legg til bubbleObject til system som skal synkroniseres
}

for (BubbleId<?> bubbleId : oppdateres) {
   BubbleObject bubbleObject = boblerForHenting.get(bubbleId);
   // oppdater bubbleObject i system som skal synkroniseres
}

for (BubbleId<?> bubbleId : slettes) {
   // slett bubbleId fra system som skal synkroniseres
}

Feilhåndtering​

Dersom det er en feil som faktisk prosesseres på tjeneren skal dette komme tilbake i responsen som en relativt fornuftig feilmelding. Noen eksempler dersom man har søkt på noe som ikke finnes:

AdresseService:
<faultcode>S:Server</faultcode>
<faultstring>Fant ingen forekomst ved søk på krets med kretsnr:359, kretstypeKode.id=4097 og kommune.id=KommuneId{value=100000301, snapshotVersion=SnapshotVersion{timestamp=CURRENT}}</faultstring>
   <detail>
       <ns3:ServiceException ...>
           <ns3:stackTraceText>no.statkart.skif.exception.FinderException: Fant ingen forekomst ved søk på krets med kretsnr:359, kretstypeKode.id=4097 og kommune.id=KommuneId{value=100000301, snapshotVersion=SnapshotVersion{timestamp=CURRENT}}

StoreService:
<faultcode>S:Server</faultcode>
<faultstring>[KommuneId{value=300712, snapshotVersion=SnapshotVersion{timestamp=CURRENT}}]</faultstring>
    <detail>
        <ns32:ServiceException ...>
            <ns32:category>:ServiceException:ApplicationException:FinderException:</ns32:category>
            <ns32:stackTraceText>no.statkart.skif.exception.ObjectNotFoundException: [KommuneId{value=300712, snapshotVersion=SnapshotVersion{timestamp=CURRENT}}]

En kjent feil er dersom man skulle fått en fornuftig feilmelding (ala det over), men man samtidig har ugyldig systemVersion får man ikke en gyldig feilmelding tilbake. Så om man får en generell feilmelding på dette formatet under kan det være lurt å sjekke at matrikkelContext-objektet er riktig satt oppt:

      <S:Fault xmlns:ns4="http://www.w3.org/2003/05/soap-envelope">
         <faultcode>S:Server</faultcode>
         <faultstring>Error mapping from no.statkart.skif.exception.FinderException to java.lang.Throwable</faultstring>
      </S:Fault>