Harjoitus 1: Vaatimukset

Transkriptio

1 Web-palveluiden toteutustekniikat OHJ /9 1 Yleistä 1.1 Tavoitteet Harjoitus 1: Vaatimukset Ensimmäisen harjoitustyön tarkoituksena on toteuttaa tietopalvelu web-sovellukselle käyttäen XML:n käsittelyn perustekniikoita ja rajapintoja. Harjoitustyön sovelullusalueena on nettiselaimen kaltainen jsp-servlet kokonaisuus (annetaan valmiina), joka mahdollistaa nettiselailun käyttäen hakusanoja. Käytännössä tämä tarkoittaa tietopalvelua, joka mahdollistaa elementtien lisäyksen, poiston, muokkauksen ja haun XML-tiedostoon. Tietopalvelu toteutetaan käyttäen eri XML-prosessoinnin perustekniikoita: DOM- ja SAX-rajapinnat XML-tiedoston jäsentämiseen, Xpath-hakulausekkeet sekä XML-Schema (XSD-tiedosto) XMLtiedoston validointiin. Harjoituksen ensimmäisessä vaiheessa ei saa hyödyntää JAXB tms. työkaluja, mutta muissa harjoituksen vaiheissa saa käyttää JDK:n ja JWSDP:n tarjoamia kirjastoja haluamallaan tavalla sekä ympäristön ulkopuolisia kirjastoja. Jos opiskelija käyttää ulkopuolisia kirjastoja, ne tulee toimittaa palautusten mukana. 1.2 Versiointi Versio Tila Päiväys Tekijä Selite (muutokset, korjaukset yms.) 1.0 Vedos TG Alustava versio 2.0 Valmis TG Jakeluversio 2.1 Valmis TG Korjattu 2 Vaatimuserittely 2.1 Yleistä Tietopalvelu tarjoaa operaatioita XML-tiedoston elementtien hallinnointiin: lisäys, poisto, haku, listaus ja muokkaus. Opiskelijalta vaaditaan, että harjoitustyön palautus sisältää toteutuksen em. toiminnoille. Tietopalvelun toiminta tulee testata käyttäen JUnit:a. Testauksen automisointiympäristön kehys annetaan, mutta opiskelijan tulee itse toteuttaa vaaditut testitapaukset, jotka osoittavat toteutuksen toimivan pyydetyllä tavalla. Vaatimukset ryhmässä 0000 ovat harjoitustyön kannalta tärkeitä. Muissa ryhmissä esiintyvät asiat ovat enemmänkin täydentäviä vaatimusattribuutteja kuin vaatimuksia. Ainoastaan rajapintojen nimet ja niiden metodien kuvaukset ovat tärkeitä ja ne pitää säilyttää sellaisinaan.

2 Web-palveluiden toteutustekniikat OHJ / Vaatimukset 0000 Yleisasiat 0001 DOM, SAX ja Xpath käyttö toteutuksessa 0002 Toteutus tietopalvelulle (XMLService) 0003 Tarvittavat tiedot tallennetaan XML-tiedostoon 0004 Tarvittavat tiedot luetaan XML-tiedostosta 0010 Toteutus XMLExceptionille 0011 Toteutus Page-tietotyypille 0012 Palvelu luo tarvittaessa XML-tiedoston, jos sellainen ei ole olemassa 0013 Oletustiedoston nimi olkoon file.xml 0014 Palvelun tulee varautua siihen, että oletustiedostot vaihtuvat ajon aikana 0015 XML-tiedosto validoidaan XML-Scheman avulla Palveluiden operaatiot ovat luonteeltaan atomisia eli niitä ei keskeytetä kesken suorituksen (tarkastus on sarjallistettua eli vain yksi operaatio tapahtuu tietyllä ajanhetkellä) 0021 Palveluiden operaatiot kuvaavat yhden transaktion eli operaatioiden aiheuttamat muutokset tiedoissa tallentuvat operaation lopuksi tiedostoon Toteuttaa testaukseen JUnit testitapauksia Harjoitustyössä tulee käyttää Javan versiota 1.5 eli Tietopalvelun pitää toimia XMLBrowser-sovelluksen kautta Ympäristömalli Ympäristömalli kuvaa harjoitustyössä toteutettavan palvelun suhteita valmiiksi annettuihin komponentteihin. Kuva 2.1 Harjoituksen ulkoiset riippuvuudet XMLBrowser-sovellus (WebApp) toimii harjoituksen käyttöliittymänä. Sovelluksen selainkonteksti löytyy osoitteesta (esim. sen jälkeen kun luotu war-paketti siirretään tomcatin kontekstiin. Sovellus (HT1Servlet + jsp-sivut) periaatteessa kyselee tarvittavia asioita ja välittää ne eteenpäin web-palvelun liiketoimintalogiikkakerrokseen saakka. Liiketoimintalogiikkakerros on opiskelijan toteuttama luokka, joka tarjoaa palvelun logiikan yhdessä luokassa.tietopalvelun (XMLService) liiketoimintalogiikkakerroksen tulee toteuttaa XMLServiceInterface-rajapinnan operaatiot. Valmiina annettavan koodin logiikkaa ei saa muuttaa.

3 Web-palveluiden toteutustekniikat OHJ /9 Testaus tehdään käyttäen JUnit-ympäristöä. Valmiin palvelun tulee toimia annetun web-sovelluksen kanssa. 2.2 Tietopalvelu Yleistä Tietopalvelun tulee toteuttaa XMLServiceInterface (kuva2.2). Kuva 2.2 XMLService-rajapinta Tietotyyppi Page kuvaa XML-elementin page:n, joka sisältää informaation yhdestä internet-sivusta. Informaatio ilmaistaan kentillä id, key, address, description. Tietopalvelun tulee heittää XMLException virhetilanteissa Vaatimukset 1000 Tietopalvelu (XMLService) 1001 Tietopalvelu hallinnoi XML-tiedostossa olevia nimikkeitä 1002 Tietopalvelun täytyy koostua vähintää liiketoimintalogiikkakerroksesta (nimeä XMLService). Käytännössä toteutus kannattaa tehdä niin että dom:lle, sax:lle jne... toteutetaan omat palvelut joita liiketoimintalogiikkakerros tarjoaa eteenpäin. Esim Lisää-operaatio (add) lisää yhden nimikkeen tietovarastoon 1004 Poista-operaatio (remove) poistaa yhden nimikkeen tietovarastosta 1005 Muuta-operaatio (modify) muuttaa annetun nimikkeen tietoja 1006 Etsi-operaatio (search) etsii yhden nimikkeen 1007 Näytä nimikkeet-operaatio (show) tekee XML-tiedostosta HTML-tiedoston 1009 Tietopalvelu heittää virhetilanteissa poikkeuksen (XMLException) 1010 Palvelun käyttämiä tiedostoja voi vaihtaa lennosta (changefiles)

4 Web-palveluiden toteutustekniikat OHJ / Lisää-operaatio (add) 1101 Operaatiolla lisätään yksi nimike XML-tiedostoon 1102 void add( Page page // tiedostoon lisättävä uusi nimike ) throws XMLException 1103 Tiedostoon ei voida lisätä nimikettä, jolla on sama tunniste kuin jo tiedostossa olevalla nimikkeellä 1104 Tietovarastoon ei voida lisätä tyhjää tai muuten viallista nimikettä 1105 Tunnisteen(id) pitää olla oikean muotoinen Helpoin tapa tarkistaa id:n validisuus on käyttää java.util.regex-kirjastoa Jos lisää-toiminto jostain muusta syystä toimii virheellisesti, asiasta huomautetaan 1109 Onnistuneen lisäyksen jälkeen tulee muutos tallentaa tiedostoon 1110 Toteutus: DOM-ratkaisu 1200 Poista-operaatio (remove) 1201 Operaatio poistaa annetun nimikkeen tiedosta void remove( String id // Varastosta poistettava nimike ) throws XMLException 1203 Poistettava tuote tunnistetaan samoilla säännöillä kuin hakukin (search) Poisto ei onnistu, jos nimikettä ei löydy (XMLException) 1205 Poisto ei onnistu, jos nimikkeitä löytyy useampi kuin yksi (XMLException) 1207 Jos poista-toiminto jostain syystä toimii virheellisesti, asiasta huomautetaan (XMLException) 1208 Onnistuneen poiston jälkeen tulee muutos tallentaa tiedostoon 1209 Toteutus: DOM-ratkaisu 1300 Muuta-operaatio (modify) 1301 Operaatio korvaa vanhan tuotteen tiedot uuden tuotteen tiedoilla void modify( Page page //Muutoksen sisältävä nimike ) throws XMLException 1304 Muutettaessa kaikki löydetyn nimikkeen tiedot, paitsi tunniste, korvautuvat uuden nimikkeen annetuilla tiedoilla Jos uuden nimikkeen Key on jo käytössä, ei muokkausta toteuteta (XMLException) 1309 Jos vanhan nimikkeen tiedoilla löytyy useampi kuin yksi vanha nimike, ei muokkausta toteuteta 1310 Jos vanhaa nimikettä ei löydy ollenkaan, ei muokkausta voida suorittaa 1311 Tunnisteen pitää olla oikean muotoinen 1312 Jos muokkaa-toiminto jostain syystä toimii virheellisesti, asiasta huomautetaan 1313 Toteutus: DOM-ratkaisu

5 Web-palveluiden toteutustekniikat OHJ / Etsi-operaatio (search) 1401 Etsi-toiminnossa haetaan annettua nimikettä Page search( String searchterm // Tiedostosta etsittävän nimikkeen avain ) throws XMLException 1403 Search() funktiolla etsitään avaimella (key) page-elementti josta muodostetaan Pagetietotyyppi 1404 Nimikkeen merkkijonoissa voidaan käyttää myös villimerkkiä * (mikä tahansa merkkijono; käyttö esim. Jukk* ja *kka ) 1405 Jos nimikettä ei löydy tai nimikkeitä löytyy enemmän kuin yksi ( XMLException ) Jos jostain muusta syystä etsi-toiminto toimii virheellisesti, huomautetaan asiasta 1407 Toteutus: XPath 1500 näytä-operaatio (show) 1501 Näytä-toiminto muodostaa XML-tiedostosta HTML-tiedoston 1502 String show( ) throws XMLException 1503 Paluutietona palautetaan absoluuttinen osoite luotuun HTML-tiedostoon 1504 HTMLGenerator apuluokkaa saa käyttää tiedoston luomiseen. Apuluokkaa saa muokata tarvittaessa Jos jostain muusta syystä näytä-toiminto toimii virheellisesti, huomautetaan asiasta 1506 HTML-tiedoston tulee olla muotoa (ei tarvitse olla pilkulleen sama): <html lang="en"> <head> <META http-equiv="content-type" content="text/html; charset=utf-8"> <title>xmlbrowser pages</title> </head> <body> Key: tut<br> Address: <a href=" <br> Description: tty<br> <a href="xmlbrowser?action=editpage.jsp&id=aac &key=tut&address= Edit </a><a href="xmlbrowser?action=delete&id=aac "> Delete</a> <hr> Key: hs<br> Address: <a href=" /a> <br> Description: Helsinginsanomat<br> <a href="xmlbrowser?action=editpage.jsp&id=gds &key=hs&address= ption=helsinginsanomat"> Edit </a><a href="xmlbrowser?action=delete&id=gds "> Delete</a> <hr> </body> </html> 1507 Toteutus: SAX

6 Web-palveluiden toteutustekniikat OHJ / Vaihda tiedostoja(changefiles) 1701 changefiles() vaihtaa.xsd ja.xml tiedostot haluttaessa XMLService changefiles( String XMLFile, String XSDFile ) throws XMLException; 1703 changefiles() palauttaa palvelun uusilla tiedostoilla Jos jostain muusta syystä Vaihda tiedostoja-toiminto toimii virheellisesti, huomautetaan asiasta 1800 XMLException 1801 XMLException pitää toteuttaa kaksi operaatiota. getexception() ja gettrace() getexception() palauttaa String:nä virheviestin. Viestin muoto on XMLException: + virhe esim. XMLException: Nimikkeen lisääminen ei onnistunut! 1804 gettrace() palauttaa String:nä tiedon siitä missä virhe on sattunut. Palautettavia tietoja on luokka, funktio ja rivi jossa virhe sattui. Viesti on muotoa XMLException trace: class: DomHandler, function: add(), line: 55! 2.3 Testaus 3000 Testaus JUnit testitapauksilla 3010 Kaikkia operaatiota pitää testata 3011 Testitapausten pitää kattaa onnistuneet operaatiot (esim. Add() lisää nimikkeen onnistuneesti) 3020 Testitapausten pitää kattaa operaatioden kaikki tässä dokumentissa määritellyt poikkeukset ( paitsi ne poikkeukset, joissa poikkeuksen aiheuttavaa virhettä ei ole määritelty ) 3023 Lisää Junitilla testauksesta JUnit-ohjeesta 2.4 Tietorakenteet 3500 Tietotyypit (Page) 3501 Tietotyyppi mallintaa XML-elementti page:n ohjelmassa käytettävään muotoon 3503 Page:n pitää sisältää seuraavat kentät 3504 Key; sisältää String:nä hakusanan 3505 Address; sisältää String:nä hakusanaa vastaavan nettiosoitteen 3506 Description; sisältää String:nä kuvauksen nettiosoitteen sisällöstä 3507 Id; sisältää String:nä page:n id:n 3508 Id:n tulee noudattaa seuraavaa muotoa: identifier := aaa bbb cccc aaa := 3 {alphaminor} 3 // kirjaimia tasan kolme bbb := 1 {alphanum} 3 // kirjaimia tai numeroita yhdestä kolmeen alphanum := alphamajor number // yksi kirjain tai numero cccc := 4 {number} 4 // numeroita tasan neljä number := [0-9] alphamajor := [A-Z] alphaminor := [a-z] Helpoin tapa tarkistaa id:n validisuus on käyttää java.util.regex-kirjastoa Tietotyypin pitää toteuttaa Serializable -rajapinta Tietenkin kaikille kentille setterit ja getterit.

7 Web-palveluiden toteutustekniikat OHJ /9 2.5 Tietovaatimukset 4000 Tietovaatimukset 4001 Nimiketiedot tallennetaan yhteen XML-tiedostoon 4002 XML-tiedoston esimerkki 4003 <?xml version="1.0" encoding="utf-8"?> <webpages> <page id="gds "> <key>hs</key> <address> <description>helsinginsanomat</description> </page> <page id="fgl "> <key>juve</key> <address> <description>juvenes ravintolat</description> </page> </webpages> 4010 XML-tiedon muodon kuvaus XML Schema-tiedostolla (file.xsd) 4011 XML-tiedon muodon oikeellisuuden tarkistaminen (validointi) XML-Schema tiedoston avulla 4012 Jos XML-tiedosto ei ole scheman mukainen, tulee asiasta tiedottaa asianmukaisella XMLException-poikkeuksella 4013 Poikkeusta ei tule heittää tyhjän varaston luvun yhteydessä 4020 Id:n tulee noudattaa seuraavaa muotoa: identifier := aaa bbb cccc aaa := 3 {alphaminor} 3 // kirjaimia tasan kolme bbb := 1 {alphanum} 3 // kirjaimia tai numeroita yhdestä kolmeen alphanum := alphamajor number // yksi kirjain tai numero cccc := 4 {number} 4 // numeroita tasan neljä number := [0-9] alphamajor := [A-Z] alphaminor := [a-z] Helpoin tapa tarkistaa id:n validisuus on käyttää java.util.regex-kirjastoa. 2.6 Palvelun asennus (Tomcat deploy) 6000 Palvelun asennus 6001 Tomcat-palvelimelle tulee asentaa (deploy) palvelubinääri 6002 Tomcat-pavelimelta tulee poistaa (undeploy) palvelubinääri 6100 Tomcatille palvelun asentamista varten luotava Manager-tunnus, jonka oikeuksilla asennetaan binääri 6101 JWSDP/conf/tomcat-users.xml-tiedostoon pitää lisätä rivin <user username= manager password= manage fullname= Manager roles= manager > Tässä tapauksessa JWSDP tarkoittaa jwsdp-tomcat-hakemistoa War-paketti luodaan WebApplication/dist-kansioon automaattisesti 6300 Lisää Tomcat:sta ja War-paketista Tomcat-ohjeesta

8 Web-palveluiden toteutustekniikat OHJ /9 2.7 Muita asioita 7000 Toteutus 7001 Koodin pitää olla tyylisääntöjen mukaista. Sekavasta koodista, liian pitkistä funktiosta ja huonosta luokkajaosta voidaan verottaa pisteitä Koodia pitää kommentoida siinä määrin että palvelun käyttäjä ymmärtää operaatioden ja luokkien (alkukommentti) toiminnan. Myös sekavat kohdat operaatioden sisällä pitää kommentoida. Sellaista koodia ei tarvitse kommentoida mistä käy selkeästi selville mitä tehdään. Esim. getdocument() kohtaa ei tarvitse kommentoida tyyliin //haetaan dokumentti 7003 Toteutuksessa saa käyttää ulkopuolisia kirjastoja 7006 Synkronointia ei tarvitse huomioida kurssin aikana (välttämättä). Eli oletustilanne on se, että AINA palveluita käyttää vain YKSI asiakas kerrallaan Esimerkkiympäristöä saa mukauttaa omien tarpeiden ja tämän harjoituksen vaatimusten puitteissa 8000 Tuotteenhallinta 8001 Harjoitus voidaan rakentaa hakemistoihin seuraavalla tavalla: / opiskelijanumero build.xml päätason käännösohjaustiedosto me.properties webser.properties konfiguraatio.txt / harjoituksen hakemisto build.xml proj.properties WebApplication/ src/ webser/ actions/ Action.java HT1Actions.java XMLServiceInterface.java ht1application/ Consts.java HT1Servlet.java build/ dist/ web/ include/ WEB-INF/ harjoituksen käännösrakentaja projektikohtaiset ominaisuudet Nettisovellus lähdekoodihakemisto Service/ src/ lähdekoodihakemisto webser/ xmlservice/ 1. vaiheen tietopalvelu XMLServiceInterface.java XMLService.java Liiketoimitalogiikkakerros Omia luokkia.java build/ dist/ JUnitTests/ src/ Alltests.java ExampleTest.java OmatTest.java common/ junit.jar Julkaisun hallinta lähdekoodihakemisto Hakemistopuuta saa muokata, mutta vähintään lihavoidut osiot tulisi löytyä Ulkopuoliset kirjastot pitää toimittaa palautuspaketin mukana (Common hakemisto) 8003 Päätason käännösohjaustiedoston (build.xml) pitää sisältää tehtävät:

9 Web-palveluiden toteutustekniikat OHJ /9 1) HARJ1 käännä ja aseta ohjelma ajokuntoon 2) PALAUTUS tuottaa palautuspaketin 3) PUHDISTUS poistaa käännöksen aikaiset tiedostot 8004 Harjoitustason käännösohjaustiedosto tulee sisältää vähintään seuraavat tehtävät: 1) build oletustehtävä, joka kääntää ja valmistelee ohjelman ajoa varten 2) clean poistetaan käännöksen aikaiset tiedostot 8005 Konfiguraatiodokumentti, jos harjoitustyön rakenteeseen on tehty muutoksia esim. common kansiossa oleva kirjasto pitää lisätä build path:in proj.properties tiedostoon tulee laittaa ominaisuuksia, jotka liittyvät harjoitustyöhön me.properties sisältävät nimen ja opiskelijanumeron 8100 Ainoa absoluuttisia polkuja sisältävä tiedosto on webser.properties, joka sijaitsee kotihakemistossa. Kaikkien muiden hakemistoviittauksien tulee osoittaa epäsuorasti (../lib/munomajokukirjasto.jar) tai ominaisuusmuuttujaa hyväksi käyttäen (${user.home}/webser.properties) 2.8 Palautus 9000 Palautus 9001 Palautuspaketti sisältää koko harjoitustyöhakemistopuun (eli juurihakemiston sisältö esimerkissä) 9002 Palautettavan jar-paketin nimi on muotoa: harj1_opikelijanumero_etunimisukunimi.jar 9004 Palautuspaketin tulee sisältää opiskelin oma harjoitustyö KÄÄNTÄMÄTTÖMÄNÄ, (siis ei binäärejä vaan aja clean ennen palautuksen tekoa). Käännöksen vaatimat lisäkirjastot tulee sisällyttää harjoitustyön palautukseen.