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

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.