Tietokantasovellusten harjoitustyö - dokumentointiohje

Harri Laine - 13.1.1998 (pienehköjä muutoksia 5.4.2000)

Harjoitustyössä määritellään, suunnitellaan ja toteutetaan pieni www-alustalle toteutettava tietojärjestelmä. Työn tuloksena syntyy kaksi dokumenttia sekä joukko ohjelmatiedostoja. Seuraavassa on hahmoteltu dokumenttien sisältö. Ohjeessa ei ole mukana sellaisia itsestäänselvyyksiä kuin kansilehti ja sisällysluettelo.

Suunnitteludokumentti

Tämän dokumentin tarkoituksena on määritellä laadittava sovellus. Dokumentin perusteella työn ohjaaja pystyy ottamaan kantaa työn sisältöön ja rajaamaan työtä. Dokumentin laatimisessa tarvittavia tekniikoita on käsitelty Johdatus sovellussuunnitteluun - kurssin monisteessa.

JOHDANTO

Järjestelmän tarkoitus

Tiivis kuvaus siitä mistä on kyse.
Millaisen toiminnan tukemiseen järjestelmä on tarkoitettu.
Mitkä ovat järjestelmän tavoitteet.
Nämä tiedot saa yleensä tehtäväkuvauksesta.

Toimintaympäristö

Missä laite ja ohjelmistoympäristössä järjestelmän on tarkoitus toimia.

Rajaukset

Mahdolliset rajaukset koskien määrittelyn, suunnittelun ja toteutuksen laajuutta.

Toteutusympäristö

Missä ympäristössä työ toteutetaan.

YLEISKUVA JÄRJESTELMÄSTÄ

Sidosryhmäkaavio

Sidosryhmäkaavio näyttää järjestelmän sidosryhmät ja niiden yhteydet järjestelmään. Tällä kursilla kehitettävissä järjestelmissä sidosryhminä ovat enimmäkseen järjestelmän käyttäjäryhmät. Käyttäjäryhmien ja järjestelmän välisinä yhteyksinä kuvataan tällöin järjetelmän käyttötapaukset karkealla tasolla. Käyttötapaukset ovat järjestelmän käyttäjilleen tarjoamia palveluita. Käyttäjäryhmät voidaan esittää vapaamuotoisina symboleina. Käyttäjäryhmien ja järjestelmän väliset viivat esittävät käyttötapauksia. Viivojen päähän voidaan laittaa nuolenkärki osoittamaan palvelun tarjoajaan (eli yleensä järjestelmään - vain tapauksessa, jossa sidosryhmänä on toinen järjestelmä, jonka palveluja käytetään hyväksi, osoittaa nuoli tuohon toiseen järjestelmään).

Sekä käyttötapaukset että käyttäjäryhmät kuvataan erikseen tekstinä. Alla esimerkki:

Kuva:1: Esimerkki kaaviosta (kaavio laadittu Power Point:lla)

Käyttäjäryhmät

Määritellään sidosryhmäkaaviossa esiintyvät käyttäjät

Esimerkki

Jokamies

Jokamiehellä tarkoitetaan ketä tahansa, joka Internetin välityksellä tulee lukemaan KatonAlle yhtiön www-sivuja. Kaikki seuraavat luokat kuuluvat myös jokamies luokkaan.

Asiakas

Asiakas on rekisteröitynyt käyttäjä.

Vuokranantaja

Vuokranantaja on rekisteröitynyt henkilö, joka on antanut asunnon KatonAlle yhtiölle välitettäväksi.

Työntekijä

Työntekijä on KatonAlle yhtiön palveluksessa oleva henkilö.

Johto

Johdolla tarkoitetaan työntekijöitä, joiden tehtävänä on tehtävien anto ja asioista päättäminen.

Käyttötapaukset

Käyttötapauksella tarkoitetaan järjestelmän avulla hoidettavaa tavoitteellista tehtäväkokonaisuutta, esimerkiksi tilauksen kirjaus, tilauksen peruutus, asiakkaan kirjaus, asiakkaan poistaminen, laskun tulostus, kuukausiyhteenvedon laatiminen ovat tehtäväkokonaisuuksia, joita on luonnollista mallintaa käyttötapauksina. Kustakin käyttötapauksesta kuvataan sen sisältö: mitä käyttötapauksessa tehdään. Raporttien kohdalta kerrotaan, mitä tietoja raporttiin sisältyy. Tässä vaihessa ei vielä ratkaista sitä, miten käyttötapaus viedään teknisesti läpi, millainen ulkoasu näytöllä on ja mitä näppäimiä painetaan. Jotain yleisiä periaatteita näistäkin voi toki kertoa. Tarkoituksena on, että suunnittelu etenee karkeammalta tasolta kohti yhä enemmän ykstyiskohtia sisältäviä kuvauksia. Käytötapausten läpivienti käyttöliittymän avulla kuvataan käyttöliittymän hahmottelun yhteydessä myöhemmin.

Käyttötapausten avulla määritellään järjestelmän toiminnallisuus eli, mitä järjestelmällä tehdään. Voit luonnostella käyttötapauksia esimerkkitapausten avulla. Esimerkkitapauksessa toiminnan kohde on kiinnitetty, esimerkiksi 'ilmoittautuminen Informaatiojärjestelmät kurssin harjoitusryhmään 3' on esimerkkitapaus käyttötapauksesta 'luentokurssille ilmoittautuminen'. Voit esittää esimerkkitapauksia myös dokumentissa havainollistaaksesi käyttötapauksia. Käyttötapaukset voi esittää tärkeysjärjestyksessä, aakkosjärjestyksessä tai käyttäjittäin ryhmiteltyinä. Seuraavassa esimerkissä on kuvattu kenelle tahansa tarkoitetut käyttötapaukset asunnonvuokrausjärjestelmässä.

Esimerkki:

Jokamiehen käyttötapaukset

Yritysinfon lukeminen

Kuka tahansa voi käydä lukemassa yrityksen mainos- ja yleistietoja mm. työntekijöiden puhelinnumerot ja toimistojen sijainnit.

Asuntotilanteen yleiskuvan selvittäminen

Käyttäjälle näytetään, minkä tyyppisiä asuntoja kullakin alueella kyselyn suoritushetkellä on tarjolla vuokralle ja kuinka monta näitä on tarjolla.

Esimerkki: Millaisia asuntoja on tarjolla Kruunuhaassa?

Rekisteröityminen asiakkaaksi

Rekisteröitymisessä käyttäjä ilmoittautuu yrityksen asiakkaaksi päästen näin yrityksen muiden asiakaspalveluiden käyttäjäksi ja asiakastiedotteiden saajaksi. Jokamiehestä tulee asiakas. Hän antaa henkilötietonsa ja saa asiakastunnuksen, joka on avain asiakkaille tarkoitettuihin palveluihin. Prototyypissä asiakastunnus aktivoituu heti. Aktivoinnin voisi kytkeä myös rekisteröintimaksun maksamiseen.

KÄYTTÖLIITTYMÄN HAHMOTELMA

Käyttöliittymän hahmotelmassa luonnostellaan järjestelmän käyttöliittymä toteutettavaksi ajatellussa laajuudessa. Hahmotelmaan voi kuulua luonnoksia raporttien ja näyttöjen ulkoasusta sekä näihin liittyviä selityksiä. Erityisen tärkeää on luoda kokonaiskuva käyttöliittymästä.

miten käyttötapaukset suhtautuvat näyttöihin ja raportteihin
miten tietyn käyttötapauksen yhteydessä toimitaan
miten näyttöjen välillä liikutaan
miten raportit kytkeytyvät näyttöihin

Näyttöjen välisiä yhteyksiä on luontevaa esittää kaavioina. Kuvassa 2 on esimerkki tällaisesta kaaviosta.

.
Kuva 2: Käyttöliittymän sivujen väliset yhteydet.

Käyttötapausten ja käyttöliittymäkomponenttien välisiä yhteyksiä voi selittää tekstimuodossa. Jos useat käyttötapaukset käyttävät yhteisiä käyttöliittymäkomponentteja tai käyttötapauksen yhteydessä tarvitaan monia käyttöliittymäkomponetteja, voi riippuvuuksia kuvata matriiseina.

JÄRJESTELMÄN TIETOSISÄLTÖ

Järjestelmän tietosisältö kuvataan käsitemallin alulla. Mallin laatimisessa voi käyttää joko perinteistä käsitekaaviotekniikkaa (YYY tai ER) tai oliomallinnusta. Kaavio voidaan laatia jollakin piirrosohjelmalla tai erityisellä tällaisten kaavioiden laadintaan tarkoitetulla työkalulla. Laitoksella on käytössä erityistyökaluna Windows ympäristössä toimiva Plastic Lite ja Rational Rose Student edition sekä Nokian tutkimuskeskuksen saatu Mermaid ohjelma. Näillä saa UML-tekniikan mukaisia kaavioita (Plasticilla vain luokkakaavioita).

Samppa Saarelan ohjeita tietosisällön määrittelystä

Kaavion lisäksi täytyy kuhunkin luokkaan (tai yksilötyypiin) liittää selitys, jossa määritellään kyseinen käsite. Attribuutitkin täytyy määritellä ellei merkitys ole nimen perusteella itsestäänselvä. Jos attribuutilla on koodiarvoja tai rajattu arvojoukko on arvojen merkitys myös selitettävä. Myös yhteydet täytyy määritellä. Alla esimerkkinä yhden luokan määrittely.

Esimerkki luokan kuvauksesta:

Luokka: varustelukuvaus ydintyyppi

Ominaisuus               Arvojoukko              Kuvailu
------------------------+-----------------------+----------------
jääkaappi                merkki                  pakoll.
pakastin                 merkki                  pakoll.
astianpesukone           merkki                  pakoll.
liesituuletin            merkki                  pakoll.
lasitettu_parveke        merkki                  pakoll.
kylpyamme                merkki                  pakoll.
parketti                 merkki                  pakoll.
sauna                    merkki                  pakoll.
muuta                    doku
laadittu                 paivays                 tunniste

Jokaiseen huoneistoon voi liittyä monta varustelukuvausta, joista vain viimeisin on voimassa. Varustelukuvaus laaditaan huoneiston arvioinnin yhteydessä. Varustelukuvaus identifioidaan huoneiston ja laatimisajan perusteella. Ensimmäinen varustelukuvaus perustuu huoneiston omistajan ilmoitukseen. Varustelukuvaus kuvaa huoneiston kunnon ja varustelun. Yleisimmille varusteille on varattu oma attribuutti, jonka arvona on 'k' jos varuste on tarjolla, muulloin arvona on 'e'. Varsinainen kuntokuvaus on pitkässä vapaamuotoisessa tekstikentässä muuta. Attribuutti laadittu ilmaisee kuvauksen laatimisajan.

Jos haluat varmistua siitä, että käsite-/oliomallisi ja käyttötapauksesi sopivat yhteen ja mallit ovat kattavia voit laatia riippuvuusmatriisin kuvaamaan olioiden käsittelyä käyttötapauksissa. Riippuvuusmatriisin sarakkeina ovat olioluokat ja yhteydet. Riveinä ovat käyttötapaukset. Kuhunkin sarakkeeseen merkitään, mitä käyttötapauksessa tehdään ko. luokan olioille (C=create, R=read, D=delete, U=update). Jokaisen käyttötapauksen täytyy käsitellä jotain luokkia. Luokan olioille täytyy mahdollistaa riittävät käsittelyoperaatiot käyttötapausten kautta.

RELAATIOTIETOKANTAKAAVIO

Relaatiotietokantakaavio esitetään SQL:n create table lauseina. Kaavioon täytyy sisältyä taulujen välisten viiteyhteyksien ja avainten määritykset. Kaaviota voi havainnollistaa myös esittämällä taulujen väliset viiteriippuvuudet kuvana, mutta tämä ei ole pienen tietokannan osalta välttämätöntä. Jos relaatiokaaviossa on attribuutteja, jotka eivät esiinny käsitemallissa tai jonkin käsitemallin attribuutti on karsittu tai sen muotoa on muutetettu on tästä erikseen mainittava. Yleissääntönä on, että relaatiotietokantakaavion tulee olla yhteensopiva käsitemallin kanssa.

Teknisesti tämän kohdan voi toteuttaa sisällyttämällä varsinaiseen dokumenttitekstiin vain taulujen nimet, sekä lyhyen selityksen taulujen tarkoituksesta. Create table -lauseet voi antaa liitteenä.

Voit liittää tähän yhteyteen myös kuvan, josta käy esiin taulujen rakenne ja taulujen väliset viiteavaimet.

Toteutusdokumentti

Toteutusdokumentissa kuvataan aikaansaatu ohjelmisto.

JOHDANTO

Johdannon sisältö on pitkälti sama kuin määrittely- ja suunnitteludokumentissa. Rajaukset osassa esitetään lisärajaukset määrittely- ja suunnitteludokumenttiin nähden, esimerkiksi mitä osia ei ole toteutettu. Rajauksista pitää sopia ryhmän ohjaajan kanssa etukäteen.

OHJELMISTON YLEISRAKENNE

Ohjelmiston yleisrakenteessa kuvataan, mistä komponenteista ohjelmisto koostuu. WWW-alustaisissa sovelluksissa komponentteja ovat:

HTML-sivut (käsintehdyt tai proseduurien generoimat),
kuvat yms. erillistiedostot ja
tietokantaproseduurit

liikkuminen sivujen välillä ja
sivujen generointi proseduurissa.

Yleisrakenteen kuvaamiseksi voidaan käyttää esimerkiksi kaaviotekniikkaa, jossa on symbolit manuaalisia html-sivuja, generoituja sivuja ja proseduureja varten (kuva 3).

Kuva 3: rakennekaavion symbolit.

Symboleja yhdistetään nuolilla, jotka kuvaavat siirtymiä sivujen välillä tai sivun tuottamista proseduurissa. Siirtymää kuvaavaan nuoleen on syytä liittää tieto siirtymän aiheuttajasta, linkistä tai lomakkeen lähetysnapista. Kuvassa 4 on esimerkki rakennekaaviosta.

Kuva 4: Esimerkki rakennekaaviosta (laadittu MSWord:llä)

Kustakin komponentista laaditaan erillinen kuvaus, jossa esitetään komponentin ymmärtämisen kannalta oleelliset asiat. Kuvaus on suunnattu henkilölle, joka mahdollisesti joskus joutuisi ylläpitämään ohjelmistoa.

JäRJESTELMäN KOMPONENTIT

Kaikkien komponenttien kohdalta esitetään:

komponentin nimi
komponentin tarkoitus
komponentin tyyppi

HTML-sivujen osalta kuvataan

lyhyt luonnehdinta sivun sisällöstä
mitä tiedostoja sivuun sisältyy
mitä linkkejä tai lomakkeita sivulle sisältyy ja
mitä proseduureja sivulta käynnistetään ja miten
jos sivuun liittyy Javascriptillä tehtäviä tarkistuksia nämä mainitaan..

Lomakkeisiin liittyvien kenttien osalta kerrotaan, mitä kenttiä lomakkeeseen sisältyy. Jos arvoihin liittyy jotain erityisvaatimuksia, nämä kerrotaan. Piilokentät ja niiden käyttötarkoitus on syytä esittää. Jos sivu on konkreettinen HTML-tiedosto, kerrotaan, missä tämä tiedosto sijaitsee. Jos sivu on generoitu kerrotaan, mikä proseduuri generoi sen.

Esimerkkejä sivukuvauksista

   aloitussivu

      Käsintehty html-sivu, tiedosto: index.html, kuva liittenä k1.
      
      Sivuun liittyvät tiedostot:
         back123.gif :  taustakuva,
         button223.gif: luettelomerkki
         logo_big.jpg:  yrityksen isompi logo
     
      Sivulla on lyhyt yleisesite järjestelmästä sekä linkit,
      joiden avulla pääsee käsiksi järjestelmän tarjoamiin palveluihin:
       
         asiakastunnus 
             johtaa sisäänkirjoittautumiseen käytettävälle 
             tunnussivulle (tunnus.html)
         rekisteröidyn 
             johtaa uuden asiakkaan tietoja kyselevälle
             rekisteröintisivulle (rekisteroi.html)
         yritystiedot 
             johtaa yritysinfo-sivulle (katonalle.html)
         yleiskuva 
             käynnistää proseduurin yleiskuva, ei parametreja


   tunnussivu       

      Käsintehty html-sivu, tiedosto: tunnus.html, kuva liitteenä k2.

      Sivuun liittyvät kuvatiedostot:
         back123.gif :   taustakuva,
         logo_small.jpg: yrityksen pienempi logo

      Sivulla on lomake, jossa annetaan asiakastunnus 
      ja salasana.
      Isoja ja pieniä kirjaimia ei tulkita samoiksi.
      Lomakkeen käsittelee proseduuri kayttooikeus. 


   yleiskuva tarjonnasta

      Generoitu html-sivu, jonka tuottaa proseduuri yleiskuva,
      kuva: määrittelydokumentti (kuva 9).
  
      Sivuun liittyvät kuvatiedostot:
         back123.gif :   taustakuva,
         logo_small.jpg: yrityksen pienempi logo
  
      Sivu sisältää paikkakunnittain jaoteltuna taulukoita 
      kyseisellä paikkakunnalla tarjolla olevien eri kokoisisten 
      huoneistojen lukumääristä.

Proseduurien

tarkoitus
parametrit
toiminnan yleispiirteet
kursoreiden tarkoitus ja riippuvuus parametreista
mitä erityistä proseduuriin liittyen tulisi huomioida
kutsuttavat omat proseduurit

Proseduurien ohjelmakoodit sijoitetaan dokumentin liitteiksi.

Esimerkkejä proseduurien kuvauksista

     yleiskuva

        Generoi sivun yleiskuva tarjonnasta.
        Käynnistetään aloitussivulta.
        Ei parametreja.

        Kursorilla huoneet haetaan taulusta asunto 
        kaupunki-, alue- ja huoneistotyyppikohtaisesti tarjolla olevien 
        huoneistojen lukumäärät.

        Vastausrivit käydään läpi ja kaupungin tai alueen vaihtuessa
        aloitetaan taulukko, johon sijoitetaan huoneistotyyppi 
        ja kyseisen tyyppisten huoneistojen lukumäärä. Paikkakunnan
        vaihtumisen testaamiseen käytetään muuttujaa edellinen, 
        jonka arvona on viimeeksi käsitellyn paikkakunnan nimi 
        (kaupungin ja alueen yhdiste) 


    kayttooikeus

        Tarkastaa asiakkaan käyttöoikeuden. Jos asiakkaalla on käyttöoikeus
        generoidaan sivu asiakaspalvelut. Jos asiakkaalla ei ole 
        käyttöoikeutta generoidaan sivu virheellinen tunnus.

        Proseduuri käynnistetään tunnussivulta käsittelemään 
        lomaketta.

        Parametrit:
           asiakastunnus: merkkijono
           salasana: merkkijono    

       
        Kursorin as avulla haetaan taulusta asiakas tiedot asiakkaasta,
        jolla on parametrina annettu asiakastunnus ja salasana. Jos 
        asiakastietoja ei löydy generoidaan sivu virheellinen tunnus.
        Jos asiakas löytyi, haetaan istunnolle istuntonumero laskurista
        session_seq. Istuntonumero viedään asiakas-tauluun ja liitetään 
        parametriksi kaikkiin generoitavalle asiakaspalvelut sivulle
        sijoitettaviin linkkeihin.

ASENNUSTIEDOT

Asennustietoina kerrotaan, miten järjestelmän tiedostot sijoittuvat hakemistoihin. Kaikki tiedostot voivat olla samassa hakemistossa tai jakautua useaan eri hakemistoon. Ohjeen tarkoituksena on toisaalta kertoa miten sovellus on nyt asennettu ja toisaalta miten sen saisi asennettua uuteen ympäristöön.

KäYNNISTYS- / KäYTTöOHJE

Perusoletuksena on, että järjestelmän käyttäjä osaa käsitellä www-sivuja selaimella. Tähän liittyviä ohjeita ei siten tarvitse antaa. www-sovelluksen tulisi olla helppokäyttöinen ja intuitiivinen. Sivujen itsessään pitäisi sisältää riittävästi sivun käyttöön tarvittavaa informaatiota. Jos sivut ovat tällaisia riittää antaa ohjelman käynnistykseen tarvittava URL. Jos käyttöön liittyy joitain yleisiä toimintajärjestykseen liittyviä asioita ne voidaan kertoa tässä yhteydessä. Näiden tietojen tulisi löytyä myös tuotettavan järjestelmän sivuilta.

LIITTEET

Dokumentin liitteina annetaan

tehtäväkuvaus
korjattu määrittely ja suunnitteludokumentti
tietokannan määrittelevät create table lauseet, jos ne eivät ole mukana dokumentin tekstiosuudessa tai määrittelydokumentissa
ohjelmakoodit proseduureista

Harri Laine