NohevaII - järjestelmän tekninen kuvaus (Technical specification)

Team Tubeless NohevaII - järjestelmän tekninen kuvaus (Technical specification) Versio Päiväys Tekijä Kuvaus 0.1 21.1.2006 Kauppi esiversio 0.2 23.2.2006 Kauppi Täydennetty 0.3 23.2.2006 Korhonen Täydennetty raportin osalta 0.4 26.2.2006 Kauppi Täydennetty tietorakenteiden, käyttöliittymän, laskennan ja tietokanta yhteyden osalta 1.0 26.2.2006 Kauppi - Säädata, vbox ja projektitiedostojen kuvaukset lisätty - Viimeistelyä

Sisällys 1 JOHDANTO... 1 2 ARKKITEHTUURI... 3 2.1 SOVELLUSKERROKSET... 3 2.2 PAKETIT... 4 3 MODUULIT... 5 3.1 TIETORAKENTEET... 5 3.2 KÄYTTÖLIITTYMÄ... 6 3.3 RAPORTTI... 6 3.4 TIETOVARASTO... 7 3.4.1 Projektitiedostot... 7 3.4.2 Tietokanta... 7 3.5 LASKENTA... 8 4 LIITYNNÄT ULKOPUOLISIIN JÄRJESTELMIIN... 10 4.1 VBOX-TIEDOSTOT... 10 4.2 SÄÄDATA... 10 4.3 CSV (TIETOJEN VIENTI)... 11 5 TOTEUTUSTEKNOLOGIA... 12 5.1 KEHITYSYMPÄRISTÖ... 12 5.2 VERSIONHALLINTA... 12 5.2.1 Koodien hakeminen CVS:stä eclipseen... 12 5.2.2 Projektin kääntäminen... 12 5.3 HAKEMISTORAKENNE... 13 LÄHTEET... 14

1 Johdanto Tämän dokumentin tarkoitus on kuvata NohevaII järjestelmän arkkitehtuuria ja valittuja teknisiä ratkaisuja. Dokumentista on tarkoitus olla apua projektiryhmän jäsenille ja asiakkaalle, etenkin ylläpito- ja jatkokehitysvaiheessa. Sovelluksen toiminnallinen kuvaus löytyy vaatimusmäärittely dokumentista [1]. NohevaII sovellus on ns. standalone sovellus, jota käytetään rengastestien mittaustietojen analysointiin. Sovellusta ajetaan käyttäjän tietokoneesta käsin kuten mitä tahansa muutakin Windows sovellusta. Sovellus on toteutettu Java-ohjelmointikieltä käyttäen. Javasta suositellaan käytettäväksi versiota 1.5.0_06 tai uudempaa. Suunnittelun lähtökohtana on ollut, että sovellus toimii uudehkossa standardi PC koneessa, jossa on Windows:n käyttöjärjestelmä ja riittävästi muistia. Periaatteessa sovellusta saattaa olla mahdollista ajaa myös Linux tai Unix käyttöjärjestelmissä mutta sovelluksen toimivuutta näissä ei ole testattu. Suunnittelun lähtökohtana onkin ollut, että sovellus toimii Windows käyttöjärjestelmässä ja siinä ei ole otettu huomioon muiden käyttöjärjestelmien mahdollisia eroavaisuuksia. Ohjelman yksinkertaistettu toimintaperiaate esitetty alla kuvassa (Kuva 1). Kuva 1 Sovelluksen toimintaperiaate 1/13

Sovelluksen käyttämä tallennusformaatti (XML) on valittu, sen helppokäyttöisyyden takia. XML-tiedostot saa helposti käsiteltyä nykyaikaisilla ohjelmointikielellä ja tiedoston sisällöstä saa tarvittaessa selvää tavallisella tekstieditorilla. Projektitiedoston tallennuksesta enemmän kappaleessa (3.4.1) 2/13

2 Arkkitehtuuri Sovellukset arkkitehtuurissa on pyritty noudattamaan periaatetta, jossa eri osat ovat mahdollisimman itsenäisiä ja riippuvat toisistaan mahdollisimman vähän eli ns. high cohesion, low coupling -periaatetta. Sovellus on jaettu kerroksiin ja kehitystä helpottaviin paketteihin (java packages). Näistä tarkemmin kappaleissa 2.1 ja 2.2. 2.1 Sovelluskerrokset Sovelluksen arkkitehtuuri jakaantuu kolmeen kerrokseen: tietorakenteisiin toimintalogiikkaan ja käyttöliittymään. Tietorakenteet on alin kerros, jossa pidetään muistissa testiprojektin tietoja, mittaustuloksia ja laskennan tuloksia. Toimintakerros sisältää varsinaisen toimintalogiikan kuten laskennan, tietojen varastoinnin ja liitynnät järjestelmän ulkopuolisiin tietoihin. Käyttöliittymäkerros huolehtii tietojen esittämisestä käyttäjälle ja käyttäjän syötteiden vastaanottamisen. Tietorakenne kerrosta käytetään käyttöliittymä- sekä toimintalogiikkakerrosta käsin. Toimintalogiikka kerrosta käytetään käyttöliittymä kerroksesta käsin. Sovelluksen kehityksen ja testauksen kannalta kerrosrakenne tarkoittaa myös sitä, että mitä alemmalla kerroksella ollaan sitä enemmän muutoksilla on vaikutuksia ylempiin kerroksiin. Kuvassa (Kuva 3) on esitetty sovelluksen eri kerrokset. Käyttöliittymä Toimintalogiikka Laskenta VBOX-tiedostojen luku Säädatan haku Raportointi Tietojen varastointi (XML-tiedosto) Tietojen varastointi (Tietokanta) Tietorakenteet A B = A käyttää B:tä Kuva 3 Sovelluskerrokset 3/13

2.2 Paketit Sovelluskehityksen helpottamiseksi sovelluksen eri kerrokset on jaettu paketteihin. Paketit ja niitä vastaavat kerrokset ovat lueteltu taulukossa (Taulukko 1) Taulukko 1 - Paketit ja kerrokset Paketti Kerros Tehtävä DS Tietorakenne Tietojen muistissa pitäminen sovelluksen Calculation Toimintalogiikka Testitulosten laskenta Parser Toimintalogiikka VBOX-tiedostojen lukurutiinit Report Toimintalogiikka Raportointi Storage Toimintalogiikka Tietojen varastointi paikallisesti ja tietokantaan. UI Käyttöliittymä Testiprojektin tietojen esittäminen käyttäjälle Unittests - Yksikkötestit, joilla testataan laskennan ja tiedoston luvun oikeellisuutta. Paketit ja niihin kuuluvat lähdekooditiedostot löytyvät suoraan samannimisestä hakemistoista. Kehityksessä käytetty hakemistorakennetta on esitetty kappaleessa (5.3) 4/13

3 Moduulit 3.1 Tietorakenteet Sovelluksen keskeisimmät tietorakenteet ovat Project, TestType, TestSet ja Test. Projekti (Project) sisältää testiprojektin yleisluontoiset tiedot ja projekti voi koostua monesta eri testityypistä (TestType). Testityyppi voi koostua useista eri testisarjoista (TestSet). Testisarja pitää testikerran tiedot kuten auton, käytetyn menetelmän ym. tiedot sisällään. Testisarja koostuu vielä useista yksitäisesti kokeista (Test). Yksittäinen koe sisältää apuluokkien välityksellä kokeen tiedot kuten mittaustulokset (TestData) ja laskennat tulokset (CalculatedResult). Tietorakenteiden luokkakaavio on esitetty kuvassa (Kuva 5). Kuva 5 - Tietorakenteet 5/13

3.2 Käyttöliittymä Sovelluksen käyttöliittymän koodi on paketissa UI. Käyttöliittymä on toteutettu käyttämällä Javan Swing kirjastoa. Kuvaajien piirtämiseen on käytetty JFreeChart kirjastoa (http://www.jfree.org/jfreechart/). Käyttöliittymä on pääsääntöisesti toteutettu MainUI luokassa ja muutama muun apuluokan avulla. MainUI on pääluokka, joka muodostaa käyttäjälle näkyvän kokonaisuuden käyttöliittymästä. Testiprojektin tiedot on sijoiteltu eri välilehdille (Javan JTabbedPane). MainUI näyttää testiprojektin tiedot tietorakennekerroksen tietojen pohjalta ja kutsuu toimintalogiikkakerroksen tarjoamia toimintoja, käyttäjän valitseman toiminnon mukaan. MainUI:n tärkeimmät metodit ovat updateuifromds(), jolla päivitetään käyttöliittymää tietorakenteiden tietojen pohjalta ja readdatafromui(), jolla luetaan käyttöliittymästä käyttäjän syöttämät tiedot tietorakenteisiin. 3.3 Raportti Raportin käyttämä koodi on paketissa report. Raportti toteutettiin JFreeReport 0.8.6 versiolla (http://www.jfree.org/jfreereport/). GetProjectData.java hakee projektin tiedot raportin käyttämään TableModel-olioon, ja Nreport.java huolehtii itse raportin laukaisemisesta että projektin tietojen linkittämisestä xml-mallin kanssa. Raportin ulkoasumäärittelyjen siirtäminen erilliseen xml-tiedostoon mahdollistaa raportin ulkoasun muuttamisen ilman, että ohjelmaa tarvitsee kääntää uudelleen. Toinen mahdollisuus olisi ollut määritellä koodissa raportin ulkoasu, mutta silloin ulkoasuun ei olisi voinut koskea kuin muuttamalla koodia ja ohjelma pitäisi kääntää joka muutoksen jälkeen uusiksi. Raportin ulkoasun määrittelevä xml-tiedosto käyttää JFreeReportin extended-muotoa, koska tämä rajoittaa vähemmän ulkoasun määrittelyä kuin vaihtoehtona oleva simplemuoto. XML-tiedosto koostuu aluksi xml:n määrittelyistä. Sitten tulee parserin konfiguraatio tageissa <parser-config>. Yleensä kumpaankaan näihin ei tarvitse puuttua, korkeintaan raportin nimeen. Parserin asetusten jälkeen tulee tagi <report-config>, jossa määritellään raportin käyttämä paperin koko ja suunta, marginaalit ja raportin käyttämä merkistö. <styles> tagilla määritellään raportin yleiset tyylit, joita voidaan käyttää suoraan raportilla tai hivenen varioiden. Seuraavaksi voidaan määritellä omanlaisia datatyyppejä tagilla <templates>. Voidaan esimerkiksi määritellä tietyntyyppiselle desimaaliluvulle juuri kaksi desimaalia formaatiksi. <report-description> aloittaa varsinaisesti raportin määrittelyn. Tämän tagin sisällä määritellään kaikki raportilla näkyvät asiat. <reportheader> määrittelee raportin alussa olevat asiat. Tämän tagin sisällä määritellään headerin tyyli ja koko ja kaikki elementit, joita se sisältää. Kun report header on määritelty, määritellään <report-footer> niin haluttaessa. Report footer on raportille viimeisenä tuleva asia. <page-header> on vastaavasti sivun alussa tuleva ylätunniste ja <pagefooter> sivun alatunniste. Kuten report-headerin tapauksessa, molemmat page-tagitkin koostuvat style- ja element-tageista. <groups> tagi aloittaa ryhmien määrittelyn. Periaatteessa jokainen taulukko raportilla on oma ryhmänsä. Ryhmälle määritellään, minkä kentän mukaan se muodostuu ja millaiset headerit ja footerit. Kun ryhmät on 6/13

määritelty, määritellään toistuvat rivit tagissa <itemband>. Taulukot koostuvat näistä itembandin sisällä olevista määrittelyistä, koska itemband määrittelee jokaisen rivin toistuvan muotoilun. Itemband on viimeinen raportille tuleva määrittely, joten reportdescription päättyy tähän. Viimeinen asia xml-tiedostossa on <functions> tagi, jossa määritellään raportilla käytettävien ulkoisten javaohjelmien nimet ja arvot sekä paluuarvot. Funktioilla on toteutettu mm. raportin päivämäärä, sivunumerot ja itembandien ja group headereiden piilottaminen, jotta rinnakkaisia headereita ei näkyisi yhtä aikaa raportilla. 3.4 Tietovarasto 3.4.1 Projektitiedostot Käyttäjän muokkaama projekti tallennetaan tiedostoon XML-muodossa. Käytetty XML- API on Javasta vakiona löytyvä W3C Document Object Model toteutus. Projektin tietorakenteet muutetaan XML:ksi käymällä projektin tietorakenteet läpi aloittaen Project-objektista. Kustakin läpikäydystä osasta muodostetaan XML-elementti, jonka alielementteinä ovat puussa seuraavaksi läpikäytävät osat, sekä yksinkertaisemmat tietotyypit, kuten merkkijonot ja luvut. Yksinkertaisempia tietotyyppejä tallennetaan tarpeen mukaan myös attribuutteina. Rengastietojen tapauksessa samoihin renkaihin viitataan monesta luokasta, joten renkaat tallennetaan vain kerran Project-objektia tallennettaessa ja niihin viitataan muualta dokumentista renkaan koodin perusteella. Luettaessa projektia renkaat tallennetaan hakutauluun, jotta renkaan viittaukset saadaan luodussa projektissa menemään oikeisiin renkaisiin. 3.4.2 Tietokanta Tietokanta on toteutettu pääasiassa kahden luokan avulla. Nämä luokat sijaiset paketissa Storage.Database. PortForward on apuluokka, joka avaa ssh-tunnelin tietokantapalvelimelle. Tietokantayhteydeltä vaadittiin salausta, ja koska käytössä oleva tietokantapalvelin (MySQL 3.23) ei tue suoraa SSL-yhteyttä, oli tunneli käytännössä ainoa järkevä vaihtoehto yhteyden salaamiseen. Tunnelin käyttäminen myös vähentää riippuvuutta nykyiseen palvelinratkaisuun. PortForward käyttää tunnelin avaamiseen Java Secure Channel (jsch-0.1.25.jar) -kirjastoa, joka on SSH2-toteutus javalle. Tämä käyttää lisäksi Java Cryptography Extension (JCE) -kirjastoa (sunjce_provider.jar) mm. salausavaimien luomiseen yhteyden muodostamiseksi. Tunneliyhteys pyritään pitämään auki ohjelman käytön ajan, jolloin kirjautumista ei tarvitse tehdä joka kerta kantaa käytettäessä uudelleen. DatabaseStorage on luokka, joka hoitaa varsinaisen tietokantaliikenteen. Tässä käytetään apuna MySQL Connector/Jdriver (mysql- 7/13

connector-java-3.1.12-bin.jar) -kirjastoa. Kantayhteys avataan ja suljetaan jokaista projektin tallennusta/hakemista varten. Tämä varmentaa toimintaa, koska yhteyden katkeamiseen operaatioiden välillä ei tarvitse varautua, eikä kantayhteyttä pidetä turhaan auki. Tästä ei myöskään ole haittaa tunnelia käytettäessä, koska tunneli pysyy auki, jolloin yhteyden muodostaminen itse kantaan on erittäin nopeaa. Projektia tallennettaessa projekti muutetaan xml-muodon kautta merkkijonoksi (FileStorage-luokasta löytyvän metodin avulla), joka tallennetaan kantaa mediumtextkenttään. Tähän mahtuu (2 24 )-1 = 16 777 215 merkkiä, joka riittää hyvin, sillä projektitiedostot lienevät suurimmillaankin vain kymmeniä kilotavuja (tai hieman yli 100kt). Toisaalta MySQL:ssä kyselystä saatavan datan määrä on rajoitettu Megatavuun, joten tätä suurempia projekteja ei nykyisellä toteutuksella voisi myöskään kannasta hakea. Tietokannan avain-kenttänä käytetään tiedoston nimeä, jolloin samalla nimellä ei voi vahingossa tallentaa vanhempaa versiota projektista uudemman päälle (versionumeron käyttö projekti-tiedoston nimessä saattaisi olla kannattavaa). Tämän takia tiedosto on tallennettava ennen kantaan vientiä. Lisäksi tallennetaan projektin nimi, koodi, sekä päivämäärä ja aika, jolloin projekti on kantaan viety. Nämä ovat kannassa varchar(255) - kenttiä, paitsi päivämäärä ja aika, joka on datetime-kenttä. Projektia kannasta haettaessa tarjotaan käyttäjän nähtäväksi lista, jossa on jokaisesta projektista tiedostonimi ja aika jolloin se on kantaan viety. Projektin nimeä ja koodia ei tällä hetkellä käytetä mihinkään, mutta ne on tallennettu kantaan erikseen, jotta näitä voidaan tarvittaessa myöhemmin myös käyttää hakuperusteena, mikäli nykyinen (tiedostonimi + aika) osoittautuisi riittämättömäksi tai epäkäytännölliseksi. Käyttäjän valittua listasta haluamansa projektin, haetaan kyseisen projektitiedoston merkkijono kannasta ja muunnetaan takaisin projektiksi myöskin FileStorage-luokasta löytyvällä metodilla. 3.5 Laskenta Laskenta on toteutettu paketissa nohevaii.calculation. Laskennalla on kolme tehtävää paikkakorjaus, tulosten laskenta ja kuvaajien muodostus. Paikkakorjaus Testidatan muokkaaminen niin, että eri paikkojen väliset erot tasoitetaan. Syötteenä on TestData-olio ja tuloksena on paikkakorjattu TestData-olio. Toteutus metodissa nohevaii.calculation.nohevacalculation.positioncorrection Tulosten laskenta Suorittaa paikkakorjauksen ja laskee paikkakorjatun testidatan perusteella renkaiden tulokset. Syötteenä TestData-olio, tuloksena CalculatedResults-olio joka sisältää jokaisen renkaan kohdalta tulosindeksin, keskiarvon mittausdatasta ja luottamusvälit. Toteutus on metodissa nohevaii.calculation.nohevacalculation.calculateresults 8/13

Kuvaajien muodostus Muodostaa kahdenlaisia kuvaajia. Ensimmäinen kuvaaja on ns. analyysikuva jossa näytetään jokaisen renkaan jokaisen paikan yksittäinen tulos. Toteutus luokassa nohevaii.calculation.testdatachart. Toinen kuvaaja esittää renkaiden lopulliset tulokset palkkeina. Toteutus luokassa on nohevaii.calculation.resultchart. 9/13

4 Liitynnät ulkopuolisiin järjestelmiin NohevaII-sovelluksen liitynnät ulkopuolisiin järjestelmiin tapahtuu lukemalla ja kirjoittamalla määrämuotoisia tekstitiedostoja. 4.1 VBOX-tiedostot VBOX-tiedostoja tuetaan kolmea eri tyyppiä: kiihdytys-, jarrutus- ja käsittelykoe. Näistä kiihdytys ja jarrutuskokeet ovat samanlaisia tiedostoja, mutta niistä luetaan eri kohdat. Tästä syystä niiden lukeminen tapahtuu samoilla metodeilla. VBOX-tiedostojen luvun hoitaa Parser-luokka. Sille annetaan luotaessa Test-objekti, johon luettavat tiedot halutaan tallentaa. Test-objektista muutetaan date-kenttää, sekä orginaltestdata-kenttää. Parserointi tapahtuu kutsuttaessa parse-metodia. Sille annetaan argumentiksi VBOXtiedoston nimi, sekä tiedoston tyyppi, joka on joko käsittelykoe, kiihdytyskoe tai jarrutuskoe. Luettavasta tiedostosta luetaan mittausarvojen lisäksi myös päivämäärä Testobjektille, sekä kellonajat kullekin TestData-objektin riville. Käsittelykoe on jaettu useampaan eri tiedostoon. Nämä tiedostot luetaan kutsumalla parse-metodia peräkkäin kullekin tiedostolle. Kukin kutsu lisää yhden rivin TestDataobjektiin. Uuden Parser-objektin luominen johtaa aina vanhan TestDatan ylikirjoittamiseen, joten rivien parseroinnin täytyy tapahtua samalla Parse-objektilla. Kiihdytys- ja jarrutuskokeen tiedot löytyvät yhdestä tiedostosta. Jos parse-metodia kutsutaan uudestaan, niin vanhat tiedot kirjoitetaan yli. 4.2 Säädata Säädata on tallennettu FTP-palvelimelle siten, että kutakin päivää kohti on yksi tiedosto. Sen haun hoitaa WeatherFetcher-luokka. FTP-yhteyteen käytetään Jakarta Commons Net -kirjastoa. Haku tapahtuu kutsumalla fetchtemperatures -metodia. Sille annetaan argumenttina Test-objekti, jonka orginaltestdata-kentän riveille ollaan hakemassa lämpötiloja. Kullekin TestData-objektista löytyvälle uniikille päivälle haetaan oma tiedostonsa. Tiedostoista parsitaan kutakin ajankohtaa vastaava lämpötila siten, että kellonaika pyöristetään edelliseen tasaviisiminuuttiseen. 10/13

4.3 CSV (Tietojen vienti) Mittaustuloksia on mahdollista viedä CSV-tiedostoon. CSV-tiedosto on tiedostossa, jossa eri tiedot ovat eroteltu toisistaan puolipisteellä (;-merkillä). CSV-tiedoston pystyy avaamaan esim. Excel-sovelluksessa. 11/13

5 Toteutusteknologia Tässä kappaleessa kuvataan NohevaII-sovelluksessa käytetty kehitysympäristö ja muut sovelluksen kehittämiseen liittyvät asiat. 5.1 Kehitysympäristö Projektin kehitysympäristönä käytetään Eclipse 3.1-sovellusta, joka on ilmainen ja ns open source - sovellus (http://www.eclipse.org). Eclipse- sovelluksessa on sisään rakennettu tuki versionhallinnalla, joten sovellus sopii hyvin useammankin henkilön yhtäaikaiseen kehitystyöhön. Sisäänrakennetun versiohallinnan etuina myös se, että projekti ei tarvitsi erityisiä projektitiedostoja, vaan kaikki projektin asetukset ja tarvittavat tiedostot saadaan suoraan versionhallinnan kautta. Projekti käännetäänkin vain hakemalla vain uusin versio versiohallinnasta. Tästä enemmän kappaleissa (5.2 ja 5.3). Kokeilu mielessä käytettiin myös kurssin tarjoamaa Borland Together Architect sovellus kehitintä, joka on muuten sama kuin Eclipse mutta sillä pystyy tekemään kätevästi UMLkaavioita lähdekoodin perusteella. Tätä työkalua käytettiin muun muussa kappaleessa (3.1) esitetyn luokkakaavion tekemiseen. 5.2 Versionhallinta Versionhallinnasta käytetään CVS ohjelmaan. Lopullinen versio nohevaii sovelluksen lähdekoodista tulee sijaitsemaan asiakkaan omalla palvelimella. 5.2.1 Koodien hakeminen CVS:stä eclipseen Luo virtuaalinen hakemisto komentokehotteessa. Komento on o subst t: "C:\polku\jossa\projekti\sijaitsee" Luo hakemisto T:\nohevaII Käynnistä Eclipse ja vaihda työhakemisto (Switch workspace) T:\nohevaII Valitse "New project" ja CVS ja sen alta "Checkout projects from CVS" Host: (palvelimen osoite) Repository path: (cvs-repository polku) Connection type: extssh Paina seuraava ja valitse "Use an existing module" (Tässä voi kestää jonkin aikaa) Valitse nohevaii ja sen alta code Valitse "Check out as a project in the workspace". Vaihda projektin nimeksi nohevaii Loput vaihtoehdot oletuksina ja paina Finish 5.2.2 Projektin kääntäminen Projektin saat kääntymään Valitsemalla Navigator välilehden alta nohevaiistarter.java ja tuplaklikkaamalla tätä. Tämän jälkeen hiiren oikealla napilla ja sieltä "Run As" ja "Java Application" 12/13

5.3 Hakemistorakenne NohevaII sovelluksen eri osat sijaitset alla olevissa hakemistoissa. Taulukko 2 Yleinen hakemistorakenne Hakemisto bin doc lib Model Folder src Kuvaus Sisältää käännetyt java tiedostot eli class-tiedostot, joita käytetään sovelluksen ajamiseen Sisältää sovelluksen javadoc dokumentaation Sisältää sovelluksen tarvitsemat kirjastotiedostot Sisältää luokkakaavioita ym. teknisistä dokumentaatio. Sisältää lähdekoodit, tämä hakemisto jakautuu vielä alihakemistoihin, katso taulukko2 Taulukko 3 src\nohevaii hakemiston sisältö Hakemisto Kuvaus calculation Laskentaan liittyvät lähdekoodit ds Tietorakenteet parser VBOX-lukurutiinit report Raportointiin liittyvät lähdekoodit storage Tietojen varastointiin liittyvät lähdekoodit ui Käyttöliittymän lähdekoodit unittests Yksikkötestit, kuten vbox ja laskennan oikeellisuuden tarkastaminen 13/13

Lähteet Team Tubeless, Vaatimusmäärittely