T-76.115 Tekninen spesifikaatio

T-76.115 Tekninen spesifikaatio OtaShop2 Versio Päivämäärä Tekijä Kuvaus Tarkastettu 1.0 30.11.2003 Inkinen Dokumetti tarkastettu ja löydetyt epäkohdat korjattu 2003-11-30 0.7 30.11.2003 Larmo Lisätty Käyttöliittymän kuvaus 0.6 30.11.2003 Ojanen Lisätty DAO:n kuvaus 0.5 30.11.2003 Inkinen Tarkennettu pakettien ja luokkien kuvauksia, käyttöliittymän kuvausta sekä otsikoita 0.4 29.11.2003 Kosunen Lisätty kuvaus language managerista 0.3 29.11.2003 Inkinen Muutoksia rakenteeseen ja otsikoihin. Uutta sisältöä pakettien kuvauksiin 0.2 28.11.2003 Ojanen Tietokannan kuvaus ja ER 0.1 24.11.2003 Inkinen Pohja luotu Sisältö 1. Johdanto 1.1 Asiakirjan tarkoitus 1.2 Määriteltävä tuote 2. Järjestelmä-alusta 2.1 Järjestelmän laitealusta 2.2 Tietokanta sekä laitealusta 3. Järjestelmän arkkitehtuuri 3.1 Järjestelmän yleiskuvaus 3.2 Suunnittelufilosofia 3.3 Java-paketit ja luokat 3.4 Tietokantakuvaus 3.5 Liitännät muihin järjestelmiin 4. Käyttöliittymä 4.1 JSP 5. Tekniset päätökset 5.1 Käytetyt tekniikat 5.2 Hylätyt tekniikat 6. Lähteet

1. Johdanto 1.1 Asiakirjan tarkoitus Tämä dokumentti on OtaShop2-projektin tekninen spesifikaatio. Asiakirja on tarkoitettu järjestelmän tuleville ylläpitäjille ja siinä selvitetään järjestelmän tekninen toiminta, käytetyt teknologiat sekä ympäristö jossa järjestelmää käytetään. Asiakirja tulee olemaan tärkeä varsinkin projektin loppuvaiheessa jolloin valmis järjestelmä siirretään asiakkaan hallintaan. 1.2 Määriteltävä tuote Järjestelmä joka määritellään tässä dokumentissa on OtaShop2-verkkokauppa. OtaShop2 tulee Teknisen Korkeakoulun kirjaston (myöhemmin kirjasto) käyttöön. OtaShop2-kauppaa käytetään Teknillisen Korkeakoulun (TKK) laboratorioiden julkaisujen välittämiseen. Järjestelmä mahdollistaa maksujen, kuten tilauksesta ja postituksesta syntyvien kulujen perimisen ja maksamisen verkkopankin kautta. 2. Järjestelmä-alusta 2.1 Järjestelmän laitealusta Projektin vaatimukseksi on annettu että järjestelmä tulee toimia "kohtuuhintaisella laitteistolla". Koska järjestelmän vaatimat resurssit ovat riippuvaisia käytetystä sovelluspalvelimesta sekä kaupan asiakkaiden määrästä, ei laitteston enimmäishintaa ole määritelty tarkemmin. Kehitysvaiheessa järjestelmää käytetään laitteistolla ja ohjelmistoilla jotka on määritelty tarkemmin projektisuunnitelmassa. 2.2 Tietokanta ja laitealusta OtaShop2-järjestelmässä käytetään tietokantapalvelinta tilausten ja maksujen hallintaan. Kaikki pysyvä tieto tallennetaan tietokantaan. Pysyvää tietoa ovat julkaisujen tiedot, tuotteiden toimitukseen liittyvät tiedot sekä tarvittavat asiakastiedot. Julkaisutiedot löytyvät TKK:n kirjaston Tenttu-tietokannasta. Kirjasto päivittää uusimmat tiedot julkaisuista Tenttu-tietokantaan, ja OtaShop2:n julkaisutiedot replikoidaan kerran vuorokaudessa Tenttu-kannasta. OtaShop2:n tietokanta luodaan käyttäen standardi SQL:ää. Valmistajakohtaisia laajennuksia ei käytetä. Tällä tavalla voidaan varmistua siitä että otettaessa järjestelmää käyttöön ei olla riippuvasia yhden valmistajan ohjelmistosta tai sen versiosta. Järjestelmän toteutusvaiheessa tulemme käyttämään "Oracle 9i standard"-tietokantapalvelinta. 3. Järjestelmän arkkitehtuuri 3.1 Järjestelmän yleiskuvaus Järjestelmä toteutetaan J2EE-standardin mukaan ja se on suunniteltu helposti laajennettavaksi. Toiminnallisuus eriytetään omiin paketteihin, ja jokaisella paketilla on julkinen rajapinta jonka kautta sitä käytetään. Modulaarinen rakenne helpottaa järjestelmän laajentamista sekä ylläpitämistä.

Seuraavassa lyhyesti kunkin tällä hetkellä toteutetun paketin tarkoitus ja toiminta. Paketin nimi DAO Cart Order Payment Language Lyhyt kuvaus paketin toiminnasta Tietokantahakujen ja kannan ylläpitämiseen liittyvät toiminnot Ostoskorin sekä HTTP-istunnon hallinta Tilausten sekä tuotteiden hallintaan liittyvät toiminnot Maksamisen ja eri maksutapojen hallinta Sivulla näkyvien tekstien lokalisaatio Pakettien keskinäiset suhteet esitettän seuraavassa kuvassa.

3.2 Suunnittelufilosofia OtaShop2-järjestelmä on suunniteltu käyttäen tunnettuja suunnittelumalleja. Käytetyt mallit sekä niiden lähemmät kuvaukset löytyvät henkilökohtaisen tehtävän Design Patterns -harjoituksesta. 3.3 Java-paketit ja luokat Seuraavassa on selvitetty tarkemmin kunkin paketin toiminta sekä niiden sisältämät luokat. Luokkien tarkka toteutus on luettavissa JavaDoc-dokumentaatiossa 3.3.1 DAO DAO-paketti sisältää kaikki tietokantaan liittyvät toiminnot. Paketissa mallinnetaan myös kaupassa myytävät tuotteet, sekä niihin liittyvät tiedot. Paketti on suunniteltu siten että se mahdollistaisi uusien tuotetyyppien lisäämisen mahdollisimman helposti. Paketin mallina on käytetty sekä builder että factory -suunnittelumalleja, ja tämän avulla uusien tuotetyyppien lisääminen onnistuu ilman isompia muutoksia.

DAO-paketin tarkempi kuvaus Paketissa on käytetty sekä builder että factory suunnittelumalleja. ItemBuilder luokka toimii sekä builderina että factorynä.3.3.2 Cart Cart-paketti toimii asiakkaan ostoskorina verkkokaupassa asioinnin aikana. Halutut tuotteet voidaan tallettaa ostoskoriin, ja kun asiakas on valmis tekemään tilauksen, niin tiedot välitetään eteenpäin Order-paketille. Ostoskoriin voi vapaasti lisätä tuotteita sekä poistaa niitä istunnon aikana. Cart-paketin tarkempi kuvaus Cart-paketti koostuu vain yhdestä luokasta. ShoppingCart-luokka sisältää metodit joilla tuotteita voidaan lisätä, poistaa, muuttaa, tyhjentää koko kori ja kysyä korissa olevien tuotteiden määrää. Tuotteiden lisääminen tai poistaminen muuttaa automaattisesti tuotteiden lukumäärätiedon, eikä asiakkaan tai kutsuvan luokan tarvitse ottaa asiaan kantaa. Korissa voi olla samaa tuotetta useampi kuin yksi kappale, mutta tämän tiedon tallennus on toteutettu Item-rajapinnan kautta. Cart:n hallinnoima ostoskoritieto pysyy tallessa koko käyttäjän vierailun ajan, koska valinnat säilötään sovelluspalvelimen muistiin, käyttäjää varten luotuun istuntoon. Käytännössä jokaista verkkokaupassa vierailevaa käyttäjää varten luodaan HashMap-tyyppinen olio, johon käyttäjän toivomat Item-rajapinnan toteuttavat tuotteet tallennetaan. 3.3.3 Order Order-paketti on suunniteltu builder suunnittelumallia käyttäen. Order paketti pitää huolen asiakkaan ja tilauksen tietojen hallinasta. Order saa asiakastiedot käyttöliittymältä, josta tarkemmin kappaleessa Käyttöliittymä. Asiakastiedot tallennetaan istuntoon, josta ne välitetään eteenpäin payment-paketille.

Order-paketin tarkempi kuvaus Order-paketti koostuu abstraktista CustomerBuilder-luokasta sekä sen palauttamista asiakasta kuvaavista luokista. Paketin ulkopuoliset luokat käyttävät aina CustomerBuilder-luokkaa, joka automaattisesti asettaa asiakas-tyypin oikein. Kaikki asiakasta kuvaavat luokat totetuttavat Customer-rajapinnan. CustomerBuilder mahdollistaa asiakastietojen määrittelemisen eri tavoilla. OtaShop2-projektin ensimmäisessä vaiheessa asiakastietojen määritteleminen tehdään aina HTML-formin avulla, ja CustomerBuilder palauttaa FormCustomerBuilder-luokan. Pienillä muutoksilla CustomerBuilder-luokkaan on mahdollista toteuttaa asiakastietojen hakeminen esimerkiksi tietokannasta tai evästeestä (cookie). Muut tavat tullaan määrittelemään asiakkaan kanssa. 3.3.4 Payment Payment-paketti huolehtii verkkomaksu-tapahtumasta. Paketti on toteutettu siten että se mahdollistaa erillaiset maksutapahtumat. Tällä hetkellä hyväksytyt ja toteutetut maksutavat ovat verkkomaksu Nordean, Leonian ja Kultarahan verkkopankeissa. Tämän lisäksi varmistettu verkkomaksu Visalla (Verified by Visa) onnistuu. Luokissa on käytetty template method suunnittelumallia ja tämän johdosta uusien tapausten lisääminen on jatkossa helppoa. Paketti keskustelee Order-paketin kanssa, jolta se saa tarvittavat tiedot laskun summasta sekä maksutavasta. Näitä tietoja hyväksikäyttäen se ohjaa asiakkaan oikean pankin sivuille, josta maksu varsinaisesti suoritetaan. OtaShop2-järjestelmä siis ei suoraan käsittele asiakkaan maksutapahtumaa, vaan pankki hoitaa sen ja antaa siitä tiedon takaisin OtaShop2-järjestelmään.

Payment-luokka on paketissa abstrakti ja eri maksutavat perivät sen. Järjestelmän muut osat käyttävät tätä abstraktia luokkaa, eivätkä joudu käsittelemään eri maksutapoja. Tämä mahdollistaa uusien maksutapojen lisäämisen, ilman että järjestelmän muita osia tarvitse muuttaa. PaymentTypes-luokka määrittelee vakiot joilla eri maksutapoja voidaan kutsua. Maksutavan määrittää kaupan asiakas, joka asiakastietojen kyselyn yhteydessä voi valita maksutavan. 3.3.5 Language Language-paketti huolehtii verkkokaupan lokaalisaatiosta, eli monikielisyydestä. Tarkempi kuvaus language-paketin luokista Language paketissa on ainoastaan yksi luokka. Se on järjestelmän apuluokka joka palauttaa halutuista teksteistä aina kielivalinnan mukaan oikean kieleisen version. LanguageManager luokka on toteutettu Singleton suunnittelumallilla. 3.4 Tietokantakuvaus OtaShop2-tietokantaan on talletettu kaikki pitempään pysyvät tieto. Kanta koostuu kahdesta pääasiallisesta osasta, kirjaston olemassaolevasta järjestelmästä siirrettävät tiedot (julkaisutiedot ja laboratorioiden tiedot) sekä OtaShop2:n omat tiedot. Julkaisutiedot saadaan TKK:n kirjaston Tenttu-tietokannasta, josta ne kerran vuorokaudessa replikoidaan OtaShop2:n tietokantapalvelimelle. Kirjaston omasta tietokannasta siirretään myös laboratorioiden vastuualuekoodit ja osastotiedot. OtaShop2-järjestelmän tuottamat tilaustiedot tallennetaan tietokantaan ja niiden tilaa ylläpidetään.

Tietokanta sisältää myös kaupan muita tietoja, kuten ylläpitäjien käyttäjätietoja 3.4.1 Tietokannan tarkka kuvaus OtaShop2-tietokannan rakenne on kuvattu seuraavassa ER-kaaviossa: publication-taulun kuvaus kokonaisuudessaan: Name Null? Type PUB_ID NOT NULL VARCHAR2(20) PRICE NOT NULL NUMBER(10) DOC_TYPE NOT NULL NUMBER(2) RESPONSIBLE_AUTHOR NOT NULL VARCHAR2(100) ALL_AUTHORS VARCHAR2(512) TITLE NOT NULL VARCHAR2(500) PUB_YEAR NOT NULL NUMBER(4) RESP_AREA_CODE NOT NULL VARCHAR2(10) DATE_SAVED NOT NULL VARCHAR2(10) DATE_ALTERED NOT NULL VARCHAR2(10) MAG_NAME VARCHAR2(300) MAG_VOLUME VARCHAR2(10) MAG_NUM VARCHAR2(10) SER_NUM VARCHAR2(10) SER_AUTHORS VARCHAR2(100) SER_TITLE VARCHAR2(512) EDITION VARCHAR2(100) PUB_PLACE VARCHAR2(100) PUBLISHER VARCHAR2(100)

CONFERENCE VARCHAR2(200) PATENT VARCHAR2(100) PATENT_OWNER VARCHAR2(100) PATENT_INVENT VARCHAR2(100) PATENT_APPLICATION VARCHAR2(100) PAGE_NUMBERING VARCHAR2(100) KEYWORDS_ENGL VARCHAR2(300) FOREIGN_PUB VARCHAR2(4) WEIGHT_FACTOR VARCHAR2(10) PROJECT VARCHAR2(100) SAVER_TRIP_ID VARCHAR2(100) CONF_AUTHORS VARCHAR2(100) CONF_TITLE VARCHAR2(100) ELECT_AVAIL VARCHAR2(100) AUTH_TITLE VARCHAR2(100) DESCRIPTION VARCHAR2(1024) 3.5 Liitännät muihin järjestelmiin OtaShop2-järjestelmä käyttää kirjaston Tenttu-tietokantaa julkaisutietojen ylläpitämiseen ja hallintaan. OtaShop2:n julkaisutietokanta replikoidaan sovituin väliajoin Tenttu-kannasta. Tietokannan replikointi on tarkemmin selvitetty kappaleessa "Tietokannan tarkka kuvaus". OtaShop2 ei itse hallitse verkkomaksutapahtumia, vaan itse maksu suoritetaan pankin omilla WWW-sivuilla. OtaShop2 välittää pankin maksujärjestelmään maksettavan summan, ja kun maksu on suoritettu saa järjestelmä tästä tiedon. Pankit ja luottokorttiyhtiöt joita tämä koskee on määritelty tarkemmin Payment java-paketin kuvauksessa. 4. Käyttöliittymä Verkkokaupan käyttöliittymä ja ulkoasu on kuvattu tarkemmin erillisessä ulkoasudokumentissa. 4.1 JSP Verkkokaupan käyttö tulee tapahtumaan normaalia WWW-selainta käyttäen. Käyttöliittymä tullaan toteuttamaan siten, että asiakkailla ja ylläpitäjillä on erillaiset näkymät. Kaikki ylläpitoon liittyvät näkymät toiminnot tulevat olemaan käytettävissä selaimen kautta. Kaupan ulkoasu on tehty yhtenäiseksi OtaShop1-verkkokaupan kanssa. OtaShop1:n ulkoasu on suunniteltu yhdessä TKK:n viestintäkeskuksen kanssa joka on myös hyväksynyt ulkoasun. OtaShop1 on toinen verkkokauppa jonka TKK:n ATK-keskus on tilannut ja joka on vielä kehitysvaiheessa. OtaShop1-verkkokaupassa tullaan myymään TKK:n logotuotteita, kuten pinssejä, t-paitoja ja mukeja. OtaShop1 toteutetaan PHP-tekniikkaa käyttäen. Koska ulkoasut ovat yhtenäiset voidaan kauppoja tarpeen vaatiessa käyttää myös rinnakkain. OtaShop2 on kuitenkin alusta lähtien suunniteltu siten että se on helposti laajennettavissa myös logo-tuotteiden myyntiin soveltuvaksi. Käyttöliittymä toteutetaan Java Server Pages-teknologiaa (JSP) käyttäen. JSP mahdollistaa dynaamisesti luotavien sivujen esittämisen ja antaa mahdollisuuden toteuttaa monimutkainen toiminnallisuus normaalina Java-ohjelmakoodina. Kappaleessa Yleiskuvus on esitetty käyttöliittymän sekä Java-pakettien keskinäiset suhteet.

5. Tekniset päätökset 5.1 Käytetyt tekniikat 5.1.1 Oracle 9i standard Järjestelmän kehitysvaiheessa tulemme projektissa käyttämään Oracle 9i standard-tietokantapalvelinta. Asiakas on toimittanut tämän ohjelmiston projektin käyttöön. Tietokannan rakenne ja toiminnot toteutetaan standardi SQL-kieltä käyttäen, joten tietokantapalvelin voidaan tarpeen vaatiessa vaihtaa toiseen, esimerkiksi käyttöönoton yhteydessä. 5.1.2 Apache WWW-palvelin Apache on tällä hetkellä käytössä TKK:n ATK-keskuksessa. Muita WWW-palvelimia ei käytetä. Tästä syystä myös OtaShop2:ssa tulee käyttää Apache WWW-palvelinta. Apache on tällä hetkellä suosituin WWW-palvelin markkinoilla. Apache on helposti laajennettavissa erillaisilla lisämoduleilla ja tarvitsemamme toiminnot löytyvät jo valmiiksi. Kaiken lisäksi Apache on ilmainen ja sen lisenssi on hyvin vapaa joten se soveltuu erinomaisesti projektin käyttöön. 5.1.3 Apache Tomcat Tomcat on Apache-projektin Java-sovelluspalvelin. Projektissa käytetään Apache WWW-palvelinta joten ohjelmistot on rakennettu toimimaan keskenään saumattomasti. Tämän lisäksi Apache-projektissa on useita työkaluja jotka helpottavat projektin kääntämistä ja testaamista ja toimivat yhteen Tomcat-palvelimen kanssa. Projektissa käytetään Maven-käännösympäristöä, sekä JUnit-yksikkötestausjärjestelmää. 5.2 Hylätyt tekniikat 5.2.1 PHP Projektin alussa järjestelmän toteutsvaihtoehdoissa annettiin asiakkaan puolesta joko PHP tai J2EE. OtaShop1, on toteutettu PHP:tä käyttäen. Neuvotteluissa asiakkaan kanssa totesimme kuitenkin että J2EE on sopivampi alusta OtaShop2:n toteutukseen sillä se mahdollistaa turvallisemman ja helpommin laajennettavan järjestelmän toteuttamisen. Tämän lisäksi kaikilla projektin jäsenillä on kokemusta Java-projekteista joten J2EE:n opetteluun ei kulu ylimääräistä aikaa. Vaatimusta tarkennettiin myöhemmin siten että J2EE on nyt vaatimus asiakkaan puolesta. 6. Lähteet

Asiakirjan nimi OtaShop2 vaatimusmäärittely OtaShop2 projektisuunnitelma Design Patterns OtaShop2 ulkoasudokumentti Lyhyt kuvaus asiakirjan sisällöstä OtaShop2-projektin vaatimusmäärittely dokumentti OtaShop2-projektin suunitelma Henkilökohtainen tehtävä: Design patterns, Matti Kosunen OtaShop2:n ulkoasun määrtelmä ja kuvaus