Sampsa Lintunen
Tiina Pöyhönen
Teemu Vähä-Ruka
Timo Ylönen
TemplateHandler-käyttöohje 25.6.2003
Jyväskylän yliopisto
Tekijät:
Sampsa
Lintunen (
sampsa@cc.jyu.fi)
Tiina
Pöyhönen (
tmpoyhon@cc.jyu.fi)
Teemu
Vähä-Ruka (
teemuvr@cc.jyu.fi)
Timo
Ylönen (
tylonen@cc.jyu.fi)
Yhteystiedot: Agora, huone C223.2, puh.nro. 014-260 49 64. Projektiorganisaation sähköpostilista on kottarainen@korppi.jyu.fi. Sen keskustelua voi seurata osoitteessa http://korppi.it.jyu.fi/list-archive/kottarainen/. Kotisivu löytyy osoitteesta: http://kotka.it.jyu.fi/kottarainen/.
Työn nimi: Kottarainen-projekti, TemplateHandler-käyttöohje.
Työ: TemplateHandler-käyttöohje tietotekniikan sovellusprojektiin.
Tiivistelmä: Kottarainen-projekti toteutti prototyypin WWW-pohjaisesta kyselyjen hallintasovelluksesta. Projektissa keskityttiin kyselyn laatimiseen ja siihen vastaamiseen. Kottarainen-sovellus tulee olemaan yksi aiemmin toteutetun Korppi-järjestelmän moduuleista. TemplateHandler-käyttöohjeessa esitellään sivupohjien käsittelyyn tarkoitetun java-pavun käyttöä.
Avainsanat: Tiedonkeruu, kyselyt, palaute, WWW-lomakkeet, WWW-sovellus, Korppi-järjestelmä.
Kottarainen-niminen tietotekniikan Sovellusprojekti toteutti prototyypin WWW-pohjaisesta kyselyjen laatimis-, hallinta- ja analysointisovelluksesta Jyväskylän yliopiston käyttöön. Projektin puitteissa toteutuneita osia ovat kyselyiden luominen WWW-ympäristöön ja kyselyyn vastaaminen. Muut osiot siirrettiin jatkokehitykseen, mutta ne on huomioitu sovelluksen ja tietokannan rakenteessa sekä kirjattu vaatimusmäärittelyyn.
Kottarainen-sovellus
on yksi Korppi-nimisen opetushallintajärjestelmän moduuleista.
Järjestelmään ovat aiemmin toteuttaneet sovelluksia Kotka-,
Korppi-, Halko-,
Kolibri-,
Koppelo- ja Kiuru-projektit. Niitä on edelleen jatkokehitetty
Jyväskylän yliopiston tietotekniikan laitoksella.
TemplateHandler-pavun tarkoituksena on helpottaa SQL- ja HTML-koodin käsittelyä ja hallittavuutta Java-ohjelmissa. Perusperiaatteena on, että SQL- ja HTML-koodit sijaitsevat erillisissä sivupohjatiedostoissa, jotka pitävät sisällään useita erilaisia SQL-kyselyjä ja HTML-lohkoja. Kyselyt ja HTML-lohkot sisältävät staattista tekstiä ja makroja, joiden arvoja voidaan Java-koodissa asettaa. TemplateHandler korvaa ko. makrot palauttaen käsitellyn ja oikean muotoisen SQL- tai HTML-tekstin.
Alkuperäinen TemplateHandlerin käyttökohde on käyttää sitä JSP-ohjelmissa, mutta luokkaa voi käyttää myös muissa Java-sovelluksissa. Tässä ohjeessa kuitenkin esitellään käyttöä nimenomaan JSP-sivuilta. Sovelluksen toteutus ja muut Java-pavut sekä JSP-sivut on esitelty Sovellusraportissa.
Luvussa 2 esitellään TemplateHandlerin käyttöä JSP-sivulla sekä sivupohjan syntaksi. Luvussa 3 opastetaan TemplateHandler-pavun käyttöä ohjelmakoodin tasolla. Luvuissa 4 ja 5 on havainnollistettu TemplateHandlerin käyttöä esimerkein HTML-sivujen ja SQL-lauseiden tapauksissa.
TemplateHandler-pavun käyttämiseksi tarvitaan tekstimuotoinen sivupohja-tiedosto sekä ohjelmakoodia sisältävä JSP-tiedosto. Kyseisellä JSP-sivulla määritellään sivupohjatiedostossa korvattavat arvot ja käytettävä sivupohjatiedosto sekä kutsutaan TemplateHandler-papua. Tässä luvussa on esitelty TemplateHandlerin toimintaa rakennekuvan avulla sekä sivupohjatiedoston syntaksi.
Luvussa
esitellään
TemplateHandlerin
käyttöä JSP-sivulta (katso kuva 1). WWW-sovellusta selaava
käyttäjä kutsuu JSP-sivua siirtyessään toiselle sivulle.
JSP-sivulla
luodaan uusi
TemplateHandler-käsittelijäolio
ja asetetaan sille oikea hakemistopolku. Hakemistopolku kertoo
käsittelijäoliolle, missä sivupohjatiedostot sijaitsevat
(JSP-sivujen ja Java-Papujen yhteydessä HTMT-tiedostot ja lisäksi
Java-pavuissa SQL-hakuja tehtäessä SQLT-tiedostot).
Hakemistopolun asettamisen jälkeen oliossa luodaan uusi taulukko parametreille ja asetetaan siihen JSP-sivulla määritellyt arvot, joiden nimet vastaavat HTMT-tiedostossa määriteltyjen muuttujien nimiä. Seuraavaksi käsittelijä täydentää sivupohjan annetuilla arvoilla. Käsittelijä käyttää HTMT-sivua pohjana ja täydentää sen HTML-koodiksi parametrien arvojen avulla sekä palauttaa sivupohjatiedoston kyseisen osion HTML-koodin JSP-sivulle. Lopuksi JSP-sivulla tulostetaan saatu HTML-koodi käyttäjälle. Kuva 1 näyttää, kuinka käsittelijä täydentää koodilohkoja.
Sivupohja- eli template-tiedosto voi sisältää useita eri osioita. HTMT-tiedostot sisältävät HTML-osioita ja SQLT-tiedostot SQL-osioita eli eri SQL-kyselyjä. TemplateHandler-käsittelijäpapua voi kutsua JSP-sivulta tai muista Java-pavuista useampaan kertaan siten, että se käsittelee eri kerroilla määritellyn sivupohjatiedoston eri osioita. Näin voidaan täydentää vaikkapa sivupohjatiedoston osioita toisten sivupohjatiedoston osioiden sisään ja samaan tiedostoon voi laittaa esimerkiksi useampia SQL-lauseita.
TemplateHandler käsittelee aina yhden tiedoston yhtä osiota kerrallaan. Osioiden nimet aloitetaan ja lopetetaan hakasululla ( [ ja ]). Aloitusmerkki [ on oltava rivin ensimmäinen merkki. Seuraava template-tiedoston esimerkki sisältää osiot ensimmainen_osio ja toinen_osio:
[ensimmainen_osio]
Nimeni
on pera
[toinen_osio]
Pituuteni
on 190 cm
Makrot aloitetaan ja lopetetaan aaltosululla ja kaksoispisteellä ( {: ja :}). Seuraavaksi esitellään äskeinen esimerkki sisältäen makrot Nimi ja Pituus, jotka korvataan kutsuvassa JSP-sivussa tai Java-pavussa määritetyillä tiedoilla. Osiot näyttävät template-tiedostossa seuraavilta:
[ensimmainen_osio]
Nimeni
on {:Nimi:}
[toinen_osio]
Pituuteni
on {:Pituus:} cm
Tiedot makroja varten annetaan käsittelijälle parametri-taulukossa, jossa avaimena on haluttu sana. Edellisen esimerkin tapauksessa taulukossa ovat siis alkiot avaimilla Nimi ja Pituus arvoinaan pera ja 190, mikäli halutaan lopputuloksen olevan kuten ensimmäisessä esimerkissä.
Luvussa esitellään TemplateHandler-nimisen Java-pavun käyttöä ohjelmakoodin tasolla. Papu voidaan luoda ja ottaa käyttöön joko JSP-sivulla tai toisessa Java-pavussa. Luvussa esimerkkien avulla havainnollistetaan pavun toimintaa ja siten helpotetaan sen toiminnan ymmärtämistä ja pavun käyttöönottoa.
TemplateHandlerin konstruktorissa sille viedään käsiteltävän HTMT- tai SQLT-sivupohjatiedoston nimi polkuineen. Ohjelmoijan on pidettävä huoli siitä, että tiedoston koko hakemistopolku on oikein.
Seuraavassa on esimerkki TemplateHandlerin luomisesta:
TemplateHandler TH = new TemplateHandler("esimerkki.sqlt");
Nyt siis on luotu uusi TemplateHandler-käsittelijäolio, jonka sivupohjatiedostoksi on asetettu esimerkki.sqlt. Mikäli tiedosto sijaitsisi jossain muussa hakemistossa kuin itse TemplateHandler-papu, niin parametrina tulisi viedä tiedoston täydellinen polku.
Parameter-olio on taulukko, jossa avain on String-tyyppiä perinteisen numeroinnin sijaan. Olion avulla viedään parametreina halutut arvot TemplateHandlerille, joka sitten täydentää konstruktorissa määritellyn sivupohjan kyseisillä tiedoilla. Kerrallaan käsitellään vain kutsussa mainittua sivupohjatiedoston osiota (katso luku 3.3).
Seuraavana on esimerkki params-olion luonnista ja arvon asettamisesta taulukkoon:
Properties
params = new Properties();
params.setProperty("Nimi",
"Pena Peloton");
Nimi-parametri vastaa sivupohjalla aaltosulkeiden ja kaksoispisteiden välissä olevaa kenttää (katso luku 2.2). Kyseinen kenttä korvataan siis parametrin Nimi arvolla Pena Peloton .
Kun TemplateHandleria pyydetään käsittelemään tietty sivupohjatiedoston osio, sille viedään parametreina käsiteltävän osion nimi ja Parameter-luokan taulukossa makrot korvaavat tekstit. Paluuarvona saadaan String-muuttujana halutuilla parametreilla täydennetty valmis sivupohja eli joko HTML-koodi tai SQL-lause.
Seuraavana on esimerkki osion ensimmainen_osio käsittelykutsusta. Params-muuttujassa (katso luku 3.2) viedään halutut arvot makrojen tilalle:
String sisalto = TH.CompleteTemplate("ensimmainen_osio",params);
Luvussa esitellään esimerkin avulla, millainen sisältö voisi olla JSP-tiedostolla ja HTML-sivupohjatiedostolla.
HTMT-tiedoston esimerkki.htmt sisältö voisi yksinkertaisimmillaan koostua yhdestä osiosta ( [Main]) ja yhdestä makrosta ( {:Nimi:}) seuraavasti:
[Main]
Minun
nimeni on {:Nimi:}
JSP-tiedostossa esimerkki.jsp luodaan käsittelijäolio, asetetaan parametrit ja käsitellään sivupohja, eli korvataan makro {:Nimi:} halutulla merkkijonolla. Sivun sisältö voisi näyttää seuraavalta:
<%@page import="kottarainenbeans.*"%>
<%
//Tässä
haetaan oikea polku:
String
templatepath = pageContext.getServletContext().getRealPath
("esimerkki.htmt");
//Tässä
luodaan uusi käsittelijä, jolle annetaan //parametrina edellinen polku:
TemplateHandler
TH = new TemplateHandler(templatepath);
//Tässä
luodaan uusi Properties-taulukko, johon //voidaan asettaa haluttuja parametreja
//arvoineen:
Properties
params = new Properties();
params.setProperty("Nimi","Nikodeemus");
//Metodi CompleteTemplate täydentää osion main //annetuilla parametreilla ja palauttaa sen //kokonaisuudessaan. sisalto-muuttujan arvo on //siis seuraavan rivin suorituksen jälkeen "Minun //nimeni on Nikodeemus".
String sisalto = TH.CompleteTemplate("Main",params);
%>
//Seuraava
rivi on käsky tulostaa JSP-sivulle
//sisalto-muuttujan
sisällön.
<%= sisalto %>
Luvussa esitellään esimerkin avulla, millainen sisältö voisi olla JSP-tiedostolla ja SQL-sivupohjatiedostolla.
SQLT-tiedoston esimerkki.sqlt sisältö voisi olla vaikkapa yksinkertainen valintalause:
[Person]
SELECT
{:Fields:}
FROM
{:Table:}
Vastaavassa JSP-tiedostossa esimerkki.jsp sisältö voisi olla esimerkiksi seuraavanlainen (katso templateHandlerin tarkempi kommentointi luvun 4 esimerkistä):
<%@page import="kottarainenbeans.*"%>
<%
//Tässä
haetaan oikea polku:
String
templatepath = pageContext.getServletContext().getRealPath
("esimerkki.sql");
//Tässä
asetetaan uusi TemplateHandler ja sille
//oikea
polku.
//Lisäksi
alustetaan uusi Propesties-taulukko,
//johon
asetetaan arvot avaimilla Fields ja Table
TemplateHandler
TH = new TemplateHandler(templatepath);
Properties
params = new Properties();
params.setProperty("Fields","Etunimi,Sukunimi");
params.setProperty("Table","Person");
//Seuraavan
rivin jälkeen käytössä olisi SQL-//lause SELECT
Etunimi,Sukunimi FROM Person
String
parsedSQL = TH.CompleteTemplate("Person",params);
Projektiryhmä päätyi TemplateHandlerin käyttöön sen vuoksi, että erilaiset ohjelmakoodin palaset, kuten SQL, HTML ja Java, saataisiin mahdollisimman pitkälle pidettyä erillään toisistaan. Tavoitteessa onnistuttiinkin hyvin. Aluksi tämän sivupohjiin perustuvan ajattelutavan omaksuminen oli työlästä, mutta kun koodi saatiin toimivaksi, sen ylläpito oli helppoa.
Lintunen Sampsa, Pöyhönen Tiina, Vähä-Ruka Teemu, Ylönen Timo, "Kottarainen- projektin Sovellusraportti" Jyväskylän yliopisto, tietotekniikan laitos, 2003.
Santanen Jukka-Pekka, "Opinnäytteiden kirjoittaminen, lyhyt oppimäärä", Jyväskylän yliopisto, tietotekniikan laitos, 2000.