Projekti: Sääsovellus¶
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. Kirjoita sähköpostia kurssiosoitteeseen
prog3@tuni.fi, jos haluat tehdä työn yksin ja tarvitset siten erikseen luodun
tietovaraston tai 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ä. Ilman ryhmää jäänyt
opiskelija voi tehdä harjoitustyön yksin, mutta tällöin hän ei voi saada
ryhmätyöskentelykategorian pisteitä, joita ei luonnollisesti voi saada myöskään,
jos tekee työn tarkoituksella yksin.
Takarajat¶
Lopullinen palautus: perjantai 26.4.2024 klo 23.59.
Armonaika päättyy: perjantai 3.5.2024 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¶
Tulevien päivien sääennusteesta on hyötyä menemisiä suunnitellessa ja päivän vaatetusta valitessa. Jotta voisit helpommin pysyä sääennusteesta kärryillä, päätät toteuttaa ohjelman, joka noutaa netistä säädataa ja näyttää ennusteen graafisessa käyttöliittymässä. Ohjelmalla voidaan tarkastella tulevien päivien sääennustetta eri paikkakunnilla.
Ryhmä valitsee itse missä laajuudessa (minimi, perus tai huippu) se toteuttaa ohjelman. Jos tavoitteena on vähintään perustoteutus, ohjelman on minimitoiminnallisuuden lisäksi muun muassa muistettava viimeksi tarkasteltu paikkakunta ja sen on osattava tallentaa usein tarkasteltuja paikkakuntia suosikeiksi. Laajimillaan ohjelmassa voidaan esimerkiksi tarkastella sade-ennustetta myös karttojen avulla.
Työssä käytetään OpenWeatherMap-palvelun tarjoamaa ilmaista säädataa.
Ohjelman kulku¶
Ohjelman toiminnan saa suunnitella hyvinkin vapaasti, tässä vain yksi esimerkki mahdollisesta kulusta. Mallia voi hakea myös jo olemassaolevista sääsovelluksista, joita tarjoavat muun muassa Ilmatieteenlaitos ja Foreca. Esimerkkissä on tavoiteltu vähintään perustoiminnallisuutta.
Ohjelman käynnistyessä avautuu ennuste viimeksi haetulle paikkakunnalle. Paikkakuntia voi hakea ja tallentaa suosikeiksi erillisessä ikkunassa. Myös sääkartat löytyvät omasta ikkunastaan. Pääikkuna näyttää tämän hetkisen säätilan ja ennusteen seuraaville päiville sekä tunnin tarkkuudella että päiväkohtaisen koonnin, josta löytyvät muun muassa päivän ylin sekä alin lämpötila. Päiväkohtaisessa koonnissa on korostettu päivä, joka on kulloinkin näkyvissä tuntikohtaisessa ennusteessa.
Ohjelman sulkeutuessa tallennetaan tiedostoon ohjelmassa sulkemishetkellä näkyvä paikkakunta sekä viimeksi haetut ja suosikeiksi tallennetut paikkakunnat. Vaikka tallennukseen voi käyttää esimerkiksi vapaamuotoista tekstitiedostoa, tiedostoformaatiksi suositellaan JSON:ia, koska Gson-kirjastolla tai vastaavalla JSON-datan käsittelyyn tehdyllä kirjastolla on suoraviivaista muuntaa Java-olio JSON-muotoon ja kirjoittaa JSON-data tiedostoon. Myös päin vastainen prosessi, jossa JSON-data luetaan tiedostosta ja muunnetaan Java-olioksi, on helppo toteuttaa kirjastoa käyttäen.
Alla on hahmotelma siitä, miltä ohjelman käyttöliittymä saattaisi näyttää:
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ä, jos mitään?
Ohjelman käyttöliittymä: Miten ohjelman eri toimintoja voidaan suorittaa?
Käyttäjän rooli ohjelmassa: Miten käyttäjä hakee haluamaansa tietoa?
Säätietojen esittäminen: Mitä tietoa säädatasta näytetään, ja missä muodossa se esitetään käyttäjälle?
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.
Ohjelma käyttää pääikkunanaan valmiina annettua toteutusta.
Ohjelmalla voi hakea säätietoja eri paikkakunnille.
Kulloisellekin näytettävälle paikkakunnalle esitetään nykyinen säätila sekä yksinkertainen ennuste. Ohjelmassa on näytettävä vähintään kolme eri datatyyppiä (esimerkiksi lämpötila, sademäärä, tuulen nopeus).
Ohjelma käyttää säädatapalvelun tarjoamia sääikoneita.
Käyttää vähintään yhtä valmiina annettua rajapintaa (iAPI.java tai iReadAndWriteToFile.java). Rajapintoja saa muokata omiin tarpeisiin sopivaksi.
Projektille löytyy versiohistoria gitlabista.
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.
Perustoteutus sisältää minimitoteutuksen ominaisuudet seuraavilla lisäyksillä ja muutoksilla:
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.
Ohjelmalla voidaan tallentaa paikkakuntia suosikeiksi, jolloin niiden ennuste voidaan helposti hakea myöhemmin uudelleen.
Ohjelman tila (nykyinen paikkakunta sekä suosikit) tallennetaan ohjelman sulkeutuessa levylle, josta ne ladataan ohjelman uudelleen käynnistämisen yhteydessä.
Yksinkertaisen ennusteen sijaan näytetään yksityiskohtaisempi ennuste, johon kuuluu sekä tuntikohtainen ennuste että päiväkohtainen koonti, josta löytyy vähintään päivän alin ja ylin lämpötila.
Ohjelma käyttää omia ikoneita (ei säädatapalvelusta haettuja). Ikoneilla on oltava enemmän variaatiota, eli useampia erilaisia, kuin mitä säädatapalvelu tarjoaa.
Ohjelma selviää hallitusti tiedostojen käsittelyssä tapahtuvista virheistä.
Ohjelmalle on toteutettu yksikkötestejä.
Toteuttamalla lisäominaisuuksia voi saada lisäpisteitä. Yksi lisäominaisuus on lähtökohtaisesti 25–100 pistettä. Lisäpisteitä voi saada myös työn lisäansioista. Toteutuksen lisäpisteillä voi kompensoida virheitä yhden arvosanan verran.
Huipputoteutus¶
Maksimiarvosana 5.
Ohjelmassa on toteutettuna vähintään kaksi lisäominaisuutta. Yksi lisäominaisuus on lähtökohtaisesti 25–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 25–100 pistettä, riippuen ominaisuuden vaativuudesta sekä toteutuksen laadusta. 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.
Sääkartat. Sääkartta koostuu karttapohjasta ja säädatapalvelusta saadusta karttadatasta. Kartta voi olla myös animoitu, jolloin näytetään data useammalle eri ajankohdalle.
Kuvaajien käyttö. Ohjelmassa näytetään kuvaajia hyödyntäen jotain dataa, kuten vaikkapa lämpötila tai sademäärä.
Paikkakuntien hakuhistoria. Viimeksi haetut paikkakunnat pidetään muistissa, jotta niihin on helppo myöhemmin palata. Myös hakuhistoria tallennetaan tiedostoon ja palautetaan, kun ohjelma käynnistetään uudelleen.
Tuki useammalle mittayksikköjärjestelmälle. Tässä työssä tulisivat varmaan käytännössä kyseeseen brittiläinen ja metrijärjestelmä. Toteutetaan sen datan puitteissa, mitä säädatapalvelusta on saatavilla.
Ohjelmaan on toteutettu graafista käyttöliittymää testaavat yksikkötestit. Käytä JavaFX-käyttöliittymän testaamiseen TestFX-testikehystä.
Yksikkötestit on toteutettu jatkuvan integroinnin periaatteen mukaisesti etätietovarastoon.
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 lisäksi harjoitustyölle voidaan antaa lisäpisteitä lähinnä lisätyöstä seuraavasti:
Korkeatasoinen grafiikka.
Erittäin hyvä käyttöliittymä.
Laadukkaasti dokumentoidut rajapinnat ja luokat.
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ö.
Et voi saada pisteitä tästä osiosta, jos teet projektin yksin. Puuttuvat pisteet voivat vaikuttaa arvosanaasi, vaikka osio on pistemäärältään melko pieni. Voit kerätä puuttumaan jääneitä pisteitä lisäominaisuuksia toteuttamalla (katso alla).
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-spring2024/group----
missä ---- on Plussan ryhmätunnus. Jos tunnus on esimerkiksi 1234 on ryhmän
etätietovarasto osoitteessa
https://course-gitlab.tuni.fi/compcs140-spring2024/group1234
Kloonaa tämä etätietovarasto omaksi paikalliseksi tietovarastoksesi.
Ota yhteyttä kurssisähköpostiosoitteen (prog3@tuni.fi) kautta, jos ryhmäsi
etätietovarasto puuttuu.
Tietovarastossa on valmis JavaFX-projektipohja. Projekti on Maven-muotoinen ja avautuu suoraan
NetBeans IDE:llä. Voit poistaa nbactions.xml-tiedoston tarpeettomana, jos et käytä NetBeansia.
Tiedoston voi jättää myös paikalleen, vaikka käyttäisit esimerkiksi Eclipseä, koska sen ei
pitäisi haitata muiden työkalujen toimintaa.
Projektipohja on modulaarinen: src/main/java-hakemistossa on annettu moduulin määrittelevä
module-info.java-tiedosto, johon lisätty käyttöriippuvuus projektipohjan moduulin ja
harjoituksista tutun, JSON-muotoista dataa käsittelevän Gson-kirjaston moduulin välille.
Gson-riippuvuus on määritelty valmiiksi myös projektin pom.xml-tiedostoon. Joudut
todennäköisesti muokkaamaan module-info.java-tiedostoa käsin, jos haluat käyttää JSON-datalle
jotain muuta kirjastoa tai ylipäätänsä muita kirjastoja. (JSON-data kannattaa käsitellä
ehdottomasti jonkin kirjaston avulla, sillä oman koodin teko JSON:in käsittelyyn on pitkälti
pyörän keksimistä uudelleen.) Huomaa, että voit poistaa module-info.java-tiedoston,
jos haluat tehdä perinteisen moduulittoman Java-projektin.
Aseta harjoitustyön materiaalien etätietovarasto etätietovarastoksi paikalliseen tietovarastoosi siltä varalta, että harjoitustyöhön julkaistaan korjauksia tai lisämateriaalia. Esimerkki:
git remote add materials https://course-gitlab.tuni.fi/compcs140-spring2024/group_template_project
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¶
Projektipohjan juuressa on annettu .gitlab-ci.yml-niminen tiedosto,
joka määrittää kuinka GitLab suorittaa niin sanotun CI/CD-putken. Putki
tukee jatkuvaan integraatioon perustuvaa 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ä.
Materiaalien etätietovaraston päivitys 11.4.2024¶
Materiaalien etätietovarastoon tehtiin 11.4.2024 seuraavat päivitykset:
.gitlab-ci.yml: CI/CD-putken ajoympäristölle (image) on määritelty uudempi versio.
"maven:3.6.3-openjdk-11"→"maven:3.8.4-openjdk-17".
pom.xml: Javan versioksi on päivitetty 17.
<maven.compiler.source>11</maven.compiler.source>→<maven.compiler.source>17</maven.compiler.source><maven.compiler.target>11</maven.compiler.target>→<maven.compiler.target>17</maven.compiler.target>
Muutoksia ei ole pakko ottaa käyttöön, jos projektisi toimii ilman niitä. Jos kuitenkin
haluat päivittää edellä mainitut tiedostot, voit käyttää Gitin pull-komentoa:
git pull materials main
joka vaikuttaa osaavan päivittää yllä mainitut tiedostot odotettua paremmin. (Yllä materials
on materiaalien tietovarastolle annettu nimi, jonka tilalla voi myös käyttää suoraan tietovaraston
nimeä.) Huomaa, että merge-konflikti on kuitenkin mahdollinen. Jos haluat edetä varovammin,
voit käyttää ensin Gitin fetch-komentoa, joka voit hakea etätietovarastossa olevat muutokset
ilman, että muutoksia yhdistetään paikallisen tietovaraston sisältöön. Tämän jälkeen voit arvioida
Gitin diff-komennolla muutoksia tarkemmin ja antaa Gitin merge-komennon,
jos tilanne vaikuttaa siltä, että konfliktia ei tapahdu. Jos merge tuottaa konfliktin
ja manuaalinen yhdistämisprosessi vaikuttaa työläältä, voi prosessin yrittää hätätilanteessa
perua komennolla git merge --abort.
On myös sallittua kopioida ja liimata muutokset omaan projektiin ilman Gitin käyttöä.
Säädatan käytöstä¶
Jotta säädataa saadaan palvelusta ladattua, on ensin luotava käyttäjätili ja haettava API-avain. Paina etusivun oikeasta ylänurkasta “Sign In”-linkkiä ja luo uusi tili painamalla Create Account -linkkiä. Käytä tilin luomiseen yliopiston sähköpostiosoitetta (@tuni.fi). Kun olet luonut tilin, kirjaudu sisään ja navigoi tililläsi “My API keys”-sivulle. Sinulle on todennäköisesti jo luotu API-avain, mutta jos sellaista ei ole vielä luotu, voit luoda sen tällä sivulla. Avaimen luomisen jälkeen menee joitain tunteja, ennen kuin avain alkaa toimia. API-avainta tarvitaan kaikissa palveluun tehtävissä hauissa.
Datapalvelun ilmaisversio on varsin rajoittunut. Opiskelijoille on kuitenkin saatavilla ilmaiseksi laajempi datapaketti. Opiskelijaversiota palvelusta voit hakea tältä sivulta. Opiskelijaversiossa tulevat lisänä muun muassa karttadata, tuntikohtainen ennuste ja historiadata, joten sen hakeminen on käytännössä edellytys, jos haluaa saada työstä minimitoteutusta paremman arvosanan. Opiskelijapaketin saamisessa voi mennä joitain päiviä, joten kannattaa hakea sitä hyvissä ajoin.
Sivustolta löytyvät myös ohjeet API:n käyttöön. Esimerkiksi tämänhetkisen säätilan ohje löytyy täältä: https://openweathermap.org/current Oletusarvoisesti API palauttaa datan JSON-muodossa. Suurin osa API-hauista tapahtuu koordinaatteja käyttämällä. Paikkakuntien koordinaatteja voi hakea palvelun tarjoamalla geokoodaus-API:lla, toki myös muita haluamiaan geokoodauspalveluja on mahdollista käyttää. OpenWeatherMap:n geokoodauspalvelu kuitenkin tarjoaa kaikki työhön vaadittavat ominaisuudet.
Linkit API-ohjeisiin löytyvät ehkä helpoiten hinnoittelusivulta. Opiskelijapakettiin kuuluvat Current weather and forecast collection Developer-tasolla sekä Historical weather collection Medium-tasolla.
Tekoälyn käytöstä¶
Harjoitustyön tekemisessä on sallittua käyttää tekoälyä. Harjoitustyön dokumentaatiosta ja lähdekoodin kommenteista on käytävä ilmi missä työn kohdissa tekoälyä on käytetty ja missä laajuudessa tekoälyä on käytetty kyseisissä kohdissa. Dokumentissa on myös kerrottava mitä tekoälytyökaluja harjoitustyössä on hyödynnetty.
Tekoälyn käytöstä ei saa lisä- tai miinuspisteitä.