1. Ohjelmointi 3: rajapinnat ja tekniikat »
  2. Harjoitustyön aloitus »
  3. Projekti: Sisusta selvää

Projekti: Sisusta selvää

Projekti tehdään oletusarvoisesti 2–3 hengen ryhmissä.

Jokaisen ryhmän jäsenen henkilökohtainen työpanos on oltava näkyvissä ohjelmassa!

Harjoitustyön yksin tekevät ja ryhmättömät!

Yksittäinen opiskelija ei voi luoda ryhmää Plussassa ja jää siksi ilman tietovarastoa, joka tarvitaan harjoitustyön tekemiseen ja palauttamiseen ilman yhteydenottoa kurssin opettajiin. Ota yhteyttä kurssin vastuuopettajiin (jorma.laurikkala@tuni.fi ja mika.saari@tuni.fi), jos haluat tehdä työn yksin. Ota yhteyttä kurssisähköpostin (prog3@tuni.fi) kautta, jos haluat tehdä työn ryhmässä, mutta et ole vielä löytänyt ryhmääsi. Kerro jälkimmäisessä tapauksessa tavoitearvosanasi, jotta opettajat voivat liittää sinut ryhmään, jolla on samankaltaiset tavoitteet. Huomaa, että ei ole taattua, että ryhmä löytyy, jos sitä ei ole löytynyt tähän mennessä. Opiskelija voi tehdä harjoitustyön yksin, jos hän jää ilman ryhmää.

Takarajat

  • Lopullinen palautus: perjantai 28.4.2023 klo 23.59.

  • Armonaika päättyy: perjantai 5.5.2023 klo 23.59.

    • Projektille myönnetään automaattisesti viikko lisäaikaa. Tämä niin sanottu armonaika alkaa virallisen takarajan jälkeen.

    • Armoaikaa katsotaan käytetyksi, jos projektille on tehty yksikin palautus armonajan kuluessa.

    • Armonajallakin palautus kannattaa tehdä mahdollisimman aikaisin, koska arvostelu kiristyy koko ajan lisäajan kuluessa.

      • Ykkösen raja pysyy samana armonajasta huolimatta.

      • Muita arvosanarajoja nostetaan heti armonajalle siirryttäessä puolella arvosanalla. Jos projekti on palautettu heti normaalin takarajan jälkeen, sen on arvosanan 4 saadakseen saatava arvosanan 4,5 edestä pisteitä, arvosanan 3 uusi raja on arvosanan 3,5 raja ja niin edelleen.

      • Rajoja nostetaan armonajan kuluessa edelleen niin, että sen lopussa arvosanan 4 raja on alkuperäisen arvosanan 5 tasolla. Muut arvosanat on skaalattu vastaavasti. Rangaistusvaikutus ei ole hyppäyksittäinen, vaan kovenee liukuvasti koko ajan.

  • Projektista, joka ei täytä minivaatimuksia, voi saada niin sanotun bumerangin, jolloin on viikko aikaa korjata työ.

Osaamistavoitteet

Projektissa harjoitellaan seuraavia asioita käytännössä:

  • Toiminnallisuuden lisääminen sovellukseen olio-ohjelmointia hyödyntäen.

  • Ulkoisten kirjastojen käyttö (sopimussuunnittelu).

  • Graafisen käyttöliittymän toteuttaminen osaksi ohjelmaa.

  • Oman koodin testaus yksikkötasolla.

  • Ohjelman toteuttaminen tiimityönä.

Toteutettava ohjelma

Sisu aiheuttaa ennenaikaisia harmaita hiuksia, joten mahdollistaaksesi helpon tavan pitää kirjaa siitä, missä tutkinnon suorituksen kanssa mennään, päätät toteuttaa ohjelman sitä varten. Ohjelmalla voidaan tarkastella Tampereen yliopiston tutkinto-ohjelmien rakennetta. Lisäksi ohjelmassa voi seurata käyttäjän omien opintojen etenemistä. Käyttäjä voi määrittää tutkinto-ohjelman omakseen ja merkitä siihen kursseja suoritetuksi sitä mukaa, kun opinnot etenevät.

Ohjelman kulku

Ohjelmaa käynnistettäessä tulee ensin näkyviin asetusikkuna, jossa annetaan esimerkiksi opiskelijan nimi ja opiskelijanumero sekä mahdollisesti opintojen aloitusvuosi tai valmistumisen tavoitevuosi. Asetuksien valinnan jälkeen siirrytään ohjelman pääikkunaan, josta valitaan opiskelijalle tutkinto-ohjelma, opintosuunta ja muita mahdollisesti tarvittavia tietoja. Tutkinto-ohjelmaa ja opintosuuntaa voi vaihtaa pääikkunassa. Tutkinto-ohjelman valintanäkymän lisäksi voidaan näyttää opiskelijan opintojen etenemisnäkymä, jossa näytetään opiskelijan suoritusten sen hetkinen tilanne. Opiskelija voi tässä näkymässä merkitä kurssejaan suoritetuksi.

Opiskelijatiedot ovat henkilötietoja, joille määriteltellään oma JSON-tiedosto. Ohjelman suoritus päättyy pääikkunasta nappia painamalla. Tällöin opiskelijan eteneminen talletetaan JSON-tiedostoon.

Alla on hahmotelma siitä, miltä ohjelman käyttöliittymä saattaisi näyttää:

../../_images/gui_luonnos.png

Monet ohjelman yksityiskohdat on jätetty tässä tarkoituksella avoimiksi ja ne voi toteuttaa parhaaksi katsomallaan tavalla. Tällaisia asioita ovat muun muassa:

  • Ohjelman tarkka alkutilanne: Mikä on ohjelman alkutila ja mitä tietoa se kysyy ohjelman alussa käyttäjältä?

  • Ohjelman käyttöliittymä: Miten ohjelman eri toimintoja voidaan suorittaa?

  • Käyttäjän rooli ohjelmassa: Miten opiskelijan eteneminen esitetään?

  • Kurssitietojen esittäminen: Millaisella näkymällä kurssitiedot esitetään? Millä tarkkuudella yhden kurssin tiedot esitetään?

Työn pohjaksi on tarjottu projektin ryhmäkohtaisessa etätietovarastossa yksinkertainen JavaFX-projekti, joka luo ja avaa tyhjän ikkunan. Projekti on Maven-muotoinen ja sen voi avata suoraan NetBeansilla. Pohja sellaisenaan on tarkoitettu lähinnä arvosanaa 1 tavoitteleville.

Ohjelman ominaisuudet

Harjoitustyössä on toteutettava ainakin minimitoteutuksen ominaisuudet. Minimitoteutuksen täyttävästä työstä voi ansaita hyväksytyn suorituksen (arvosana 1). Perustoteutukselle määriteltyjen ominaisuuksien mukaisella toteutuksella voi työstä ansaita korkeintaan arvosanan 3. Korkeampi arvosana edellyttää perustoteutuksen lisäksi joidenkin lisäominaisuuksien toteutusta tai lisätyötä.

Projektipisteistä muodostuu osa-arvosana kaavalla arvosana = pisteet / 100. Projektipisteet muodostavat 35% kurssin kokonaisarvosanasta.

Minimitoteutus

Maksimiarvosana 1. Maksimissaan 140 pistettä.

Minitoteutuksesta tulee löytyä seuraavat ominaisuudet:

  • Ohjelma kääntyy.

  • Ohjelmassa on yksi dialogi-ikkuna, esimerkiksi alkumenu.

  • Ohjelma käyttää pääikkunanaan valmiina annettua toteutusta.

  • Ohjelma hakee tutkintojen rakennetiedot määritellyistä JSON-tiedostoista ja käyttää tiedostojen käsittelyyn tarkoitettua rajapintaa niiden lukemisen toteuttamisessa.

  • Ohjelma osaa näyttää valitun tutkinnon rakenteen pääikkunassa.

  • Ohjelmassa on käytetty periytymistä rakenteen osien toteuttamisessa.

  • Loppudokumentti, josta löytyy:

    • Luokkien vastuujako. UML:n luokkakaavio on tässä hyödyllinen.

    • Ryhmän työnjako

Toteuttamalla minimitoteutuksen päälle määriteltyjä perus- ja lisäominaisuuksia sekä muilla harjoitustyön ansioilla saa kerrytettyä lisää projektipisteitä.

Perustoteutus

Maksimiarvosana 3. Vähintään 300 pistettä.

Perustoteutus sisältää minimitoteutuksen ominaisuudet, mutta lukee tutkintojen rakennetiedot JSON-tiedostojen sijasta verkosta. Perustoteutus hakee rakennetiedot Sisun API:sta ja käyttää API-tietojen lukemisen toteuttamiseen siihen tarkoitettua rajapintaa.

Perustoteutuksella on lisäksi seuraavat ominaisuudet:

  • Ohjelmaan on toteutettu omatoimisesti graafinen käyttöliittymä. Voit käyttää pohjana valmiina annettua projektia, mutta tällöin käyttöliittymässä on oltava selkeää omaleimaisuutta annettuun pohjaan verrattuna.

  • Näytettävää tutkintoa voi vaihtaa ja opiskelijan tutkinnon tilanne esitetään ohjelmassa.

  • Ohjelma selviää hallitusti asetustiedostojen käsittelyssä tapahtuvista virheistä.

  • Ohjelmalle on toteutettu yksikkötestejä.

Toteuttamalla lisäominaisuuksia voi saada lisäpisteitä. Yksi lisäominaisuus on lähtökohtaisesti 50–100 pistettä. Lisäpisteitä voi saada myös työn lisäansioista. Toteutuksen lisäpisteillä voi kompensoida virheitä yhden arvosanan verran.

Huipputoteutus

Maksimiarvosana 5. Vähintään 500 pistettä.

  • Ohjelmassa on toteutettuna vähintään kaksi lisäominaisuutta. Yksi lisäominaisuus on lähtökohtaisesti 50–100 pistettä.

Pisteitä voi saada myös lisäansioista. Toteutuksen lisäpisteillä voi kompensoida virheitä yhden arvosanan verran.

Lisäominaisuudet

Alla olevia lisäominaisuuksia ei ole pakko toteuttaa, mutta hyvästä toteutuksesta ansaitsee lisäpisteitä. Lähtökohtaisesti kukin lisäominaisuus on arvoltaan 50–100 pistettä. Yksittäisen lisäominaisuuden arvoa voidaan kuitenkin tarvittaessa kasvattaa myöhemmin, jos se osoittautuu erityisen työlääksi. Pisteiden saaminen lisäominaisuudesta edellyttää, että ominaisuus on dokumentoitu palautuksessa siten, että se on selkeästi esitetty lisäosaksi. Töiden tarkastajat eivät etsi lisäominaisuuksia palautetusta koodista.

  • Kurssin katselunäkymä. Kurssista näytetään lisätietoja näytöllä, kun hiiren kursori viedään kyseisen kurssin yläpuolelle.

  • Opiskelija-asetukset. Ohjelman käynnistyksen yhteydessä avataan asetusikkuna, josta voi asettaa ohjelmaa käyttävän opiskelijan tiedot. Suorituksen tilanne haetaan JSON-tiedostosta ja tallennetaan sinne.

  • Opiskelijan opintojen etenemisen aikataulun esittäminen tutkinnon rakenteeseen peilaten.

  • Opettajaroolin lisääminen ohjelmaan.

  • Sisun API:sta löytyvän jonkin tietokokonaisuuden, kuten arviointikohteiden, esittäminen osana ohjelmaa.

  • Ohjelmaan on toteutettu graafista käyttöliittymää testaavat yksikkötestit. Käytä JavaFX-käyttöliittymän testaamiseen TestFX-testikehystä.

  • Oma lisäominaisuus. Ohjelmaan on toteutettu jokin itse keksitty tämän listan ulkopuolinen lisäominaisuus, joka vaatii selkeästi itsenäistä koodausta.

  • Huom! Lisäominaisuuden pitää olla selkeästi koodaustyötä vaativa ominaisuus.

  • Huom! KAIKKI LISÄOMINAISUUDET PITÄÄ DOKUMENTOIDA PISTEET SAADAKSEEN.

Lisäansiot

Lisäominaisuuksien hyväksi harjoitustyölle voidaan antaa lisäpisteitä lähinnä lisätyöstä seuraavasti:

  • Ylimääräiset, hyvin toteutetut yksikkötestit (korkeintaan 150 pistettä).

  • Korkeatasoinen grafiikka (korkeintaan 100 pistettä).

  • Erittäin hyvä käyttöliittymä (korkeintaan 100 pistettä).

  • Laadukkaasti dokumentoidut rajapinnat ja luokat (korkeintaan 50 pistettä).

Arvosanan määräytyminen

Arvosana määräytyy valitun toteutustason (minimi, perus tai huippu) ominaisuuksista saatujen pisteiden ja mahdollisten lisäpisteiden summan mukaan. Toteutustasot rajaavat maksimiarvosanaa yllä määritellyllä tavalla.

Arvosteltavat osiot:

  • Ohjelman suunnittelu ja kokonaisrakenne.

  • Luokkasuunnittelu ja toteutus:

    • Olio-ohjelmoinnin periaatteiden käyttö.

    • Luokkien ja rajapintojen dokumentaatio.

  • Poikkeuskäsittely:

    • Poikkeusten oikea käyttö ja käsittely.

  • Koodin laatu:

    • Hyvien ohjelmointitapojen ja -periaatteiden noudattaminen.

    • Koodityyli.

  • Versiohistoria ja tiimityö.

  • Lisäpisteet:

    • Annetaan lisäominaisuuksista ja lisäansioista (erityisen hyvin toteutetut toiminnallisuudet).

Ympäristö

Ryhmän etätietovarasto

Kullekin Plussassa muodostetulle ryhmälle on luotu oma GitLab-etätietovarasto. Tietovaraston osoite on

https://course-gitlab.tuni.fi/compcs140-spring2023/group----,

missä ---- on Plussan ryhmätunnus. Jos tunnus on esimerkiksi 1234 on ryhmän etätietovarasto osoitteessa

https://course-gitlab.tuni.fi/compcs140-spring2023/group1234.

Tietovarastossa on valmis JavaFX-projektipohja sekä Sisun dataa sisältäviä JSON-tiedostoja. Projekti on Maven-muotoinen ja avautuu suoraan NetBeans IDE:llä. Kloonaa tämä tietovarasto omaksi paikalliseksi tietovarastoksesi.

Ota yhteyttä kurssisähköpostiosoitteen (prog3@tuni.fi) kautta, jos ryhmäsi etätietovarasto puuttuu.

Aseta harjoitustyön materiaalien etätietovarasto remoteksi paikalliseen tietovarastoosi siltä varalta, että harjoitustyöhön julkaistaan korjauksia tai lisämateriaalia.

Versionhallinnan käyttö on sekä arvosteltava osa projektia että osoitus tiimityöstä. Ryhmän etätietovaraston tulee sisältää jokaiselta ryhmän jäseneltä selkeä kontribuutio projektiin.

Jatkuva integrointi

Etätietovaraston juuressa on annettu .gitlab-ci.yml-niminen tiedosto, joka määrittää kuinka GitLab suorittaa niin sanotun CI/CD-putken. Putki tukee jatkuvaan integraatioon perustuvaan ohjelmistokehitystä siten, että se suorittaa kunkin puskun jälkeen .gitlab-ci.yml-tiedostossa määritellyt tehtävät. Tiedostoon on määritelty varmiiksi build-tehtävä, joka kääntää projektin Mavenin avulla.

CI/CD-putken käyttäminen on vapaaehtoista. Nimeä .gitlab-ci.yml uudelleen tai poista se, jos et halua projektia käännettävän jokaisen puskun jälkeen. Huomaa kuitenkin, että putki on helppo tapa tunnistaa ainakin kieliopillisesti rikki olevat tiedostot, joita niitäkään ei saisi puskea tietovarastoon.

Jatkuvaa integrointia on mahdollista laajentaa testaukseen. GitLabiin on määritelty ajuri (runner), joka suorittaa test-tehtävän, jos ryhmä on sellaisen määritellyt omatoimisesti .gitlab-ci.yml-tiedostoon. Muista antaa myös tälle tehtävälle compcs140-tunniste (tag). Test-tehtävä määrittelemällä voi vahvistaa työtään testauksen osalta ja kenties hankkia näin lisää lisätyöstä annettavia lisäpisteitä.

Sisun API:n käytöstä

Sisun dataan pääsee käsiksi verkossa muun muassa Kori API:n kautta. API palauttaa dataa JSON-muodossa.

Harjoitustyön kannalta oleellinen tieto on, että listan yliopistomme tutkintorakenteista saa suorittamalla www-pyynnön https://sis-tuni.funidata.fi/kori/api/module-search?curriculumPeriodId=uta-lvv-2021&universityId=tuni-university-root-id&moduleType=DegreeProgramme&limit=1000.

Tutkintojen rakenteet on kuvattu Sisussa käyttäen suunnilleen seuraavanlaista tyyppihierarkiaa:

  • Abstrakti kattotyyppi Module.

  • DegreeProgramme.

    • Tutkintorakenteen juuritaso, joka kertoo tutkinnon nimen, laajuuden opintopisteinä ja niin edelleen.

  • StudyModule.

    • Opintokokonaisuus, jonka alaisuudessa on yleensä useita kursseja tai alimoduuleja.

    • Opintokokonaisuudesta voi saada suoritusmerkinnän opintorekisteriin ja sen yhteydessä on tietoa esimerkiksi opintokokonaisuuden laajuudesta opintopisteinä, arvostelukriteereistä sekä vastuuhenkilöistä.

  • GroupingModule.

    • Tekninen apuväline, joka mallintaa tutkintorakenteen hierarkian välitasoa, jonka alaisuudessa on yleensä useita kursseja tai alimoduuleja, mutta joka ei kuitenkaan ole varsinainen opintokokonaisuus.

    • Eroaa opintokokonaisuudesta lähinnä siinä, että tästä ei voi saada erillistä suoritusmerkintää, eikä tämän yhteydessä siten ole tietoa esimerkiksi opintopisteistä.

  • CourseUnit.

    • Kuvaa opintojakson: koodi, nimi, laajuus opintopisteinä, kurssin kuvaus ja niin edelleen.

    • Tämä ei Sisussa ole Module:n alityyppi ja kurssitietoja haetaankin Sisusta API:sta eri päätepisteiden kautta kuin moduuleja. Kurssejakin voi hakea esimerkiksi id:n tai groupId:n perusteella.

    • Tietyn groupId:n omaavan kurssin tarkemmat tiedot saa esimerkiksi pyynnöllä (groupId on "uta-ykoodi-47926"): https://sis-tuni.funidata.fi/kori/api/course-units/by-group-id?groupId=uta-ykoodi-47926&universityId=tuni-university-root-id.

    • Moduulit, joiden alaisuudessa on suoraan kursseja, viittaavat kursseihin niiden groupId:den avulla.

Tutkintorakenne koostuu puumaisesta moduulihierarkiasta. Kukin moduuli sisältää moduulin tyypistä riippumatta attribuutin rule, joka kuvaa kyseisen moduulin alimoduulit eli sen lapset puurakenteessa. Tutkintorakenteen voi siten käydä läpi aloittamalla juuritasolta eli sen DegreeProgramme-moduulista ja käymällä rekursiivisesti sitten läpi kunkin kohdatun moduulin rule-attribuutin kuvaamat alimoduulit. Kunkin yksittäisen konkreettisen rule:n kohdalla on ilmaistu sen tyyppi. Esimerkiksi CourseUnitRule ja ModuleRule kuvaavat tiettyjä, suoraan moduulin alaisuuteen kuuluvia kursseja tai moduuleja. Sen sijaan AnyCourseUnitRule ja AnyModuleRule ilmaisevat, että kyseisen moduulin alaisuuteen saa lisätä mitä vain kursseja tai moduuleja.

Edellä mainittujen tyyppien tekniset kuvaukset löytyvät Sisun Kori API -sivuston alaosasta.