Kokako - projekti
Sovellussuunnitelma
Honkonen Tapio
Lamminen Turo
Räsänen Tuomas
Väärämäki Tapio
Versio 0.9
Julkinen
22. toukokuuta 2006
Jyväskylän Yliopisto
Tietotekniikan Laitos
Jyväskylä
|
Hyväksyjä |
Päivämäärä |
Allekirjoitus |
Nimenselvennys |
|
Projektipäällikkö |
___.___.2006 |
|
|
|
Tilaaja |
___.___.2006 |
|
|
|
Tilaaja |
___.___.2006 |
|
|
|
Ohjaaja |
___.___.2006 |
|
|
Tietoa dokumentista
Tekijät:
Dokumentin nimi: Kokako-projekti, Sovellussuunnitelma
Sivumäärä: 17
Tiedosto: sovellussuunnitelma160306.doc
Tiivistelmä: Sovellussuunnitelma
kuvaa miten vaatimusmäärittelyssä esitetyt vaatimukset toteutetaan. Se kuvaa
sovellukselle asetetut tavoitteet sekä toimintojen ja ominaisuuksien
priorisoinnin. Tämän lisäksi sovellussuunnitelmassa hahmotellaan sovelluksen
rakenne ja sen käyttöliittymä.
Dokumentti on vaatimusmäärittely Jyväskylän yliopiston Tietotekniikan laitoksella
toteutettavaan Kokako-sovellusprojektiin. Sovellussuunnitelma kuuluu
olennaisena osana projektin suunnitteluun ja läpivientiin. Dokumentissa
selvitetään sovelluksen arkkitehtuuri ja sen toiminnot.
Avainsanat: sovelluksen arkkitehtuuri, opinto-opas,
julkaisuprosessi, koostaminen
Muutoshistoria
|
Versio |
Päivämäärä |
Muutokset |
Tekijät |
|
0.1 |
25.2.2006 |
Sovellussuunnitelman
laatiminen aloitettiin. |
Väärämäki Tapio |
|
0.15 |
1.3.2006 |
Suunnitelman
runkoa täsmennetty ja jäsennelty |
Väärämäki Tapio |
|
0.2 |
17.3.2006 |
Luvut 1-3 saatu
valmiiksi |
Väärämäki Tapio |
|
0.3 |
10.4.2006 |
Lisää lukuja
kirjoitettu, joitakin korjauksia aiempiin |
Väärämäki Tapio |
|
0.4 |
20.4.2006 |
Tekstin
raakaversio saatu valmiiksi, luokkakuvauksia lukuun ottamatta |
Väärämäki Tapio |
|
0.5 |
25.4.2006 |
Luokkakuvaukset
valmiina |
Väärämäki Tapio |
|
0.6 |
26.4.2006 |
Dokumentti
standardi-ulkoasun mukaiseksi |
Väärämäki Tapio |
|
0.7 |
12.5.2006 |
Vesa Korhosen
korjausehdotukset lisätty |
Väärämäki Tapio |
|
0.9 |
22.5.2006 |
Joitakin pieniä
korjauksia kirjoitus- ja ulkoasuun liittyen. Viitteiden ja kuvaluettelon lisäys,
sekä sisällysluettelon tyylien korjaus |
Väärämäki Tapio |
Tietoa projektista
Kokako-projekti edelleenkehittää opinto-oppaan koostamistyökalua Jyväskylän yliopiston Informaatioteknologian
tiedekunnalle. Työkalusta on tarkoitus laatia niin yleis- ja helppokäyttöinen, että
sitä on mahdollista käyttää vastaaviin tarkoituksiin esimerkiksi muissa tiedekunnissa.
Ensisijaisesti on tarkoitus toteuttaa ympäristö opinto-oppaaseen tulevien
XML-dokumenttien luontiin ja niiden tyyppimääritysten muuntaminen Xoo-projektin
luoman luku.dtd:n mukaiseksi. Tämän jälkeen on tarkoitus
toteuttaa olemassa olevaan koostamistyökaluun helppokäyttöisempi käyttöliittymä
sekä dokumenttien käsittelyyn tarvittava versionhallinta.
Tekijät:
Tilaaja:
·
Ihanainen Eija opintoasiat@it.jyu.fi 014 260 2791
·
Auer
Antti auer@jyu.fi 014 260
4319
·
Honkaranta Anne anne.honkaranta@it.jyu.fi 014 260 3041
·
Nurminen Miika minurmin@jyu.fi 014 260 2530
·
Lappalainen Vesa vesal@mit.jyu.fi 014 260 2722
Ohjaajat:
Yhteystiedot:
kokako_opis.group@korppi.jyu.fi
https://korppi.jyu.fi/list-archive/kokako06_opetus
Sisältö
1.2 Toteuttavan sovelluksen taustaa ja tavoitteita
2 Sovellukseen liittyvä termistö
3 Ohjelman rakenne ja sen komponentit
3.1 Sovelluksen ohjelmistokomponentit ja
prioriteettitasojen kuvaukset
3.3 Sisällöntuottajan käyttöliittymä
3.6 Versionhallintajärjestelmä
3.8 Julkaisuskripti (HTML- ja PDF-muodot)
3.9 Korpin kurssikuvaukset -liitäntä
3.10 Henkilökunnan yhteystiedot –liitäntä
4.2 Rakennemalli / Koostamiskäyttöliittymä
6 Sovelluksen kehittämisessä käytettävät
työkalut
7 Lähdekoodin kommentointi ja nimeäminen
7.1 Esimerkki kommentoidusta lähdekoodista
Kuva
1: Opinto-oppaan julkaisuprosessi
Kuva 2: Sovelluksen ohjelmistokomponentit
Kuva 3: Luonnos koostamiskäyttöliittymän
ulkoasusta
Kokako-projekti
on kevään -06 Jyväskylän yliopiston Tietotekniikan laitoksen sovellusprojekti.
Projekti kehittää opinto-oppaan laatimis- ja koostamistyökalua Jyväskylän yliopiston
informaatioteknologian tiedekunnalle. Työkalusta on tarkoitus laatia niin yleis-
ja helppokäyttöinen, että sitä on mahdollista käyttää vastaaviin tarkoituksiin esimerkiksi
muissa tiedekunnissa. Sitä tulee käyttämään kaksi eri käyttäjäryhmää,
dokumentin sisällöntuottaja ja koostaja. Työkalun tarkoituksena on tehdä
lähdedokumenteista yhtenäisiä ja täten helpottaa koostajan työtä
automatisoimalla koostamisprosessia.
Kokako-projekti
on jatkoa XooZoo- ja Xoo-projekteille. XooZoo-projektin tehtävänä oli informaatioteknologian
tiedekunnan (myöhemmin tekstissä IT-tiedekunta) opinto-oppaan hallinnan,
sisällön ja rakenteen kehittäminen. Projekti keskittyi tutkimukseen ja
suunnitteluun. Käytännön toteutukselle jäi vähemmän aikaa, ja niinpä projekti
jatkui Xoo-jatkoprojektilla, jonka tehtävänä oli viedä XooZoo-projektissa aloitettu
työ loppuun.
Xoo-projekti
koosti IT-tiedekunnalle opinto-oppaan XooZoo-projektissa saatujen tuloksien
pohjalta. Koostamistyössä havaittiin kuitenkin vielä useita puutteita, joista
halutaan eroon. Nyt Kokako-projektin tehtävänä on jatkaa koostamisjärjestelmän
kehittämistä edelleen.
Kokako-projektin
kesto on neljä kuukautta, ja se on valmis viimeistään 31.5.2006. Ensisijaisesti
on tarkoitus toteuttaa ympäristö opinto-oppaaseen tulevien XML-dokumenttien
luontiin ja niiden tyyppimääritysten muuntaminen Xoo-projektin luoman luku.dtd:n mukaiseksi. Tämän jälkeen on tarkoitus
totetuttaa olemassa olevaan koostamistyökaluun helppokäyttöisempi
käyttöliittymä sekä dokumenttien käsittelyyn tarvittava versionhallinta.
Tämä dokumentti
kuvaa vaatimusmäärittelyssä esiteltyjä sovelluksen komponentteja ja toimintoja
tarkemmin. Sovellussuunnitelmassa esitellään myös sovelluksen toteuttamisessa
käytettävät työkalut ja ohjelmointikielet. Lopuksi dokumentissa kuvataan
lyhyesti, miten sovellusta tullaan testaamaan.
Jyväskylän
yliopiston IT-tiedekunta on julkaissut vuosittain opinto-oppaan uusille ja
vanhoille opiskelijoille. Opinto-oppaan laatiminen koostuu useasta eri
työvaiheesta, joita ovat mm. sisällöntuotanto ja koostaminen. Käytännössä
opinto-oppaan laatimisprosessi käynnistyy sisällöntuottamisella, jossa kukin
sisällöntuottajat laatii oman osuutensa opinto-opasta varten. Tämän jälkeen koostaja
kokoaa erilliset dokumentit yhdeksi kokonaisuudeksi ja huolehtii samalla dokumentin
taittamisesta. Koostamisprosessi on ollut melko työläs, koska sisällöntuottajat
ovat toimittaneet omat osadokumenttinsa erilaisilla tyylimäärittelyillä
varustettuna, ja niistä on pitänyt koostaa yksi yhtenäinen dokumentti.
Koostamisvaiheessa on siten jouduttu tekemään paljon manuaalista työtä, joka on
koettu varsin raskaaksi ja ehkäpä hieman turhaksikin.
XooZoo-projektista
lähtien opinto-oppaan eri luvut on kirjoitettu XML-muotoon. Se on kuitenkin
havaittu liian työlääksi ja vaikeaksi tavallista käyttäjää ajatellen. Nyt on tarve kehittää editorikäyttöliittymä,
jonka avulla käyttäjät pystyvät kirjoittamaan XML-dokumentteja ilman erityistä
XML-osaamista.
Varsinaisen
sisällöntuotannon lisäksi sovelluksella pitää pystyä koostamaan useat eri
XML-dokumentit yhdeksi yhtenäiseksi dokumentiksi. Tarvittaessa koostamis- ja
sisällöntuotantotyökalut saattavat olla täysin erillisiäkin sovelluksia.
Tavoitteena on
luoda sellainen sovelluskokonaisuus, jonka avulla sisällöntuottajien on
mahdollista luoda tyylimäärittelyiltään yhtenäisiä dokumentteja opinto-opasta
varten. Sovelluksen tulee pystyä myös koostamaan nämä dokumentit
automaattisesti – tai korkeintaan hyvin pienellä manuaalisella työllä – yhdeksi
suureksi XML-dokumentiksi, ja muuntaa tämä XML-dokumentti joko PDF- tai
HTML-muotoon.
Sovelluksen
luonteesta johtuen sen käyttömahdollisuudet eivät rajoitu vain opinto-oppaan
tuottamisprosessiin. Koostamis- ja sisällöntuotanto-ominaisuuksia on
mahdollista hyödyntää kaikissa sellaisissa prosesseissa, joissa on tarvetta
koostaa yksi dokumentti useasta pienemmästä osadokumentista. Opinto-oppaiden
lisäksi tällaisia dokumentteja ovat ainakin valintaopas ja erilainen oppimateriaali.
Tässä luvussa
kuvataan sovellussuunnitelmassa esille tulleita termejä.
|
XML (eXtensible Markup
Language |
on metakieli,
jolla määritellään rakenteisia merkkauskieliä. XML- ja HTML-merkkauskielten
erona on se, että HTML-merkkauskielessä käytetään ennalta määriteltyjä
merkkaustunnisteita, kun taas XML-merkkauskielen dokumenteille voi laatia
sovellus- ja aihekohtaisia omia merkkauskieliä skeemamääritystä käyttäen. XML
siis tarjoaa syntaksin ja merkkaussäännöt, joiden pohjalta voidaan määritellä
omia merkkauskieliä. |
|
DTD (Document Type
Definition) |
Määrittää rakenteisen dokumentin skeeman. Tämän avulla XML-prosessorille
kerrotaan mitä elementtejä ja attribuutteja dokumentti saa sisältää, missä järjestyksessä ne saavat
ilmetä ja mitkä ovat niiden keskinäiset suhteet. |
|
Luku.dtd |
on opinto-oppaan koostamistyökalun käyttämä DTD. Tämä on opinto-oppaan
tekstilukujen käyttämä DTD-määritys. (Opinto-oppaan koostaminen perustuu
kooste.dtd-määritykseen). |
|
OpenOffice 2.0 |
on Microsoft Officen kaltainen ohjelma, josta löytyy hyvin pitkälti samat
ominaisuudet. OpenOfficea on tarkoitus käyttää dokumenttien tuottamis- ja
muokkausohjelmana opinto-oppaan tuottamisprosessissa. |
|
XSLT (Extensible Style Language and Transformations) |
on laajasti käytetty XML-dokumenttin
muunnoskieli. Tyypillisiä XSLT:n sovelluskohteita ovat XML-aineiston muunnokset
toiseen XML-merkkauskielen mukaiseksi, HTML-muotoon tai tekstiksi. |
Tässä luvussa
kuvataan yleisesti sovelluksen rakennetta ja sen sisältämiä komponentteja.
Luvun tarkoituksena on selventää lukijalle, että millaisista komponenteista
sovellus rakentuu. Osa tarvittavista komponenteista on jo olemassa, mutta osa
kehitetään Kokako-projektin aikana. Tämä luku kuvaa eri komponenttien
kehitystilan, ja ottaa myös lyhyesti kantaa kehitettävien komponenttien kehitystyön
priorisointiin. Luvun pohjana toimii opinto-oppaan julkaisuprosessia kuvaava kaaviokuva,
joka on esitetty alla (kuva 1). Kuvan käyttäjäryhmistä on kerrottu tarkemmin
vaatimusmäärittelyssä.
Kuva 1: Opinto-oppaan julkaisuprosessi
Julkaisuprosessin
läpiviemiseen tarvitaan Kokako-projektissa kehitettävää sovellusta. Se on mahdollista
jakaa eri komponentteihin kuvan 2 mukaisesti:
Kuva 2: Sovelluksen
ohjelmistokomponentit
Yllä olevan
kaaviokuvan lisäksi jokainen sovelluskomponentti on kuvattu tarkemmin alla
olevissa luvuissa. Sanallisen kuvauksen lisäksi jokaisen komponentin kohdalla
on merkitty komponentin kehityksen kiireellisyysastetta kuvaavaa prioriteetti.
Prioriteettien kuvaukset ovat seuraavat:
Seuraavissa alaluvuissa
kerrotaan kustakin komponentista ja niiden liitännästä kehitettävään sovellukseen.
Sisäänkirjautuminen
on merkitty kaaviokuvaan punaisella värillä, eli tämän komponentin kehitystyö
alkaa täysin alusta. Vaatimusmäärittelyssä sisäänkirjautumiselle asetettiin
vaatimukseksi tarkistaa käyttäjän käyttäjätunnus, salasana ja sovelluksen
käyttäjäryhmä. Sisäänkirjautuminen on välttämätön sovelluksen toiminnan
kannalta. Sisäänkirjautumisessa saatavia käyttäjätietoja hyödynnetään
dokumenttien metatietoja täydennettäessä.
Prioriteetti: Korkea
Sisällöntuottajan
käyttöliittymä on se perustila, johon sisällöntuotanto-ryhmään kuuluvat
käyttäjät ohjataan sisäänkirjautumisen jälkeen. Käyttöliittymästä käsin
sisällöntuottaja ohjaa sovelluksen toimintaa, kuten luo uusia dokumentteja,
muokkaa olemassa olevia dokumentteja, esikatselee luomiaan XML-dokumentteja
joko HTML- tai PDF- muodossa tai vie laatimiaan dokumentteja versionhallintajärjestelmään.
Tätä komponenttia voidaankin pitää eräänlaisena ohjauskomponenttina, jolla käyttäjä
komentaa muiden komponenttien toimintaa. Tätä komponenttia ei ole työstetty
lainakaan ennen Kokako-projektia, joten kehitystyö alkaa ”puhtaalta pöydältä”.
Tässä komponentissa on toiminallisuutta melko vähän, koska monet toiminnot
perustuvat valmiisiin skripteihin ja niiden käyttämiseen. Osa käyttöliittymän
toiminnoista, kuten tiedostonäkymä, vaatii kuitenkin huomattavaa työpanostusta,
jotta lopputuloksesta saadaan hyvä.
Prioriteetti: Korkea
Editorikäyttöliittymä
on se komponentti, joka käynnistetään aina kun käyttäjä haluaa laatia uusia tai
muokata olemassa olevia XML-dokumentteja. Editorikäyttöliittymä pohjautuu OpenOfficen
Write –sovellukseen, jonka toiminallisuutta on rajoitettu voimakkaasti.
Tärkeintä editorikäyttöliittymässä on, että käyttäjä ei saa tehdä tekstiin
mitään muita kuin hänelle valmiiksi tarjottuun tyylimäärittelyyn kuuluvia
muotoiluita. Uusien dokumenttien laatiminen perustuu olemassa olevaan dokumenttipohjaan,
johon on sisällytetty kaikki sallitut tyylimäärittelyt. Näitä tyylimäärittelyitä
hyödyntäen käyttäjä laatii dokumentin. Editorikäyttöliittymä sisältää tallenna-painikkeen, jota painaessa
käyttäjän muokkaama dokumentti tallennetaan ensin ODT-muotoon ja muunnetaan sen
jälkeen XSLT-muunnoksella XML-muotoon. Mikäli käyttäjä muokkaa aiemmin
laatimiaan dokumentteja, niin silloin vastaava muunnos tehdään toiseen
suuntaan, eli XML-dokumentti muunnetaan takaisin ODT-muotoon. Komponentti on jo
periaatteessa toteutettu valmiiksi, mutta toisaalta siihen pitää tehdä vielä
paljon rajaamis- ja muokkaustyötä. Komponentti on välttämätön XML-dokumenttien
laatimista ajatellen.
Prioriteetti: Korkea
Koostajan
käyttöliittymä on laajennettu versio sisällöntuottajan käyttöliittymästä.
Koostajan käyttöliittymä sisältää kaikki samat toiminnot kuin sisällöntuottajankin
käyttöliittymä, mutta tämän lisäksi koostajan versiossa on mahdollista käyttää
erilaisia koostamistoimintoja. Tällaisia toimintoja ovat:
Koostajan
käyttöliittymän kehitystilanne on aivan sama kuin sisällöntuottajan
käyttöliittymäkin, eli sitä ei ole kehitetty vielä lainkaan. Komponentti
käyttää paljon ulkoisia skriptejä ja muita sovelluksia, joten tämä komponentti
ei itsessään sisällä kovin paljon toiminallisuutta. Osa käyttöliittymän
toiminnoista, kuten tiedostonäkymä, vaatii kuitenkin huomattavaa työpanostusta,
jotta lopputuloksesta saadaan toimiva.
Prioriteetti: Korkea
Versionhallintajärjestelmää
käytetään mm. sisällöntuottajien ja koostajien laatimien dokumenttien
tallentamiseen. Tästä johtuen versionhallintajärjestelmä liittyy sisällöntuottajan
käyttöliittymä- ja koostajan käyttöliittymä -komponentteihin. Versionhallintajärjestelmänä
käytetään jotakin olemassa olevaa ohjelmistokomponenttia, kuten CVS:ää tai
Subversionia. Versionhallintaan liittyvä kehitystyö on
versionhallintajärjestelmän integroimista kummankin käyttäjäryhmän
käyttöliittymiin. Itse versionhallintajärjestelmä on kuitenkin valmis
osakomponentti. Tämän komponentin olemassaolo ei ole välttämätöntä järjestelmän
toiminnan kannalta.
Prioriteetti: Keskitaso
Koostamisskripti
on Xoo-jatko -projektissa kehitetty ohjelmistokomponentti, joka toimii komentorivitasolla.
Skripti käynnistetää koostajan käyttöliittymästä silloin kun koostaja haluaa
tehdä opinto-oppaasta XML-koosteen tai PDF- tai HTML-julkaisun. Komponentti on
täysin valmis, ja se pitää ainoastaan integroida toimimaan koostajan
käyttöliittymän kautta. Skriptin toiminta käyttöliittymästä käsin on
välttämätöntä, jotta kehitettävällä sovelluksessa on mahdollista tehdä tai
julkaista koosteita.
Prioriteetti: Korkea
Julkaisuskriptejä
käytetään kun dokumentteja halutaan katsella tai julkaista joko HTML- tai PDF-muodossa.
HTML-muunnos toimii siten, että XML-dokumentti muunnetaan XSLT-muunnoksella
HTML-dokumentiksi. PDF-muunnoksessa dokumentti muunnetaan ensin
XSLT-muunnoksella LaTeX-muotoon, ja siitä toisen muunnosskriptin avulla PDF-dokumentiksi.
Julkaisuskriptit jakautuvat siis kahteen kahteen aliskriptiin, HTML- ja
PDF-skripteihin. Kummatkin näistä alikomponenteista ovat jo valmiiksi
toteutettuja, ja niiden käyttö pitää vain integroida osaksi sovelluksen
käyttöliittymää. Esikatselu- ja julkaisu ovat kriittisiä toimintoja
koostamisprosessia ajatellen.
Prioriteetti: Korkea
Korppi-järjestelmää
käytetään käyttäjien autentikoinnin lisäksi opinto-oppaan kurssikuvausten noutamiseen. Tässä tapauksessa Korppi-kytkennällä
tarkoitetaan juuri kurssikuvausten noutamiseen liittyvää skriptiä, joka hakee
haluttujen kurssien kuvaukset automaattisesti Korppi-järjestelmästä. Valmis
skripti tätä varten on jo olemassa, joten kehitystyötä ei tarvita. Tähän
komponenttiin liittyvä ohjelmointityö on skriptin integroiminen koostajan
käyttöliittymään.
Prioriteetti: Keskitaso
Henkilökunnan
yhteystiedot noudetaan tiedekunnan WWW-sivuilta automatisoidusti sopivan skriptin
avulla. Tätä komponenttia ei ole vielä kehitetty loppuun asti, mutta tilaajan
tekninen edustaja on lupautunut vastaamaan skriptin kehitystyöstä.
Tekijäryhmälle tehtäväksi jää skriptin käytön integrointi koostajan
käyttöliittymään.
Prioriteetti: Keskitaso
Sovelluksen
käyttöliittymä koostuu ohjelmistokomponenteista, joiden lataus- ja esitysmäärä
riippuu käyttäjän roolista. Täysimittainen kaikki komponentit sisältävä
käyttöliittymä esitetään koostajille, joiden pitää pystyä käsittelemään
yksittäisten dokumenttien lisäksi myös kokonaisia koostedokumentteja.
Sisällöntuottajille riittää hieman rajoitetumpi käyttöliittymä, sillä he eivät
muokkaa kuin yksittäisiä sisältödokumentteja.
Seuraavissa
alaluvuissa esitellään kutakin ohjelmistokomponenttia ja niiden käyttöliittymää
hieman tarkemmin. Koostamiskäyttöliittymän, eli sovelluksen pääasiallisen
käyttöliittymän, hahmotelma on esitetty kuvassa 3:
Kuva 3: Luonnos
koostamiskäyttöliittymän ulkoasusta
Tiedostonäkymä (kuvan
3 oikea palasta) näyttää käyttäjälle mitä tiedostoja hänellä on tallennettuna
versionhallintaan. Puunäkymä perustuu graafiseen esitykseen versionhallinnan sisällöstä,
ja se näyttää kaikki ne tiedostot, joita käyttäjällä on oikeus muokata.
Tiedostot ovat eriteltynä lukujen mukaisiin kansioihin, eli esimerkiksi ainejärjestö, TKTL ja Tietotekniikan laitos.
Sisällöntuottaja
näkee tiedostolistauksen käyttöliittymän oikeassa laidassa Dokumentit-otsakkeen alla. Tiedostolistauksessa näytetään kaikki
käyttäjän sen hetkiseen koosteprojektiin liittyvät sisältödokumentit.
Sisällöntuottaja pystyy muokkaamaan ainoastaan niitä sisältödokumentteja,
joihin hänen käyttäjäryhmänsä oikeuttaa.
Koostajalla on
käytössä sisältödokumentteja listaavan tiedostonäkymän lisäksi myös toinen
tiedostolistaus sovelluksen vasemmassa laidassa, Projektit-otsakkeen alla. Ainoastaan koostajalle esitettävässä
tiedostonäkymässä listataan kaikki eri koostedokumentit. Koostedokumentteja
ovat esimerkiksi opinto-opas koosteet vanhoille ja uusille opiskelijoille.
Koostedokumentit sisältävät tiedot koosteen rakenteesta ja siihen sisällytettävistä
dokumenteista. Projektit-otsakkeella
tarkoitetaan sitä, että koostedokumenttien kohdalla kyse on suurista
dokumenttikokonaisuuksista, kuten opinto- tai valintaoppaasta. Dokumentit-otsakkeen alla on puolestaan
yksittäisiä sisältödokumentteja, jotka voi kuulua useisiin eri
koostedokumentteihin.
Kummankin tiedostonäkymän, Dokumentit ja Projektit, toteutus perustuu samaan ohjelmistokomponenttiin eli
puunäkymään. Niiden sisältö määritetään komponentin latauksen yhteydessä
syötettävillä parametreilla, joita ovat mm. käyttäjätunnus ja rooli.
Rakennemallin
toimii ensisijaisesti koostajan työkaluna, jota hyödynnetään koosteiden
laatimisessa (Rakenne-kohta kuvassa 3).
Rakennemalli perustuu rakennepuuhun, joka ilmaisee kooste- tai sisältödokumentin
rakenteen. Sisältödokumenteissa on vain
yksi juurisolmu, jonka alla on sisältödokumentin alilukuja ilmaisevia lapsisolmuja.
Koostedokumentit rakentuvat sen
sijaan useista toisiinsa yhdistetyistä juurisolmuista, joita ovat esiluku, tekstiluku, liite ja takaluku. Näiden solmujen ja niiden lapsisolmujen
lisäksi rakennepuuhun kuuluu myös sisällysluettelo,
jonka sijainnista ja käyttämisestä päättää koostaja. Kukin juurisolmu edustaa
tiettyä dokumenttikategoriaa, johon sisällytetään kategorian mukaisia
dokumentteja. Vuoden 2005-2006 opinto-oppaan kohdalla esilukuja ovat mm. johdanto ja esipuhe, tekstilukuja oppaan varsinainen sisältö, liitteitä mm. johtosäännöt ja henkilötiedot sekä takalukuna kampusalueen kartta.
Sisältödokumenttien
lisäämineen koosteeseen tapahtuu raahaamalla sisältödokumentti Dokumenti-tiedostonäkymästä johonkin
rakennemallin solmukohtaan. Poistaminen tapahtuu valitsemalla haluttu luku
rakennemallista, minkä jälkeen käyttäjä painaa näppäimistön delete-näppäintä. Lukujen keskinäistä
järjestystä muutetaan valitsemalla luku ja raahaamalla se uuteen kohtaan.
Rakennemalli-kohdan
näkymää päivitetään aina kun koostaja lisää tai poistaa siihen kuuluvia dokumentteja.
Sisältödokumenttien lisäämisen yhteydessä oppaan lukunumerot lasketaan uudelleen.
Tällä hetkellä ainoastaan tekstiluvut
numeroidaan, mutta tulevaisuuden kehitysversioissa koostaja saanee päättää mitkä
kategoriat numeroidaan. Koostajalle tullaan tulevaisuudessa antamaan luultavasti
myös mahdollisuus päättää mitkä kategoriat sisällytetään sisällysluetteloon.
Käyttäjällä on mahdollisuus
käynnistää valitsemansa koostedokumenttiin kuuluvan sisältödokumentin muokkaus valitsemalla
sisältödokumentti puurakenteesta ja painamalla tämän jälkeen muokkaa dokumenttia -painiketta. Tämän
toiminnallisuuden tarkoituksena on tukea sisällöntuottajia erityisesti pitkien
lukujen muokkaamisessa ja navigoinnissa. Koostajan on puolestaan yksinkertaista
tehdä pieniä korjauksia eri lukuihin, kun muokkausta kaipaava sisältödokumentti
ja sen muokattava kohta löytyvät nopeasti.
Näytä muutokset -toiminnon tulokset esitetään
rakennemallissa. Kaikki ne puun solmut, joita on muokattu edelliseen dokumentin
versioon verrattuna, esitetään poikkeavalla, esimerkiksi punaisella värillä. Tämän
toiminnallisuuden toteutusprioriteetti on alhainen, ja se tullaan toteuttamaan
vasta myöhemmissä kehitysprojekteissa.
Rakennemallin
tehtävänä on tarjota koostajalle tehokas työkalu koosteiden laatimiseen ja sitä
on mahdollista hyödyntää myös sisällöntuottajan toimesta. Koostaja on kuitenkin
se käyttäjäryhmä, jolle rakennemalli on ensisijaisesti tarkoitettu.
Esikatselun
tehtävänä on näyttää käyttäjien tuottamat kooste- ja sisältödokumentit HTML-
tai PDF-muodossa. Esikatselua tarvitaan, koska XML-editorissa näkyvä
XML-dokumentti ei vastaa ulkoasultaan täysin julkaisuversion ulkoasua. Koostedokumenttien
kohdalla kokonaista koostetta ei ole edes mahdollista viedä XML-editoriin,
koska koostaminen tapahtuu rakennemallin avulla.
Esikatselu
käynnistetään painamalla ”Esikatsele
PDF-muodossa”- tai ”Esikatsele HTML muodossa” -painikkeita. Tämän jälkeen
sovellus käynnistää XMLà HTML tai XMLà PDF –muunnoksen, jossa tiedosto muunnetaan
haluttuun formaattiin. Muunnoksen valmistuttua käynnistetään HTML- tai
PDF-selain, jossa muunnettu dokumentti näytetään.
Esikatselun
toimiminen edellyttää, että käyttäjän tietokoneelle on asennettu HTML- ja
PDF-selaimet ja niiden käynnistyspolut on määritetty ohjelmaan.
Painikerivistä
löytyy kaikki ne toiminnot, joilla tehdään muutoksia dokumentteihin ja
tallennetaan tai julkaistaan niitä. Sisällöntuottajalla on käytössä seuraavat
toiminnot:
Koostajalla on
sisällöntuottajan toimintojen lisäksi käytettävissä myös kaikki koostamiseen
liittyvät toiminnot, joita ovat:
Kunkin painikkeen
toiminto on selitetty vaatimusmäärittelyssä [1], toiminnon nimeä vastaavan
käyttötapauksen kohdalla.
Lähes kaikki
sisältödokumentteihin ja koosteisiin viittaavat painikkeet vaativat jonkin tiedoston
valintaa tiedostonäkymästä ennen kuin painikkeita voi käyttää. Suurin osa
painikkeista käynnistää jonkin skriptin tai valmiin ohjelmistokomponentin, joihin
valittuna oleva tiedosto ilmoitetaan käynnistysparametrina.
Editorikäyttöliittymäksi
kutsutaan sovelluksen XML-editoria, joka toteutetaan rajaamalla OpenOffice
Writerin toiminnallisuutta tarjoamalla käyttäjälle valmis dokumenttipohja.
Sisältödokumenttien laatiminen XML-editorin avulla tapahtuu aivan kuten
normaalien dokumenttien kirjoittaminen OpenOfficen Writer -sovelluksella. Tyylimäärittelyiden
tekeminen poikkeaa perinteisestä dokumentin laadinnasta, koska se on
mahdollista ainoastaan ohjelman tyylidialogissa tarjottujen tyylimääritteiden
avulla.
Editorikäyttöliittymä
käynnistetään aina kun käyttäjä painaa Uusi
dokumentti- tai Muokkaa dokumentti
–painikkeita. Editorin käynnistäminen tarkoittaa OpenOffice Writerin käynnistämistä
eli se vaatii käyttäjän tietokoneelta huomattavasti resursseja.
Editorissa
laaditut dokumentit tallennetaan luonnollisesti XML-muotoon. Tämä vaatii kuitenkin
XSLT-muunnoksen, jolla OpenOfficen natiivimuodossa (ODT) oleva dokumentti
muunnetaan XML-muotoon. Dokumentteja käsitellään siis editorissa ODT-muodossa
ja ne muunnetaan tallennusvaiheessa XML-muotoon. Tästä johtuen Muokkaa dokumentti -painiketta painettaessa
dokumentti joudutaan muuntamaan ensin XSLT-muunnoksella XML-muodosta takaisin
ODT-muotoon, ennen kuin dokumenttia on mahdollista ryhtyä muokkaamaan.
Sovellus on
jaettu tässä dokumentissa pienempiin osakomponentteihin, jotta sitä olisi
helpompi tarkastella. Vastaavasti myös sovelluksen ohjelmakoodi on jaettu pienempiin
moduuleihin, jotka puolestaan
jakautuvat vielä luokkiin. Näin
sovelluksen koodi on yksinkertaisempaa hallita, ja osakomponentti-ajattelu
toteutuu myös käytännössä. Tässä luvussa esitellään ohjelman moduulit.
Sovellus koostuu
kuvan 4 esittämistä moduuleista:
Kuva 4. Sovelluksen moduulit
Käyttöliittymä-moduuli sisältää varsinaisen käyttöliittymän
alustamiseen ja luomiseen liittyvät luokat. Kaikki käyttöliittymän varsinaiset
toiminnallisuudet löytyvät kuitenkin muista moduuleista kuten actions ja dialogs. Puunäkymät toteutetaan tree-
ja beans-paketteihin kuuluvissa
luokissa. Sisäänkirjautuminen ja sen toiminnallisuudet on toteutettu tämän
moduulin luokissa.
Actions-moduuli sisältää kaikki sovelluksen dialogi-kutsut, joita tarvitaan kun
käyttäjä käynnistää valitsemansa toiminnon tai dialogin. Esimerkiksi uutta
dokumenttia laadittaessa käyttäjä painaa Uusi
dokumentti -painiketta, jolloin actions-moduuliin
kuuluva NewDocAction-luokka kutsuu dokumentin
luomisessa tarvittavaa NewDocDialog-dialogia.
Varsinaisten toimintokutsujen lisäksi actions-moduuli
sisältää kaikki toimintojen ulkoasuun liittyvät tiedot. Niitä ovat toiminnon avustusteksti,
toiminnon ikoni ja toiminnon nimi. Tällaisesta keskitetystä ratkaisusta on
hyötyä erityisesti silloin, kun sama toiminto on mahdollista käynnistää useasta
eri kohteesta. Tässä sovelluksessa jokainen toiminto on mahdollista käynnistää
joko painikeriviltä tai valikosta.
Dialogs-moduuliin on sisällytetty kaikki sovelluksen dialogit. Niitä tarvitaan
useimmiten jonkin toiminnon käynnistyksen tai suorituksen yhteydessä.
Esimerkiksi Uusi dokumentti -painiketta
painettaessa käyttäjälle aukeaa dialogi, johon hän syöttää laadittavaan
dokumenttiin liittyviä kuvailutietoja. Dialogit käynnistetään actions-moduulin luokista.
IO-moduuli sisältää dialogien tiedostonäkymien toteutuksessa tarvittavat
luokat. Esimerkiksi Muokkaa dokumenttia –painiketta
painettaessa käyttäjän pitää valita muokattavan tiedosto. Valinta tehdään
tiedostonäkymässä, jonka toteutuksessa käytetään IO-moduulin luokkia.
XML-moduuli sisältää XSLT-muunnoksissa käytettävät luokat. XSLT-muunnoksia
tarvitaan esimerkiksi silloin kun XML-dokumentti muunnetaan ODT-muotoon tai
toisinpäin.
Beans-moduuliin sisältyviä luokkia tarvitaan puunäkymän toteutuksessa. Moduulin
luokat esittävät puumalleja, eli informaatiota hierarkkiseen muotoon
järjestettynä. JTree-komponentista
perityn paketin luokat toimivat graafisena esitysalustana Tree-moduulin TreeModel-luokille.
Käytännössä tämä tarkoittaa sitä, että sovelluksen puumallit luodaan ja niiden
sisältöä muokataan Tree-paketin
luokissa, mutta niiden esittämiseen tarvitaan yhtä ylemmän tason rajapintaa,
jonka Beans-paketin luokat tarjoavat.
Tree-moduuliin kuuluvat luokat pitävät sisällään puumallin ja sen solmut.
Puumallin rakenne ja sisältö määritellään puumallin luomisen yhteydessä.
Datatransfer-moduuli sisältää puunäkymien raahaustoiminnon
toteutuksessa tarvittavat luokat. Java ei tarjonnut valmista toteutusta
puunäkymissä tarvittaville raahaustoiminnoille, joten kaikki raahaamiseen
liittyvät toiminnot pitää toteuttaa itse.
Sovelluksen
moninaisuudesta johtuen myös kehitystyökaluja on useita erilaisia.
Kehitystyökalun valinta riippuu komponentin toimintaympäristöstä sekä
komponentin mahdollisesta kehitysasteesta. Mikäli komponentti on jo olemassa
tai siitä on toteutettu edes jokin osa, niin teknistä arkkitehtuuria ei ryhdytä
enää muuttamaan, vaan siihen pyritään mukautumaan. Alusta asti kehitettävien
komponenttien kohdalla työkalujen valinta on tehty yhdessä tilaajan teknisten
edustajien kanssa.
Sisäänkirjautumisen
ja käyttöliittymien ohjelmointiin käytetään JBuilder ja NetBeans –työkaluja,
sekä ohjelmointikielenä Javaa. Kyseiseen ohjelmointikieleen päädyttiin, koska
se koettiin monipuoliseksi ja tehokkaaksi Kokako-projektin käyttötarpeita
ajatellen.
Editorikäyttöliittymä
perustuu OpenOffice Writer –sovelluksen modifioimiseen ja ohjelmointiin.
Ohjelmointi tapahtuu Java-ohjelmointikielellä, koska Java tarjoaa parhaan
rajapinnan editorin muokkausta ajatellen. Editorikäyttöliittymän dokumenttipohjan
muokkaaminen tapahtuu pääasiassa OpenOfficen omien säätötoimintojen avulla,
mutta osa toiminnoista joudutaan toteuttamaan Java-ohjelmointikielellä.
Dokumenttien muuntaminen ODT-muodosta XML-muotoon ja toisinpäin tapahtuu
XSLT-muunnoksella. Muunnosskriptien laatiminen tehdään XSLT-kielellä.
Versionhallintajärjestelmä,
julkaisuskripti, koostamisskripti, Korpin kurssikuvaukset -liitäntä ja
henkilökunnan yhteystiedot -liitäntä ovat valmiita ohjelmistokomponentteja,
joiden integrointi käyttöliittymään tapahtuu Java-ohjelmointikielellä.
Kokako-projektin
aikana syntyvä lähdekoodi sijoitetaan BSD-lisenssin alaisuuteen. Projektin jäsenet
antavat Jyväskylän yliopistolle rinnakkaiset oikeudet projektin tulosten
hyödyntämiseen ei-kaupallisiin tarkoituksiin, mukaan lukien muuntelu- ja
edelleenluovutusoikeudet. Projektin jäsenet eivät luovu tekijän- ja muista
aineettomista oikeuksistaan.
Projektiin
liittyvä sähköinen aineisto säilytetään CVS-versionhallintajärjestelmässä.
XSLT-muunnosskriptien
kommentointi tehdään suomenkielellä ja Java-koodin kommentointi JavaDoc-käytänteiden
mukaisesti englanniksi [2].
XSLT-kommentoinnissa
käytetään hyvän suomenkielen mukaisia käytänteitä. Siinä ei ole kuitenkaan
mitään erityisiä, ohjelmointikielistä tuttuja vaatimuksia kommentoinnille.
Javassa
käytettävä JavaDoc-kommentointi on huomattavasti XSLT-kommentointia
rajoitetumpaa. Jokaisen lähdekooditiedoston
alkuun kirjoitetaan projektin nimi, tekijän nimi, päivämäärä, tiedoston nimi ja
kuvaus lähdekoodin tarkoituksesta. Lähdekoodin muutoshistoriasta tehdään myös
merkintä, josta ilmenee muutoksen tekijä, päivämäärä ja tehdyt muutokset.
Lisäksi jokaisen luokan toiminta kommentoidaan erikseen.
Luokkien,
olioiden, metodien ja attribuuttien nimet kirjoitetaan englanniksi. Pakettien
(Package) nimet aloitetaan pienellä kirjaimella, esimerkiksi paketti. Luokkien
nimet kirjoitetaan isolla alkukirjaimella. Mikäli luokan tai paketin nimi
koostuu useasta sanasta, kirjoitetaan sanojen alkukirjaimet isolla ja sanat
kirjoitetaan yhteen, esimerkiksi luokka kirjoitetaan muotoon FileTreeModel ja muuttuja muotoon fileTreeModel.
Lähdekoodista
muodostetaan dokumentointi käyttäen JavaDoc-sovellusta.
Yllä olevia ohjelmakoodin kommentointiin ja nimeämiseen liittyviä ohjeita noudattaen koodi näyttää alla olevan esimerkin mukaiselta.
package tree;
import
javax.swing.tree.DefaultMutableTreeNode;
import java.io.File;
/**
* FileTreeNode extends DefaultMutableTreeNode.
* Uses instances of File as a user objects.
* Can be a directoryNode or an ordinary
fileNode.
* @author Tuomas Räsänen
* @version $Revision: 1.7 $ $Date: 2006/04/12
*/
public class FileTreeNode
extends DefaultMutableTreeNode {
private String mask;
private boolean tyhja = false;
/**
* Creates an instance of FileTreeNode with
* specified File as an user object.
* @param file File
* @param mask String filename filter mask
as RegExp
* @param recursive boolean indicating
* if new FileTreeNodes should be added as
children.
*/
public FileTreeNode(File file, String mask,
boolean recursive) {
super.setUserObject(file);
this.mask = mask;
if (recursive)
createNodes(this, this.mask);
}
Sovelluksen
koostuessa useista pienistä osakomponenteista on myös testaaminen luonnollista
aloittaa pienemmistä osakokonaisuuksista, ja laajentaa sitä kohti kokonaista
sovellusta aina kun osakokonaisuuksia on saatu testattua. Tällä tavoin osakomponenttien
toiminta saadaan varmennettua ensin, ja vasta sen jälkeen keskitytään
komponenttien yhteen sovittamisesta aiheutuviin ongelmiin.
Suunnitteluvaiheessa
on käynyt ilmi, että testaamiselle on jäämässä projektissa vain vähän aikaa.
Kun kyseessä on näinkin laaja sovellus, vaatisi ohjelman perusteellinen
testaaminen paljon aikaa ja kontribuutiota tekijäryhmältä. Tilaajaan kanssa keskusteltu,
että projektin ensisijaisen tavoite on kehittää sovellus siihen vaiheeseen,
että vuoden 2006 opinto-oppaan sisältödokumentteja on mahdollista laatia
sovelluksen XML-editorin avulla. Testaamista pyritään tekemään komponenttien iterointityön
ohessa ja myös varsinaisen ohjelmistokehityksen jälkeen, mikäli tekijäryhmällä vain
on resursseja jäljellä. Tärkeimpiä komponentteja testataan jatkuvasti
kehitystyön yhteydessä, ja niiden toiminnallisuus pyritään saattamaan
mahdollisimman luotettavalle tasolle. XSLT-muunnoksien toimivuus ja
luotettavuus testaan automatisoitujen testiskriptien avulla. Niiden toimivuus
voidaan siis taata huomattavasti muita komponentteja paremmin.
Kokako-projektin
sovellussuunnitelma-dokumentti kuvaa projektissa kehitettävän sovelluksen arkkitehtuuria,
sen toteuttamisessa käyttäviä työkaluja sekä kehitysprosessin priorisointia.
Tämän lisäksi dokumentissa on hieman hahmoteltu sovelluksen käyttöliittymää ja
toiminnallisuutta. Sovellussuunnitelma pohjautuu aiemmin laadittuihin
projektisuunnitelma- ja vaatimusmäärittely-dokumentteihin. Sovellussuunnitelman
sisältö tulee toimimaan pohjana sovellusraportin kirjoittamiselle.
[1] Kokako-ryhmä, Kokako-vaatimusmäärittely
[2] Sun Microsystems, How to Write Doc Comments for the Javadoc Tool,
<URL: http://java.sun.com/j2se/javadoc/writingdoccomments/index.html>, viitattu 22.5.2006