Tik-76.115 Toteutusmäärittely

Aiheen nimi: TRAKLA-järjestelmän kehittäminen

• viimeinen muutos 3.7.1996
• muutoshistoria:

Sisällysluettelo

1. Johdanto
2. Järjestelmän yleiskuvaus
3. Arkkitehtuurin kuvaus
4. Moduuli (ja prosessi) -kuvaukset
5. Moduulien toteutuksen kuvaus

1. Johdanto

TRAKLA on Tik-76.122 Tietorakenteet ja algoritmit -kurssin kotitehtävien jakeluun, vastausten palautukseen, tarkastukseen ja arvosteluun tarkoitettu järjestelmä.
Järjestelmään liittyvät käsitteet on selostettu erillisessä sanastossa.

Tämän dokumentin Järjestelmän yleiskuvaus -osassa ovat linkit seuraaviin kuvauksiin: sovellusalue ja järjestelmän osuus siinä, laitteisto- ja ohjelmistoympäristö, toteutuksen keskeiset reunaehdot ja järjestelmän liittyminen ympäristöön.

Arkkitehtuurin kuvauksessa on esitelty järjestelmän ratkaisuperiaatteet, tietokanta-arkkitehtuuri ja ohjelmistoarkkitehtuuri sekä moduulit ja prosessit.

Moduulikuvaukset tulevat sisältämään kustakin moduulista yleiskuvauksen ja moduulien toteutuksen kuvauksen sekä moduulien funktioiden esittelyn.

2. Järjestelmän yleiskuvaus

TRAKLA on itsenäinen järjestelmä, jolla on liittymä ainoastaan opintosuoritusrekisteriin. Järjestelmä tuottaa pistetiedot kotitehtävien arvosanaa varten. Tiedoista tietojenkäsittelyopin laboratorion kanslia muodostaa opiskelijoille kurssin arvosanan, joka menee opintosuoritusrekisteriin.

3. Arkkitehtuurin kuvaus

3.1 Ratkaisuperiaatteet

TRAKLA-järjestelmä koostuu neljästä toiminnaltaan suhteellisen itsenäisestä osajärjestelmästä; tiedonhallinta, tehtävät, postiserveri ja assistentin käyttöliittymä.

Tiedonhallinta

Tiedonhallinta toimii järjestelmän muiden osien rajapintana tietokantaan. Järjestelmän sovellusohjelmat käsittelevät tietokantaa tiedonhallinnan funktioiden välityksellä.

Tehtävät

Tehtävät jakautuvat toiminnallisesti kahteen osaan; tehtävien generointi ja tehtävien tarkastus.
Tehtävien generointi työstää opiskelijalle kierroskohtaiset yksilölliset kotitehtävät ja tarkastus suorittaa ko. tehtävien vastausten tarkastuksen ja pisteytyksen.
Tehtävien generointi ja tarkastus koostuvat itsenäisistä tehtäväkohtaisista moduuleista, joten kurssin perustamisen yhteydessä voidaan kurssin tehtäväkierrosten lukumäärä ja kierrosten tehtävät määritellä kurssikohtaisesti.

Serveri

Postiserveri on sähköposti-pohjainen opiskelijan käyttöliittymä TRAKLA-järjestelmään. Serveri koostuu kahdesta osasta; vastaanotto-serveri, joka ottaa vastaan opiskelijan lähettämät viestit ja suorittaa viesteissä määritellyn toimenpiteen, ja lähetys-serveri, joka huolehtii järjestelmän lähettämien viestien lähettämisestä opiskelijalle sähköpostin välityksellä.

Assistentin käyttöliittymä

Assistentti perustaa kurssin käyttöliittymän avulla luomalla kurssikohtaisen hakemiston ja tiedostot. Sen jälkeen hän päivittää editorilla kurssitietoihin kurssin, kierroksien ja tehtävien tiedot.

3.2 Tietokanta-arkkitehtuuri

Tietokannat toteutetaan ASCII-tiedostoina. Hakemistorakenne on esitetty seuraavassa kaaviossa.

   data
    |
    |--- tehtavarungot
    |    |
    |    |--- 1.<nimi1>
    |    |--- 2.<nimi2>
    |    |--- jne.  (Muut tehtävärungot omina tiedostoina)
    |
    |--- kurssimalli  (Ehdotus kurssin kierroksista ja tehtävistä)
    |--- help  (Traklan help-viesti) 
    |--- lokit
    |    |
    |    |--- scripti_loki
    |    |--- toiminto_loki
    |    |--- tarkistus_loki
    |    |--- virheet
    |
    |--- kurssit
         |
         |--- <kurssi1> (Jokaiselle kursille oma hakemisto)
         |    |
         |    |--- kurssi
         |    |--- opiskelijat
         |    |--- pistemaarat
         |    |--- vastaukset
         |    |    |
         |    |    |--- <n> (Tiedostot numeroitu juoksevasti)
         |    |
         |    |--- harjoittelu_vastaukset
         |    |    |
         |    |    |--- <n> (Tiedostot numeroitu juoksevasti)
         |    |
         |    |--- erillistilaukset
         |    |    |
         |    |    |--- <n> (Tiedostot numeroitu juoksevasti)
         |    |
         |    |--- lahetettavat_kirjeet
         |    |    |
         |    |    |--- <n> (Tiedostot numeroitu juoksevasti)
         |    |
         |    |--- postit
         |
         |--- <kurssi2>
         |    |
         |    |--- kurssi
         |    |--- jne. (Loput kurssikohtaiset tiedostot)

Tiedostojen tietosisältö on kuvattu seuraavassa luettelossa. Tietosisällöt ja tietojen kuvaukset tarkentuvat prototyypin totetutusvaiheessa. Toiminnallisen määrittelyn kohdassa 3.1.1 Tietoryhmät on selostettu tietojen tarkoitus.

• kurssi
• kurssi_id
• alkpvm
• loppvm
• kierros (useita)
• kierno
• viim_pal_pvm
• viim_klo
• generointi_aika
• tehtava (useita)
• tehtno
• tehtnimi
• maxpisteet
• opiskelijat
• opiskelija (useita)
• opkno
• nimi
• email_id
• pistemaarat
• pistemaara (useita)
• opkno
• kierno
• tehtno
• tarkistus_aika
• pisteet
• vastaukset/<n>
• opkno
• kierno
• tehtno
• palautus_aika
• vastteksti
• harjoittelu_vastaukset/<n>
• email_id
• kierno
• tehtno
• harjteksti
• erillistilaukset/<n>
• opkno
• tyyppi
• kierno
• email_id
• lahetettavat_kirjeet/<n>
• email_id
• sisalto
• postit
• kirje (useita)
• tehtavarungot/<n>.<nimi>
• sisältää tehtävän tekstiosan
• kurssimalli
• sisältää samat tiedot kuin kurssi
• help
• sisältää TRAKLAn serveri-komennot
• scripti-loki
• sisältää ajoihin liittyvät lokitiedot
• toiminto-loki
• sisältää järjestelmän kaikkiin toimintoihin liittyvät lokitiedot
• tarkistus-loki
• sisältää tehtävien tarkistukseen liittyvät lokitiedot
• virheet
• sisältää kaikista virhetilanteista syntyvät virheilmoitukset

3.3 Ohjelmistoarkkitehtuuri, moduulit ja prosessit

Järjestelmän prosesseja ovat (ohjelmien nimet ovat suluissa):

    prosessit
    |
    |--- assistentin käynnistämät
    |    |
    |    |--- kurssin perustaminen  (kurssin_perustaminen)
    |    |--- kierroksen tehtävien generointi
    |    |      (tehtävien_massagenerointi)
    |    |--- kierroksen mallivastausten generointi ja pisteiden
    |         laskenta  (mallivastausten_massagenerointi)
    |    
    |
    |
    |--- ajoitetut, määrävälein käynnistyvät 
         |
         |--- vastaanottoserveri  (receive)
         |--- erillistilaukset  (erillistilaukset)
         |--- harjoitteluvastausten käsittely  (harjoitteluvastaukset)
         |--- tehtävien tarkastus  (tarkastus)
         |--- lähetysserveri  (send)
         

Uuden kurssin alkaessa assistentti suorittaa kurssin perustamisen. Jokaisen kierroksen alkaessa assistentti käynnistää massageneroinnin. Jokaisen kierroksen viimeisen palautuspäivän jälkeen assistentti käynnistää mallivastausten massageneroinnin.

Ajoitetut, määrävälein käynnistyvät prosessit suoritetaan peräkkäin yllä olevan kaavion mukaisessa järjestyksessä. Samoista tiedostoista tietoa hakevat ja sinne vievät prosessit eivät saa olla suorituksessa samanaikaisesti. Tämä hoidetaan prosessien lukituksella, jolla myös estetään saman prosessin käynnistyminen useampaan kertaan.

4. Moduuli (ja prosessi) -kuvaukset

4.1 Tiedonhallinnan moduulit

Tiedonhallinnan funktiot on ryhmitelty tiedostoittain, joihin toimenpiteet kohdistuvat. Kuvatut funktiot ovat rajapintafunktioita, joita muut osajärjestelmät käyttävät. Tiedonhallinnan sisäiset funktiot kuvataan prototyypin toteutusvaiheessa.
Funktioiden nimet ovat vanhan järjestelmän mukaisia.

• anna_seuraava_kurssi; hakee seuraavan kurssin tiedot
• anna_kierros; hakee meneillään olevan kierroksen tiedot
• kirjaa_tehtavien_generointi; tallettaa kierroksen tehtävien generointiajan

• kirjaa_ilmoittautuminen; tallettaa opiskelijan tiedot
• anna_opiskelijan_henkilotiedot; hakee tietyn opiskelijan tiedot
• anna_seuraava_opiskelija; hakee seuraavan opiskelijan tiedot

• kirjaa_tehtavan_pisteet; tallettaa opiskelijan tehtävästä saaman pistemäärän
• anna_arvostelu_kysely; hakee tietyn opiskelijan pistetilanteen

• tallenna_palautettu_vastaus; tallettaa vastauksen
• nouda_palautettu_vastaus; hakee seuraavan vastauksen
• poista_palautettu_vastaus; poistaa käsiteltävän vastauksen

• tallenna_harjoittelu_vastaus; tallettaa harjoitteluvastauksen
• nouda_harjoittelu_vastaus; hakee seuraavan harjoitteluvastauksen
• poista_harjoittelu_vastaus; poistaa käsiteltävän harjoitteluvastauksen

• tallenna_erillistilaus; tallettaa erillistilauksen
• nouda_erillistilaus; hakee seuraavan erillistilauksen
• poista_erillistilaus; poistaa käsiteltävän erillistilauksen

• tallenna_lahteva_kirje; tallettaa lähetettävän kirjeen
• nouda_lahteva_kirje; hakee seuraavan lähetettävän kirjeen
• poista_lahteva_kirje; poistaa käsiteltävän lähetettävän kirjeen

• tallenna_saapunut_kirje; tallettaa saapuneen kirjeen

• anna_tehtava_runko; hakee tietyn tehtävän rungon

• kirjaa_lokiin; kirjoittaa ilmoituksen lokiin normaali- tai virhetilanteesta

• siirra_epaonnistunut_vastaus; kirjoittaa epäonnistuneesti tarkistetun vastauksen virhetiedostoon
• kirjaa_virheisiin; kirjoittaa virheilmoituksen

• avaa_tietokanta; avaa tiedoston
• sulje_tietokanta; sulkee tiedoston

4.2 Tehtävien moduulit

Tehtävien massagenerointi tuottaa kierroksen alkaessa kotitehtävät kaikille opiskelijoille.
Tehtävien tarkastus on ohjelma, joka tarkastaa saapuneet vastaukset ja kirjaa pisteet tietokantaan säännöllisin väliajoin tehtäväkierroksen palautusaikana.

Mallivastausten massagenerointi on ohjelma, joka lähettää opiskelijoille mallivastaukset ja pistetilanteen vastausten viimeisen palautuspäivän ja tarkastusten jälkeen. Moduuli ajetaan kerran per kotilaskukierros.
Erillistilaukset lukee erillistilaukset-tiedostosta tehtävätilauksia, malliratkaisu- ja pistetilannepyyntöjä ja toteuttaa pyynnön mukaisen toiminnon.
Harjoitteluvastaukset lukee harjoittelu_vastaukset -tiedostoa, tarkistaa välittömästi tehtävät, arvostelee ne, generoi malliratkaisut ja kirjoittaa ratkaisut ja pisteet lahetettavat_kirjeet -tiedostoon.

Tehtävien massageneroinnin ja tehtävien tarkastuksen rakenne on luonnosteltu tässä vaiheessa, mutta muut moduulit tarkennetaan prototyypin toteutusvaiheessa.

Tehtävien massagenerointi

main
	avaa_prosessilukko
	tehtavien_generointi
		avaa_tietokanta		(TOIMINTO_LOKI)
		avaa_tietokanta		(KURSSI)
		avaa_tietokanta		(TEHTAVARUNGOT)
		avaa_tietokanta		(OPISKELIJAT)
		avaa_tietokanta		(LAHETETTAVAT_KIRJEET)
		anna_tehtava_koodit
		anna_tehtava_runko
		anna_seuraava_opiskelija
		generoi_opiskelijan_tehtavat
			anna_opiskelijan_henkilotiedot
			generoi_tehtava
				tailor_*_* (useita funktioita)
			tallenna_lahteva_kirje
		sulje_tietokanta	(KURSSI)
		sulje_tietokanta	(TEHTAVARUNGOT)
		sulje_tietokanta	(OPISKELIJAT)
		sulje_tietokanta	(LAHETETTAVAT_KIRJEET)
		sulje_tietokanta	(TOIMINTO_LOKI)
	sulje_prosessilukko

Tehtävien tarkastus

main
	avaa_prosessilukko
	vastausten_generointi
		avaa_tietokanta		(TOIMINTO_LOKI)
		avaa_tietokanta		(VIRHEET)
		avaa_tietokanta		(KURSSI)
		avaa_tietokanta		(TEHTAVARUNGOT)
		avaa_tietokanta		(OPISKELIJAT)
		avaa_tietokanta		(PISTEMAARAT)
		avaa_tietokanta		(VASTAUKSET)
		anna_tehtava_koodit
		anna_tehtava_runko
		nouda_palautettu_vastaus
		tarkasta_opiskelijan_tehtavat
			anna_opiskelijan_henkilotiedot
			tarkasta_vastaus
				check_*_* (useita funktioita)
			kirjaa_tehtavan_pisteet
			kirjaa_vastauksen_tarkistus
			poista_palautettu_vastaus
		sulje_tietokanta	(KURSSI)
		sulje_tietokanta	(TEHTAVARUNGOT)
		sulje_tietokanta	(OPISKELIJAT)
		sulje_tietokanta	(PISTEMAARAT)
		sulje_tietokanta	(VASTAUKSET)
		sulje_tietokanta	(VIRHEET)
		sulje_tietokanta	(TOIMINTO_LOKI)
	sulje_prosessilukko

4.3 Serverin moduulit

Serveri jakautuu kahteen ohjelmaan lähetysserveriin ja vastaanottoserveriin.

Vastaanottoserveri on pääohjelma, joka lukee saapuneita viestejä mailboxista. Ohjelmasta kutsutaan rfc-moduulia, joka jäsentää sähköpostiviestin header-osan ja cmdparcer-moduulia, joka jäsentää ja tulkitsee itse viestin.
get_from ja get_reply-to ovat rfc-moduulin funktioita ja server_commands cmdparcer-moduulin funktio.

Lähetysserveri on pääohjelma, joka pyytää yksitellen tietokannalta lähetettävät kirjeet, kutsuu lähetysfunktiota ja merkitsee kirjeet lähetetyiksi.

Serverin moduulien rakennekaaviot täydennetään prototyypin toteutusvaiheessa.

Serverin ohjelmien rakennekaavio:

Lähetysserveri

    main
    |
    |--------- lukitse_processi        
    |--------- avaa_tietokanta
    |--------- vapauta_processi
    |--------- nouda_lahteva_kirje
    |--------- send_mail
    |--------- poista_lahteva_kirje
    |--------- sulje_tietokanta
    |--------- vapauta_process

Vastaanottoserveri

    main
    |
    |-------- avaa_tietokanta
    |-------- get_from
    |         |--------------get_person
    |         |              |------------get_rfc
    |-------- get_reply_to
    |         |--------------get_person
    |         |              |------------get_rfc
    |-------- server_commands
    |         |--------------execute
    |                        |------------order
    |                        |            |-------anna_
    |                        |            |       opiskelijan_
    |                        |            |       henkilotiedot
    |                        |            |-------avaa_
    |                        |            |       tietokanta
    |                        |            |-------anna_kierros
    |                        |            |-------tallenna_
    |                        |            |       erillistilaus
    |                        |            |-------sulje_
    |                        |                    tietokanta
    |                        |------------registration
    |                        |            |-------get_reply_to
    |                        |            |-------get_from
    |                        |            |-------avaa_tietokanta
    |                        |            |-------kirjaa_
    |                        |            |       ilmoittautuminen
    |                        |            |-------tallenna_ 
    |                        |            |       erillistilaus
    |                        |            |-------sulje_tietokanta
    |                        |------------report
    |                        |            |-------anna_opiskelijan_
    |                        |            |       henkilotiedot
    |                        |            |-------anna_kierros
    |                        |            |-------anna_arvostelukysely
    |                        |            |-------t_per_k
    |                        |------------exercise
    |                                     |-------anna_kierros
    |                                     |-------argumenttivalitus
    |                                     |-------tallenna_palautettu_
    |                                     |       vastaus
    |                                     |-------kirjaa_vastauksen_
    |                                     |       palautus
    |                                     |-------add_exc
    |-------- nak
    |-------- ack
    |-------- sulje_tietokanta

4.4 Käyttöliittymän moduulit

Kurssin perustaminen luo uudelle kurssille kurssit-hakemistoon oman alihakemiston ja sen alle tarvittavat alihakemistot ja tiedostot. Kurssimalli-tiedoston pohjalta luo kurssi-tiedoston sisällön.

5. Moduulien toteutuksen kuvaus

Modulien toiminnan yksityiskohtaiset kuvaukset kirjoitetaan ohjelmakoodeihin kommenteiksi.