www.niksula.cs.hut.fi/~jjkankaa// Käyttöohje v. 0.8 Päivitetty 19.3.2001 klo 21:59
2 (12) Dokumentin versiohistoria Versio Päivämäärä Tekijä / muutoksen tekijä Selite 0.8 19.3.2001 Janne Kosmeettisia muutoksia ja enimmät kirjoitusvirheet pois 0.5 19.3.2001 Mickey Shroff Alustava versio www.niksula.cs.hut.fi/~jjkankaa// KÄYTTÖOHJE 2
3 (12) Sisällys DOKUMENTIN VERSIOHISTORIA... 2 1. JOHDANTO... 4 1.1 KÄYTTÄJÄT... 4 1.2 YHTEENSOPIVUUS... 4 1.3 KÄYTTÖTARKOITUS... 4 1.4 YLEISKUVAUS... 5 1.5 MÄÄRITELMÄT, TERMIT JA LYHENTEET... 5 1.6 VIITTEET... 5 1.7 VIRHERAPORTOINTI... 6 2. ASENNUS JA KÄYTTÖÖNOTTO... 6 2.1 ASENNUS... 6 2.2 KÄYTTÖÖNOTTO... 6 3. TOIMINNOT (REFERENCE)... 7 3.1 KÄYTTÖTARKOITUS... 7 3.2 TOIMINNOT... 7 4. VIRHEILMOITUKSET... 12 www.niksula.cs.hut.fi/~jjkankaa// KÄYTTÖOHJE 3
4 (12) 1. JOHDANTO Dokumentin tämä versio koskee pääasiassa seuraavassa vaiheessa(luovutusvaihe) tapahtuvaa testausta. Päivitetään seuraavan vaiheen aikana asiakkaalle suunnatuksi, lopulliseksi versioksi. 1.1 Käyttäjät Käyttäjäluokkia on kaksi. He ovat ns. Java-ohjelmoijia ja ohjelmistosuunnittelijoita. Ohjelmoijilta vaaditaan vankat perustiedot Java ohjelmoinnista. Ohjelmistosuunnittelijoiden pitäisi olla perillä patternien periaatteista. 1.2 Yhteensopivuus Koska kyseessä on sovelluskehikko, jonka palvelut mukautetaan kehitettävän ohjelmiston tarpeisiin, ei se aiheuta yhteensopivuusongelmia, vaan lähinnä pyrkii välttämään tällaisten tilanteiden syntymistä. Koska sovelluskehikko on toteutettu Javalla, ei laitteiston yhteensopivuudessa pitäisi aiheutua ongelmia. Sovelluskehikko ei itsessään aseta laitteistoon kohdistuvia vaatimuksia. Ohjelmistoa, jota kehitetään sovelluskehikon palveluiden kautta asettaa omat sovelluskohtaiset tehovaatimukset laitteistolle. Näin ollen ei laitteistolle voida tässä vaiheessa asettaa muita vaatimuksia kuin, että Java virtuaalikone pyörii kyseisessä. 1.3 Käyttötarkoitus Sovelluskehikkoa käytetään apuna käyttäjien tunnistamiseen ja käyttäjäoikeuksien hallintaan hajautetussa. Sovelluskehikko toteuttaa kehysrakenteen, jonka toiminnoilla voidaan implementoida erilaisia sovelluksia hajautetussa. Esimerkki tällaisesta sovelluksesta voisi olla weppikauppa, jossa käyttäjien tunnistaminen ja käyttäjäoikeuksien hallinta on keskeisessä asemassa. Sovelluskehikon avulla käyttäjätietokantojen sekä muiden sovelluksen tietokantojen hallinta on helppoa ja hauskaa. Tässä dokumentissa pyritään selvittämään kuinka sovelluksia voidaan toteuttaa käyttäen apuna sovelluskehikon palveluita. Sovelluskehikkoon saadaan sovelluksen tarvitsemaa toiminnallisuutta toteuttamalla komentoja. Käyttäjäoikeuksien hallinta voidaan toteuttaa sovelluskehikon abstrakteja tietolähderajapintoja periyttämällä. www.niksula.cs.hut.fi/~jjkankaa// KÄYTTÖOHJE 4
5 (12) 1.4 Yleiskuvaus Lyhyt dokumentin sisäinen kuvaus. Kappale 1 kokonaisuudessaan pohjustaa lukijan kyseiseen aiheeseen. Kappale 2 antaa ohjeet sovelluskehikon asentamiseksi toimintakuntoon. Kappale 3 esittelee kuinka sovelluskehikon palveluita voidaan käyttää. Kappale 4 esittää sovelluskehikon poikkeukset. 1.5 Määritelmät, termit ja lyhenteet Sovelluskehikko Projektissa toteutettava lopputuote Sovellus Asiakkaan toteuttama sovelluskehikkoa hyödyntävä ohjelma Sovelluskehikon käyttäjä Asiakkaan ohjelmoija, joka käyttää sovelluksen tekemiseen projektissa valmistunutta sovelluskehikkoa Sovelluksen käyttäjä Asiakkaan sovellusta käyttävä henkilö tai prosessi Komento Komento on esimerkiksi jokin operaatio tai toiminto, jonka sovelluksen käyttäjä voi suorittaa sovelluksessa. Oikeus Sovelluksen käyttäjä tarvitsee komennon suorittamiseen oikeuden, joka tarkastetaan ennen kuin komento suoritetaan. Oikeuteen voi sisältyä lipuke. Kredentiaalit Käyttäjätietojen osa, joka sisältää tarpeelliset tiedot käyttäjän oikeuksien tarkistamiseen sovelluksessa. Kredentiaalit koostuvat esimerkiksi käyttäjän yksilöivästä tunnisteesta ja joukosta oikeuksia. 1.6 Viitteet Sovelluskehikon toiminnallinen määrittely v. 1.0: http://www.niksula.cs.hut.fi/~jjkankaa//toiminnallinenmaarittely1.0.doc Sovelluskehikon teknillinen määrittely, v. 3.0: http://www.niksula.cs.hut.fi/~jjkankaa//tekninenmaarittely3.0.doc www.niksula.cs.hut.fi/~jjkankaa// KÄYTTÖOHJE 5
6 (12) 1.7 Virheraportointi Virheet raportoidaan kurssin tarjoamaa Burana-virheenraportointijärjestelmää käyttäen. Mahdolliset virheet raportoidaan Buranan käyttöohjeen mukaisesti. Ongelma tilanteissa yhteyshenkilö Tomas Björnfot vastaa kysymyksiin. Kysymykset voidaan lähettää osoitteeseen tomas.bjornfot@aware.fi. 2. ASENNUS JA KÄYTTÖÖNOTTO 2.1 Asennus Sovelluskehikko toimitetaan jar-paketissa. Sovelluskehikon konfigurointi tapahtuu erilaisten tiedostojen avulla, jotka löytyvät config-hakemiston alta. Kun testisovellusta halutaan ajaa täytyy se tehdä siitä hakemistosta, josta configalihakemisto löytyy. Sovelluskehikon testisovelluksen pitäisi toimia myös silloin, jos config-hakemisto lisätään luokkapolkuun (classpath). Sovelluskehikko vie levytilaa n. 2Mb. Testiympäristönä käy mikä tahansa Javaa tukeva ympäristö. Suositeltavaa olisi kuitenkin käyttää Windows NT4:sta tai Windows2000 käyttöjärjesteltelmänä, koska varsinainen sovelluskehikon testaus on suoritettu kyseisissä ympäristöissä. Sovelluskehikon käyttö omissa sovelluksissa vaatii oman sovelluksen Javalähdekoodien kääntämisen. Siksi sovelluskehikon käyttöön tarvitaan Javaohjelmointiympäristö. Sovelluskehikko toimii jdk1.2.2. versioista ylöspäin. Asennus vaatii aikaa 10-30 minuuttia riippuen siitä onko sovelluskehikon käyttäjällä Java-ohjelmointiympäristö asennettuna. Asennus voidaan tarkistaa onnistuneeksi ajamalla TestClass-sovellus. Jos tämän suoritus menee läpi ilman virheilmoituksia voidaan sovelluskehikon asennus todentaa onnistuneeksi. TestClass-luokka ja siihen liittymät muut luokat toimitetaan sovelluskehikon mukana. 2.2 Käyttöönotto Ennen sovelluskehikon käyttöönottoa ja esimerkkisovelluksen ajamista, tulisi tämä käyttöohje lukea huolellisesti läpi, turhien ongelmia välttämiseksi. Kappaleessa 2.1 käsitellään sovelluskehikon asennusta. www.niksula.cs.hut.fi/~jjkankaa// KÄYTTÖOHJE 6
7 (12) 3. TOIMINNOT (REFERENCE) 3.1 Käyttötarkoitus Sovelluskehikko tarjoaa kolmenlaisia palveluita: komentojen luonnin, käyttäjän tunnistamisen ja käyttäjien oikeuksien hallinnan. Komentojen luonti -palvelulla tarkoitetaan toiminnallisuuden lisäämistä sovelluskehikkoon. Tämä tarkoittaa sitä, että komentoja käyttämällä voidaan luoda oman sovelluksen toiminnallisuus. Komennot voivat olla joko turvattuja tai turvaamattomia. Turvaamattomia komentoja voivat suorittaa kaikki käyttäjät, turvattuja komentoja voivat suorittaa vain sellaiset käyttäjät, joilla on tähän oikeudet. Komennon luonti koostuu kolmesta vaiheesta: komentoluokan, komentokohteen ja komentovasteen koodaamisesta. Komentoluokan välityksellä annetaan komennon mahdolliset välitettävät parametrit. Komentokohteessa suoritetaan varsinaiset toimenpiteet, jotka komennolla halutaan saavuttaa. Kun komento suoritetaan, palauttaa se komentovasteen. Komentovasteella voidaan saada mahdolliset palautteet komennon suorittamisesta. Käyttäjien tunnistaminen -palvelu antaa mahdollisuuden tunnistaa sovelluskohtaiset käyttäjät halutulla tavalla. Käyttäjät voidaan tunnistaa lukuisilla eritavoilla, kuten sormenjäljistä, verkkokalvosta tai perinteisellä salasana- ja käyttäjätunnus -sanaparilla. Sovelluskehikko antaa siis mahdollisuuden toteuttaa erilaisia käyttäjän tunnistamispalveluita. Käyttäjien oikeuksien hallinta -palvelu mahdollistaa erilaisten käyttäjätasojen määrittelyn. Käyttäjätasoja voi olla esimerkiksi administrator, normal user tai advanced user. Käyttäjien oikeuksia käsitteleviä palveluita voidaan kehittää lisää sovelluskehikon palveluita käyttämällä. 3.2 Toiminnot Kaikista toiminnoista tulevat esimerkkikoodit toimitettavan paketin mukana. 3.2.1 Turvaamattoman komennon luonti Tällaisen komennon suorittaminen ei vaadi minkäänlaisia oikeuksia komennon suorittajalta, käyttäjältä. Tämän kaltaisilla komennoilla on siis mahdollista toteuttaa sovellukseen toimintoja, jotka ovat kaikkien käyttäjien käytettävissä. Seuraavaksi käydään komennon luonti esimerkinomaisesti läpi. 3.2.1.1 Komentoluokka Toteutetaan sovelluskehikon tarjoama Command- rajapinta: public class NotSecuredExampleCommand implements Command www.niksula.cs.hut.fi/~jjkankaa// KÄYTTÖOHJE 7
8 (12) Tässä toteutettavan komennon luokkanimi on tummennetulla, joka voidaan vapaa valintaisesti valita. Jokaisella komennolla pitää olla ID, jonka avulla sovelluskehikko reitittää komennot komentokohteelle. Tämä ID-string voidaan valita siten, että muilla komennoilla ei ole samaa ID:tä. private final String commandid = "NOT_SECURED_EXAMPLE_COMMAND"; Lisäksi juuri luodun NotSecuredExampleCommand-luokan täytyy toteuttaa getcommandid-metodi, jota sovelluskehikko käyttää tunnistaakseen komennon. public String getcommandid( ) { } return commandid; Ohjelmoija voi lisätä myös omia metodejaan komentoluokkaan. Näitä voidaan käyttää esim. parametrien välittämiseen komentokohteelle. 3.2.1.2 Komentovaste Toteutetaan sovelluskehikon tarjoama Response- rajapinta: public class NotSecuredExampleResponse implements Response Response voi sisältää mitä tahansa tai voi olla myös tyhjä luokka. 3.2.1.3 Komentokohde Periytetään CommandTarget: public class NotSecuredExampleTarget extends CommandTarget{ getinstance-metodi täytyy override:ta. Tämän metodin avulla on mahdollista tehdä komentokohteesta singleton. public static CommandTarget getinstance() { throw new UnsupportedOperationException(); www.niksula.cs.hut.fi/~jjkankaa// KÄYTTÖOHJE 8
9 (12) } execute-metodiin laitetaan kaikki koodi siitä, mitä komennolla halutaan tehdä. Argumentti command sisältää luodun komento-instanssin, jolta voidaan suorittaa omia komentometodeja, jotka sisältävät jonkinlaista parametri tietoa. public abstract Response execute(command command); Execute-metodin sisällä myös luodaan instanssi komentovasteesta, joka palautetaan komentoa kutsuvalle oliolle. NotSecuredExampleResponse resp = new NotSecuredExampleResponse(((NotSecuredExampleCommand)command ).getmessage()); 3.2.1.4 Sovelluskehikon konfigurointi Jotta komento voitaisiin käyttöönottaa täytyy sovelluskehikko konfiguroida huomioimaan juuri luotu komento. Tiedostoon commandfactory.properties täytyy lisätä juuri luodun komennon Id ja sen luokka. NOT_SECURED_EXAMPLE_COMMAND=fi.aware.AHMA.test.NotSecuredExamp lecommand Näin sovelluskehikko saa tiedon siitä mikä ID kuuluu millekin komennolle. Seuraavaksi täytyy huolehtia siitä, että komento menee oikealle komentokohteelle. Tiedosto commandmap.properties on luotu tätä tarkoitusta varten. NOT_SECURED_EXAMPLE_COMMAND=fi.aware.AHMA.test.NotSecuredExamp letarget www.niksula.cs.hut.fi/~jjkankaa// KÄYTTÖOHJE 9
10 (12) 3.2.2 Turvatun komennon luonti Turvattuja komentoja voidaan käyttää tilanteissa, joissa vain tietyt käyttäjät/käyttäjäryhmät voivat suorittaa vain tiettyjä komentoja. 3.2.2.1 Komentoluokka Turvattu komento periytetään SecuredCommand-luokasta. 3.2.2.2 Komentovaste Sama kuin turvaamattomassa komennossa. 3.2.2.3 Komentokohde Sama kuin turvaamattomassa komennossa. 3.2.2.4 Sovelluskehikon konfigurointi Komennon ID ja komentokohteen kirjaaminen käy samoin kuin turvaamattomassa komennossa, kunhan ID ja luokkien nimet vaihdetaan oikeiksi. 3.2.3 Käyttäjien tunnistaminen Käyttäjien tunnistaminen tapahtuu metodirajapintaa käyttäen seuraavasti: UseridPasswordAuthentication passwordauth = (UseridPasswordAuthentication)authInst.getInstance(authType); Principal p = passwordauth.authenticate(userid, password); Sovelluskehikossa on jo valmiiksi toteutettu käyttäjätunnus/salasana autentikointi tapa. Näin saatua principal:ia voidaan käyttää turvattujen komentojen suorittamiseen. Principal voidaan hakea erilaisista tietokannoista. Sovelluskehikko on konfiguroitu käyttämään SQL-kantaa(SQLUserDatasource.java) käyttäjätietojen hakemiseen. Principal-luokasta periytetty TestPrincipal Toimii tällä hetkellä käyttäjätietolähteen pohjana. Tämän kertoo mitä käyttäjätietoja haetaan kannasta käyttäjän Principalinstanssiin. www.niksula.cs.hut.fi/~jjkankaa// KÄYTTÖOHJE 10
11 (12) Konfigurointitiedostossa AHMA.properties voidaan kyseinen principal vaihtaa omaan principaliin. Samassa tiedossa voidaan valita aktiivinen käyttäjätietolähde. Alla olevasta rivistä pitäisi ottaa kommentti pois, jos SQL-käyttäjätietolähdettä halutaan käyttää ja LDAP:n vastaava kommentoida. #UserDatasourceConfigFile =config\\sqluserdatasource.properties Käyttäjätietolähdekannassa tulisi aina olla käyttäjätunnus- ja salasanasarake. Tiedosto SQLUserDatasource.properties sisältää SQL-kannan asetukset, jotka pitäisi vaihtaa omaa SQL-kantaa vastaaviksi. 3.2.4 Käyttäjä oikeuksien hallinta Kun halutaan suorittaa turvattu komento, sovelluskehikko hoitaa oikeuksien tarkistamisen. Oikeudet haetaan ns. credentials-tietolähteestä, joka voi olla jokin tietokanta. Tällä hetkellä credentials-tietolähteenä toimii SQL-tietokanta. Tiedostosta AHMA.properties tulisi varmistaa, että rivi CredDatasourceConfigFile =config\\sqlcredentialsdatasource.properties ei ole kommentoituna. Credentials-tietokannassa tulisi aina olla seuraavat sarakkeet: käyttäjätunnus, komennon ID, sekä action string. SQLCredentialsDatasource.properties tiedostoon voidaan vaihtaa vastaavat kentät omaa kantaa vastaaviksi. 3.2.5 Komentojen suorittaminen 3.2.5.1 Sovelluskehikon alustaminen Ennen sovelluskehikon palveluiden ohjelmallista käyttämistä täytyy sovelluskehikko alustaa. Alustaminen tapahtuu seuraavalla metodikutsulla: CommandManager.init(). www.niksula.cs.hut.fi/~jjkankaa// KÄYTTÖOHJE 11
12 (12) 3.2.5.1 Turvaamattoman komennon suorittaminen Turvaamaton komento ei tarvi käyttäjän tunnistamispalveluita, vaan komento voidaan suorittaa sinällään näin: NotSecuredExampleCommand cmd = (NotSecuredExampleCommand)CommandFactory.createCommand("NOT_SECU RED_EXAMPLE_COMMAND ) 3.2.4.1 Turvatun komennon suorittaminen Koska turvatun komennon suorittaminen vaati oikeuksien tarkistamisen, täytyy käyttäjä autentikoida ennen komennon suorittamista: UseridPasswordAuthentication passwordauth = (UseridPasswordAuthentication)authInst.getInstance(authType); Principal p = passwordauth.authenticate(userid, password); Autentikoinnin seurauksena saadaan käyttöön käyttäjän principal, jonka avulla sovelluskehikko voi päätellä, onko kyseisellä käyttäjällä oikeuksia komennon suorittamiseen. TestCommand testcmd = (TestCommand)CommandManager.getInstance("TEST_COMMAND"); testcmd.setprincipal(p); TestResponse testresp = (TestResponse)CommandManager.execute(testCmd); 4. VIRHEILMOITUKSET Sovelluskehikon omia poikkeuksia ovat: AuthenticationException, tilanne jolloin käyttäjän tunnistaminen ei onnistu. NoPermissionException, tilanne jolloin käyttäjän oikeudet eivät riitä komennon suorittamiseen. TargetNotFoundException, tilanne joka syntyy, kun komennon kohdetta ei löydy. www.niksula.cs.hut.fi/~jjkankaa// KÄYTTÖOHJE 12
13 (12) CommandNotFoundException, tilanne joka syntyy, kun komento luokkaa ei löydy tai sitä ei ole konfiguroitu käytettäväksi sovellukseen. Sovelluskehikko käyttää virheiden ilmoittamiseen ja tallentamiseen log4javakomponenttia. Konfigurointi tiedossa AHMALog.properties voidaan vaihdella kyseisen komponentin kirjaamistasoja. Apachen weppi-sivuilla on tarkemmat tiedot komponentin toiminnasta ja konfiguroinnista. www.niksula.cs.hut.fi/~jjkankaa// KÄYTTÖOHJE 13