Sisältö

1.0 Johdanto

1.1 Projektin kuvaus

Tämä kayttöohje ja ylläpito dokumentti esittelee sukututkimustietokanta- ohjelmiston, joka toteutettiin Helsingin yliopiston Tietojenkäsittelytieteen laitoksen ohjelmistotuotantoprojektissa syksyllä 2001. Ohjelmisto sisältää MySQL sukututkimustietokannan, johon tutkijat voivat Internetin kautta liittää tutkimuksiaan, jotka ohjelmisto kääntää SQL komennoiksi ja tallettaa tietokantaan. Tutkimusten hallinta, rekisteröityminen ja hakujen teko tietokantaan tapahtuu JSP-tekniikalla toteuttettujen sivujen kautta.

1.2 Määritelmät, termit ja lyhenteet

1.3 Dokumentin rakenne

Tämä dokumentti on jaettu viiteen eri lukuun, joista seuraavassa kuvataan toteuttettu ohjelmisto, selitetään sen toiminta pääpiirteittäin ja perehdytään ohjelmiston erilaisiin ominaisuuksiin ja rajoitteisiin.

Kolmannessa luvussa käydään yksityiskohtaisesti lävitse ohjelmiston asentaminen, ulkoiset osat mukaanlukien. Lisäksi käydään lävitse ohjelman konfigurointiin liittyvät asetukset ja parametrit.

Neljäs luku käsittää ohjelmiston käyttöohjeen, joka selittää yksinkertaisesti miten ohjelmaa voidaan käyttää ja mitä sillä voi tehdä.

Viides luku käsittelee ylläpitoon liittyviä asioita, tietokannan päivittämistä, mahdollisten virhetilanteiden käsittelyä ja ohjelmiston päivittämistä.

2.0 Ohjelmisto

2.1 Yleiskuva ohjelmistosta

Sukututkimustietokanta-ohjelmisto toteutettiin Helsingin yliopiston Tietojenkäsittelytieteen laitoksen ohjelmistotuotanto projektin yhteydessä Suomen Sukutukimusseuralle. Projektin aikana luotiin MySQL tietokanta, joka rakenteeltaan soveltuu GEDCOM standardin mukaisen tiedon tallettamiseen siten, ettei tietoa pääse katoamaan. Lisäksi luotiin JSP-tekniikalla liittymä tietokantaan, jonka kautta järjestelmään voidaan syöttää uusia tutkimuksia tai suorittaa hakuja jo talletettuihin tutkimuksiin. Kolmanneksi luotiin Jäsentäjä, joka hoitaa GEDCOM muotoisten tutkimusten käsittelyn ja luo SQL-käskyjä, joiden avulla tutkimuksen sisältö voidaan päivittää tietokantaan.

2.2 Ohjelmiston ominaisuudet

JSP-tekniikalla toteutettu WWW-sivusto:

Toteuttaa liittymän tietokantajärjestelmään

Tietokantaliitymän ominaisuudet konfiguroitavissa

Tietokanta haut:

Mahdollisuus etsiä yksilöitä nimen perusteella

Mahdollisuus etsiä yksilöitä syntymä tai kuolema paikan perusteella

Mahdollisuus etsiä yksilöitä syntymä täi kuolema ajan perusteella

Mahdollisuus hakea lisätietoa jokaisesta yksilön perheenjäsenestä

Rekisteröityminen:

Rekisteröitynyt käyttäjä voi syöttää kantaan omia tutkimuksiaan

Rekisteröitynyt käyttäjä voi muuttaa omia henkilötietojaan

Rekisteröitynyt käyttäjä voi poistaa rekisteröintinsä milloin vain

Tutkimusten hallinta:

Näyttää käyttäjälle tiedot hänen omista tutkimuksistaan

Käyttäjä voi syöttää tietokantaan uusia tutkimuksia

Käyttäjä voi päivittää jo kantaan syöttämiään tutkimuksia

Käyttäjä voi poistaa jo kantaan syöttämiään tutkimuksia

Jäsentäjä GEDCOM lähteiden käsittelyyn:

Jäsentäjä on taustalla suoritettava jatkuva prosessi

Jäsentäjän ominaisuudet konfiguroitavissa

Tietokannan päivitys:

Jäsentäjä päivittää tutkimustauluun tutkimuksen tilan

Jäsentäjä päivittää tutkimustauluun tiedot jäsennyksen aikaisista virheistä

GEDCOM lähteiden jäsennys:

Jäsentäjä tutkii ajoittain tiettyä hakemistoa etsien uusia tutkimuksia

Jäsentäjä toimii rekursiivisesti käydessään läpi GEDCOM lähteen rakenteita

Mikäli jäsentäminen päättyy virheeseen, SQL-käskyjä ei kirjoiteta levylle

Lokien kirjoitus:

Kaikki lokit sijoitetaan omiin hakemistoihinsa niiden nimen ja tyypin mukaan

Jäsentäjä kirjoittaa jatkuvasti lokia omasta tilastaan

Jäsentäjä kirjoittaa lokin jokaisesta jäsentämästään tiedostosta

2.3 Ohjelmiston rajoitteet

JSP-tekniikalla toteutettu WWW-sivusto:

Rekisteröityneiden käyttäjien antamia yhteystietoja ei tarkisteta

Jäsentäjä GEDCOM lähteiden käsittelyyn:

GEDCOM lähteiden loogista rakennetta ei tarkasteta

Tietyt rakenteellisest virheet aiheuttavat koko tutkimuksen hylkäämisen:

• Tyhjä rivi GEDCOM aineistossa

• Virheellinen GEDCOM tiedoston loppu

GEDCOM standardin kaikkia ominaisuuksia ei tueta täydellisesti

Ansel-kielitukea ei ole toteutettu

2.4 Järjestelmän vaatimukset

Ohjelmisto on toteutettu Java-ohjelmointikielellä ja on periaatteessa siirrettävissä suoraan mihin tahansa järjestelmään ilman muutoksia. Ohjelman kääntämiseen ja käynnistämiseen, sekä SQL-komentojen suorittamiseen käytetyt komento skriptit ovat kuitenkin järjestelmä riippuvaisia ja toimivat ainoastaan Unix/Linux ympäristössä. Seuraavassa on lista järjestelmä vaatimuksista jotka ohjelmisto asettaa.

3.0 Asentaminen

3.1 Ulkoiset osat

3.1.1 TOMCAT

3.1.2 MySQL

Palvelinohjelmiston lisäksi ohjelmisto tarvitsee toimiakseen tietokantajärjestelmän, johon GEDCOM lähteistä kerätyt tiedot voidaan talletaa käyttöä varten. MySQL tietokantajärjestelmä, jolla ohjelmisto on testattu, on ladattavissa asennusohjeineen seuraavasta osoitteesta: http://www.mysql.com/downloads/

Kun tietokantajärjestelmä on asennettu, tarvitsee vielä luoda taulut joihin GEDCOM lähteistä kerätyt tiedot voidaan sijoittaa. Taulujen luontia varten seuraavassa on linkki tiedostoon joka sisältää SQL-komennot, jotka luovat tarvittavat taulut: http://www.mysql.com/downloads/

3.2 Sisäiset osat

Ulkoisten osien lisäksi itse ohjelmisto koostuu kahdesta erillisestä sisäisestä osasta. Ensimmäisen osan muodostavat JSP-sivut ja toisen osan Jäsentäjä. Molemmat osat käyttävät yhteistä konfiguraatio tiedostoa ja samoja luokkarakenteita, mutta toimivat toisistaan erillisinä kokonaisuuksina ja täysin toisistaan riippumatta. Sukututkimus ohjelmiston lähdekoodi on pakattu yhteen tar muotoon pakattuun tiedostoon nimeltään sukututkimus.tar

Lisäksi ohjelmiston mukana tulee 6 erillistä suoritettavaa komento tiedostoa, jotka helpottavat ohjelmiston käyttöä, mutta ovat järjestelmä riippuvaisia ja toimivat vain Linux/Unix yhteensopivassa käyttöjärjestelmässä.

3.2.1 Ohjelmiston asennus

Ohjelmiston asennus etenee seuraavasti:

Tässä vaiheessa ohjelmisto on asennettu onnistuneesti ja valmis käytettäväksi.

3.3 Ohjelmiston konfigurointi

3.4 Ohjelmiston käyttäminen

Kun ohjelmisto on onnnistuneesti asennettu ja käännetty se on valmis käytettäväksi. Ensin käynnistetään Tomcat palvelin. Tämän jälkeen käynnistetään tausta prosessit komento skriptillä startall.sh, joka sijaitsee sukutukimus hakemistoa yhtä alempana. Kyseinen skripti käynnistää Jäsentäjän, joka suorittaa GEDCOM lähde tiedostojen käsittelyn ja toisen komento skriptin start_sql.sh, joka puolestaan suorittaa Jäsentäjän tuottamat SQL-komennot.Ohjelmisto voidaan ajaa alas milloin vain tappamalla tausta prosessit.

4.0 Käyttöohje

Sivun yläosassa sijaitsevan päävalikon kautta käytetään järjestelmän toimintoja. Päävalikon kautta on mahdollista siirtyä pääsivulle, hallita tutkimuksia, käyttäjätietoja tai muodostaa hakuja. Lisäksi on mahdollista muuttaa valikoiden kieli. Päävalikon alta löytyy toiminnallisuus sisään tai ulos kirjautumiseen.

4.1 Hakujen tekeminen

Tutkimuksiin kohdistuvat yksilöhaut tehdään päävalikon Haku toiminnon kautta. Hakuja on mahdollista tehdä ilman rekisteröitymistä ja ne kohdistuvat kaikkiin tietokannassa oleviin tutkimuksiin. Haut koostuvat nimen osasta, syntymä- tai kuolinpaikkasta sekä syntämä- tai kuolinajasta. Haut muodostetaan täyttämällä Haku sivun kentät ja painamalla Hae. Jos haku tuottaa tuloksen, näytetään kaikki hakuehdot täyttäneet yksilöt. Valitsemalla muodostuneesta listasta nimi, päästään tarkastelemaan kyseistä yksilöä. Yksilöön liittyviä henkilöitä voidaan tämän jälkeen tutkia painamalla nimen kohdalla olevaa linkkiä. Yksilön suvusta näytetään isovanhemmat, vanhemmat, parisuhteet sekä parisuhteista syntyneet lapset. Muut yksilöön liittyvät tutkimukseen kirjatut tiedot löytyvät tältä sivulta.

4.2 Rekisteröityminen

Rekisteröityneen käyttäjän on mahdollista lisätä tietokantaan uusia tutkimuksia, sekä muokata ja poistaa itse lähettämiään tutkimuksia.

4.2.1 Käyttäjäksi rekisteröityminen

Rekisteröityminen tapahtuu valitsemalla päävalikon Rekisteröidy toiminto. Rekisteröityminen edellyttää nimen, käyttäjätunnuksen, salasanan, sähköposti- osoitteen sekä puhelinnumeron täyttämisen Rekisteröitymissivulle niille varatuille paikoilleen. Näin tehdyllä käyttäjätunnuksella on mahdollista kirjoittautua sisään järjestelmään.

4.2.2 Käyttäjätietojen muuttaminen

Muuttaakseen käyttäjätietojaan tulee olla kirjoittautuneena järjestelmään. Käyttäjätietojen muuttaminen onnistuu Käyttäjätiedot linkin kautta päävalikosta. Muuttuneet käyttäjätiedot syötetään vanhojen tilalle. Tiedot päivitetään järjestelmään valitsemalla Lähetä.

4.2.4 Rekisteröinnin poistaminen

Rekisteröinnin poistaminen edellyttää järjestelmään kirjoittautumista. Rekisteröinnin poistaminen onnistuu Käyttäjätiedot linkin kautta päävalikosta. Käyttäjätietojen, sekä kaikkien käyttjäjän tutkimusten poisto suoritetaan valitsemalla Poista tunnuksesi.

4.3 Tutkimusten hallinta

Tutkimusten hallinta edellyttää järjestelmään sisäänkirjautumista. Tutkimuksia voidaan lisätä, poistaa tai muokata päävalikon Tutkimusten hallinta linkin kautta. Muokkaus tarkoittaa vanhan tutkimuksen korvaamista uudella. Hallinta sivulla näytetään käyttäjän järjestelmään syöttämät tutkimukset sekä niiden tila.

4.3.1 Tutkimusten syöttö

Tutkimusten lisääminen edellyttää järjestelmään sisäänkirjautumista. Hallinta sivu löytyy päävalikon Tutkimusten hallinta linkin kautta. Ensin tutkimukselle annetaan järjestelmässä näkyvä nimi, jonka jälkeen tiedosto syötetään järjestelmään etsimällä se ensin browse toiminnon avulla omaltakoneelta ja tämän jälkeen painamalla lähetä, jolloin tiedosto lähetetään järjestelmään. Kun tiedosto on käsitelty, se näkyy käyttäjän tutkimusten listassa ja siihen voidaan kohdistaa hakuja.

4.3.2 Tutkimusten päivitys

Tutkimusten muuttaminen edellyttää järjestelmään sisäänkirjautumista. Hallinta sivu löytyy päävalikon Tutkimusten hallinta linkin kautta. Valitsemalla tutkimusvalikosta komento Update, jonka jälkeen korvaava tiedosto syötetään järjestelmään etsimällä se ensin browse toiminnon avulla käyttäjän koneelta ja tämän jälkeen painamalla lähetä, jolloin tiedosto lähetetään järjestelmään.

4.3.3 Tutkimusten poisto

Tutkimusten poistaminen edellyttää järjestelmään sisäänkirjautumista. Hallinta sivu löytyy päävalikon Tutkimusten hallinta linkin kautta. Valitsemalla tutkimusvalikosta komento Delete, poistetaan tutkimus järjestelmästä.

5.0 Ylläpito

5.1 Ohjelmiston hallinta

5.1.1 Tietokannan päivitys

5.1.2 Lokien kirjoitus

Ohjelmisto kirjoittaa lokia kaikkiaan neljästä eri lähteestä. Jäsentäjä kirjoittaa jtkuvasti lokia omasta tilastaan, mahdollisista virhetilanteista ja konfigurointi ongelmista. Kyseinen loki tiedosto löytyy hakemistosta Tomcat/webaps/sukututk/WEB-INF/classes/log/parser/.

Jokaisesta jäsennettävästä GEDCOM tutkimuksesta kirjoitetaan myös loki. Lokit sijoitetaan omiin hakemistoihinsa Tomcat/webaps/sukututk/WEB-INF/classes/log/ hakemiston alle tutkimuksen ID:n perusteella. Kirjoitettu loki tiedosto sisältää tietoa siitä mitä tietoa tutkimuksesta ei onnistuttu jäsentämään, eli mitä sisltöä ei talletettu tietokantaan.

Kolmanneksi taustalla ajettava komento skripti, joka suorittaa Jäsentäjän luomia SQL-komentoja kirjoitaa lokia omista toimistaan hakemistoon Tomcat/webaps/sukututk/WEB-INF/classes/log/sqllog/.

Myös TOMCAT kirjoittaa lokia. Lokit ovat hakemistossa Tomcat/logs.

5.1.3 Rakenteen ylläpito

Lukuunottamatta lokien kirjoitusta järjestelmän tila ja hakemistorakenne pysyy muuttumattomana suorituksen aikana. Mikäli ohjelmisto on käytössä yhtämittaisesti pitkiä aikoja olisi kuitenkin syytä ajoittain esimerkiksi poistaa turhia loki tiedostoja levytilan säästämiseksi. Lokien poistaminen ei vaikuta ohjelmiston toimintaan, kunhan hakemistorakenteeseen ei tehdä muutoksia. Poistot voi siis suorittaa vaikka suorituksen aikana.

5.2 Virhetilanteet ja toipuminen

5.2.1 Virheelliset syötteet

Virheelliset syötteet, erityisesti rakenteeltaan virheelliset GEDCOM-lähdetiedostot kuuluvat mahdollisista virhetilanteista lievimpiin. Niiden käsittely on automaattista, eikä ole millään tapaa riippuvainen ylläpidon toimenpiteistä. Virheellinen syöte saattaa aiheuttaa tutkimuksen hylkäämisen, mutta silloin tietokannan eheydestä huolehditaan siten, ettei rakenteeltaan virheellisestä tutkimuksesta muodosteta lainkaan SQL-komentoja. Java-rakenteiden avulla huolehditaan siitä, että muodostetut SQL-komennot ovat aina oikean tyyppisiä.

5.2.2 Parserin kaatuminen

Virheellinen GEDCOM-lähdetiedosto tai konfiguraation, saattaa aiheuttaa ohjelmiston, erityisesti Jäsentäjän kaatumisen tietyissä tilanteissa. Mikäli näin tapahtuu on syytä tarkistaa Jäsentäjän lokitiedostosta mikä aiheutti virhetilanteen. Mikäli kaatuminen aiheutui rakenteellisesti virheellisen lähdetiedoston jäsennyksen yhteydessä ei korjauksia tarvita. Jäsentäjä voidaan käynnistää uudelleen startall.sh skriptillä.

5.2.3 Tietokantaongelmat

Vakavimpiin ongelmiin kuuluvat tietokanta ongelmat voivat haitata koko järjestelmän toimintaa ratkaisevasti. Mikäli tietokanta rakenteet vahingoittuvat tai yhteys tietokantaan katkeaa esimerkiksi kesken SQL-komentojen suorittamista, saattaa kannan sisältö muuttua loogisesti virheelliseksi. Näistä ongelmista toipuminen ei tapahdu automaattisesti, vaan on mahdollista ainoastaan joko manuaalisesti poistamalla virheelliset tutkimukset tai väärät tiedot kannasta.

5.3 Ohjelmiston jatkokehitys

Sukututkimustietokanta-ohjelmisto on toiminnallisesti valmis kokonaisuus, mutta tilaa jatkokehitykselle löytyy myös. Ennenkaikkea tietokannan hallintaa varten olisi syytä tutkia mahdollisuutta luoda ylläpitoa varten JSP-sivusto jonka kautta koko kannan sisältöä voisi selata ja muokata.

Toiseksi olisi syytä kiinnittää huomiota Jäsentäjän toiminnallisuuden parantamiseen ja virheiden käsittelyyn. Järjestelmä riippuvista komento skripteistä olisi myös syytä hankkiutua eroon, sisällyttämällä niiden toiminta kokonaan Jäsentäjään, kuten SQL-komentojen suorittamisen tapauksessa. Lisäksi loki kirjoitus olisi syytä toteuttaa siten, että mahdollinen sisältö kirjoitettaisiin suoraan tietokantaan Research-tauluun kyseisen tutkimuksen Jäsennyksen yhteydessä, jolloin käyttäjät voisivat itse päästä tarkastelemaan mitä heidän tutkimuksestaan käytännössä hylättiin.

Kolmanneksi olisi syytä kiinnittää huomiota järjestelmän antamaan palautteeseen, jolla koko järjestelmän käytettävyyttä voitaisiin parantaa niin normaalien käyttäjien, kuin ylläpidonkin kannalta. Lisäksi olisi myös syytä kiinnittää huomiota tietokannan sisällön esittämiseen, erilaisten hakujen yhteydessä.

Monet yllä mainituista kohdista on jo osittain toteutettu, kyse onkin lähinnä parannusten toteuttamisesta sen sijaan että lisättäisiin uusia toimintoja. Esimerkiksi Jäsentäjä on jo suorassa yhteydessä tietokantaan ja päivittää Research-tauluun tietoja tutkimuksen tilasta reaaliaikaisesti. Parannukset eivät sinänsä vaadikaan uusien luokkien tai ulkoisten osien lisäyksiä ohjelmistoon, vaan ne voidaan toteuttaa laajentamalla jo olemassa olevaa toiminnallisuutta.