Kottarainen-projekti
Sampsa Lintunen
Tiina Pöyhönen
Teemu Vähä-Ruka
Timo Ylönen

TemplateHandler-käyttöohje 25.6.2003

Jyväskylän yliopisto 
Tietotekniikan laitos

Kottarainen-projektin tietoja
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ä.
Versionhallinta
Versio	Päiväys	Tehnyt	Muutokset	
1.0	15.4.2003	Sampsa Lintunen	Ensimmäinen versio ohjeesta.	
1.1	12.6.2003	Timo Ylönen	Korjauksia.	
1.2	16.6.2003	Timo Ylönen	Lisää korjauksia.	
1.3	19.6.2003	Tiina Pöyhönen	Santasen ehdottamia korjauksia.	
1.4	25.6.2003	Teemu Vähä-Ruka	Santasen ehdottamia korjauksia.	
Sisällysluettelo
1	Johdanto
2	Rakenne ja käyttötapa JSP-ohjelmassa
2.1	JSP-ohjelman toiminnasta TemplateHandlerin avulla
2.2	Sivupohjan syntaksi
3	TemplateHandlerin käyttö
3.1	Konstruktori
3.2	Parameter-luokka
3.3	Osion käsittely
4	HTML-esimerkki
5	SQL-esimerkki
6	Yhteenveto
Lähteet

1	Johdanto
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. 

2	Rakenne ja käyttötapa JSP-ohjelmassa
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.
2.1	TemplateHandlerin kutsuminen JSP-sivulta
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.

Kuva 1: TemplateHandler-käsittelijän toiminta.
2.2	Sivupohjan syntaksi
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ä.
3	TemplateHandlerin käyttö
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.
3.1	Konstruktori
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.
3.2	Parameter-luokka
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.
3.3	Osion käsittely
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);

4	HTML-esimerkki
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 %>

5	SQL-esimerkki
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);
%>
6	Yhteenveto
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. 
Lähteet
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.