XML Ohjelmistokehityksessä 8105200 1/9 1 Yleistä 1.1 Tavoitteet Harjoitus 2: Vaatimukset Harjoitustyön toisen vaiheen tarkoituksena on toteuttaa ensimmäisen vaiheen tietovaraston päälle verkkopalvelu, joka tarjoaa vastaavan toiminnallisuuden kuin minkä tietovarasto tarjoaa. Tämän lisäksi harjoitustustyössä luodaan staattinen asiakas, jonka kautta voidaan käyttää web-palvelun toimintoja. Verkkopalvelutoiminnallisuuden lisäksi toteutettavaan komponenttiin luodaan julkaisurajapinta, jota käyttäen asiakas voi pyytää palvelun julkaisua, julkaisun kumoamista sekä palvelun informaation noutamista. Tämä toiminto rakennetaan käyttäen hyväksi UDDI-palvelinta, johon julkaistaan palvelun koostava liikealakokonaisuus (business entity eli meillä Warehouse tms.) ja sen lisäksi vastaavat liikealapalvelut (meillä Item Service ja Loan Service). Palveluiden rajapinnoissa on jouduttu tekemään kompromisseja, jotta harjoitusten kolmannen vaiheen toteutus voidaan tehdä käyttäen hyväksi samaa rajapintaa. 1.2 Palautus Harjoitus palautettavat 21.03.05 klo 12.00 (maanantai). 1.3 Versiointi Versio Tila Päiväys Tekijä Selite (muutokset, korjaukset yms.) 1.0 Vedos 02.02.05 MM Alustava versio 1.0 Ehdotus 08.02.05 MM Korjattu rajapintojen kuvauksia 1.1 Ehdotus 11.02.05 MM, AR Katselmointi 1.2 Ehdotus 14.02.05 MM, AR Katselmointi 1.3 Julkistus 16.02.05 MM,AR Katselmointi
XML Ohjelmistokehityksessä 8105200 2/9 2 Vaatimuserittely 2.1 Yleistä 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.1.1 Vaatimukset 0000 Yleisasiat 0001 Luo web-palvelu Warehouse JWSDP:llä 0002 Toteuttaa nimikepalvelun (ItemService) 0003 Toteuttaa lainauspalvelun (LoanService) 0004 Toteuttaa palvelun julkistuksen (ServicePublisher) 0005 Käytetään hyväksi HT1:n tietovarastoa 0100 Inspector-tarkastajaan opiskelija toteuttaa toiminnallisuuden, joka demoaa rajapintojen toiminnallisuutta 0101 Palvelun käyttämiseksi luodaan staattinen asiakas 0200 Lainaajaa ei tarvitse autentikoida 0201 Rinnakkaisuutta ei tarvitse erikseen huomioida 2.2 Nimikepalvelu (ItemService) 2.2.1 Vaatimukset 1000 Nimikepalvelu-rajapinta (ItemService) 1001 Nimikepalvelu toteuttaa HT1:n kohtien 1000-1400 kuvausta vastaavan verkkopalvelun 1002 Palvelussa on lisää-operaatio (add), jolla lisätään uusi nimike (Item) tietovarastoon 1003 Palvelussa on poista-operaatio (remove), jolla poistetaan olemassaoleva nimike (Item) varastosta 1004 Palvelussa on etsi-operaatio (find), jolla etsitään nimikettä (Item) tietovarastosta (HUOM! Rajapinta muuttunut) 1005 Palvelussa on muuta-operaatio (change), jolla muutetaan yksittäisen nimikkeen (Item) tietoja 1006 Palvelussa on näytä-operaation (show), jolla listataan kaikki tietovarastossa olevat nimikkeet (Item) (HUOM! Rajapinta muuttunut) 1007 Nimikepalvelu voidaan sijoittaa Tomcatin kontekstiin /warehouse/item
XML Ohjelmistokehityksessä 8105200 3/9 Kaikki metodit varautuvat heittämään RemoteException poikkeustilanteessa. «interface» rmi::remote «extends» «interface» IItemService + add(item :Item) : void + remove(identifier :String, label :String) : void + change(identifier :String, label :String, newitem :Item) : void + finditemcount(searchcriteria :Item) : Integer + finditem(index :Integer) : Item + showitemcount() : Integer + showitem(index :Integer) : Item 1100 Lisää operaatio (add) 1101 add-operaatiolla lisätään yksi nimike varastoon 1102 Attribuutit: item: Varastoon lisättävän uuden tuotteen tiedot. Item item 1124 Lisäys toimii kuten harjoituksessa 1 1125 Jos add-operaatio jostain muusta syystä toimii virheellisesti, asiasta huomautetaan poikkeuksella. 1200 Poista operaatio (remove) 1201 remove-operaatio poistaa annetun nimikkeen varastosta. 1202 Attribuutit: String identifier String label identifier: Poistettavan tuotteen tunniste label: Poistettavan tuotteen nimi 1225 Jos remove-operaatio jostain syystä toimii virheellisesti, asiasta huomautetaan poikkeuksella 1300 Muuta operaatio (change) 1301 change-operaatio korvaa vanhan tuotteen tiedot uuden tuotteen tiedoilla. 1302 Attribuutit: String identifier String label Item newitem identifier: Poistettavan tuotteen tunniste label: Poistettavan tuotteen nimi newitem: Tuotteen uudet tiedot. Tyhjä kenttä tarkoittaa, että tieto on kopioitava vanhasta. 1310 Vanha tuote tunnistetaan samoilla säännöillä kuin Harjoitustyö 1:ssä. 1311 Virhetilanteessa ilmoitetaan poikkeuksella missä tuli virhe 1400 Etsi operaatio (find) 1401 find-toiminolla haetaan annettua nimikettä. 1410 Find-toiminto toteutetaan rajapinnassa kahdella iteraattorifunktiolla Integer finditemcount( Item searchcriteria ) Item finditem( Integer index ) 1420 finditemcount-metodilla haetaan tunnistettavien nimikkeiden lukumäärä (>=0) 1421 finditemcount-metodin palauttaman joukon voidaan olettaa säilyvän palvelussa ainakin peräkkäisten finditemcount ja finditem kutsujen ajan 1430 finditem-metodilla haetaan tunnistettavista nimikkeistä halutulla indeksillä oleva nimike 1440 Hakuehdot ovat samat kuin Harjoituksessa 1 find-operaatiolla 1441 Virhetilanteessa palautetaan sopiva poikkeus
XML Ohjelmistokehityksessä 8105200 4/9 1450 Find-toiminnon käyttö: Integer count = itemservice.finditemcount( searchcriteria ); for (int index = 0; index < count; index++) { anitem = itemservice.finditem( index ); // tee jotain itemillä } 1500 Näytä operaatio (show) 1501 show-toiminto palauttaa nimikejoukon kaikista varastossa olevista nimikkeistä. 1510 Show-toiminto koostuu kahdesta metodista: Integer showitemscount( ) Item showgetitem( Integer index ) 1520 ShowItemsCount-metodi palauttaa kaikkien talletettujen nimikkeiden lukumäärän (>=0) 1521 showitemcount-metodin palauttaman joukon voidaan olettaa säilyvän palvelussa ainakin peräkkäisten showitemcount ja showitem kutsujen ajan 1530 showitem-metodi palauttaa indeksin mukaisen nimikkeen 1540 Jos indeksi on <0 tai suurempi kuin nimikkeiden lukumäärä, huomautetaan asiasta poikkeuksella 1541 Jos show-metodit jostain muusta syystä epäonnistuu, niin asiasta huomautetaan poikkeuksella. 1550 show-toiminnon käyttö: Integer count = itemservice.showitemcount( ); for (int index = 0; index < count; index++) { anitem = itemservice.showitem( index ); // tee jotain itemillä } 2.3 Lainauspalvelu (LoanService) 2.3.1 Vaatimukset 2000 Lainauspalvelu-rajapinta (LoanService) 2001 Lainauspalvelu ylläpitää lainaustietoja 2002 Palvelussa on nimikkeen lainaus-operaatio (borrowitem), jolla voidaan lainata nimike lainaajalle 2003 Palvelussa on lainan palautus-operaation (returnloan), jolla voidaan palauttaa nimike lainasta 2004 Palvelussa on lainan etsintä-operaatio (findloan), jolla voidaan etsiä tiettyä laina 2005 Palvelussa on lainojen näyttö-operaatio (showloans), jolla voidaan näyttää kaikki lainat 2010 Nimikepalvelu tulee sijoittaa Tomcatin kontekstiin /warehouse/loan
XML Ohjelmistokehityksessä 8105200 5/9 Kaikki metodit varautuvat heittämään RemoteException poikkeustilanteessa. «interface» rmi::remote «extends» «interface» ILoanService + borrowitem(borrower :String, identifier :String) : void + returnloan(borrower :String, identifier :String) : void + findloancount(borrower :String, identifier :String) : Integer + findloan(index :Integer) : Loan + showloancount() : Integer + showloan(index :Integer) : Loan 2100 Lainaa nimike (borrowitem) 2101 borrowitem-toiminnolla lainataan nimike (Item) jollekin henkilölle. borrower: Lainaajan nimi 2102 Attribuutit: identifier: Lainattavan tuotteen tunniste String borrower String identifier 2110 Toiminnallisuus kuten harjoituksessa 1 2120 Jos tulee joku virhe, niin siitä tulee ilmoittaa poikkeuksella. 2200 Palauta laina (returnloan) 2201 returnloan-toiminnolla voidaan palauttaa laina. 2202 Attribuutit: String borrower String identifier borrower: Lainaajan nimi identifier: Lainattavan tuotteen tunniste 2210 Toiminnallisuus kuten harjoituksessa 1 2220 Jos tulee joku virhe, niin siitä tulee ilmoittaa poikkeuksella. 2300 Etsi laina (findloan) 2301 findloan-toiminnolla haetaan tietyn nimikkeen tunnisteen tai nimikkeen lainaajan perusteella. 2302 FindLoan-toiminto koostuu 2:sta iteraatio-metodista Integer findloancount( String borrower, String identifier ) Loan findloan( Integer index ) 2310 findloancount palauttaa etsittyjen lainojen lukumäärän (>= 0) 2311 FindLoanCount-metodin palauttaman joukon voidaan olettaa säilyvän palvelussa ainakin peräkkäisten findloancount ja findloan kutsujen ajan 2320 findloan palauttaa pyydetyllä indeksillä olevan lainan löydettyjen joukosta 2321 Jos indeksi findloan-metodille on virheellinen (indeksi < 0 tai suurempi kuin nimikkeiden lukumäärä), tulee operaation palauttaa poikkeus sisältäen selkeän viestin, miksi operaatio epäonnistui 2330 Muuten toiminnallisuus kuten harjoituksessa 1 2331 Jos tulee joku virhe, niin siitä tulee ilmoittaa poikkeuksella.
XML Ohjelmistokehityksessä 8105200 6/9 2340 FindLoan-toiminnon käyttö: Integer count = loanservice.findloancount( identifier, borrower ); for (int index = 0; index < count; index++) { aloan = loanservice.findloan( index ); // tee jotain loanilla } 2400 Näytä lainat (showloans) 2401 showloans-toiminnolla haetaan kaikki lainat. ShowLoans-operaatio koostuu 2:sta iteraatio-metodista Integer showloanscount() 2402 Loan showloan( Integer index ) 2410 ShowLoansCount palauttaa lainojen lukumäärän (>= 0) ShowLoansCount-metodin palauttaman joukon voidaan olettaa säilyvän palvelussa 2411 ainakin peräkkäisten showloanscount ja showloan kutsujen ajan 2420 ShowLoan palauttaa pyydetyllä indeksillä olevan lainan Jos indeksi showloan-metodille on virheellinen (indeksi < 0 tai suurempi kuin lainojen lukumäärä), tulee operaation palauttaa poikkeus sisältäen selkeän viestin, miksi 2421 operaatio epäonnistui 2430 Jos tulee joku muu virhe, niin siitä tulee ilmoittaa poikkeuksella. showloans-toiminnon käyttö: Integer count = loanservice.showloancount( ); for (int index = 0; index < count; index++) { aloan = loanservice.showloan( index ); 2440 } // tee jotain loanilla 2.4 Tarkastus 3000 Tarkastuksen apuvälineet (ExcerciseEngine2) ExcerciseEngine-luokka tarjoaa tehtaan erilaisiin palvelurajapintoihin tarkastusta 3001 varten Opiskelija laajentaa ExcerciseEngine-luokasta luokan ExcerciseEngine2, joka 3002 palauttaa vaaditut rajapinnat opiskelijan haluamasta luokasta (luokista) 3003 getitemservice-operaatio palauttaa ItemService-rajapinnan asiakastoteutuksen 3004 getloanservice -operaatio palauttaa LoanService-rajapinnan asiakastoteutuksen 2.5 Tietovaatimukset 4000 Tietovaatimukset 4001 Nimiketiedot ja lainatiedot tallennetaan yhteen XML-tiedostoon 4002 Lainaaja ei tarvitse tunnistusta 4003 Tietovaraston osalta pätevät harjoituksen 1 ominaisuudet 4004 Tiedoston tallennus (mieluiten) palvelun omaan hakemistoon 2.6 Palvelun asennus (Tomcat deploy) 6000 Palvelun asennus 6001 Tomcat-palvelimelle tulee asentaa (deploy) palvelubinääri
XML Ohjelmistokehityksessä 8105200 7/9 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 voi lisätä rivin <user username= manager password= manage fullname= Manager roles= manager > 6200 Item palvelu tomcatin kontekstiin /warehouse/item 6201 Loan palvelu tomcatin kontekstiin /warehouse/loan 2.7 Palvelun julkistus UDDI-palveluun (ServicePublisher) 7000 Julkistu-rajapinta (ServicePublisher) 7001 ServicePublisher rajapinta osaa julkistaa palvelun (publishservice), etsiä palvelun (findservice) ja poistaa palvelun (removeservice) annetulta UDDI-palvelimelta 7002 Organisaation tiedoiksi voi laittaa omia tietoja tai jotain huuhaa tietoja. Ainakin organisaatiolle pitää keksiä nimi ja yhteyshenkilö 7100 publishservice-operaatio julkistaa palvelun (organisaatio ja palvelut) UDDIpalvelimelle void publishservice( String uddihostname, // UDDI-registeri esim. localhost String username, // julkaisun käyttäjätunnus String password // julkaisun salasana ) throws Exception 7101 Palvelun julkaisun epäonnistuminen ilmaistaan poikkeuksella (esim. PublishException) 7102 UddiHostName on verkkoosoite UDDI-registeriä tarjoavaan palvelimeen 7103 Username ja password ovat julkaisuun tarvittavat käyttäjätiedot Oletuksena JWSDP:n UDDI-palvelimella ovat testuser ja testuser. 7200 findservice-operaatio etsii palvelua annetulta UDDI-palvelimelta Document findservice ( String uddihostname, // UDDI-registeri esim. localhost String servicename // Service Item tai Service Loan ) throws Exception 7201 FindService-operaatio palauttaa löydetyn palvelun WSDL-dokumentin 7202 ServiceName:lla voidaan ilmaista se palvelu, josta halutaan tiedot (esim. Service Item tai Service Loan) 7203 Virheen tapahtuessa tai jos palvelua ei löydy UDDI-palvelimelta, ilmaistaan asiasta poikkeuksella 7300 removeservice-operaatio poistaa annetulta palvelimelta sinne julkaisemamme palvelun void removeservice( String uddihostname, // UDDI-registeri esim. localhost String username, // julkaisun käyttäjätunnus String password, // julkaisun salasana String servicename // Service Item tai Service Loan ) throws Exception
XML Ohjelmistokehityksessä 8105200 8/9 7301 Palvelun julkistamisessa käytetään UDDI-palvelimen oletustunnusta registry.username=testuser registry.password=testuser 7400 ServicePublisher toteutukselle voi tehdä oman testaus main-luokan, joka osaa ajaa kolme yllä olevaa metodia seuraavilla kutsuilla (esim.): 2.8 Toteutus java xmlohj.publisher -1 // suorita publishservice java xmlohj.publisher -2 // suorita publishservice java xmlohj.publisher -3 // suorita removeservice 5000 Toteutus 5001 Harjoitustyössä tulee käyttää ensimmäisen harjoituksen tietovarastoa hyväksi joko siten, että kopioi harjoitustyön lähdekoodia hyväksi sellaisenaan (kopioi), tai käännettynä (common-hakemistossa JAR-pakettina) 5002 Toteutuksessa pitää käyttää Java JDK:n ja JWSDP:n tarjoamia kirjastoja 5003 Toteutuksessa saa käyttää ulkopuolisia kirjastoja Poikkeukset ovat vastaavat kuin harjoituksessa 1, mutta ne TULEE periä 5004 RemoteException-luokasta ServicePublisher rajapinnan metodien ei tarvitse heittää virhetilanteessa 5005 RemoteException-poikkeuksia vaan pelkkiä Exception-tyyppisiä ServicePublisher kannattaa kasata JAR-kirjastoksi common-hakemistoon ja käyttää 5006 client-hakemistossa olevaa 2.9 Tuotteenhallinta 8000 Tuotteenhallinta 8001 Ulkopuoliset kirjastot pitää toimittaa palautuspaketin mukana common-hakemistossa ja toimittaa ne Tomcatille (ulkoisten kirjastojen asentuvuus ja toimivuus Tomcatilla pitää olla varmistettu) 8002 Päätason käännösohjaustiedoston (build.xml) pitää sisältää tehtävät: 1) HARJ2 käännä ja aseta ohjelma ajokuntoon (palvelun käännös, asennus, asiakasosuuden kääntö) 2) AJA2 suorita harjoituksen 2 client-ohjelman 3) PALAUTUS tuottaa palautuspaketin 4) PALVELU.JULKISTA julkista organisaatio omilla tiedoillasi sekä palvelut UDDI:in 5) PALVELU.ETSI.ITEM etsi item-palvelu ja tulosta wsdl 6) PALVELU.ETSI.LOAN etsi loan-palvelu ja tulosta wsdl 7) PALVELU.POISTA poista organisaatio UDDIsta 8) PUHDISTA poista käännöstuotteet, poista palvelu Tomcatilta ja UDDIrekisteristä 8003 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) run_graf ajaa Inspector:in graafisena 3) clean poistetaan käännöksen aikaiset tiedostot
XML Ohjelmistokehityksessä 8105200 9/9 8004 Konfiguraatiodokumentti, jossa kerrotaan mitä ominaisuuksia pitäisi löytyä xmlohj.properties tiedostosta sekä mitä oletetaan CLASSPATH:in ja PATH:in sisällöstä. 8100 xmlohj.properties-tiedostosta pitää löytä seuraavat ominaisuudet: xmlohj.home = sinun harjoituksen juurihakemisto (esim. c:/xmlohj/, jos harjoituksesi tulee c:/xmlohj/123456-hakemistoon) tomcat.host = localhost tms. eli Tomcat palvelimen nimi tomcat.port = 8080 tai 9000 tms. eli portti, josta Tomcat vastaa uddi.host = localhost tms. eli uddi-palvelimen nimi uddi.port = 8080 tai 9000 tms. eli portti, josta uddi vastaa registry.username=testuser uddi-registerin käyttäjätunnus registry.password=testuser uddi-registerin käyttäjätunnuksen salasana 8101 DemoService (nimeltään NewService) sisältää esimerkin xmlohj.properties ja proj.properties tiedostoista Harjoitus voidaan rakentaa hakemistoihin seuraavalla tavalla: 123456/ opiskelijanumero build.xml päätason käännösohjaustiedosto Harjoitus2/ ensimmäisen harjoituksen hakemisto build.xml harjoituksen käännösrakentaja proj.properties projektikohtaiset ominaisuudet configure.html.txt dokumentti, joka kertoo mitä ominaisuuksia pitää määritellä, jotta käännös ja ajo onnistuisivat Client/ src/ lähdekoodihakemisto xmlohj/ client/ asiakasohjelman toteutus inspector/ tarkastuksien toteutus build/ Server/ src/ lähdekoodihakemisto xmlohj/ server/ palvelimen toteutus build/ Publisher/ src/ lähdekoodihakemisto xmlohj/ build/ common/ junit.jar munomajokukirjasto.jar Hakemistopuuta saa muokata, mutta vähintään lihavoidut osiot pitää löytyä 2.10Palautus 9000 Palautus 9001 Palautuspaketti sisältää koko harjoitustyöhakemistopuun 9002 Palautuspaketti on jar-paketti 9003 Palautuspaketin nimi on muotoa: xmlohj_ht2_opikelijanumero_etunimisukunimi.jar 9004 Palautetaan vain lähdekoodi ja lisäkirjastot, jotka eivät kuulu oletusympäristöön Eli aja clean ennen pakkausta