Tik-76.115 Tekninen suunnitelma

Synapsi: Automaattinen ohjelmiston etäpäivitys
NetSeal Technologies
Tietojenkäsittelyn ohjelmatyö Tik-76.115

SISÄLLYSLUETTELO

0. VERSIOHISTORIA

1. JOHDANTO

1.1 Tarkoitus ja kattavuus

1.2 Tuote ja ympäristö

1.3 Määritelmät, merkintätavat ja lyhenteet

1.4 Yleiskatsaus dokumenttiin

2. JÄRJESTELMÄN YLEISKUVAUS

2.1 Sovellusalueen kuvaus

2.2 Järjestelmän liittyminen ympäristöönsä

2.3 Laitteistoympäristö(n kuvaus)

2.4 Ohjelmistoympäristö(n kuvaus)

3. ARKKITEHTUURIN KUVAUS

3.1 Ratkaisun suunnitteluperiaatteet

3.2 Tietokanta-arkkitehtuuri

3.2.1 Yleiskuvaus

3.2.2 Neuroni palvelin

3.2.3 Neuroni asiakas

3.3 Ohjelmistoarkkitehtuuri, moduulit ja prosessit

3.3.1 PUP protokolla

3.3.2 Neuroni palvelin

3.3.3 Neuroni asiakas

4. MODUULI (JA PROSESSI) KUVAUKSET

4.1 Yleistä

4.2 Moduulikuvaukset

4.2.1 synapsi.data

4.2.2 synapsi.gui

4.2.3 synapsi.updateThread

4.2.4 synapsi.main

4.2.5 synapsi.connect

4.2.6 NCMain

4.2.7 NCStates

4.2.8 NCGUi

4.2.9 NCConnect

4.2.10 NCData

4.2.11 NCError

4.2.12 NCUtil

5. MUUT ERITYISET TEKNISET RATKAISUT

6. HYLÄTYT RATKAISVAIHTOEHDOT

7. VIRHEKÄSITTELY

Viitteet

1. JOHDANTO

1.1 Tarkoitus ja kattavuus

Dokumentti sisältää projektin lopputuotteen teknisen kuvauksen sisältäen tuotteen käyttöympäristön kuvauksen, järjestelmän arkkitehtuurin ja toiminnallisuuden kuvauksen sekä yleisellä tasolla että yksittäisten ohjelmamoduulien tasolla ja käytetyn ohjelmistoarkkitehtuurin kuvauksen. Varsinainen lopputuote - Neuroni-ohjelmisto - tullaan toteuttamaan dokumentissa kuvattujen ratkaisujen pohjalta. Tämä dokumentti siis määrittelee sen, miten projektin toiminnallisessa määrittelyssä kuvattu ohjelmistotuote tullaan varsinaisesti toteuttamaan.

Dokumentti käsittelee koko Neuroni-ohjelmiston toteutuksen kuvauksen yleisestä arkkitehtuurista aina moduuli- ja luokkatasolle asti.
 

1.2 Tuote ja ympäristö

Ohjelmiston tarkoituksena on se, että RoamMate-server voi clientin tullessa sen alueelle päivittää RoamMate:n moduuleita eli esim. vaihtaa koneessa oleva NetSeal-ajuri uudempaan tms. Järjestelmän tavoitteena on saada automaitsoitua kyseinen toimenpide mahdollisimman pitkälle ja näin helpottaa clientin ohjelmiston päivitystä.

Projektin tuote tulee perustumaan client-server -mallille. RoamMate Serverin päässä tullaan määrittelemään päivitettävät ohjelmakomponentit. Nämä komponentit päivittyvät ja tulevat automaattisesti käyttöön Mobile Unitin päässä. MU-ohjelmistosta tullaan tekemään toimiva versio Windows NT:lle. RS-versio tulee toimimaan JRE:n päällä.

1.3 Määritelmät, merkintätavat ja lyhenteet

1.4 Yleiskatsaus dokumenttiin

Ensimmäisessä luvussa käydään läpi asioita, jotka helpottavat ko. dokumentin lukemista ja ymmärtämistä kuten selitetään käytetyt termit sekä annetaan viitteet muihin dokumentteihin, jotka liittyvät tähän tekniseen määrittelyyn.

Toisessa luvussa käsitellään toteutettavaa Neuroni-ohjelmistoa korkealla tasolla ja käsitellään sen toteuttamisen vaikuttavat rajoitukset ja reunaehdot. Luvussa kuvataan myös ohjelmiston tuleva käyttö- ja toteutusympäristö. Luvun tarkoituksena on antaa yleiskuva tuotteen toteutukselle asetetuista rajoituksista ja tavoitteista.

Kolmannessa luvussa siirrytään toteutettavan ohjelmiston arkkitehtuurin kuvaukseen ja kuvataan korkealla tasolla ohjelmiston rakenne sekä komponentit. Luku sisältää myös ohjelmiston käyttämän tiedonsiirtoprotokolla (PUP) kuvauksen. Tämän osion luettuaan lukijalla pitäisi olla hyvä yleisen tason käsitys ohjelmiston toiminnasta.

Neljäs luku menee syvemmälle ohjelmiston toteutukseen - siinä kuvataan tarkasti ohjelmistossa käytetyt ohjelmamoduulit, niiden väliset rajapinnat sekä kuvataan moduulien toteutus. Luvussa käsitellään ohjelmiston yksityiskohtainen toiminta ja toteutus.

Luvussa viisi paneudutaan sellaisiin ohjelmiston toteutuksen ratkaisumalleihin, joista on tarvetta erikseen mainita niiden erityisen elegantin toteutuksen vuoksi. Luvussa kuusi taas summataan hylättyjä ratkaisumalleja - tämän luvun perusteella voidaan myöhemmin tarkastella, miksi jokin ratkaisuvaihtoehto hylättiin, jolloin ei jouduta enää uudelleen miettimään samoja asioita. Viimeinen luku kertoo ohjelmistossa käytettävän virheenkäsittelyn toiminnasta ja periaatteista.

2. JÄRJESTELMÄN YLEISKUVAUS

2.1 Sovellusalueen kuvaus

2.2 Järjestelmän liittyminen ympäristöönsä

2.3 Laitteistoympäristö

Client-kone:

• 486-prosessori 66 Mhz nopeudella
• 32 megatavua RAM-muistia.
• kiintolevytilaa 30 megatavua ennen kuin mitään Neuroni-ohjelmiston osia tai testausosia on asennettu.
• Ethernet-verkkokortti.

• 586-prosessori 166 Mhz nopeudella
• 64 megatavua RAM-muistia
• kiintolevytilaa 60 megatavua ennen JRE:n asennusta
• kiintolevytilaa 30 megatavua ennen kuin mitään Neuroni-ohjelmiston osia tai testausosia on asennettu.
• Ethernet-verkkokortti.

2.4 Ohjelmistoympäristö

• Windows NT4 + sp6
• RoamMate Client -ohjelma
>li>Ethernet-verkkoyhteys

• Windows NT4 + sp6
• JRE 1.2 tai uudempi
• RoamMate Server -ohjelma
• Ethernet-verkkoyhteys

3. ARKKITEHTUURIN KUVAUS

3.1 Ratkaisun suunnitteluperiaatteet

Ohjelmistoarkkitehtuuri on korkeimmalla tasolla asiakas-palvelin -malli, mutta yhden fyysisen yksikön (eli koneen) sisällä perinteinen yksi suorituskelpoinen ohjelma. Palvelimen toteutuksessa hyödynnetään Javan säikeitä toteutettaessa useamman asiakkaan yhtäaikainen päivittäminen.
Asiakkaan ja palvelimen välinen työnjako: Asiakas kuuntelee palvelimen ehdotuksia ja vastaa niihin. Lisäksi se hoitaa asiakaskoneen ohjelmiston varsinaisen päivityksen, joka sisältää ohjelmiston asennusohjelman käynnistyksen ja Windowsin rekisterin päivitystä ja lukemista. Asiakas tarjoaa RMC:n käyttäjälle mahdollisuuden päättää päivityksen aloituksesta. Palvelin pitää kirjaa saatavilla olevista ohjelmistoversioista ja tarjoaa ylläpidolle käyttöliittymän asiakkaiden versiotietojen ja palvelimella olevien ohjelmistoversioiden hallintaan. Palvelimen tehtävä on ehdottaa sen alueelle saapuville asiakkaille päivitystä ja lähettää päivityspaketteja. Lisäksi sen on osattava pitää kirjaa asiakkaiden versiotiedoista.

GUI:n suunnittelussa painopiste on palvelimen toteutuksessa, koska asiakkaan GUI tulee olemaan melko yksinkertainen. Käyttöliittymäsekä asiakaspäässä että palvelimessa on graafinen. Palvelimessa teteutus on suoraan Java1.2.2 kirjastoilla ja asiakkaan päässä MFC-kirjastolla.

Tietojen tallennus toteutetaan palvelimessa Java-luokkina, jotka serialisoidaan levylle/levyltä; varsinaista tietokantaa ei ole. Asiakaspäässäkään ei ole tietokantaa, vaan ainoastaan muutama rekisteriin talletettu arvo. Kaikki muu data on ajonaikaista ohjelman sisäisesti tarvitsemaan informaatiota.

Moduulijaossa pyritään noudattamaan periaatetta, että jaetaan ongelma riittävän pieniksi osiksi, mutta ei yhtään pienemmiksi. Neuroni-palvelimen moduulijako on, ja yleensäkin suunnittelun tarkkuus on, huomattavasti tärkeämpi kuin Neuroni-asiakkaan tapauksessa, ja siksi siihen tullaan kiinnittämään paljon enemmän huomiota. Palvelimessa moduulijako on myös helpompi toteuttaa järkevästi, koska valittu ohjelmointikieli tukee sitä paremmin.

Ohjelmointikieleksi valittiin palvelimen toteutuksessa Java. Asiakaspää toteutus tehdään mahdollisuuksien mukaan ANSI-C:llä. C++ -kieltä/kirjastoja tullaan käyttämään, mutta varotaan käyttämästä kielen erityisominaisuuksia ja muitakin vaikeasti siirrettäviä ominaisuuksia. Yksinkertaisuus ja siirrettävyys ovat tässä yhteydessä toivimuuden lisäksi tärkeimpiä ominaisuuksia.
 

3.2 Tietokanta-arkkitehtuuri

3.2.1 Yleiskuvaus

3.2.2 Neuroni palvelin

Yllä olevassa UML-kaaviossa selviää dataluokkien keskinäiset suhteet. Myös luokat identifioiva tieto näkyy kuvassa. DataSettings-luokalla ei luonnollisesti ole identifioivaa tietoa, koska luokan ilmentymiä on vain yksi. DataMain säilyttää viittauksia DataClient-, DataGroup- ja DataVersion-instansseihin Javan tarjoamissa vektori-luokissa. Mikäli tietojen hakeminen vektorien avulla osoittautuu jatkossa pullonkaulaksi, voidaan ne korvata jollain tehokkaammalla menetelmällä esim. hajautustaululla, binääripuulla. Tietojen tallentaminen ja lukeminen levyltä suoritetaan Java-kielen tarjoamalla serialisointi- ja deserialisointirutiineilla.

3.2.3 Neuroni asiakas

3.3 Ohjelmistoarkkitehtuuri, moduulit ja prosessit

3.3.1 PUP protokolla

PUP protokolla toimii lähettämällä ASCII-muotoisia rivinvaihtoon (0x0a) päättyviä komentoja. Komentojen parametrit erotetaan toisistaan ja komentojen nimistä välilyönneillä. Neuronin palvelinpää aloittaa aina protokolla-ajon, eikä palvelinpään tarvitse siis jatkuvasti kuunnella, mitä asiakkaalla on sanottavaa, vaan se voi lähettää viestin ja odottaa vastausta (tai aikakatkaisua). Asiakaspää sen sijaan on velvollinen kuuntelemaan jatkuvasti palvelimen yhteysyrityksiä ja jatkamaan protokolla-ajon jälkeenkin kuuntelua.

Neuroni asiakkaan PUP-protokollan tilakaavio on esitetty kohdassa 3.3.3Neuroni asiakas.

Protokollan viestit ryhmiteltyinä käyttöajankohdan- ja tarkoituksen mukaan:

• Kättely
• Sanoma: NSHELLO x.xx
Sanoma on serverin kättely, jossa x.xx on serverin versio. Vastaukseksi odotetaan NCHELLO-sanomaa, jonka versiosta voidaan päätellä onko protokolla yhteensopiva.

Sanoma: NCHELLO x.xx


Sanoma on clientin kättelysanoma, jossa x.xx on clientin versio. Tämä sanoma annetaan vastauksena serverin NSHELLO-sanomaan.

Version kysely
• Sanoma: GETVERSION
Tällä sanomalla serveri pyytää clienttiä ilmoittamaan Roammate-versionsa. Client vastaa VERSION-sanomalla.

Sanoma: VERSION x.xx


Tällä sanomalla client vastaa serverin versio kyselyyn ilmoittamalla versionsa kohdassa x.xx.

Päivityksen hyväksyntä
• Sanoma: UPDATE x.xx
Tällä sanomalla serveri kysyy haluaako client päivityksen versioon x.xx. Vastauksena clientilta saadaan joko YES- tai NO-sanoma.

Sanoma: YES


Tällä sanomalla client ilmoittaa haluavansa päivityksen.

Sanoma: NO


Tällä sanomalla client ilmoittaa, että päivitystä ei haluta ottaa vastaan. Tämä on myös implisiittinen DISCONNECT molemmilta osapuolilta ja yhteys voidaan katkaista.

Päivitypaketin siirto
• Sanoma: PACKAGE filename length checksum
Päivityspaketin siirto poikkeaa muista sanomista siinä, että sanoman jälkeen lähetetään paketti binääridatana. Client lukee filename-kentästä serverin antaman päivityspaketin tiedostonimen. Client lukee viestin jälkeen length-kentän ilmoittaman määrän tavuja ja laskee näistä tarkistussumma, jonka pitäisi vastata checksum-kentän arvoa. Rajoitus: koska kentät erotetaan toisistaan välilyönneillä, ei filename-kentässä välitettävä tiedostonimi saa sisältää välilyöntejä. Checksum-kenttä kertoo siirrettävästä tiedostosta lasketun md5 tiivisteen. Kentässä on 32 merkkiä jotka tulkitaan 128 bittisen luvun heksadesimaaliesitykseksi. Tämä on täsmälleen sama esitys kuin on käytössä esim. md5sum -ohjelman tulosteessa ja md5sum -ohjelman ja Neuronin laskemat tarkistussummat mille tahansa tiedostolle on oltava samat.

Sanoma: PACKAGEOK


Client vastaa tällä sanomalla vastaanottaneensa päivityspaketin onnistuneesti.

Sanoma: PACKAGEBROKEN


Client vastaa tällä sanomalla, mikäli pakettia ei saatu kokonaisuudessaan luettua tai tarkistussumma ei vastaa ilmoitettua. Server voi nyt vastata joko DISCONNECT jos katsoo parhaaksi luovuttaa tai UPDATE, jos yritetään uudestaan.

• Yhteyden katkaisu
• Sanoma: DISCONNECT
Yhteyttä katkaistaessa ensin server lähettää tämän sanoman ja tämän jälkeen client vastaa samalla sanomalla.

Protokollan viestikaavio:

3.3.2 Neuroni palvelin

• NSMain:

Välittää viestejä muiden moduulien välillä eli on nimensä mukaisesti päätyöjuhta. Moduuli käynnistää uudet päivitys-threadit ja pitää kirjaa päivitystä odottavista asiakkaista.
 
• NSGUI:

Neuroni-palvelimen graafinen käyttöliittymä. Tarjoaa palvelimen ylläpitäjälle toiminnot RMC-ohjelmistojen automaattista päivitystä varten. NSGUI ajetaan omassa säikeessään ja se kommunikoi NSMainin ja NSDatan kanssa aina kun käyttäjä haluaa saada jonkin toiminnon suoritetuksi.
 
• NSData:

Palvelinpään tietopankki. Sisältää Java-luokat kaiken palvelimella säilytettävän tiedon tallennukseen. Tarjoaa palvelut NSMain:lle ja NSGUI:lle tiedon nopeaan ja luotettavaan hakuun ja tallennukseen. Tietojen tallennus fyysisesti hoidetaan serialisoimalla NSDatan Java-luokkahierarkia levylle.
 
• NSUpdateThread:

Luokka jonka tehtävänä on käsitellä yhden asiakkaan päivitys. Tästä moduulista luodaan yksi instanssi asiakasta kohden. Updaten tehtävänä on tarkistaa asiakkaan versio, päivittää versiotieto NSMain kautta NSDataa:n ja tarvittaessa ehdottaa asiakkaalle päivityksen aloittamista sekä hoitaa mahdollinen päivitys alusta loppuun.
 
• NSPUP:

PUP-protokollan totetutus on integroitu NSUpdateThread-luokkaan. Protokolla on toteutettu tilakoneella, joka vie päivityksen läpi lähettämällä komentoja asiakkaalle.
 
• NSConnection:

Yhteyden muodostamiseen ja ylläpitoon, kuten myös viestien lähettämiseen ja vastaanottamiseen tarvittavat rutiinit ja data.
Moduulin tarkoituksena on piilottaa TCP:n suora käyttö NSPUP:lta ja tarjota NSPUP:lle hyvin yksinkertainen rajapinta yhteyden luomiseen ja katkaisemiseen, viestien lähettämiseen ja yhteyden kuunteluun (so. viestien vastaanottoon).

3.3.3 Neuroni asiakas

• NCMain:

Tähän moduuliin kuuluu kaikki muu kuin alla kuvattu asiakaspään toiminnallisuus. Pääasiallinen tehtävä on käynnistää asiakaspää ja kutsua muiden NC:n moduulien funktioita NC:n toiminnallisuuden toteuttamiseksi. NC:n päivityslogiikka on moduulissa NCStates.
 
• NCStates:

Tärkeimpänä PUP -protokollan implementaatio asiakaspäässä. Sisältää tilakoneen, jossa NC viettää kaiken aikansa yhteyden kuuntelun aloittamisesta yhteyden katkaisuun.
 
• NCGUI:

Sisältää kaksi erillistä käyttöliittymää. Toisessa käyttöliittymässä on yksi check box, jolla käyttäjä voi määrätä, haluaako hän ylipäätään päivityksiä. Jos käyttäjä on valinnut, että hän haluaa päivityksiä, niin asiakkaan tullessa palvelimen, jolla olisi päivitys kyseistä asiakasta varten, käyttöliittymä kysyy, päivitetäänkö.
 
• NCData:

Sisältää Windowsin rekisterin käsittelyn. Rutiinit rekisteriarvojen lukuun ja talletukseen. Tarjoaa NCMainille  rajapinnan, jolla voidaan suoraan kysyä ja tallettaa versionumeroita sekä mahd. suoraan vertailla niitä. Lisäksi metodit asennuspaketin kirjoittamiseen levylle, sekä mahdollisesti asennuksen käynnistämiseen tarvittavat funktiokutsut.
 
• NCConnection:

Tarjoaa samat palvelut kuin NSConnection, mutta hiukan eri rajapinnalla koska toteutus on modulaarinen, mutta ei oliopohjainen. Tässä pyritään taas kerran parempaan siirrettävyyteen ja siksi on valittu C++:n sijasta ANSI-C.
(Ks. NSConnection)
 
• NCUtil:

Sekalaisia apufunktioita mm. viestien tyyppien lukemiseen ja kirjoittamiseen sekä konversioita ja tarkistussumman laskenta.
 
• NCError:

Rutiini(t) NC:n virheenkäsittelyyn ja lokimerkintöjen tekemiseen/tulostamiseen.

Neuroni asiakkaan PUP-protokollan mukainen tilakaavio:

4. MODUULI- JA PROSESSIKUVAUKSET

---

4.1 Yleistä

Oheisessa kappaleessa on kuvattu Neuroni-ohjelmiston moduulien yksityiskohtaiset kuvaukset sisältäen yleiskuvaukset, toteutukseN sekä virheiden käsittelyn. Tämän lisäksi kustakin moduulista joka on toteutettu Java-kielellä, on konstruoitu JavaDoc-työkalun avulla ohjelmakooditiedostoissa olevista kommenteistä kyseisen moduulin rajapinnat kuvaava HTML-sivusto. Näin ollen moduulien rajapintoja ei ole tässä dokumentissa varsinaisesti käsitelty vaan se on löydettävissä kunkin moduulin kohdalta linkin takana olevalta JavaDoc-sivustolta. C/C++ -kielellä toteutetuista mooduleista on vastaavasti rajapintojen kuvaukset toteutettu generoimalla kooditiedostoista Doc++ -työkalulla HTML-sivusto.

Kuten projektisuunnitelmassa on määritelty, ohjelmoinnissa käytettävä kielenä on englanti. Ohjelmakoodin yhtenäisen ulkoasun takaamiseksi koodin kommentit on kirjoitettu myös englanninkielellä. Tämän vuoksi generoidut JavaDoc- ja Doc++ -dokumentit ovat myös englanninkielisiä. Näiden rajapintakuvausten kääntämistä edelleen suomeksi ei ole katsottu tarpeelliseksi projektin puitteissa.
 

4.2 Moduulikuvaukset

Tässä kappaleessa on kuvattu asiakkaan ja palvelimen moduulien toiminta.
 

4.2.1 synapsi.data

4.2.1.1 Yleinen kuvaus

4.2.1.2 Rajapinta

4.2.1.3 Virhekäsittely

Moduuli myös tarkistaa levyltä lukemansa tietojen eheyden Javan deserialisointi rutiinien lisäksi MD5-tiivisteen avulla. Mikäli levyltä yritetään lukea virheellistä dataa, kieltäytyy moduuli tästä ja käynnistyy kuten ensimmäisellä käyttökerralla, jolloin mitään tallennettua dataa ei luonnollisestikaan ollut. Käyttäjälle pyritään luonnollisesti tekemään virheilmoitus korruptoituneesta levydatasta moduulin synapsi.gui avulla.

Muihin virhetilanteisiin ei ole toistaiseksi varauduttu. Virhetilanteet raportoidaan muun "erityisraportoinnin" lisäksi niiden vakavuuden mukaisesti synapsi.Log luokalle kuten luvussa 7 on kuvattu.
 

4.2.2 synapsi.gui

4.2.2.1 Yleinen kuvaus

Moduuli kommunikoi muiden moduulien kanssa synapsi.main-moduulin välityksellä, joka toimii ikään kuin viestin välittäjänä moduulien välillä. Tyypillisessä tilanteessa synapsi.gui käyttää synapsi.datan palveluja main-moduulin välityksellä esim. hakiessaan tietyn asiakasryhmän tietoja ohjelmiston tietokannasta.
 

4.2.2.2 Rajapinta

4.2.2.3 Toteutus

Ikkunoiden kuvaamisluokat on toteutaan käyttäen Java Swingin tarjoamia standardikomponentteja, widgettejä, kuten nappulat, menut ja tekstikentät. Luodut ikkunatyypit (luokat) perivät joko JFrame-luokan (pääikkuna ja help-ikkuna) tai JDialog-luokan (muut ikkunat). Tällä järjestelyllä voidaan kätevästi toteuttaa se, että toteutuksessa vain päällimmäinen ikkuna on ainoastaan aktiivisena. Poikkeuksena tähän on help-ikkuna, joka voi olla aktiivisena samaan aikaan jonkin muun ikkunan kanssa.

Ikkunassa tapahtuvien tapahtumien (nappuloiden painallukset yms.) vastaanotto ja käsittely tapahtuu kyseisen ikkunaluokan metodilla (actionPerformed) eli ikkunaluokat toteuttavat myös ActionListener-rajapinnan. Tällaisella rakenteella tapahtumien käsittely on helppo hajauttaa omiin luokkiinsa ja moduulin rakenne pysyy näin selkeänä.
 

4.2.2.4 Virhekäsittely

Mikäli käyttäjä yrittää suorittaa toimenpiteen, joka aiheuttaa virhetilanteen (esim. sellaiset ohjelmistoversion poisto, joka on vielä jonkin ryhmän käytössä), annetaan käyttäjälle virheilmoitus ja pyydetty toiminto jätetään suorittamatta. Käyttäjän antama syöte siis aina tarkistetaan ennen halutun operaation suorittamista.
 

4.2.3 synapsi.net.UpdateThread

4.2.3.1 Yleiskuvaus

4.2.3.2 Rajapinta

4.2.3.3 Toteutus

4.2.3.4 Virheenkäsittely

4.2.4 synapsi.main

4.2.5 synapsi.Connection

4.2.5.1 Yleiskuvaus

4.2.5.2 Rajapinta

4.2.5.3 Toteutus

4.2.5.4 Virheenkäsittely

4.2.6 Moduuli NCMain

4.2.6.1 Yleiskuvaus

4.2.6.2 Rajapinta

4.2.6.3 Toteutus

4.2.6.4 Virhekäsittely

4.2.7 Moduuli NCStates

4.2.7.1 Yleiskuvaus

4.2.7.2 Rajapinta

4.2.7.3 Toteutus

4.2.7.4 Virhekäsittely

Virhetilanteet joihin on varauduttu ja vastaava virheen vakavuustaso sekä virheilmoituksen teksti:
 

warning, "Unexpected message or timeout.".

warning, "Garbled message."

warning, "Cannot read update packet.".

warning, "Receiving update packet failed."

warning, "Packet exeeds maxsimum lenght."

error, "Cannot allocate memory".

Koska tämä moduuli ei voi aiheuttaa fataaleja virheitä (NC_error_hanleriä ei kutsuta tasolla FATAL), kaikkien virhetilanteiden jälkeen päivitetään epäonnistuneiden määrän kertovaa globaalia muuttujaa ja palataan kutsuvaan funktioon ilman suurempia seremonioita.

4.2.8 Moduuli NCGUI

4.2.8.1 Yleiskuvaus

4.2.8.4 Virhekäsittely

4.2.9 Moduuli NCConnect

4.2.9.1 Yleiskuvaus

4.2.9.2 Rajapinta

4.2.9.3 Toteutus

4.2.9.4 Virhekäsittely

Virhetilanteet joihin on varauduttu ja vastaava virheen vakavuustaso, virheilmoituksen teksti sekä mahdollinen toimenpide:
 

warning, "Reading from invalid socket".
Suljetaan yhteys serveriin.

warning, "Incomplete message string".
Suljetaan yhteys serveriin.

fatal, "WinSock 2 not available."
Ilmoitetaan käyttäjälle alustuksen epäonnistumisesta.
(koska fatal, NC poistuu takavasemmalle samantien)

error, "Cannot allocate memory".

error, "Cannot open socket".

error, "Error listening to socket"

warning, "Error accepting connection".

warning, "Tryiing to send when not connected."

warning, "Sending with an unknown message type".

warning, "Sending to socket failed"
Suljetaan yhteys serveriin.

4.2.10 Moduuli NCData

4.2.10.1 Yleiskuvaus

4.2.11 Moduuli NCError

4.2.11.1 Yleiskuvaus

4.2.11.2 Rajapinta

4.2.11.3 Toteutus

4.2.11.4 Virhekäsittely

Virhetilanteet joihin on varauduttu:
 

Palautetaan kutsuvalle funktiolle negatiivinen paluuarvo.

Kirjoittetaan lokiin virheellisen parametrin arvon kohdalle <UNKNOWN>.

Kirjoitetaan lokiin tyhjä merkkijono.

Kirjoitetaan mitä sattuu lokiin, kunnes '\0' -merkki löytyy muistista.

4.2.12 Moduuli NCUtil

4.2.12.1 Yleiskuvaus

4.2.12.2 Rajapinta

4.2.12.3 Toteutus

4.2.12.4 Virhekäsittely

5. MUUT ERITYISET TEKNISET RATKAISUT

Muita erityisiä teknisiä ratkaisuja ei ole tässä vaiheessa tullut esille eikä suunniteltu toteutettaviksi.

6. HYLÄTYT RATKAISUVAIHTOEHDOT

Ei toistaiseksi hylättyjä ratkaisuvaihtoehtoja.

7. VIRHEKÄSITTELY

Yleinen virheenkäsittely

Virheilmoitusten tekeminen

Testaustarkoituksia varten on jokaisen moduuliin kuitenkin hyvä määrittää soveltuva print-metodi/funktio, jonka avulla päästään helposti selvyyteen moduulin sen hetkisestä tilasta esim. tietorakenteiden sisällöt ja muut oleelliset datat. Tämän oman print-metodin kutsuminen on kuitenkin kielletty muualta kuin testikoodista.

Palvelimen päässä virheilmoitukset tulee antaa synapsi.Log luokalle. Clientin päässä vastaavia tehtäviä hoitaa funktio nc_handle_error() tiedostossa "nc_error_win32.c".

Virheilmoitusta tehdessä tulee virheen raportoijan ilmoittaa pakkaus, luokka ja metodi, missä virhe syntyi. Tämän lisäksi tulee ilmoittaa virheen vakavuus, sekä oma selventävä vapaamuotoinen kommentti virhetapauksesta. Esim. palvelimen Log-luokan dokumentoinnista voi katsoa aihetta tarkemmin.

Virheilmoitukset tulostetaan tällä hetkellä suoraan konsoliruudulle. Jatkossa on tarkoitus, että virheilmoitukset menevät sopivaan tiedostoon levylle, mistä niitä on helppo jälkikäteen arvioida. Virheet voidaan myös laittaa omiin tiedostoihinsa virhetyyppien perusteella.

Virheet luokitellaan neljään ryhmään:

• Log - Ei virheilmoitus. Tämän tyypin virheillä on mahdollisuus raportoida ohjelman oikeasta etenemisestä koodissa. Esim. onnistuneen protokollan mukaisen kommunikoinnin loppumisesta voidaan ilmoittaa tällä viestillä.
• Minor - Pieni virhe. Tämän ei pitäisi aiheuttaa jatkossa mitään ongelmia. Esim. parametrien tai paluuarvon tarkastuksessa löytynyt "virheellinen" data voidaan raportoida tällä virhetyypillä.
• Major - Iso virhe. Aiheuttaa luultavasti jonkinlaisen virheellisen tapahtuman ohjelmassa. Esim. omasta tietorakenteesta löytynyt väärän tyyppinen luokka, jota kyseinen koodi ei osaa käsitellä.
• Fatal - Katastrofi. Aiheuttaa ohjelman täydellisen jumiutumisen tai kaatumisen. Esim. ikuinen silmukka tai dead lock ohjelman kannalta tärkeässä säikeessä.

Toiminta epänormaaleissa tilanteissa

Verkkoyhteyden katkeaminen - Palvelin ilmoittaa käyttäjälle yhteyden katkeamisesta, mutta muuten ohjelman suoritus jatkuu normaalisti. Client ilmoitta yhteyden katkeamisesta ainoastaan, mikäli se oli juuri lataamassa uutta päivitystiedostoa.

Viitteet