Tietokantasovellus- dokumentointiohje

1. 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.

2. YLEISKUVA JÄRJESTELMÄSTÄ

• Sidosryhmäkaavio

  Sidosryhmäkaavio näyttää järjestelmän sidosryhmät ja niiden yhteydet järjestelmään. Tällä kurssilla 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ärjestelmä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.

3. 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ä vaiheessa 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 yksityiskohtia sisältäviä kuvauksia. Käyttötapausten läpivienti käyttöliittymän avulla kuvataan käyttöliittymän hahmottelun yhteydessä myöhemmin.

Käyttötapausten avulla määritellään, 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 havainnollistaaksesi 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.

4. JÄRJESTELMÄN TIETOSISÄLTÖ

Järjestelmän tietosisältö kuvataan käsitekaavion avulla.  Kaavio voidaan laatia jollakin piirrosohjelmalla tai erityisellä tällaisten kaavioiden laadintaan tarkoitetulla työkalulla. Laitoksen Windows perusasennuksesta löytyy kaavioiden tekoon Plastic Lite ja Dia. Linux-ympäristöstä löytyy Dia ja Umbrello.

Esimerkki käsitekaaviosta (tehty Poseidon -ohjelmalla (community edition on vapaasti ladattavissa osoitteesta: http://gentleware.com/downloadcenter.0.html)



Kuva 2: Esimerkki käsitekaaviosta.

Kaavion lisäksi täytyy kuhunkin tietokohteeseen liittää selitys, jossa määritellään kyseinen kohde. Attribuutitkin täytyy määritellä ellei merkitys ole nimen perusteella itsestään selvä. Jos attribuutilla on koodiarvoja tai rajattu arvojoukko, on arvojen merkitys myös selitettävä. Myös yhteydet täytyy määritellä. Alla on esimerkkinä yhden tietokohteen määrittely.

• Esimerkki tietokohteen kuvauksesta:   Tietokohde: varustelukuvaus

  Attribuutti	Arvojoukko	Kuvailu
  Laatimisaika	aikaleima	milloin laadittu, tunnistava yhteys
  yleiskuvailu	pitkä teksti	vapaamuotoista tekstiä

  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. Varustelukuvaus kytkeytyy laatijaan. Edelleen varustelukuvaukseen liittyy joukko varuste-esittelyjä.

Jos haluat varmistua siitä, että tietosisältömallisi ja käyttötapauksesi sopivat yhteen ja mallit ovat kattavia voit laatia riippuvuusmatriisin kuvaamaan tietokohteiden käsittelyä käyttötapauksissa. Riippuvuusmatriisin sarakkeina ovat kohdetyypit ja yhteydet. Riveinä ovat käyttötapaukset. Kuhunkin sarakkeeseen merkitään, mitä käyttötapauksessa tehdään ko. luokan kohteille (C=create, R=read, D=delete, U=update). Jokaisen käyttötapauksen täytyy käsitellä jotain kohdetta. Tietokohteelle täytyy mahdollistaa riittävät käsittelyoperaatiot käyttötapausten kautta.

5. 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

Luonnoksia käyttöliittymästä voi tehdä jollakin piirrosohjelmalla. Tekstinkäsittelyjärjestelmät piirrostoiminnot riittävät yleensä hahmotelman laatimiseen. Joistakin näytöistä ja raporteista riittää sanallinen hahmotelma. Taustakuvia ja vastaavia hienouksia ei tässä vaiheessa ole tarpeen esitellä.

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



Kuva 3: Käyttöliittymän sivujen väliset yhteydet (tehty Plastic Lite:lla)

.

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äkomponentteja, voi riippuvuuksia kuvata matriiseina.
 

6. 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 muutettu 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. Alla on esimerkki kaaviokuvasta. Kuvassa nuolet lähtevät viiteavain sarakkeen kohdalta, pk= primary key, fk= foreign key. Tämäkin kuva on tehty Plastic Lite:llä. Muita mainittuja työkaluja voi samoin käyttää monipuolisesti eri tarkoituksiin.



Kuva 4: Relaatiotietokantakaavio kuvana.

Muunnossäännöt käsitemallista relaatiomalliin löytyvät Tietokantojen perusteet kurssin materiaalista.

 

 

---

Toteutusdokumentti

Toteutusdokumentissa kuvataan aikaansaatu ohjelmisto.

1. JOHDANTO

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

 

2. 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
• ohjelmat, joita käytetään sivujen tuottamiseen tai lomakkeiden käsittelyyn. Servlet-toteutuksessa ohjelmat jakautuvat servletteihin ja apuluokkiin.
Kokonaisuuden kuvaamiseksi esitetään kaavio, josta näkyy, miten komponentit liittyvät toisiinsa. Kaaviossa esitetään
• liikkuminen sivujen välillä ja
• sivujen generointi ohjelmissa.
Jos ohjelmiston käyttöliittymä hyödyntää kehyksiä (frame), on kuvattava millaisia riippuvuuksia kehysten sisällöillä on.

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




Kuva 5: 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 6 on esimerkki rakennekaaviosta.



Kuva 6: 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.

3. JÄRJESTELMÄN KOMPONENTIT

Kaikkien komponenttien kohdalta esitetään:

• komponentin nimi
• komponentin tarkoitus
• komponentin tyyppi
Komponentit voidaan esitellä esim. ryhmiteltyinä html-sivuihin, servletteihin ja apuluokkiin. Lisäksi voi omana osionaan luetella sovelluksessa käytettävät kuva-, ääni- yms. tiedostot.

HTML-sivujen osalta kuvataan

• lyhyt luonnehdinta sivun sisällöstä
• mitä tiedostoja sivuun sisältyy
• mitä linkkejä tai lomakkeita sivulle sisältyy ja
• mitä ohjelmia sivulta käynnistetään ja miten (linkki vai lomakkeenkäsittelijä)
• jos sivuun liittyy Javascriptillä tehtäviä tarkistuksia, nämä mainitaan.
 

HTML-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ä ohjelma generoi sen.

Esimerkkejä sivukuvauksista

   aloitussivu

      Staattinen html-sivu, tiedosto: index.html, kuva sivusta liitteenä k1.

      Sivuun liittyvät tiedostot:
         back123.gif :  taustakuva,
         button223.gif: luettelomerkki
         logo_big.jpg:  yrityksen isompilogo

      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ää servletin Yleiskuva. Servletille ei välitetä parametreja.


   tunnussivu       

      Staattinen html-sivu, tiedosto: tunnus.html, kuva sivusta 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 sevletti  Kayttooikeus. 


   yleiskuva tarjonnasta

      Generoitu html-sivu, jonka tuottaa srvletti Yleiskuva,
      kuva sivusta suunnitteludokumentissa (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 erikokoisten 
      huoneistojen lukumääristä.

Ohjelmien (servlettien ja apuluokkien)  kohdalta esitetään
• tarkoitus
• parametrit
• toiminnan yleispiirteet
• ohjelman suorittamat tietokantaoperaatiot
• mitä erityistä ohjelmaan liittyen tulisi huomioida
• käytettävät apuluokat ja -palvelut

Selitysten tarkoituksena on auttaa ohjelmakoodin lukemista. Ohjelmakoodiin on syytä liittää kommentteja ja käyttää havainnollisia muuttujanimiä. Ohjelmaan liittyvät yleistiedot voi kirjoittaa myös ohjelmakoodin alkuun yleiskommentiksi, jolloin ne vain kerätään ohjelmakoodista dokumenttiin. 

   Ohjelmakoodit sijoitetaan dokumentin liitteiksi.

Esimerkkejä ohjelmakuvauksista

 

   Yleiskuva servletti

        Servletti generoi sivun 'yleiskuva tarjonnasta'.
        Käynnistetään 'aloitussivun' linkistä.
        Käynnistyksen yhteydessä ei välitetä parametreja.

        Kyselyllä 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 viimeksi käsitellyn paikkakunnan nimi 
        (kaupungin ja alueen yhdiste) 

   

    Kayttooikeus servletti
        Servletti 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'.

        Servletti käynnistetään tunnussivulta käsittelemään kirjoittautuminen- 
        lomaketta.

        Servletin parametrit
           asiakastunnus: merkkijono
           salasana: merkkijono    
       

        Kyselyn 'asiakaskysely' avulla haetaan taulusta asiakas tiedot asiakkaasta,
        jolla on parametrina annettu asiakastunnus ja salasana. Jos asiakastunnus oli tyhjä
        tai asiakastietoja ei löytynyt, generoidaan sivu 'virheellinen tunnus'.
        Jos asiakas löytyi, perustetaan uusi istunto. Istuntokontrolli hoidetaan
        HttpSession-olioiden avulla. Asiakastunnus taltioidaan HttpSession olioon.

4. 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. Apuluokkien muodostamat pakkaukset pitää esitellä. Servlettien sijoittelu riippuu servlettiympäristöstä, joten sitä ei tarvitse määritellä.

5. 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  pitäisi itsessään 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. Muista kertoa ohjaajalle mahdolliset testaustunnukset ja salasanat.

6. LIITTEET

Dokumentin liitteinä annetaan

• tehtäväkuvaus
• suunnitteludokumentti (korjattuna, jos alkuperäisessä oli puutteita)
• tietokannan määrittelevät create table lauseet, jos ne eivät ole mukana dokumentin tekstiosuudessa tai suunnitteludokumentissa
• ohjelmakoodit

---

Päivitetty 15.1.2006. Harri Laine