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!

Takarajat¶

Lopullinen palautus: perjantai 8.12.2023 klo 23.59.
Armonaika päättyy: perjantai 15.12.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¶

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. Ohjelma myös muistaa viimeksi auki olleen paikkakunnan, ja usein tarkasteltuja paikkakuntia voidaan tallentaa suosikeiksi. Esimerkiksi sade-ennustetta voi tarkastella 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, kuten Ilmatieteenlaitos tai Foreca.

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 mm. 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 JSON-tiedostoon ohjelmassa sulkemishetkellä näkyvä paikkakunta sekä viimeksi haetut ja suosikeiksi tallennetut paikkakunnat.

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ä (esim. 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 JSON-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ä.
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ö.
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-fall2023/group----,

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

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

Tietovarastossa on valmis JavaFX-projektipohja. 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 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ä.

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