Oppdaterings-API til Matrikkelen

Innholdsfortegnelse

1 Overordnet om matrikkeltjeneren

2 Innsyn og oppdatering via oppdateringsapi

3 Prinsipper for domenemodellen

4 Håndtering av mer komplekse matrikkeldata

5 Dokumentasjon

6 Nedlastning

7 Kort innføring i JNBProxy

1 Overordnet om matrikkeltjeneren

Matrikkelsystemet er basert på Java/J2EE teknologi og en sentral applikasjonstjener tilbyr et tjeneste-orientert grensesnitt for all aksess til systemet. Denne arkitekturen baserer seg på en tre-lags arkitektur der tjeneren håndterer forretningslogikk og innkapsler all kommunikasjon med databasene.

Matrikkeltjeneren tilbyr et tjeneste-orientert grensesnitt som alle klienter kan benytte for kommunikasjon med systemet. I begrepet tjeneste-orientert ligger følgende:

• Aksess til systemet (lesing/skriving) gjøres gjennom et grensesnitt som definerer de konkrete tjenester som systemet tilbyr. Hver enkelt tjeneste innkapsler forretningslogikk og persistering.
• Tjenestene defineres ut fra brukstilfellene som systemet skal håndtere. Det defineres konkrete tjenester som gjør spesifikke operasjoner. Tjenestene kontrollerer utvalget av operasjoner som kan utføres i systemet.

Tjenestene er hovedsaklig gruppert etter en inndeling i funksjonelle områder. Eksempel på tjenester er:

• AdresseService; uthenting og oppdatering av adresser
• BygningService; uthenting og oppdatering av bygninger og bruksenheter
• StoreService; tjeneste for uthenting av ”enkeltobjekter”, låsing og opplåsing av objekter
• IdService; generering av unike identifikatorer for tildeling til nye objekter

Alle tjenestene er implementert som Enterprise JavaBeans av typen Stateless Session Beans.

Domenemodellen er en objekt-orientert modell av datene i matrikkelen. Domenemodellen er én felles modell som benyttes av alle tjenester. Det vil si at alle tjenester hovedsaklig benytter domenemodellen for parametre og returverdier.

Eksempler på domeneobjekter i matrikkelsystemet er:

• Matrikkelenhet
• Teig
• Veg
• Adresse
• Bruksenhet
• Bygning

Alle feil som oppstår under prosessering på matrikkeltjeneren vil meldes til klienten som unntak (exception). Det finnes to hovedgrupper unntak:

• Applikasjonsfeil; feil som kan oppstå ved normal funksjon på matrikkeltjeneren. Eksempel på dette er at data er ufullstendige ved lagring eller at det gjøres et søk som ikke gir treff.
• Systemfeil; dette er feil som oppstår ved ikke-normal funksjon på tjeneren. Enten skyldes dette en programmeringsfeil (på klient eller tjener) eller en operasjonsfeil på maskinvare, nettverk eller tredjepart programvare som benyttes.

For å få adgang til matrikkeltjeneren må klienten autentisere seg med en gyldig bruker i form av brukernavn og passord. Dette skjer i forbindelse med at man

Matrikkeltjeneren vil kjøre på en plattform med lastbalansering og høy tilgjengelighet. Dette innebærer blant annet at det vil være en klynge av matrikkeltjenere som utad fungerer som en logisk tjener.

Dette kapittelet beskriver hovedprinsippene for oppkobling og bruk av tjenester i oppdateringsapi’et. Dette api’et gir tilgang til uthenting og oppdatering av alle data i Matrikkelen. Således kan det også benyttes som et innsynsapi for klienter som vil hente all informasjon om objekter i matrikkelen. Tilgang til oppdateringsfunksjoner vs. uthentingsfunksjoner vil styres av rettighetene til brukeren som er pålogget.

Distribusjon av klientkode inneholder:

• JavaDoc (HTML) av modell
• Jar-fil med nødvendige klientside klasser
• Zip-fil med avengige jar-filer
• I tillegg, som en hjelp for å komme igang med å bruke matrikkel-API’et fra .Net så har vi levert en Zip-fil som over som også inneholder dll’er for bruk fra JNBridgePro 3.0 og et Visual Studio prosjekt som kan brukes for testing.

Klientsidekoden inneholder klientsidefunksjonalitet for å håndtere slike ting som login og caching av id’er.

Klientsidekoden vår er ment som et tilbud til leverandører som skal implementere klienter til matrikkelen. Den bakenforliggende teknologien i oppdateringsAPIet er EJB'er (RMI over IIOP). Dette er kjent teknologi som leverandørene godt kan aksessere direkte hvis de heller skulle ønske det enn å benytte klientsidebiblioteket vårt.

Klientsidekoden er implementert i Java. Leverandører kan velge å enten benytte Java selv, eller bruke en såkalt .Net-Java bro for å kunne implementere i .Net. Kartverket har benyttet JNBridgePro 3.0 i sin integrasjonstesting, men andre bro-produkter skal også kunne fungere, f.eks. JIntegra Espresso eller JuggerNET.

OppdateringsAPI’et består av flere tjenester. Disse kan deles opp i hovedfunksjonalitet og støttetjenester, støttetjenester i kursiv brukes kun indirekte.

Hovedfunksjonalitet:

• AdresseService - inneholder funksjonalitet for å gjøre komplekse søk mot, oppretting, oppdatering og sletting av adresser
• BygningService - inneholder funksjonalitet for å gjøre komplekse søk mot, oppretting, oppdatering og sletting av bygninger.
• MatrikkelenhetService - inneholder funksjonalitet for å gjøre komplekse søk mot, oppretting, oppdatering og sletting av matrikkelenheter. Inneholder også funksjonalitet for å gjøre søk mot, oppretting, oppdatering og sletting av samla fast eiendom, jordskifte krevd, grunnerverv og klage.
• StoreService – benyttes for å hente ut enkeltvise domenebobler, eventuelt med låsing for oppdatering, og for å låse de opp hvis de ikke benyttes i noen oppdateringstjenester.
• SefrakMinneService – benyttes for å hente ut informasjon om SEFRAK-objekter. Merk at her er det bare metoder for uthenting. Oppdatering er foreløpig ikke implementert i oppdateringsAPIet.
• ForretningService – inneholder funksjonalitet for å gjøre søk mot og oppdatering av forretningsinformasjon til matrikkelenheter.
• PersonService – inneholder funksjonalitet for å gjøre søk mot og oppdatering av persondata. Persondata er en fellesbetegnelse på juridiske personer (enheter), fysiske personer og annen person. Juridiske personer henters fra enhetsregistret og kan ikke endres. Fysiske personer hentes fra folkeregistret og kan ikke endres. Annen person er andre personer som idag er registrert i GAB, men som ikke er blitt knyttet mot folkeregistrerte eller enhetsregistrerte data.
• TeigService – brukes for å hente ut informasjon om teiger. Denne tjenesten het tidligere GeometriService. Metoder som hørte mer hjemme andre steder har blitt flyttet og denne tjenesten har endret navn.
• GrunnforurensingService – benyttes for å søke fram og hente ut informasjon om grunnforurensinger. Merk at her er det bare metoder for uthenting.
• KulturminneService – benyttes for å søke fram og hente ut informasjon om kulturminner. Merk at her er det bare metoder for uthenting.

Støttetjenester/Infrastrukturtjenester:

• LoginService - Benyttes for å autentisere seg mot navnetjeneren til Matrikkelen. Innloggingsinformasjonen brukt her vil bli lagret slik at man ikke trenger å logge seg inn ved senere kall.
• BrukerService – Denne brukes for å hente ut brukerinformasjon
• IdService – Når man skal opprette nye domenebobler så må man ha en id. Denne tjenesten leverer ut nye id’er.
• SequenceBlockAllocatorService – brukes av IdService for å hente ut et sett med id’er, og er ikke noe man normalt trenger å forholde seg til.
• KommuneService – brukes for å hente ut kommuneinformasjon.
• KodelisteService – brukes for å hente ut kodelistene fra tjeneren. Dette gir en oversikt over hvilke kodeverdier som er tillatt for de enkelte kodene, f.eks: KontaktpersonKode, KjøkkenKode, BygningsstatusKode, osv. Denne vil returnere verdier som sier f.eks for KjøkkenKode: ('1', 'kjokken'),('2', 'ikkeKjokken'),('3','fellesKjokken'). Det er meningen at disse verdiene skal lagres lokalt.

Noen ting å merke seg angående tjenestene er:

• Matrikkeltjeneren inneholder en navnetjener (JNDI som har referanser til alle tjenestene. For å aksessere tjenester må man derfor først koble opp til navnetjeneren, inklusive pålogging til matrikkeltjeneren.
• Alle parametre/returverdier til tjenestene er verdi-objekter (”object-by-value”). Så Vegadresse-objektet er ikke en ”remote stub” men et vanlig java-objekt som sendes over til klienten, inkl. vegadressens referanser til andre objekter.
• Dersom en metode f.eks findVegadresse-metoden ikke kan finne en adresse i databasen med de gitte søkeparametre vil en FinderException kastes. FinderException er en applikasjonsfeil.
• FinderException vil kastes av metoder som returnerer én verdi, hvis en metode returnerer en Collection så vil den være tom hvis ingen verdier finnes med de aktuelle søkeparametrene.
• MatrikkelContext er en parameter som legges ved alle service-kall. Kontektsobjektet skal inneholde koordinatsystem og identifikasjon for klient som spør om informasjon. Samme MatrikkelContext objekt kan legges ved alle service-kall.

2.2.1 Tjenester for lesing av data

Alle hovedtjenestene benyttes både ved lesing og skriving av data, men man må forholde seg forskjellig til StoreService.

Bruken av Tjenestene ved lesing av data følger denne strukturen:

1. Login, dette vil validere brukernavn og passord mot JNDI tjeneren til Weblogic. Brukernavn og passord vil så lagres og brukes hver gang dere gjør et remote-kall.
2. Søkemetoder brukes for å gjøre komplekse søk eller for å returnere flere enn ett objekt.
3. Hvis man skal hente ut en bestemt domeneboble, som man har id’en til, så kan man gjøre det med StoreService, bruk Lock.NONE.
4. Alle referanser fra en domeneboble til en annen vil være myke, dvs. at de inneholder id’en til en annen domeneboble, som man så må hente ut f.eks. vha. StoreService.

Her er to enkle eksempler som leser data i hhv. Java og C#:

   public void testFindVegadresse_Success() {
   LoginService.Accessor.get().login("test1", "matrikkel");

   Kommune nittedal = KommuneService.Accessor.get().findKommune("0233");

   Vegadresse vadresse = AdresseService.Accessor.get().findVegadresse(nittedal.getId(), 4200, 13, "B");

   assertNotNull(gadresse);
   assertEquals("Feil husnr", 13, gadresse.getHusnr());
   assertEquals("Feil bokstav", "B", gadresse.getBokstav());
   }

   public void testFindVeg() {
   LoginService.Accessor.get().login("test1", "matrikkel");
   AdresseService adresseService = AdresseService.Accessor.get();

   Kommune nittedal = KommuneService.Accessor.get().findKommune("0233");
   Veg veg = adresseService.findVeg(nittedal.getId(), 4200);

   Assert.Equals("Gamle Trondheimsvei".ToUpper(), veg.getAdressenavn().ToUpper(), "Feil adressenavn");
   Assert.Equals(4200, veg.getAdressekode(), "Feil adressekode");
   }

2.2.2 Tjenester for oppdatering av matrikkeldata

Oppdatering (update, delete) fungerer noe annerledes enn lesing.

Bruken av Tjenestene ved oppdatering følger denne strukturen:

1. Login, dette vil validere brukernavn og passord mot JNDI tjeneren til Weblogic. Brukernavn og passord vil så lagres og brukes hver gang dere gjør et remote-kall.
2. Søkemetoder brukes for å gjøre komplekse søk eller for å returnere flere enn ett objekt.
3. Hvis man skal oppdatere domenebobler, så må disse hentes ut låst fra StoreService, bruk Lock.WRITE. Dette må vanligvis gjøres etter at man har søkt de frem med en av metodene i AdresseService.
4. Hvis man skal hente ut en bestemt domeneboble, som man har id’en til, så kan man gjøre det med StoreService.
5. Alle referanser fra en domeneboble til en annen vil være myke, dvs. at de inneholder id’en til en annen domeneboble, som man så må hente ut vha. StoreService.

Bruken av tjenester for oppdatering av matrikkeldata er tilsvarende som for uthenting av data. Men det er noen viktige aspekter rundt oppdatering:

• Matrikkeltjeneren baserer seg på pessimistisk låsing for samtidighetskontroll. Derfor må alle data som skal oppdateres (eller slettes) låses før kall til oppdateringstjeneste.
• Tjenester for søking etter matrikkeldata låser normalt ikke dataene. Dersom dataene skal oppdateres må låsing utføres etter søket.
• Det finnes også uthentingstjenester som låser data samtidig, for økt effektivitet og konsistens. f.eks. BygningService lockObjectsForOppdatering. Akkurat hvilke objekter disse metodene låser dokumenteres under hver metode.
• Når dere henter ut et objekt fra StoreService som låst, StoreService.get(obj, Lock.WRITE), så forblir det låst til enten objektet benyttes i en av oppdateringstjenesten (f.eks. updateVegadresse) eller til dere kjører StoreService.unlock(obj);

Her er to eksempler som oppdaterer data i hhv. Java og C#:

   public void testUpdateVegadresse() {
   LoginService.Accessor.get().login("test1", "matrikkel");
   Kommune nittedal = KommuneService.Accessor.get().findKommune("0233");

   Vegadresse vegadresse1 = AdresseService.Accessor.get().findVegadresse(nittedal.getId(), 4200, 13, "B");

   vegadresse1 = (Vegadresse) StoreService.Accessor.get().get(vegadresse1.getId(), Lock.WRITE);
   vegadresse1.setHusNr(15);
   vegadresse1.setBokstav(””);

   AdresseService.Accessor.get().updateVegadresse(vegadresse1);


   Vegadresse vegadresse2 = (Vegadresse) StoreService.Accessor.get().get(vegadresse1.getId(), Lock.NONE);

   assertNotNull(vegadresse2);
   assertEquals("Feil husnr", 15, vegadresse2.getHusnr());
   assertEquals("Feil bokstav", "", vegadresse2.getBokstav());
   }

   public void testUpdateVegadresse(){
   AdresseService adresseService = AdresseService.Accessor.get();
   StoreService storeService = StoreService.Accessor.get();

   Kommune nittedal = KommuneService.Accessor.get().findKommune("0233");
   Vegadresse vegadresse1 = adresseService.findVegadresse(nittedal.getId(), 4200, 13, "B");

   vegadresse1 = (Vegadresse) storeService.get(vegadresse1.getId(), Lock.WRITE);
   vegadresse1.setHusnr(15);
   vegadresse1.setBokstav("");

   adresseService.updateVeg(veg);

   vegadresse2 = (Vegadresse) storeService.get(vegadresse1.getId(), Lock.NONE);

   Assert.Equals(15, vegadresse2.getHusNr(), "Feil husnr");
   Assert.Equals("", vegadresse2.getBokstav(), "Feil bokstav");
   }

2.2.3 Lagring av nye matrikkelobjekter

Tjenester som lagrer nye matrikkelobjekter forutsetter at domenebobler på forhånd er tildelt en unik id. Det er kun matrikkeltjeneren som kan tildele nye unike id’er, dette gjøres gjennom en egen service (IdService).

Objekter som ligger inne i domenebobler og som dermed ikke er en subklasse av MatrikkelBubbleObject skal ikke tildeles id’er før lagring, dette gjøres automatisk av tjeneren.

Se kap. 3.2 for en nærmere forklaring på forskjellen mellom domenebobler og komponenter.

Bruken av Tjenestene må derfor følge denne strukturen:

1. Login, dette vil validere brukernavn og passord mot JNDI tjeneren til Weblogic. Brukernavn og passord vil så lagres og brukes hver gang dere gjør et remote-kall.
2. Søkemetoder brukes for å gjøre komplekse søk eller for å returnere flere enn ett objekt.
3. Hvis man skal oppdatere domenebobler, så må disse hentes ut låst fra StoreService, bruk Lock.WRITE. Dette må vanligvis gjøres etter at man har søkt de frem med en av metodene i AdresseOppdateringsService.
4. Hvis man skal hente ut en bestemt domeneboble, som man har id’en til, så kan man gjøre det med StoreService.
5. All referanser fra en domeneboble til en annen vil være myke, dvs. at de inneholder id’en til en annen domeneboble, som man så må hente ut vha. StoreService.
6. Hvis dere skal opprette nye objekter så må dere benytte IdService for å generere nye objektId’er først. Matrikkelen forventer at nye objekter er utstyrt med id’er.

Her er et eksempel som legger inn et nytt objekt:

   public void testInsertVegadresse () {

   LoginService loginService = LoginService.Accessor.get();
   KommuneService kommuneService = KommuneService.Accessor.get();
   AdresseService adresseService = AdresseService.Accessor.get();

   loginService.login("test1", "matrikkel");

   Kommune nittedal = kommuneService.findKommune("0233");
   List veger = adresseService.findVegerMedNavn(nittedal.getId(),0, "sollia");
   VegId vegId = ((Veg)veger.get(0)).getId();

   List adresser = adresseService.findAdresserForVeg(vegId);

   int gammeltAntallVeger = adresser.size();

   Vegadresse nyVegadresse = new Vegadresse();

   idService.assignId(nyVegadresse);

   nyVegadresse.setHusnr(14);
   nyVegadresse.setVegId(vegId);

   Representasjonspunkt rep = new Representasjonspunkt(CoordinateSystem.EUREF_SONE33, 6656515.30, 273344.60, 0.00);
   nyVegadresse.setRepresentasjonspunkt(rep);

   adresseService.insertVegadresse(nyVegadresse);

   adresser = adresseService.findAdresserForVeg(vegId);


   assertEquals("Vegen skulle fått lagt inn en vegadresse til", (gammeltAntallVeger + 1), adresser.size());
   }

2.2.3 Litt om låsing

Når man skal gjøre oppdateringer i systemet så må man som vist over låse objektene som skal oppdateres først. Systemet fungerer slik at for hver transaksjonell update tjeneste som fullfører med suksess så låses alle låsene til den brukeren opp. Dette innebærer at hvis man ønsker å gjøre flere oppdateringer rett etter hverandre så må man låse de nødvendige objektene på nytt mellom hver oppdatering.

Det er også slik at systemet kun låser opp objekter ved en vellykket opdpatering. Hvis en feil oppstår under et update-kall så vil låsene som brukeren hadde før update-kallet begynte fremdeles være låst etter at kallet har feilet. Hvis brukeren avbryter operasjonen eller et kall feiler så er det opp til klientprogrammet å håndtere dette korrekt. Det vil f.eks. være opp til programmet å sørge for å kalle StoreService.unlock() for å låse opp de låste objektene.

Domenemodellen inneholder representasjon av alle dataene i matrikkelsystemet. Matrikkelsystemet baserer seg på en objekt-orientert modell der data og forretninglogikk er innkapslet. Domenemodellen kan beskrives fra to forskjellige synsvinkler:

• Analysemodellen beskriver domenemodellen fra et analysesynspunkt. Denne modellen viser de viktigste objekter i domenet og hvordan disse er relatert til hverandre. Matrikkelens analysemodell finnes her.
• Designmodellen beskriver domenemodellen slik den er programmert i systemet.

Dersom analysemodellen ble direkte overført til en designmodell ville dette gitt en domenemodell der mer eller mindre hele domenemodellen hang sammen med harde referanser (pekere). Dette gir en del utfordringer i forhold til kommunikasjon mellom klient og tjener:

• Hvordan håndtere at forskjellige tjenester ønsker å arbeide med forskjellige utsnitt av domenemodellen?

Den ene tjenesten skal f.eks. bare skal oppdatere en adresse, mens en annen skal oppdatere både adresser og dens tilhørende bruksenheter/bygninger. En tjeneste skal oppdatere adresser på en matrikkelenhet, mens en annen skal oppdatere matrikkelenheten og dens teiger.

• Hvordan håndtere delte objekter?

Et enkelt objekt kan være referert til fra mange andre objekter. Eksempelvis kan en vegadresse være referert til fra både en veg, en bruksenhet og en matrikkelenhet. På klienten ønsker vi ikke multiple instanser av delte objekter. Spesielt vil dette lett kunne forekomme ved uthenting av data gjennom en serie av kall til matrikkeltjeneren.

• Hvordan definere hvilke objekter som må låses som en helhet?

Skal kun matrikkelenhet låses dersom teiggrensene skal justeres? Hva med delte grenser mellom eiendommer? Må også adresser tilknyttet matrikkelenheten låses?

• Hvordan skal ”lazy loading” håndteres på klienten? Ofte vil det være behov for å laste data referert til fra tidligere uthentede data over på klienten. Men trenger her strategier for hvor mye som skal lastes og hvordan referanser til ikke-lastede data skal håndteres.

Matrikkelsystemet løser disse utfordringene med en designmodell som deler analysemodellen opp i veldefinerte domenebobler. En domeneboble består av en samling assosierte domeneobjekter som behandles som en enhet med hensyn til uthenting og oppdatering. Alle objektene inni en domeneboble refererer til hverandre ved hjelp av harde referanser (pekere et programmeringsspråk).

Alle objektene i domeneboblen eies av et rot-objekt. Dette har en id som er en global id for hele boblen. Objekter utenfor domeneboblen kan bare refereres gjennom rot-objektet til dens domeneboble. Referanser til objekter utenfor domeneboblen implementeres da som myke referanser (referansen er da id’en for rot-objektet i den andre domeneboblen).

Regler for domenebobler

En del regler gjelder for bruk av domenebobler:

• En samling assosierte domeneobjekter samles i en domeneboble.
• Ett domeneobjekt er rot-objekt i domeneboblen, denne har en global Id. Denne id’en er en system-generert verdi. Rot-objektets Id kan brukes for uthenting av en domeneboble, og selvsagt med søk basert på relevante søkekriterier.
• Et vilkårlig objekt i en boble kan referere til andre bobler ved deres Id. Det er ikke tillat å holde referanser til andre objekter utenfor boblen.
• Ingen objekter utenfor en boble kan ha ”varige” referanser” til noen objekt inni boblen (inkl. rot). Det kan dog finnes temporære referanser til objekter inni boble (f.eks. fra GUI-komponent til verdien som vises)
• Livssyklusen til objektene inni en boble er styrt av livssyklusen til rot-entiteten.
• Objekter inni en domeneboble, utenom id-referanser til andre bobler, kalles komponenter.

Domenebobler tilsvarer Eric Evans begrep Aggregate [Evans].

Eksempler på domenebobler

I designmodellen vil for eksempel Matrikkelenhet være rot-objekt for en domeneboble. Referanser til andre domeneobjekter gjøres ved at objekter i boblen har referanser til id'en til rot-entiteten i de respektive bobler. Dette ser vi i eksempelet under ved at relasjonen til kommune gjøres ved referanse til KommuneId.

Domeneboble for Matrikkelenhet:

Domeneboble for Adresse:

Domeneboble for Bygg:

Hvilke domenebobler som finnes kan sees i analysemodellen.

For enkelte deler av domenemodellen vil det være naturlig at tjenestene arbeider med mange domenebobler. For eksempel gjelder dette matrikkelenheter og geometri for disse. I slike tilfeller kan det være nødvendig med oversendelse av en større mengde domenebobler til/fra en tjeneste.

En tjeneste for å lagre en matrikkelenhet med oppdatert geometri trenger både bobler av typen Matrikkelenhet, Teig, Teiggrense og CurveSegment. For å håndtere slike tilfeller brukes en UnitOfWorkTransfer. Dette er et objekt brukt for overføring av data over nettverket. Egne UnitOfWorkTransfer defineres for de enkelte tjenester. Egenskapene til en UnitOfWorkTransfer er:

• Inneholder alle domenebobler som logisk hører sammen i en oppdatert og som skal oppdateres i en transaksjon. Alle boblen lagres i en hash-tabell med boblens id som nøkkel.
• Har informasjon om hvilke bobler som er nye, oppdaterte og som skal slettes.
• Holder på id’ene til hovedboblene i oppdateringen. For eksempel kan en FradelingUnitOfWorkTransfer holde på id for opprinnelig matrikkelenhet samt id for den nye grunneiendom.

Tjenester for uthenting vil også kunne defines til å returnere flere domenebobler. For eksempel av ytelseshensyn (færre runder over nettverket) eller for å sikre konsistent låsing. Siden en tjeneste bare kan ha en returverdi må dette gjøres gjennom et eget objekt som holder på alle boblene. Til dette bruk har man en BubbleTransfer, egenskapene til denne er:

• Inneholder en hash-tabell med alle boblene som skal overføres samtidig.
• Holder på id for hovedboblen(e) som overføres. For eksempel kan en MatrikkelenhetBubbleTransfer ha en egen referanse for matrikkelenhetens id.

For dokumentasjon av domeneboblene i oppdateringsmodellen så har vi lagt inn en referanse til kjernemodell dokumentasjonen. Dvs. at for alle klasser som er med i en domeneboble vil det bare være en referanse videre til dokumentasjonen av denne klassen i kjernen.

For tjenestene så vil alle metodene være dokumentert. Hvilke klasser som kan/skal være med i et transfer-objekt (UnitOfWorkTransfer eller BubbleTransfer) er beskrevet under den enkelte metode med referanser til klassene i kjernemodellen.

Det er ikke egne UML diagrammer for oppdateringsapi, da datamodellen er basert på den underliggende domenemodellen for matrikkelen.
UML diagrammer for domenemodellen finnes her, og detaljert tekstlig dokumentasjon finnes her.

Her kan dere laste ned nødvendig programvare:

Zip fil som inneholder .jar-filer som trengs for å bygge .dll vha JNBridgePro og Visual Studio 2005 prosjekt med eksempel-kode

Zip-filen inneholder alle nødvendige filer både for en ren Java oppkobling og for en .NET til Java oppkobling via JNBridgePro (v. 3.2). For .NET må det manuelt genereres en Proxy.dll for mapping av .NET til Java via JNBridgePro, og man må ha en korrekt oppsatt App.config for prosjektet for at classpath som JNBridgePro bruker skal bli riktig. Endelig må man ha installert JNBridgePro med gyldig lisens, se JNBridgePro. Zip-filen inneholder 2 nødvendige filer fra JNBridgePro v. 3.2: JNBSharedMem.dll, JNBShared.dll. Dersom en annen versjon av JNBridge benyttes bør disse erstattes med tilsvarende versjoner i henhold til JNBridgePro dokumentasjonen.

7 Kort innføring i JNBProxy fra JNBridgePro

JNBProxy brukes for å generere en .Net dll fra jar-filene som følger med Zip-filen over. Det er to fremgangsmåter for å generere en dll fil med proxyer:

• Ved hjelp av GUI-verktøyet til JNBridge (7.1a)
• Ved hjelp av ProxyGen.bat som kjører kommandolinjeverktøyet til JNBridge (ProxyGen.bat følger med i Zip-filen over) (7.1b)

• Start enten JNBProxy proxy generation tool (.NET 1.x-targeted) eller JNBProxy proxy generation tool (.NET 2.0-targeted) avhengig av hvilken versjon av .Net-rammeverket du ønsker dll'en til.
• Dersom verktøyet startes for første gang, må du velge såkalte Java Options:
  
  Velg Shared memory og angi de nødvendige dll-er og jar-filer.
• Velg 'create new .Net > Java project'
• Velg 'edit classpath' ikonet:
• 'Add' alle jar-filene fra zip-filen.
• Ifølge JNBridgePro users guide^[1], må du nå lagre prosjektet, f.eks. som v3-proxy-<versjon>.jnb i samme katalog som jar-filene og dll'ene.
  Avslutt JNBridgePro og start programmet på nytt, åpne det lagrede prosjektet igjen.
• Velg 'add classes from jar-file' ikonet:
• Velg filene oppdateringapi_v3-client-<versjon>.jar og matrikkelspif-extapi-<versjon>.jar, OK.
• Velg edit -> Check all in environment
• Velg 'add classes from classpath' ikonet:
• Skriv inn java.util.HashSet, Add, OK.
• Gå inn i java.util pakken i tre-viewet og merk HashSet-klassen.
• Velg Add+
• Velg 'Build' ikonet:
  Den nye dll'en kan med fordel kalles v3-proxy-<versjon>.dll og legges i prosjektroten sammen med de andre dll'ene.
• Du vil få beskjed om at du trenger EE lisens for å generere noen klasser. Dette kan ignoreres.
• Nå skal du ha en fungererende dll som kan legges inn i visual studio.

• Pakk ut Zip-filen over til en mappe (f.eks c:\dotnettest\)
• pakk ut den underliggende Zip-filen til samme mappe (da vil classpath i både .Net prosjektet og ProxyGen.bat bli korrekt)
• Rediger ProxyGen.bat og legg inn stier som samsvarer med installasjonen av JNBridge
• Kjør kommandoen ProxyGen.bat @VERSION@ ProxyOppdateringsAPIv@VERSION@ oppdateringapi_v3-client-@VERSION@.jar matrikkelspif-extapi-@VERSION@.jar
• Nå skal du ha en fungererende dll som kan legges inn i visual studio

7.2 Redigering av .Net-prosjekt

Når du bruker den genererte dll-en i et .Net-prosjekt må du sette opp konfigurasjon for JNBProxy i en applikasjonskonfigurasjonsfil (app.config), som beskrevet i JNBridgePro users guide i kapittelet Configuring the .NET side:

   <dotNetToJavaConfig scheme=”sharedmem”
                       jvm=”full path to jvm.dll in JDK or JRE”
                       jnbcore=”full path to jnbcore.jar”
                       bcel=”full path to bcel-5.1-jnbridge.jar”
                       classpath=”semicolon-separated Java classpath”/>

7.3 Bruk av backupserver med JNBridge og Visual Studio

For å kunne koble opp mot en backupserver så må filen matrikkel_klient.properties endres til å inneholde korrekt ip-nummer og port. Dette kan gjøres ved å legge inn en egen matrikkel_klient.properties fil i classpathen til JNBridge. Man kan enten oppdatere filen som ligger i oppdateringapi_v3-client-<versjon>.jar eller legge en ny fil i f.eks rotkatalogen som er inneholdt i classpathen. Det er da viktig at denne katalogen står først i classpathen. Det er også mulig å sette oppkoblingsserver og port programmatisk. Se src.test\SimpleTestClient.cs for eksempel på hvordan dette gjøres.

Fotnoter