\documentclass[finnish,12pt,a4paper]{article}

\usepackage[finnish]{babel}
\usepackage{graphicx,t1enc,times,html,longtable}

\setlength{\parindent}{0pt}
\setlength{\parskip}{1.6ex plus 0.5ex minus 0.2ex}

\newcommand{\code}[1]{\texttt{#1}}
\newcommand{\interface}[1]{\paragraph{#1\\*[3mm]}}
\newcommand{\method}[1]{\subparagraph{\code{#1}\\*[1mm]}}

\begin{document}
\bodytext{bgcolor=white}

\sloppy


%%%
%%% Etusivu
%%%

\begin{titlepage}
\begin{flushleft}

\vspace*{\stretch{3}}

\setlength{\baselineskip}{2\baselineskip}
{\large \bf Graafinen k�ytt�liittym� lintujen rengastusj�rjestelm��n} \\
{\large \bf Suunnitteludokumentti} \\

\vspace{\stretch{3}}

Versiohistoria:

\begin{tabular}{|l|l|p{10cm}|}
\hline
0.1 & 28.9.2000 &
Ensimm�inen luonnos. \\
\hline
0.2 & 17.10.2000 &
Toinen luonnos, moduulikuvauksia aloitettu. \\
\hline
1.0 & 19.10.2000 &
Ensimm�inen kokonainen julkaisu. \\
\hline
1.1 & 27.10.2000 &
Korjattu tarkastustilaisuudessa 24.10.2000 k�siteltyj� virheit� ja
puutteita. Testaussuunnitelma lis�tty. \\
\hline
1.2 & 9.11.2000 &
J��dytetty versio. Viimeiset muutokset tehty.\\
\hline
\end{tabular}

\vspace{\stretch{1}}

\setlength{\baselineskip}{0.5\baselineskip}
Helsinki, \today

Lincoyan Kekki, Jaakko Kiviluoto, Juha Markkanen, \\
Juha Niemi, Joona Palaste, Janne Pasanen

HELSINGIN YLIOPISTO \\
Tietojenk�sittelytieteen laitos \\
Ohjelmistotuotantoprojekti Tipu4\\

\end{flushleft}
\end{titlepage}



%%%
%%% Sis�llys
%%%

\clearpage
\pagestyle{myheadings}
\thispagestyle{empty}
\tableofcontents

\clearpage
\pagestyle{myheadings}
\thispagestyle{empty}
\listoffigures


%%%
%%% Tekstiosa
%%%

\clearpage
\pagenumbering{arabic}
\renewcommand{\baselinestretch}{1.4}\normalsize

% \begin{figure}[ht] \centering
% \includegraphics[width=0.9\textwidth]{kuva_lisays.eps}
% \caption{Tiedon lis��minen.}
% \end{figure}



\section {Johdanto}

\subsection {Tuotteen tausta ja tarkoitus}

Helsingin yliopiston el�inmuseon rengastustoimistossa k�ytet��n SQL*Forms
sovelluskehittimell� toteutettua k�ytt�liittym�� rengastus ja
tapaamistietoja sis�lt�v��n tietokantaan. Oracle on kuitenkin ilmoittanut,
ettei se en�� tue SQL*Forms-sovelluksia. Rengastustoimisto
on tehnyt p��t�ksen korvata vanha k�ytt�liittym� uudella.

Projektin tarkoituksena on suunnitella ja toteuttaa graafinen
k�ytt�liittym� lintujen rengastusj�rjestelm��n. Tavoitteena on korvata
vanha merkkipohjainen k�ytt�liittym� graafisella. Tuotantok�yt�ss�
olevasta j�rjestelm�st� on tarkoitus k�ytt�� hyv�ksi Fortran-kielisi�
ohjelman osia.

\subsection {Erikoissanasto ja k�ytetyt lyhenteet}

\begin{longtable}{p{0.22\textwidth}p{0.74\textwidth}}

\textbf{Connection pool} & Ohjelmistoratkaisu, jolla voidaan rajata yhteydet
johonkin tiettyyn resurssiin. N�it� yhteyksi� luodaan ja jaetaan asiakkaille
dynaamisesti. \\

\textbf{HTML} & Hypertext Markup Language on internetiss� k�ytetty tiedon
esitystapa, jota asiakasp��n selaimet osaavat tulkata. \\

\textbf{HTTP} & Hypertext Transfer Protocol on WWW-liikenteen protokolla. \\

\textbf{JDBC-ajuri} & Java DataBase Connectivity "=ajuri, mahdollistaa 
tietokantakutsut palvelinsovelmista. \\

\textbf{Kontrolli} & Rengastajien suorittama rengastetun linnun tapaaminen.
Kontrollit tehd��n pesilt� lintuja pyydyst�m�ll� tai esimerkiksi
kiikaroinnilla. \\

\textbf{L�yt�} & Ennest��n rengastetun linnun kohtaaminen. Lintu voi olla
el�v� tai kuollut. \\

\textbf{Rengastaja} & Lintuharrastaja joka on oikeutettu ja koulutettu
merkitsem��n lintuja virallisilla linturenkailla. \\

\textbf{Rengastus} & Uuden renkaan laittaminen linnulle, jolla ei ennest��n
ole rengasta. \\

\textbf{Servlet} & Javalla koodattu ohjelmamoduuli, joka suoritetaan
palvelimella, palvelinsovelma. \\

\textbf{SQL} & Structured Query Language. Standardi kieli, jolla voidaan
m��ritt�� erilaisia tietokantaoperaatioita. \\

\textbf{Tapaaminen} & Ennest��n rengastetun, el�v�n linnun kohtaaminen. \\

\textbf{Template} & Dokumentin runko, joka sis�lt�� tietyll� tavalla merkittyj�
kohtia, joihin voidaan ohjelmallisesti lis�t� vaihtuvia arvoja. \\

\textbf{Tipukanta} & Rengastustoimistolla k�ytett�v� relaatiotietokanta
rengastusten ja niihin liittyvien tietojen s�ilytt�miseen. \\

\textbf{WWW-Tipu} & T�ss� dokumentissa kuvattu graafinen k�ytt�liittym�
lintujen rengastustietokannalle. \\

\end{longtable}


\subsection {Yleiskatsaus dokumenttiin}

T�m� dokumentti m��rittelee projektissa toteutettavan sovelluksen.
Kahdessa ensimm�isess� luvussa esitell��n projekti ja sen tavoitteet.
Kolmas luku tulee sis�lt�m��n huomautukset vaatimusdokumenttiin tehdyist�
muutoksista, mik�li sellaisia tulee.

Nelj�s luku k�sittelee ohjelman luokkarakennetta. Luku on jaoteltu
loogisten ohjelmistokokonaisuuksien mukaan. Viidenness� luvussa perehdyt��n
erityisesti n�kyv��n k�ytt�liittym��n. Kuudennessa luvussa kerrotaan
ohjelmiston suunnittelua ja toteutusta koskevat rajoitteet.


\section {Sovellusalue}

Ohjelmisto tarjoaa selainpohjaisen k�ytt�liittym�n asiakkaan
k�yt�ss� olevaan lintujen rengastusj�rjestelm��n ja se korvaa aiemman
SQL*Forms sovelluskehittimell� toteutetun merkkipohjaisen k�ytt�liittym�n.
Tavoitteena on tarjota rengastustoimiston ty�ntekij�ille helppok�ytt�inen
ja nykyaikainen k�ytt�liittym� rengastusj�rjestelm��n.

Sovellus tuottaa dynaamisesti HTML-sivuja. K�ytt�j� voi n�iden sivujen
avulla suorittaa hakuja tietokannasta ja yll�pit�� rengastusj�rjestelm�n
tietoja. Sy�tetyt tiedot tarkistetaan ennen niiden p�ivitt�mist� tietokantaan.
HTML-sivuja luova koneisto ja sy�tteet tarkistava sovelluksen osa
sijaitsevat palvelimella. WWW-Tipu ohjelmaa t�ytyy p��st� k�ytt�m��n milt�
tahansa verkkoon liitetylt� tietokoneelta, jossa on tarkoitukseen sopiva
selain. K�ytt�j�kunta saadaan rajattua kysym�ll� ohjelman alussa
k�ytt�j�lt� k�ytt�j�tunnus ja salasana.

\subsection {Koko j�rjestelm� ja ohjelmiston rooli siin�}

Rengastusj�rjestelm�ss� yll�pidet��n tietoja rengastetuista linnuista,
lintujen tapaamisista, rengasjakeluista sek� n�ihin liittyvist�
aputiedoista. Aputietoja k�ytet��n esimerkiksi rengastusten tarkistuksiin.
Ohjelmiston avulla rengastustoimiston
ty�ntekij�t valvovat j�rjestelm�ss� pidett�v�� tietoa. He esimerkiksi
yll�pit�v�t tietoja Suomen kunnista ja niiden maantieteellisist�
koordinaateista, jotta tiedot rengastuksista ja lintu\-havainnoista
voitaisiin tarkistaa ja paikallistaa mahdollisimman tarkasti.

WWW-Tipu on rengastusj�rjestelm�n k�ytt�liittym� Tipukantaan.
Rengastajia varten on tehty oma ohjelma, jolla he v�litt�v�t tiedot
kontrolleista ja rengastamistaan linnuista j�rjestelm��n.



\section {Vaatimusm��rittely ja siihen tehdyt muutokset}

J�rjestelm�n vaatimukset on kuvattu 12.10.2000 p�iv�tyss� dokumentissa
''Graafinen k�ytt�liittym� lintujen rengastusj�rjestelm��n,
Vaatimusdokumentti''. Mit��n oleellisia muutoksia vaatimusm��rittelyyn ei
ole tehty.



\clearpage
\section {Moduulikuvaukset} \label{moduulit}

{\em Huom: Metodien kuvauksissa n�kyvyysm��re on merkitty vain jos metodi on
jotakin muuta kuin julkinen (\texttt{public}) tai ``package private''
eli ilman kirjoitettua m��rett�.}


\subsection {Ohjelmiston toimintaperiaate}

\subsubsection {Ratkaisun filosofia}

WWW-Tipun avulla yll�pidet��n Tipukannan tietoja. Ohjelmaa tulee 
k�ytt�m��n rengastustoimiston henkil�kunta. K�ytt�j�t joutuvat antamaan
k�ytt�jtunnuksen ja salasanan j�rjestelm��n ennen kuin he p��sev�t k�ytt�m��n itse
sovellusta. Valittuaan halutun n�yt�n valikosta k�ytt�j� p��see hakemaan
ja p�ivitt�m��n kannan tietoja. Muutamaa poikkeusta lukuunottamatta yksi
lomake vastaa yht� tietokannan taulua. N�yt�ll� n�kyv� lomake generoidaan
automaattisesti k�ytt�j�n valintojen mukaan.

Sovelluksesta pyrit��n tekem��n yksinkertainen ja helposti
yll�pidett�v�, sill� projektin p��tytty� rengastusj�rjestelm�n yll�pit�j�n 
teht�v�ksi j�� WWW-Tipun jatkokehitys.

WWW-Tipu toteutetaan p��osin Java-kielell�, HTML-dokumenteissa k�ytet��n
apuna JavaScript-kielt�. Ratkaisuun vaikutti se, ett� Java on tehokas ja
ilmaisuvoimainen kieli WWW:ss� toimivien ohjelmien tekemiseen.
JavaScript p��tettiin ottaa yhdeksi ohjelmiston toteuttavaksi kieleksi, 
koska sen avulla HTML-lomakkeiden k�sittely helpottuu ja voidaan jakaa osa
ohjelman ty�st� selaimessa teht�v�ksi. JavaScript lis�� ohjelman
tehokkuutta, osa lomakkeiden tarkistuksista voidaan jo tehd� selaimessa,
yksinkertaisissa virhetilanteissa tietoa ei siis tarvitse l�hett�� 
palvelimelle.

\subsubsection {Toimintaperiaate}

Toteutusymp�rist�n� on Unix. WWW-Tipu k�ytt�� valmista
Oracle-tietokantaa. Tiedon lis�yksen ja p�ivityksen yhteydess�
erillinen Fortran-kielinen Check-ohjelma tarkistaa rengastustiedot ja
tallentaa hyv�ksytyn tiedon Tipukantaan. Kaikkien tietojen tarkistukseen
ei tarvita Check-ohjelmaa, osa muutoksista voidaan tehd� suoraan
tietokantaan.

K�ytett�v� Java servlet -moottori (Apache JServ 1.1) ja Java-k��nt�j�
(Sun J2EE 1.2.2) sijaitsevat TKTL:n Unix-palvelimella alkokrunni alias
db.cs.hel\-sin\-ki.fi. Valmis WWW-Tipu ohjelma tullaan sijoittamaan ATK-
keskuksen palvelimeen.

K�ytt�liittym�n p��sivu ladataan el�inmuseon k�ytt�m�lt� Web-palvelimelta
ja loput sivuista luodaan k�ytt�j�n valintojen mukaan Unix-palvelimelle
sijoitettavien servlettien avulla. HTML-lomakkeiden tiedot l�hetet��n
servleteille HTTP-pro\-to\-kol\-lan GET- ja POST-toiminnoin, tulosteet
generoidaan asiakkaan selaimelle. J�rjestelm�n k�ytt� vaatii Internet
Explorer- tai Netscape-selaimen version 4.0 tai uudemman. 


\subsection{Moduulit ja niiden v�liset suhteet}

WWW-Tipu koostuu nelj�st� p��moduulista, jotka ovat:

\begin{longtable}{p{0.3\textwidth} p{0.62\textwidth}}

\textbf{Java Servlet -luokat} &
N�m� luokat hoitavat kommunikoinnin k�ytt�j�n kanssa HTTP-protokollan
mukaisesti. \\

\textbf{JDBC-tieto\-kanta\-yhteys} &
Hoitaa yhteyden relaatiotietokantaan, jonne tiedot rengastuksista on
talletettu. \\

\textbf{General-luokat} &
Tarvitaan muiden luokkien asetuksia ja Check-ohjelmaa varten. \\

\textbf{Check-ohjelma} &
Fortran-kielinen ohjelma, joka hoitaa k�ytt�j�n antaman datan validoinnin
ennen kuin se lis�t��n tieto\-kantaan. \\

\end{longtable}

Moduulien v�linen kommunikaatio on kuvattu kuvassa \ref{kommunikaatio}.
K�ytt�j�n sy�tt�m� informaatio l�hetet��n Servlet-luokille, jotka sitten
j�sent�v�t sen ja v�litt�v�t operaation tietokantayhteysluokalle.
Suoritettava toimenpide voi olla haku-, lis�ys-, muokkaus- tai poisto-
operaatio.

\begin{figure}[ht] \centering
\includegraphics[width=0.9\textwidth]{yhteyskaavio.eps}
\caption{Yleiskuva ohjelmiston moduuleista ja niiden v�lisest�
kommunikaatiosta.}
\label{kommunikaatio}
\end{figure}

Rengastustapahtuman tietoja lis�tt�ess� tietokantayhteysluokka kutsuu
Check-ohjelmaa tietojen muodollista tarkistamista varten ennen niiden
lis��mist� tietokantaan. Operaation j�lkeen Servlet-luokat lukevat
tietokannasta operaation tulokset ja palauttavat ne k�ytt�j�lle.



\subsection {Tietokantayhteys}

JDBC-yhteys tietokantaan hoidetaan \code{tipu.db} pakkauksen luokkien
avulla. Yhteyksi� jaetaan yhteysvarannon (connection pool) avulla. T�ten
mahdollisesti monia muitakin k�ytt�ji� palvelevaa tietokantaa ei miss��n
vaiheessa ruuhkauteta tietty� rajaa enemm�n.

\begin{figure}[ht] \centering
\includegraphics[width=0.9\textwidth]{dbclasses.eps}
\caption{Tietokantaoperaatioiden luokkarakenne ja tulostyypit.}
\label{tietokantaoperaatiot}
\end{figure}

Tietokantaan voi kohdistua nelj� erilaista operaatiota: haku, lis�ys,
poisto tai muutos. Kuvasta \ref{tietokantaoperaatiot} n�hd��n,
ett� n�m� operaatiot on toteutettu luokissa \code{SearchOperation},
\code{InsertOperation}, \code{DeleteOperation} ja \code{UpdateOperation}.
N�m� kaikki periytyv�t yhteisest� abstraktista kantaluokasta
\code{DatabaseOperation}, joka k�yt�nn�ss� tarjoaa tuen
\code{ConnectionPool}:in dynaamiselle yhteysjaolle.

Operaatiot palauttavat kutsujalleen lis�ys-, muutos- ja poistotapauksissa
totuus\-arvon, joka indikoi halutun operaation onnistumista. Haku palauttaa
erillisen \code{Search\-Results}-objektin, jolla hakutuloksia voidaan
tarkastella l�hemmin.

Kuva \ref{delete_example} antaa k�ytt�esimerkin poisto-operaatiosta
(ks. \ref{DeleteOperation}). Esimerkist� ilmenee yhteyden varaus,
operaation alustus ja suoritus, sek� tulosten tarkastelu.

\begin{figure}[ht] \centering
\includegraphics[width=0.8\textwidth]{delete_example.eps}
\caption{Yksinkertaistettu esimerkki tietokantaluokkien k�yt�st�
servletin suorittamassa poisto-operaatiossa.}
\label{delete_example}
\end{figure}


\subsubsection {Yht�aikaisuus}

K�ytt�liittym�n toteutusalustan (HTTP) yhteydett�m�st� luonteesta johtuen
ei kannasta voida varata resursseja yhden pyynn�n k�sittely� pidemm�ksi
ajaksi. Palvelin ei k�yt�nn�ss� voi varmasti tiet�� milloin jokin k�ytt�j�
on lopettanut kannan k�yt�n, esim. vain sulkemalla selainikkunansa.

T�st� syyst� mm. edellisen k�ytt�liittym�n ominaisuus, joka lukitsi esill�
olevan tietueen muokkausta varten, on nyt mahdoton toteuttaa. Seurauksena
saattaa olla esim. per�kk�isten p�ivitysten ongelma: Kun kaksi k�ytt�j��
muokkaa samaa tietuetta ja kumpikin tallettaa sen yht�aikaa.

Tapahtumien onnistuminen riippuu tietokannan transaktioiden
erist�ytyneisyys\-asteesta ja toimintamallista tilanteissa, joissa yritet��n
operoida lukittua tietuetta. WWW-Tipu asettaa jokaiselle toimittamalleen
tietokantaoperaatiolle sen vaatiman erist�ytyneisyysasteen ja toimii
operaatioiden antaman palautteen perusteella. Mik�li esim. p�ivitys
ep�onnistuu, t�st� ilmoitetaan k�ytt�j�lle, ja tarjotaan mahdollisuus
yritt�� toimintoa uudestaan.



\subsubsection {Luokka \code{tipu.db.ConnectionPool}}

Yhteysvaranto (connection pool) sis�lt�� kaikki k�ytett�v�t JDBC-
tietokantayhteydet. Servlet pyyt�� varannosta yhteyden k�ytt��ns� jokaisen
HTTP-pyynn�n alussa ja suorittaa kaikki kyseisen pyynn�n aikana teht�v�t
tietokantaoperaat annettua yhteytt� pitkin.

Yhteysvarantoa k�ytet��n, jotta kaikille k�ytt�jille voitaisiin taata
tasaisesti tietty palvelun taso. Tiettyyn maksimiin rajoitettu
yht�aikaisten tietokantaoperaatioiden m��r� takaa seuraavaa:

\begin{itemize}

\item Suorituksessa olevat operaatiot saavat jokainen k�ytt� v�hint��n
tietyn minimim��r�n tietokannan resursseista.

\item Uusille asiakkaille voidaan v�litt�m�sti ilmoittaa, mik�li palvelu
on niin ruuhkainen, ettei ole kenenk��n edun mukaista yritt�� suorittaa
en�� uusia operaatioita juuri kyseisell� hetkell�.

\end{itemize}


\interface{Staattinen rajapinta}

Tietokantaoperaation suoritukseen tarvittava yhteys pyydet��n metodilla
\code{requestConnection()} ja se t�ytyy my�hemmin vapauttaa metodilla
\code{releaseConnection()}. K�ytt�j� (servlet) n�kee vain n�m� kaksi metodia,
ja k�ytt�� niit� kuvan \ref{delete_example} osoittamalla tavalla.

\method{Connection requestConnection()}
T�m� metodi pyyt�� yhteysvarannosta yhteytt�. Suoritus j�� tarvittaessa
odottamaan, mik�li yhteytt� ei v�litt�m�sti saada.

\method{void releaseConnection(Connection con)}
T�m� metodi vapauttaa aiemmin varatun yhteyden. N�in tulisi tehd� viimeist��n
silloin kun kyseisen pyynn�n vastaus l�hetet��n. Yhteydelle voi silti j�tt��
esim. kursoreita auki, sill� itse yhteys s�ilyy avoimena, vaikka se
luovutettaisiinkin toisten operaatioiden k�ytt��n.

N�in saattaa k�yd� esim. silloin, kun k�ytt�j� selaa jonkin taulun
tietueita (k�ytt�� kursoria) tehden niihin v�lill� muutoksia (suorittaa
p�ivitysoperaatioita). Haku\-operaatiota suoritetaan aina samalla yhteydell�
mill� se on aikanaan k�ynnistettykin (\code{java.sql.ResultSet} on sidottu
sen suorittaneeseen yhteyteen), mutta p�ivitys voi saada k�ytett�v�kseen
mink� tahansa yhteysvarannon yhteyden.

\method{private ConnectionPool getInstance()}
T�m� metodi palauttaa itsen�isen \code{ConnectionPool} "=instanssin. T�t�
metodia kutsuu ainoastaan \code{requestConnection()} ensimm�isell�
kutsukerrallaan.


\interface{Instanssin rajapinta}

T�m�n luokan instanssi on rajoitettu palvelemaan ainoastaan luokan
staattista rajapintaa. Siksi luokan konstruktori on n�kyvyydelt��n
\code{private}. Toteutus on kuitenkin instanssiin pohjautuva, sill�
luokka vaatii verrattaen laajan alustusoperaation (ks. konstruktori
\code{ConnectionPool()}), joka on k�tevint� toteuttaa juuri
konstruktorissa, staattisten alustusmetodien sijaan.

\method{private ConnectionPool()}
Konstruktori suorittaa seuraavat alustusoperaatiot:

\begin{itemize}

\item Luodaan joukot (\code{java.util.Set}) k�ytetyille ja
k�ytt�m�tt�mille yhteyksille.

\item Haetaan tietokannan yhteystiedot luokan
\code{tipu.general.Tipu\-Properties} avulla ja instantoidaan JDBC-ajuri
(tekniikka dokumentoitu Sunin JDBC 2.0 spesifikaatiossa \cite{jdbc}).

\item Muodostetaan ensimm�inen k�ytt�valmis yhteys palvelemaan ensimm�ist�
asiakasta.

\end{itemize}

\method{private Connection getConnection()}
T�m� metodi hankkii kutsujalleen yhteyden jollakin seuraavista keinoista:

\begin{itemize}

\item Mik�li vapaiden yhteyksien joukosta l�ytyy toimiva yhteys, otetaan se.
Jos yhteys on kuitenkin ollut niin kauan k�ytt�m�tt�m�n�, ett� se on jo
ajurin puolesta suljettu, luodaan sen tilalle uusi yhteys, ja {\em yritet��n}
yhteyden varausta uudelleen.

T�ss� vaiheessa alkuper�inen yhteyden kysyj�
kilpailee tasavertaisesti mahdollisesti muidenkin yhteytt� pyyt�m��n tulleiden
asiakkaiden kanssa vapaista yhteyksist�.

\item Jos vapaita yhteyksi� ei ole, eik� yhteyksi� ei ole viel� muodostettu
suurinta sallittua m��r��, luodaan uusi yhteys ja kilpailutetaan se em.
tavalla. Mik�li yhteyksi� ei voida en�� luoda, j��d��n odottamaan, ett�
jokin k�yt�ss� olevista yhteyksist� ilmoittaa vapautuneensa.

\end{itemize}

\method{private Connection makeNewConnection()}
T�m� metodi pyyt�� \code{java.sql.DriverManager} "=luokalta uuden yhteyden.
Ep�onnistunut pyynt� palauttaa arvon \code{null}.

\method{private void makeBackgroundConnection()}
T�m� metodi k�ynnist�� uuden s�ikeen muodostamaan yhteytt�. Yhteys
muodostetaan s�ikeen avulla, koska yhteyden neuvottelu voi kest�� useamman
sekunnin. Kun se suoritetaan taustalla, voidaan palvella muita yhteytt�
pyyt�m��n tai vapauttamaan tulleita asiakkaita rinnalla.

Kaikki yhteytt� odottavat asiakkaat her�tet��n kilpailemaan yhteydest� heti,
kun uusi yhteys saadaan k�ytt��n.

\method{private void free(Connection con)}
T�m� metodi vapauttaa t�h�n yhteysvarantoon kuuluvan yhteyden. Yhteys siirtyy
v�litt�m�sti vapaiden yhteyksien joukkoon ja mahdollisille odottajille
ilmoitetaan t�st�.

\method{private void closeConnections(Set)}
T�m� metodi sulkee kaikki annetussa yhteysjoukossa olevat yhteydet. Metodia
k�ytt�� l�hinn� vain \code{closeAllConnections()}.

\method{private void closeAllConnections()}
T�m� metodi sulkee kaikki avoimet yhteydet, niin k�ytt�m�tt�m�t kuin
k�yt�ss� olevatkin. Metodia kutsutaan \code{ConnectionPool}-instanssin
tuhoamisen yhteydess� \code{finalize()}-metodin kautta.

\method{protected void finalize()}
Javan garbage collection kutsuu t�t� metodia, joka puolestaan kutsuu
\code{close\-All\-Connections()} "=metodia sulkeakseen kaikki auki olevat
yhteydet. (Vaihe ei sin�ns� ole tarpeellinen sill� yhteydet osaavat my�s
itse sulkea itsens� siististi kun niiden \code{finalize()} "=metodia
kutsutaan.)



\subsubsection {Luokka \code{tipu.db.Table}}

\code{Table} sis�lt�� jonkin tietokannan taulun ns. metadatan, eli (1)
attribuutit, (2) p��avaimet ja (3) attribuuttien kommentit. Jokaisella
servletill� on yksi tai useampi kohdetaulu, johon kaikki servletilt�
pyydetyt operaatiot kohdistuvat. Servlet hakee k�ynnistyess��n
jokaisen kohdetaulunsa \code{Table} "=objektin, ja s�ilytt�� niit�
j�senmuuttujissaan elinkaarensa ajan.

Vain oikeat tiedot sis�lt�v�n \code{Table} "=instanssin avulla
tietokantaoperaatiot voidaan kohdistaa johonkin tiettyyn tauluun, koska
tarvittavat SQL-lauseet osataan rakentaa ainoastaan kohdetaulun
attribuutti- ja avaintietojen perusteella.


\interface{Instanssin rajapinta}

Luokan \code{Table} instanssi tarjoaa k�ytt�j�lleen metodit attribuutti-
ja kommentti\-tietojen hakemiseen. Avaimet ja attribuutit palautetaan
j�rjestetyiss� joukoissa, jotta tietokantaoperaatioissa osattaisiin
my�hemmin sijoittaa parametrit valmisteltuihin lausekkeisiin
(\code{java.sql.PreparedStatement}) oikeille paikoille.

\method{private Table(String tableName, SortedSet keys,
     \\ SortedSet attributes, Map comments)}
Konstruktori sijoittaa parametreina saamansa arvot ja arvojoukot
j�senmuuttujiinsa.

\method{String getName()}
T�m� metodi palauttaa kohteena olevan taulun nimen.

\method{SortedSet getAttributes()}
T�m� metodi palauttaa taulun attribuuttien (eli sarakkeiden) nimet joukkona
\code{String} "=objekteja. Joukko on m��rittelyns� (ks. \cite{jdk13api}
luokka \code{java.util.Sorted\-Set}) mukaisesti aina samassa j�rjestyksess�.
K�yt�nn�ss� t�m� on \code{String} "=objekteilla nouseva aakkosj�rjestys.

\method{SortedSet getKeys()}
T�m� metodi palauttaa taulun p��avainten nimet joukkona \code{String}
"=objekteja. Mik�li joukossa on useita attribuutteja, ne ovat joukon
sis�ll� j�rjestettyn� samoin kuin kaikki attribuutit k�sitt�v� joukko.

{\em Huom: T�m� ei ole avainten taulum��rittelyn mukainen j�rjestys, vaan
ainoastaan se j�rjestys, jossa attribuutit tullaan sijoittamaan
tietokantaoperaatiossa luotavaan SQL-lauseeseen.}

\method{String getComment(String attribute)}
T�m� metodi palauttaa pyydetyn attribuutin kommentin, mik�li sellainen on
tiedossa. Muutoin palautetaan tyhj� merkkijono. Kommentteja k�yttet��n
pika-avusteina HTML-sivuilla n�kyvien kenttien yhteydess�.


\interface{Staattinen rajapinta}

Luokan \code{Table} instansseja pyydet��n staattisen rajapinnan avulla.

\method{Table getTable(String tableName)}
Hakee resurssitiedostosta taulun \code{\em tableName} tiedot ja luo
niist� k�ytt�valmiin \code{Table} "=instanssin.



\subsubsection {Luokka \code{tipu.db.DatabaseOperation}}

\code{DatabaseOperation} on abstrakti yleistys kaikista mahdollisista
servletien tietokantaan kohdistamista operaatioista.

Jokaisella operaatiolla oletetaan olevan yksi tiettyyn tauluun kohdistuva
valmisteltu lauseke (\code{java.sql.Prepared\-Statement}), jollaisen
instanssia \code{DatabaseOperation} s�ilytt�� jokaista ko. operaation
suoritukseen tarjottua tietokantayhteytt� kohti. N�in t�ytyy tehd�, sill�
valmistellut lausekkeet ovat sidottuja siihen yhteyteen, jolla valmistelu
on alkujaan suoritettu.

\interface{Instanssin rajapinta}

Jokainen tietokantaoperaatio on oltava valmisteltavissa siten, ettei
joka kerta kyseist� operaatiota tiettyyn tauluun kohdistettaessa tarvitse
kyselylauseketta k��nt�� uudestaan. Siksi jokaisen tietokantaoperaation
on toteutettava tietty tietokantaoperaatioiden hallinnalle yhteinen
rajapinta.

\method{DatabaseOperation(Table table)}
Konstruktori luo geneerisen tietokantaoperaation, joka kohdistuu tauluun
\code{\em table}.

\method{PreparedStatement getPreparedStatement(Connection)}
T�m� metodi palauttaa annetulle yhteydelle valmistellun t�t� operaatiota
vastaavan lausekkeen. Mik�li valmistelua ei juuri t�lle yhteydelle viel�
ole tehty, se tehd��n metodia kutsuttaessa, ja talletetaan t�m�n operaation
instanssiin k�ytett�v�ksi juuri t�lle yhteydelle t�m�n operaation tulevia
suorituksia varten.

\method{int getResultSetType()}
T�m� metodi palauttaa operaation vaatiman/salliman vastausjoukon
kursorityypin, jonka tulee olla on yksi \code{java.sql.Result\-Set} luokan
arvoista \code{TYPE\_FORWARD\_ONLY}, \code{TYPE\_SCROLL\_INSENSITIVE} tai
\code{TYPE\_SCROLL\_SENSITIVE}. Oletuksena palautetaan arvo
\code{TYPE\_FORWARD\_ONLY}.

\method{int getResultSetConcurrency()}
T�m� metodi palauttaa operaation vaatiman/salliman tietueiden
eristyneisyysasteen, jonka tulee olla toinen \code{java.sql.Result\-Set}
luokan arvoista \code{CONCUR\_READ\_ONLY} tai \code{CONCUR\_UPDATABLE}.
Oletuksena palautetaan arvo \code{CONCUR\_READ\_ONLY}.


\interface{Abstrakti rajapinta}

Ainoa asia mit� geneerinen tietokantaoperaatio ei voi m��ritell� on
SQL-lause, joka m��r�� mit� kyseinen operaatio k�yt�nn�ss� tekee.
Siksi jokaisen erikoistuneen operaation on toteutettava luokan
\code{DatabaseOperation} abstrakti metodi \code{getSQLString()}.

\method{String getSQLString()}
Palauttaa toteuttavan operaation SQL-kielisen lausekkeen, johon on
objektia luotaessa annetun kohdetaulun avainjoukon avulla luotu valmis
parametrilista.



\subsubsection {Luokka \code{OperationResults}}

Jokainen tietokantaoperaatio p��ttyy tulokseen, joka on luettavissa
operaation \code{execute}-metodin palauttamasta \code{OperationResults}
"=tyyppisest� objektista. Perustoteutus tarjoaa rajapinnan totuusarvoisen
tuloksen ja virheilmoituksen lukemiseen. Monimutkaisempaa tulosten
raportointia varten voidaan t�st� luokasta periytt�� uusi tulosobjekti.
N�in on tehty esim. hakutulosten kanssa (ks. \ref{SearchResults}).

\interface{Instanssin rajapinta}

Koska jokainen operaatio voi v�hint��nkin onnistua tai ep�onnistua,
tarjoaa jokainen tulosobjekti metodit t�m�n tilan selvitt�miseen.
Lis�ksi tarjotaan metodit tilan asettamiseen. N�it� metodeja k�ytt�v�t
vain \code{tipu.db.DatabaseOperation} "=luokasta periytyv�t luokat,
joten niiden n�kyvyys on ``package private'' (eli ei merkitty� m��rett�).

\method{boolean succeeded()}

T�m�n metodin avulla palvelinsovelma voi nopeasti p��tell� ryhdyt��nk�
virheenk�sittelyoperaatioihin, vai jatketaanko normaalin vastauksen
tuottamisella. Metodi palauttaa siis \code{true}, mik�li virheit� ei
tapahtunut.

\method{String getErrorMessage()}

Mik�li suoritettu operaatio ep�onnistui (\code{succeeded()} palauttaa
ep�toden), t�ll� metodilla voidaan kysy� k�ytt�j�lle ilmoitettava
virheilmoitus. Sovelma ei t�m�n tekstin perusteella voi suorittaa mit��n
korjaavia toimenpiteit�. Teksti on tarkoitettu ainoastaan virheen
raportointiin.

Mik�li virheilmoitusta ei ole tietokantaoperaatiossa annettu, palauttaa
t�m� metodi tyhj�n merkkijonon.

\method{void setSuccess(boolean state)}

T�ll� metodilla asetetaan tuloksen tila joko onnistuneeksi (\code{true})
tai ep�onnistuneeksi (\code{false}).

\method{void setErrorMessage(String message)}

T�ll� metodilla asetetaan tuloksen virheilmoitus.



\subsubsection {Luokka \code{tipu.db.SearchOperation}}

\code{SearchOperation} suorittaa \code{SELECT}-lauseella haun
tietokannan tauluun annetuilla attribuuttimaskeilla. Kaikki vertailut
tehd��n \code{LIKE}-operaattorein, joten k�ytt�j�t voivat itse sy�tt��
jokerimerkkej� hakukenttiin. Tulokset palautetaan erillisess�
\code{SearchResults}-objektissa.


\interface{Instanssin rajapinta}

Hakuoperaation rajapinta on p��osin sama kuin muidenkin
tietokantaoperaatioiden. Haku suoritetaan metodilla \code{executeSearch()}
antamalla parametriksi kartta hakuarvoista. Tuloksena k�ytt�j� saa
erillisen tulosobjektin \code{SearchResults}.

\method{SearchOperation(Table table)}
Konstruktori luo uuden, tauluun \code{\em table} kohdistuvan hakuoperaation.

\method{\mbox{SearchResults executeSearch(Connection con, Map values)}}
T�m� metodi suorittaa hakuoperaation kohdetauluun annetulla yhteydell�
\code{\em con} hakuarvoilla \code{\em values}. Kutsu palauttaa
\code{SearchResults} "=instanssin (ks. \ref{SearchResults}), joka sis�lt��
haun palauttaman \code{java.sql.ResultSet} "=kursorin, ja jonka avulla
hakutuloksia voidaan tutkia.

\method{private void setParameters(PreparedStatement stmt,
     \\ Map values)}
T�m� metodi sijoittaa annetut hakuarvot kyselylausekkeen parametreiksi.
Tyhj�t ja puuttuvat arvot korvatan SQL:n \code{LIKE} "=operaattorin
jokerimerkill� '\code{\%}', jolloin n�m� attribuutit sallivat mink� arvon
tahansa.

\method{protected String getSQLString()}
T�m� metodi palauttaa hakulausekkeen muotoa:
\begin{quote}
\code{SELECT {\em attr1}, {\em attr2}, ..., {\em attrN} FROM {\em taulu}
   \\ WHERE {\em attr1} LIKE '?' AND {\em attr2} LIKE '?' AND
   \\ ... AND {\em attrN} LIKE '?'}
\end{quote}
Kent�t \code{\em attr?} ovat kohdetaulun attribuutteja. Kysymysmerkkien
paikalle \code{PreparedStatement} "=objektiin sijoitetaan operaation
suoritukseen k�ytett�v�t parametrit.

\method{protected int getResultSetType()}
Palauttaa vakion \code{java.sql.ResultSet.TYPE\_SCROLL\_SENSITIVE}, sill�
tulosjoukkoa on voitava selata edestakaisin, ja kantaan tehtyjen
muutosten tulee n�ky� hakutuloksissa saman tien.

Esim: k�ytt�j� hakee tietyn joukon taulun rivej�, muuttaa niist� yht�,
siirtyy seuraavaan ja siit� heti takaisin edelliseen. Juuri tehtyjen
muutosten tulee t�ll�in ehdottomasti n�ky� ruudulla.

\method{protected int getResultSetConcurrency()}
Palauttaa vakion \code{java.sql.ResultSet.CONCUR\_UPDATABLE}, sill�
hakutulosten selaus voi kest�� kauan ja toisten k�ytt�jien on t�ll� v�lin
p��st�v� muuttamaan kyseisen taulun arvoja. T�st� syyst� kursori ei saa
lukita rivej� itselleen, vaan niiden muuttaminen on sallittava.



\subsubsection {Luokka \code{tipu.db.SearchResults}} \label{SearchResults}

Luokka \code{SearchResults} periytyy luokasta \code{OperationResults}.
Lis�ksi se sis�lt�� hakuoperaation palauttaman \code{java.sql.ResultSet}
"=objektin, ja mahdollistaa sen palauttamien tietojen selaamisen
k�yt�nn�llisesti (k�ytt�v�n servletin kannalta).

Haun suorittava servlet s�ilytt�� kullekkin sessiolle viimeisint�
hakutulosta ja lukee sielt� arvoja aina kun k�ytt�j� liikkuu tuloslistassa
eteen- tai taaksep�in.


\interface{Instanssin rajapinta}

Hakuoperaatiota kutsunut servlet p��see k�siksi hakutuloksiin luokan
\code{SearchResults} instanssin rajapinnan kautta. Suurin osa seuraavista
metodeista heijastaa kursorin toiminnallisuutta, joten hakujoukossa voi
liikkua samoin askelin kuin k�ytt�j� valitsee n�yt�lt� hakutuloksia:
seuraava, edellinen tai satunnainen tietue.

Hakuoperaatiolle ominaisten metodien lis�ksi \code{SearchResults} sis�lt��
my�s luokan \code{OperationResults} m��rittelem�t yleiset operaation
tilaa k�sittelev�t operaatiot.

\method{protected SearchResults(ResultSet rs)}
Konstruktori luo instanssin, joka k�sittelee annettua vastausjoukkoa.

\method{int getRow()}
T�m� metodi palauttaa sen rivin numeron, jolla kursori t�ll� hetkell� on.
Arvo on v�lilt� $1..n$, miss� $n$ on tulosjoukon rivien m��r�.

\method{SortedMap getCurrentRow()}
T�m� metodi palauttaa vastausjoukon senhetkisen rivin j�rjestettyn�
(attribuutti~$\rightarrow$~arvo) karttana.

\method{SortedMap getNextRow()}
T�m� metodi palauttaa j�rjestyksess� nykyist� kohtaa seuraavan rivin.
Kursoria siirret��n yksi rivi eteenp�in. Metodi palauttaa arvon
\code{null}, mik�li kursori on viimeisell� rivill�.

\method{SortedMap getPreviousRow()}
T�m� metodi palauttaa j�rjestyksess� nykyist� kohtaa edelt�v�n rivin.
Kursoria siirret��n yksi rivi taaksep�in. Metodi palauttaa arvon \code{null},
mik�li kursori on ensimm�isell� rivill�.

\method{SortedMap getAbsoluteRow(int row)}
T�m� metodi palauttaa k�ytt�j�n m��rittelem�n absoluuttisen rivin. Rivien
numerointi alkaa yhdest�.

\method{List getRowList()}
T�m� metodi palauttaa kaikki hakutuloksen rivit \code{java.util.List}
"=rajapinnan toteuttavana objektina. Lista koostuu \code{java.sql.SortedMap}
"=objekteista joista jokainen kuvaa yhden taulukon rivin.



\subsubsection {Luokka \code{tipu.db.InsertOperation}}

Lis�ysoperaatiolla voidaan lis�t� yksi rivi m��r�ttyyn tietokannan tauluun.
Lis�ys onnistuu, mik�li taulussa ei viel� ole samoilla avaimilla varustettua
tietuetta, taulun eheys- ja avainrajoitteet toteutuvat eik�
tiedonsiirtovirheit� tapahdu.


\interface{Instanssin rajapinta}

Keskustelu lis�ysoperaation (kuten muidenkin operaatioiden) kanssa on
hyvin suoraviivaista. Ensin operaatio konstruoidaan antamalla parametriksi
kohdetaulu. T�m�n j�lkeen koostetaan arvot kartaksi ja kutsutaan niill�
metodia \code{executeInsert()}, joka suorittaa itse operaation.

\method{InsertOperation(Table table)}
Konstruktori luo uuden, tauluun \code{\em table} kohdistuvan
lis�ysoperaation.

\method{OperationResults executeInsert(Connection con, Map values)}
T�m� metodi lis�� rivin kohdetauluun arvoilla \code{\em values}. Ko.
arvokartasta tulee l�yty� arvot ainakin kaikille p��avaimille sek� muille
``\code{NOT NULL}'' "=attribuuteille.

\method{private void setParameters(PreparedStatement stmt,
     \\ Map values)}
T�m� metodi kopioi annetut arvot SQL-lausekkeeseen. T�t� kutsutaan vain
metodin \code{executeInsert()} sis�lt�.

\method{protected String getSQLString()}
T�m� metodi palauttaa SQL-lauseen muotoa:
\begin{quote}
\code{INSERT INTO {\em taulu} ({\em attr1}, {\em attr2}, ..., {\em attrN})
   \\ VALUES ('?', '?', ..., '?')}
\end{quote}
Kent�t \code{\em attr?} ovat kohdetaulun attribuutteja.



\subsubsection {Luokka \code{tipu.db.UpdateOperation}}

P�ivitysoperaatio muuttaa jonkin jo olemassa olevan rivin attribuuttien
arvoja. Operaatio onnistuu, mik�li kohdetaulusta l�ytyy annetun ROWID:n
osoittama rivi, eik� tiedonsiirtovirheit� tapahdu.

Operaatiolle t�ytyy antaa parametrina muutettavan tietueen ROWID, jotta
ylip��ns� voidaan tiet�� mit� taulun rivi� tulee muuttaa.


\interface{Instanssin rajapinta}

Muutosoperaatiota kutsutaan metodilla \code{executeUpdate}, joka saa
parametrikseen kyseisen tietueen ROWID:n sek� uudet arvot. Uusilla arvoilla
tarkoitetaan t�ss� kaikkien attribuuttien tulevia arvoja. K�yt�nn�ss�
p�ivitykset tehd��n aina kaikille attribuuteille kerralla, sill�
arvot haetaan aina servletille l�hetetyst� lomakkeesta, jossa jokainen
kentt� on m��ritelty.

\method{UpdateOperation(Table table)}
Konstruktori luo uuden, tauluun \code{\em table} kohdistuvan
p�ivitysoperaation.

\method{OperationResults executeUpdate(Connection con, Map values, String rowId)}
T�m� metodi suorittaa p�ivitysoperaation taulun riville \code{\em rowId},
muuttaen t�m�n rivin attribuutit kartan \code{\em values} mukaisesti.

\method{private void setParameters(PreparedStatement stmt,
     \\ Map values, String rowId)}
T�m� metodi kopioi uudet attribuuttien arvot sek� ROWID:n kyselylausekkeeseen.
Annetut arvot korvaavat {\em kaikki} vanhat arvot. Mik�li arvokartasta
\code{\em values} ei jotakin arvoa l�ydy, ko. kohtaan asetetaan arvo
\code{NULL}. Eheysrajoitteen \code{NOT NULL} sis�lt�vien kenttien kohdalla
t�st� aiheutuu v�ist�m�tt� poikkeus ja toiminnon ep�onnistuminen.

K�yt�nn�ss� kaikkien kenttien p�ivityksest� ei kuitenkaan synny ongelmaa,
sill� p�ivitysoperaatiota suoritettaessa servletin kutsuobjekti
\code{javax.servlet.HttpServletRequest} sis�lt�� tietueen kaikkien
attribuuttien arvot - my�s vanhat arvot niist� kentist� joita k�ytt�j�
ei ole muuttanut.

\method{protected String getSQLString()}
T�m� metodi palauttaa SQL-lauseen muotoa:
\begin{quote}
\code{UPDATE {\em taulu}
   \\ SET {\em attr1} = '?', {\em attr2} = '?', ..., {\em attrN} = '?'
   \\ WHERE ROWID = '?'}
\end{quote}
Kent�t \code{\em attr?} ovat kohdetaulun attribuutteja.



\subsubsection {Luokka \code{tipu.db.DeleteOperation}}
\label{DeleteOperation}

Poisto-operaatio tuhoaa yhden rivin kohdetaulusta. Operaatio onnistuu,
mik�li taulusta l�ytyy annettu rivi eik� tiedonsiirtovirheit� tapahdu.


\interface{Instanssin rajapinta}

Poisto-operaatio k�ynnistet��n kutsumalla metodia \code{executeDelete()},
joka saa parametrinaan poistettavan rivin ROWID:n.

\method{DeleteOperation(Table table)}
Konstruktori luo uuden, tauluun \code{\em table} kohdistuvan poisto-operaation.

\method{OperationResults executeDelete(Connection con, String rowId)}
T�m� metodi tuhoaa kohdetaulusta rivin annetulla ROWID:ll�.

\method{private void setParameters(PreparedStatement stmt, String rowId)}
T�m� metodi kopioi ROWID:n arvon SQL-lausekkeeseen.

\method{protected String getSQLString()}
T�m� metodi palauttaa SQL-lauseen muotoa:
\begin{quote}
\code{DELETE FROM {\em taulu}
   \\ WHERE ROWID = '?'}
\end{quote}



\subsection {Servlet-luokat}

Lomakkeiden toiminnallisuus toteutetaan servlet-luokilla, joita on yksi
kutakin lomakesivua (esim. kunnat) kohden. Lis�ksi lomakkeilta avattavia
popup-valikoita (esim. lista rengastajien nimist�) varten on oma
Popup-luokkansa, joka on yhteisk�yt�ss� eri n�ytt�jen kesken.
P��piirteitt�in luokat ovat toistensa kaltaisia, erot johtuvat l�hinn�
eri lomakesivujen sis�lt�mist� kentist�.

Servlet-luokan suoritus k�ynnistyy, kun servleti� kutsutaan WWW-selaimella
ensimm�ist� kertaa servlet-palvelimen k�ynnistytty�. T�st� eteenp�in
servlet on aktiivisena palvelimen muistissa niin kauan, kunnes palvelin
suljetaan. Servlet k�ytt�� s�ikeit� palvellakseen useita yht�aikaisia
pyynt�j� ja voi my�s sis�lt�� staattista, kaikkien pyynt�jen k�yt�ss�
olevaa informaatiota.

Servlet vastaanottaa informaatiota WWW-selaimelta HTTP-protokollan GET- ja
POST-toiminnoilla ja voi istunnon lopuksi palauttaa selaimelle 
generoimansa WWW-sivun.

Lomakesivujen toiminnallisuuden toteuttavat servlet-luokat muodostavat
WWW-Tipun ytimen. Servletit kutsuvat muita \code{tipu.*} pakkauksien
luokkia mm. tietokantaa k�sitelless��n ja properties-tiedostoja lukiessaan,
sek� lis�ksi ulkoisia kirjastoja esim. templatetiedostojen tulostamiseksi.

Poistettaessa tietuetta taulusta, jossa on viite-eheysrajoitteita,
poistetaan samalla kaikki tietueeseen liittyv�t rivit.
Ennen varsinaista poistoa servlet hakee kannasta jokaisen poistettavaan 
tietueeseen liittyv�n tietokantarivin ja kysyy k�ytt�j�lt� vahvistusta
n�iden poistoon. Monivaiheiset poistot on m��ritelty jokaista n�ytt��
kohti erikseen siihen liittyv�ss� servletiss�. 


\subsubsection{Luokat \code{tipu.servlet.*}}


\interface{Instanssin rajapinta}

Kutsut Servlet-luokkiin tulevat servlet-palvelimelta HTTP-pyynt�jen
muodossa. Tarkka kutsuj�rjestys on m��ritelty Sunin Servlet -spesifikaatiossa
\cite{servlet22}.

\method{void init(ServletConfig config)} 
Huolehtii toiminnoista, jotka tulee suorittaa vain servletin
k�ynnistymisen yhteydess�, esim. m��rittelytiedostojen ja muuttumattomien
tietojen (kuntanimet) lukeminen.

\method{doPost (HttpServletRequest request, HttpServletResponse response)}
Servletin p��metodi, joka saa parametrina WWW-selaimen post-muodossa
l�hett�m�n informaation (lomakkeen sis�lt�) ja HttpServletResponse-
muotoisen vastauksen, johon servletin l�hett�m� vastaus generoidaan.

\method{getValues (HttpServletRequest request, Hashtable values)}
Hakee HttpServletRequestilta kaikki arvojoukot (avain, arvo) ja tallentaa
ne parametrina annettuun Hashtable-tietueeseen.

\method{putValues (Hashtable values, SimpleHash modelRoot)}
Muutetaan Hashtable-muotoinen tietue templatekirjaston ymm�rt�m��n
muotoon ennen WWW-sivun muodostamista. Arvojoukkoja ei voida
s�ilytt�� pelk�st��n SimpleHash-muodossa, koska t�ll�in 
sis�ll�n k�sittely olisi mahdotonta.



\subsection {Templatetiedostot}

WWW-Tipu k�ytt�� lomake-sivujen laatimiseen ilmaista (GPL) FreeMarker
"=templatekirjastoa, jolla sivujen ulkoasun m��rittely voidaan eriytt��
muusta toiminnallisuudesta. FreeMarkerin dokumentaatio l�ytyy seuraavista
osoitteista:

\begin{itemize}

\item Manuaali \cite{freemarker_manual}: \htmladdnormallink{http://freemarker.sourceforge.net/docs/manual/}{http://freemarker.sourceforge.net/docs/manual/}
\item Javadoc \cite{freemarker_javadoc}: \htmladdnormallink{http://freemarker.sourceforge.net/docs/}{http://freemarker.sourceforge.net/docs/}

\end{itemize}



\subsection {Apuluokat}

\subsubsection {Luokka \code{tipu.general.TipuProperties}}

Luokka \code{tipu.general.TipuProperties} sis�lt�� ohjelmiston WWW-Tipu
vaatimat asetukset, mm. k�ytett�v�n JDBC-yhteyden parametrit,
Check-ohjelman kutsutavan, ym.

Luokka lataa asetukset tiedostosta \code{etc/www-tipu.config} silloin kun
niit� ensimm�isen kerran tarvitaan.


\interface{Staattinen Rajapinta}

Rajapinta koostuu pyynt�metodeista, joilla voi kysy� haluamansa asetusavaimen
arvon. Arvo voidaan tulkita ja palauttaa merkkijonona, numerona tai
totuusarvona.

\method{String get(String key, String defaultValue)}
Palauttaa arvonaan asetusparametrin \code{\em key} arvon. Jos parametrilla
ei ole arvoa, palauttaa arvon \code{\em defaultValue}.

\method{String get(String key)}
Muuten kuin yll�oleva, mutta palauttaa \code{null}-arvon, jos parametrilla
ei ole arvoa.

\method{int getInt(String key, int defaultValue)}
Palauttaa arvonaan asetusparametrin \code{\em key} arvon kokonaislukuna,
tai -1 jos arvoa ei voitu tulkita kokonaisluvuksi. Jos parametrilla ei ole
arvoa, palauttaa arvon \code{\em defaultValue}.

\method{int getInt(String key)}
Muuten kuin yll�oleva, mutta palauttaa arvon -1, jos parametrilla ei ole
arvoa.

\method{boolean getBoolean(String key, boolean defaultValue)}
Palauttaa arvonaan asetusparametrin \code{\em key} arvon totuusarvona,
tai \code{false} jos arvoa ei voitu tulkita totuusarvoksi. Jos
parametrilla ei ole arvoa, palauttaa arvon \code{\em defaultValue}.

\method{boolean getBoolean(String key)}
Muuten kuin yll�oleva, mutta palauttaa arvon \code{false} jos parametrilla
ei ole arvoa.



\subsubsection {Luokka \code{tipu.general.Exec}}

Luokkaa \code{tipu.general.Exec} k�ytet��n ohjelmiston WWW-Tipu
tarvitseman Check-ohjelman ajamiseen. Tapa jolla ohjelma
ajetaan on spesifioitu tiedostossa \code{etc/www-tipu.config}.


\interface{Staattinen rajapinta}

Rajapinnan muodostavat kaksi variaatiota samasta metodista, joiden kummankin
teht�v�n� on ajaa annettu Check-ohjelma tietyin parametrein.

\method{boolean exec(command, session, screen, parameter)}
Suorittaa Check-ohjelman, jonka nimi on annettu parametrina
\code{\em command}. Muut parametrit ovat istunnon, n�yt�n ja n�yt�st�
riippuvan parametrin (esim. diarionumeron) arvot. Palauttaa arvonaan
\code{true} jos ohjelman suoritus onnistui, muuten \code{false}.
Kaikki parametrit ovat tyyppi� \code{String}.

\method{boolean exec(session, screen, parameter)}
Muuten kuin yll�oleva, mutta k�ytt�� luokkaa \code{TipuProperties}
hakemaan Check-ohjelman nimen asetustiedostosta. Oletusarvona on
\code{CHECK}.



\clearpage
\section {K�ytt�liittym�}

\subsection{Yleist�}

WWW-Tipua k�ytet��n selaimen kautta ja se koostuu dynaamisesti luoduista
sivuista jotka sis�lt�v�t ainoastaan HTML�� ja JavaScripti�. Koska eri
selaimet ovat toteuttaneet joitakin asioita eri tavoin, t�m� voi johtaa
siihen ett� eri selainten v�lill� k�ytt�liittym�ss� esintyy pieni�
eroavaisuuksia. K�ytt�liittym�n rakenne on sama kuin vanhassa j�rjestelm�ss�.

Sivuilla tulisi pysty� navigoimaan ilman selaimen  omia navigointitoimintoja
kuten esim. ``Takaisin'' (Back) ja ``Eteen'' (Forward). Mahdollisuus n�iden
k�ytt��n tulee kuitenkin ottaa huomioon toteutuksessa. Nykyisest�
selaintekniikasta johtuen ohjelmassa ei voi k�ytt�� vanhasta
j�rjestelm�st� tuttuja n�pp�inyhdistelmi� tomintojen suorittamiseen.
K�ytt�j� suorittaa halutut toiminnot hiiren avulla.

K�ytt�j� k�ytt�� j�rjestelm�� usein ja paljon, joten h�nen toimintojaan ei
tarvitse ohjata vaan ty�n tehokkuus on t�rke��. 

Ohjelmassa on mahdollista p�ivitt�� saamaa kentt�� per�kk�in eri
arvoilla. T�laisessa tapauksessa yhden k�ytt�j�n tekem�t muutokset
tietueeseen korvataan toisen k�ytt�j�n tallentamilla tiedoilla.

K�ytt�liittym�n toteutetaan suomeksi.

\subsection{Navigointi}

\subsubsection{Valikko}

Valikko (kuva \ref{valikko}) on monista sovelluksista tuttu alasvetovalikko,
jonka avulla k�ytt�j� pystyy siirtym��n mist� tahansa n�yt�st� suoraan mihin
tahansa muuhun n�ytt��n. Valikkopalkki sijaitsee koko ajan sivun
yl�reunassa. Kun k�ytt�j� liikuttaa hiiren osoitinta valikon p��ll�, niin
senhetkinen valinta korostetaan muuttamalla v�ri� ja palkin alle ilmestyy
alavalikko.

\begin{figure}[t] \centering
\includegraphics[width=0.8\textwidth]{valikko.eps}
\caption{Ruudun yl�reunassa sijaitseva valikkopalkki.}
\label{valikko}
\end{figure}

Alavalikkossa (kuva \ref{valikko2}) korostetaan valittu toiminto samalla
tavalla, ja k�ytt�j� valitsee toiminnon klikkaamalla sit�. Jos k�ytt�j� ei
haluakaan valita mit��n, niin h�n siirt�� hiiren valikon ulkopuolelle, jolloin
alavalikko h�vi��. 

\begin{figure}[ht] \centering
\includegraphics[width=0.25\textwidth]{valikko2.eps}
\caption{Alavalikko rengastustoiminnoista.}
\label{valikko2}
\end{figure}


\subsubsection{Lomake}

\begin{figure}[t!] \centering
\includegraphics[width=0.7\textwidth]{lomake.eps}
\caption{Tyypillinen n�kym� k�ytt�j�n selatessa kantaan talletettujen
kuntien tietoja.}
\label{lomake}
\end{figure}

Suurin osa WWW-Tipun n�yt�ist� ovat lomakkeita joilla katsotaan tai
muokataan tietokannan sis�lt�� (esim. kuva \ref{lomake} sivulla
\pageref{lomake}). Lomakkeelle sy�ttettyjen tietojen tarkistus tapahtuu
vasta kun se 'l�hetet��n', eli yritet��n lis�t� tai p�ivitt�� tietoja
tietokantaan. Ainoastaan yksinkertaiset tarkistukset, kuten
sy�tteen pituus, tehd��n tietoja sy�tett�ess�.

Lomake koostuu kentist�, joiden arvo sy�tet��n kent�n mahdollisesta
arvojoukosta riippuen eri tavoin, joko tekstikenttill� ja
valintalaatikoilla. Valintalaatikkoa k�ytet��n, jos kent�n mahdollisia
arvoja on v�h�n. Niiden tekstikenttien vieress� joiden arvojoukko on
rajattu mutta suuri, on nappi jota painamalla p��see selailemaan
mahdollisia arvoja uudessa ikkunassa ja valitsemaan niist� yhden.


\subsubsection{Painikkeet}

Painikkeet sijaitsevat lyhyess� lomakkeessa sen lopussa ja pitk�ss� sek�
alussa ett� lopussa.

\begin{longtable}{p{0.3\textwidth} p{0.62\textwidth}}
Painike & Toiminto \\ 
\hline
Hae & Suorittaa haun lomakkeella olevilla tiedoilla. Tulokset n�ytet��n listassa
linkkein� joita klikkaamalla kyseisen tietueen arvot tuodaan lomakkeelle. \\
Lis�� & Lis�t��n lomakkeella olevat tiedot kantaan. Jos niiss� on virheit�
ilmoitetaan siit� k�ytt�j�lle. \\
P�ivit� & P�ivitet��n lomakkeella olevat tiedot kantaan. Jos niiss� on virheit�
ilmoitetaan siit� k�ytt�j�lle. \\
Poista & Poistetaan lomakkeilla olevilla tiedoilla l�ytyv� tietue tietokannasta.
Jos ei l�ydy tasan yht� tietuetta ilmoitetaan siit� k�ytt�j�lle eik�
poisteta mit��n. Jokainen poisto varmistetaan k�ytt�j�lt� kysym�ll�
h�nelt� onko h�n varma suoritettavasta poistosta.  \\
Tyhjenn� lomake & Tyhjennet��n kaikki lomakkeella olevat kent�t. \\
\end{longtable}


\subsubsection{Linkit}

Jos on tehty haku ja tuloksia on enemm�n kuin yksi niin niit� pystyt��n
selailemaan linkeill� ``<< Edellinen'' ja ``Seuraava >>''. Linkki�
``Sivuluettelo'' seuraamaalla p��st��n n�kem��n hakutulokset
luettelomuodossa. Linkit sijaitsevat painikkeiden alapuolella.

\subsubsection{Virheilmoitukset}

Virhetilanteen sattuessa k�ytt�j�lle tulostetaan virheilmoitus sivulle,
jolla k�ytt�j� oli virheen sattuessa. 
Virheilmoitus kertoo virheen syyn.
Virhetilanteen j�lkeen k�ytt�j� voi korjata virheellisen lomakkeen tai
tietokantavirheen sattuessa toistaa kesken j��neen operaation.


\subsection{Esimerkki k�ytt�tapauksesta}

Rengastustoimiston ty�ntekij� N.N. haluaa tarkistaa renkaalla X rengastetun
linnun tiedot.

\begin{enumerate}

\item Selaimen k�ynnist�minen. N.N. k�ynnist�� selainohjelmansa ja
avaa selaimeen WWW-Tipun aloitussivun.

\item Sis��n kirjautuminen. H�n sy�tt�� tunnuksen ja salasanan ja klikkaa
``Kirjaudu sis��n''-painiketta.

\item Rengastusn�yt�lle siirtyminen. H�n valitsee alasvetovalikosta
``Rengastukset'' ja klikkaa sit�. T�m� vie h�net rengastukset n�yt�lle.


\item Hakuehtojen sy�tt�minen. H�n sy�tt�� renkaan tunnuksen X sille
tarkoitettuun kentt��n ja klikkaa ``Hae''-painiketta.

\item Tietueen valitseminen. Annetuilla tiedoilla l�ytyi yksi rengastus joten
N.N. p��see suoraan tarkistamaan haluamansa tiedot ruudulle tulleesta
lomakkeesta.

\end{enumerate}


\subsection {Tiedon haku}

K�ytt�liittym�ss� on tarpeen k�ytt�� hakutoimintoja kahteen eri
tarkoitukseen: kokonaisten tietueiden tietojen ja yksitt�isten kenttien
arvojen hakemiseen tietokannasta.

% {kuva 1, Haku.eps}
\begin{figure}[t!] \centering
\includegraphics[width=0.6\textwidth]{haku.eps}
\caption{Hakutapahtuman kulku. P��sivusta on esimerkkin� kuva 8,
hakukriteereist� kuva 9 ja tulossivusta kuva 10.}
\label{haku}
\end{figure}


\subsubsection {Kokonaisten tietueiden haku}

% {kuva 2, Kunnat.eps}
\begin{figure}[b!] \centering
\includegraphics[scale=0.35]{kunnat.eps}
\caption{Kuntien yll�pitolomake. K�ytt�j� p��see Hae-painikkeella hakemaan
kuntia.}
\label{kunnat}
\end{figure}

Kokonaisilla tietueilla tarkoitetaan yhdell� sivulla kerrallaan n�kyv��
tietokokonaisuutta, esimerkiksi Apurekisterit - Kunnat -sivun
kenttien sis�lt��. Hakutoimintoa tarvitaan t�ll�in yhden tai useamman
hakuehdot t�ytt�v�n tietueen tietojen tarkastelua, yll�pitoa tai
kopiointia varten. Haun toimintaperiaate ilmenee kuvasta \ref{haku}.

Hakutoiminto on k�ytett�viss� kaikissa sy�tt�- ja yll�pitolomakkeissa. Kun
k�ytt�j� on kirjoittanut haluamansa hakukriteerit lomakkeeseen, h�n voi
aloittaa haun napsauttamalla Hae-painiketta (kuva \ref{kunnat}).

Jos haku ei palauta yht��n tulosta, tulossivulla n�kyy siit� ilmoitus. Jos
haku palauttaa vain yhden tuloksen, sit� vastaava tietue n�ytet��n
k�ytt�j�lle automaattisesti omalla sivullaan. Jos hakutuloksia on
v�hint��n kaksi, hakusivun alalaidassa n�ytet��n kunkin kriteerej�
vastaavan tietueen avaintiedot kymmenen kappaleen luetteloissa
(kuva \ref{kunnat_haku}). K�ytt�j� voi selata luetteloa eteen- ja taaksep�in
tai siirty� suoraan haluamalleen sivulle tulosluettelossa.

% {kuva 3, Kunnat - Haku.eps}
\begin{figure}[t!] \centering
\includegraphics[scale=0.35]{kunnat_haku.eps}
\caption{Kuntien hakulomake. Lomakkeella on suoritettu haku kaikista Uudenmaan
kunnista ja tulokset ovat listattuna hakukenttien alla.}
\label{kunnat_haku}
\end{figure}

% {kuva 4, Kunnat - Haku - 2.eps}
\begin{figure}[t!] \centering
\includegraphics[scale=0.35]{kunnat_haku_2.eps}
\caption{Hakutulosten selaus tietueittain.}
\label{kunnat_haku_2}
\end{figure}

K�ytt�j� voi valita yksitt�isen tietueen muokattavaksi valitsemalla sen
luettelosta. T�ll�in valittu tietue n�ytet��n samoin kuin tavallisessa
sy�tt�lomakkeessa (kuva \ref{kunnat_haku_2}). Sivun alaosassa on linkki
tulosluetteloon sek� edelliseen ja seuraavaan tietueeseen, mik�li ne ovat
tulosjoukossa.

\subsubsection {Yksitt�isten kenttien arvojen haku}

Monissa lomakkeissa on kentti�, joiden kelvolliset arvot voidaan
lukea tietokannasta. N�it� arvoja vastaavat kuvaukset on yleens� j�rkev��
tarjota k�ytt�j�lle valintaluetteloissa. Muutamissa tapauksissa
valintaluettelosta tulisi liian pitk�, jotta se olisi k�ytt�kelpoinen
WWW-lomakkeessa. T�m�n vuoksi k�ytt�liittym� antaa k�ytt�j�lle
mahdollisuuden kirjoittaa kent�n arvon itse tai hakea sen kentt��n
erillisell� hakutoiminnolla.

% {kuva 5, Rengastukset - Sy�tt�.eps}
\begin{figure}[t!] \centering
\includegraphics[scale=0.35]{rengastukset_syotto.eps}
\caption{Rengastustietolomakkeessa joillakin kentill� on oma hakupainikkeensa.}
\label{rengastukset_syotto}
\end{figure}

Kentt�kohtaisen arvon hakutoiminnon voi k�ynnist�� hakupainikkeella, jonka
tunnisteena on kolme pistett� (\ldots). Painike on k�ytett�viss� esimerkiksi
Rengastukset - Sy�tt� -sivun Kunta-kent�ss� (kuva \ref{rengastukset_syotto}).
Painiketta napsautettaessa kuvaruutuun avautuu uusi, pienempi ikkuna (kuva
\ref{kunnan_haku}).

% {kuva 6, Kunnan haku.eps}
\begin{figure}[b!] \centering
\includegraphics[scale=0.4]{kunnan_haku.eps}
\caption{Mik�li esim. Kunnan lyhennett� ei muista, voi arvoa hakea
kentt�kohtaisella hakutoiminnolla.}
\label{kunnan_haku}
\end{figure}


T�m� ikkuna sis�lt�� kuvauksen haettavasta tiedosta, sy�tt�kent�n
hakukriteerille, luettelon hakukriteeri� vastaavista tietokannan arvoista
sek� painikkeet haun aloitukseen, haun peruutukseen ja arvon valintaan
p��ikkunan sy�tt�kentt��n. Ikkuna sulkeutuu automaattisesti, kun k�ytt�j�
valitsee Valitse- tai Peruuta-painikkeen.



\clearpage
\section {Rajoitteet suunnittelulle ja toteutukselle}

\subsection {Noudatettavat standardit}

Servlet-ohjelmamoduuli kommunikoi k�ytt�j�n kanssa HTTP 1.1 "=protokollan
\cite{rfc2616} mukaisesti. Asiakasp��ss� n�kyv�t HTML-dokumentit
kirjoitetaan HTML 4.01 "=spe\-si\-fi\-kaa\-ti\-on \cite{html401} mukaisesti.

\subsection {Muut tarvittavat ohjelmat}

WWW-Tipu tarvitsee toimiakseen Oracle 8 "=tietokannan sek�
rengastustietoja tarkistavan Check-ohjelman.

\subsection {Arvio toteutuksen koosta}

Varovainen esiarvio toteutuksen koosta on noin 2100 rivi�, noin 30 rivin
tarkkuudella. (Laskettu Ohjelmistotuotanto-kurssin kohdan "arviointi"
\cite{laskenta} avulla.)

\subsection {Ohjelmointityyli}

WWW-Tipu kirjoitetaan Sun Microsystemsin kehitt�m�ll� Java 1.2 "=kielell�.
Kielen syntaktinen ulkoasu (mm. sisennystyyli, isojen ja pienten kirjainten
k�ytt�) on Java Code Conventions "=spesifikaation \cite{javacode} mukainen.

Luokkien, metodien ja muuttujien nimet kirjoitetaan englanniksi, jotta
niist� tulisi johdonmukaisia Java-kielen varattujen sanojen ja valmiiden
luokkakirjastojen nimien kanssa. Tulostettava teksti ja kommentit
kirjoitetaan suomeksi, jotta ne olisivat yhdenmukaisia aikaisemman
j�rjestelm�n tulostamien tekstien kanssa.



\section {Testaussuunnitelma}

T�ss� kuvataan yleisesti testauksen eri vaiheet. Tarkemmat kuvaukset ja
testitapaukset tulevat erilliseen testausdokumenttiin. 

\subsection{Testimoottori}

Testattavat moduulit (poislukien servletit) sis�lt�v�t main-metodin, jolla
sis�ist� toiminnallisuutta, esimerkiksi tietokantayhteyksi� voidaan
testata tarvittavilla suorituspoluilla ja muuttujilla. 

Servletej� voidaan testata ja kuormittaa erillisell� luokalla, joka
l�hett�� servletille HTTP GET-muotoisia pyynt�j� ja tallettaa servletin
vastaukset tekstitiedostoihin. 

\subsection {Komponenttitestaus}

Ohjelmiston jokainen moduuli (ks. kappale \ref{moduulit}) testataan
erillisen� komponenttina. Komponentit testataan ``white box''-
menetelm�ll�, jotta voidaan testata niiden sis�ist�
toimivuutta. Testauksessa on tarkoitus k�ytt�� polkukattavuutta, eli
jokainen mahdollinen suorituspolku testataan ainakin kerran.
Jokaiselle komponentille m��r�t��n erityinen testaaja, joka on eri henkil�
kuin kyseisen komponentin implementoija.

\subsection {Integrointitestaus}

Integrointitestauksessa varmistetaan j�rjestelm�n eri moduulien
(luokkien) toiminta yhdess� mustalaatikkotestauksena. Kunkin luokan
sy�tteiden ja tulosteiden oikeellisuus varmistetaan jakamalla niiden
arvoalueet ekvivalenssiluokkiin, joista muodostetaan testiaineisto. T�m�n
j�lkeen toteutetaan luokille testiaineiston mukaiset testitapaukset.

WWW-Tipu testataan alhaalta yl�s-menetelm�ll�. T�ll�in ohjelmiston
toteutus ja testaus aloitetaan luokkakaavion alimmista
luokista. J�rjestelm�st� viel� puuttuvien alempia luokkia kutsuvien
luokkien toimintaa simuloidaan erikseen koodattavilla
ajuriluokilla. N�iden ajuriluokkien tulosteista voidaan todentaa kutsutun
luokan tulosteen vastaavuus m��riteltyyn.

\subsection {Validointitestaus}

Validointitestaus tehd��n kun integrointitestaus on valmis ja siin�
havaitut virheet korjattu. Validointitestauksen tarkoituksena on tarkastaa
t�ytt��k� WWW-Tipu sille vaatimusm��rittelyss� asetetut vaatimukset. T�m�
tapahtuu suorittamalla joukko testitapauksia ``black box''-menetelm�ll�,
jotka osoittavat ett� ohjelmisto t�ytt�� sille asetetut toiminnallisuus-,
suorituskyky- ja muut vaatimukset sek� sen ett� dokumentaatio on
oikeellinen.

\subsection {Hyv�ksymistestaus}

Viimeisen� suoritetaan hyv�ksymistestaus, t�m� on tilaisuus jossa
loppuk�ytt�j�t k�ytt�v�t WWW-Tipua oikealla aineistolla lopulisessa
``tuotantoymp�rist�ss�''. T�ss� k�yd��n asiakkaan kanssa l�pi ohjelmisto,
dokumentointi ja k�ytt�ohje ja katsotaan vastaako se h�nen odotuksiaan.




%%%
%%% Liitteet
%%%

\appendix



%%%
%%% Viitteet
%%%

\clearpage
\flushleft
\bibliographystyle{plain}
\bibliography{../tipu4}
\addcontentsline{toc}{section}{\refname}

\end{document}
