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:

                                                   kokako06_opetus@korppi.jyu.fi

                                                   kokako_opis.group@korppi.jyu.fi

                                                   https://korppi.jyu.fi/list-archive/kokako06_opetus


Sisältö

 

1 Johdanto.. 1

1.1 Dokumentin tarkoitus. 1

1.2 Toteuttavan sovelluksen taustaa ja tavoitteita.. 2

2 Sovellukseen liittyvä termistö.. 3

3 Ohjelman rakenne ja sen komponentit.. 4

3.1 Sovelluksen ohjelmistokomponentit ja prioriteettitasojen kuvaukset  4

3.2 Sisäänkirjautuminen.. 5

3.3 Sisällöntuottajan käyttöliittymä.. 6

3.4 Editorikäyttöliittymä.. 6

3.5 Koostajan käyttöliittymä.. 6

3.6 Versionhallintajärjestelmä.. 7

3.7 Koostamisskripti 7

3.8 Julkaisuskripti (HTML- ja PDF-muodot). 7

3.9 Korpin kurssikuvaukset -liitäntä.. 7

3.10 Henkilökunnan yhteystiedot –liitäntä.. 7

4 Käyttöliittymä.. 8

4.1 Tiedostonäkymä.. 8

4.2 Rakennemalli / Koostamiskäyttöliittymä.. 9

4.3 Esikatselu.. 10

4.4 Painikerivi 10

4.5 Editorikäyttöliittymä.. 10

5 Sovelluksen moduulirakenne.. 12

5.1 Käyttöliittymä.. 12

5.2 Actions. 12

5.3 Dialogs. 13

5.4 IO.. 13

5.5 XML.. 13

5.6 Beans. 13

5.7 Tree.. 13

5.8 Datatransfer.. 13

6 Sovelluksen kehittämisessä käytettävät työkalut.. 14

7 Lähdekoodin kommentointi ja nimeäminen.. 15

7.1 Esimerkki kommentoidusta lähdekoodista.. 15

8 Testaus. 17

9 Yhteenveto.. 18

Viitteet.. 18

Kuvaluettelo

 

Kuva 1: Opinto-oppaan julkaisuprosessi 4

Kuva 2: Sovelluksen ohjelmistokomponentit 5

Kuva 3: Luonnos koostamiskäyttöliittymän ulkoasusta. 8

Kuva 4. Sovelluksen moduulit 12

 



1 Johdanto

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.

1.1 Dokumentin tarkoitus

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.


1.2 Toteuttavan sovelluksen taustaa ja tavoitteita

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.


2 Sovellukseen liittyvä termistö

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.

 

 

 


3 Ohjelman rakenne ja sen komponentit

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

 

 

3.1 Sovelluksen ohjelmistokomponentit ja prioriteettitasojen kuvaukset

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.

3.2  Sisäänkirjautuminen

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

 

3.3  Sisällöntuottajan käyttöliittymä

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

3.4  Editorikäyttöliittymä

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

3.5 Koostajan käyttöliittymä

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

3.6 Versionhallintajärjestelmä

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

3.7 Koostamisskripti

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

3.8 Julkaisuskripti (HTML- ja PDF-muodot)

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

3.9 Korpin kurssikuvaukset -liitäntä

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

3.10 Henkilökunnan yhteystiedot –liitäntä

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

 


4 Käyttöliittymä

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

4.1 Tiedostonäkymä

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. Dokumenti­t-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.

4.2 Rakennemalli / Koostamiskäyttöliittymä

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.

4.3 Esikatselu

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.

4.4 Painikerivi

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.

4.5 Editorikäyttöliittymä

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.


 

5 Sovelluksen moduulirakenne

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

 

5.1 Käyttöliittymä

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.

5.2 Actions

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.

5.3 Dialogs

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.

5.4 IO

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.

5.5 XML

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.

5.6 Beans

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.

5.7 Tree

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

5.8 Datatransfer

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.

 

 

 

 

 

 

 

 

 


 

6 Sovelluksen kehittämisessä käytettävät työkalut

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

 


 

7 Lähdekoodin kommentointi ja nimeäminen

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.

 

7.1 Esimerkki kommentoidusta lähdekoodista

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 08:41:37 $

 */

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);

    }


 

8 Testaus

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.

 


9 Yhteenveto

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.

 

Viitteet

[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