\newcommand{\tiedostonimi}[1]{\texttt{#1}}
\newcommand{\termi}[1]{\textit{#1}}

\section{Johdanto}

Asdf on Helsingin yliopiston tietojenk�sittelytieteen laitoksen ohjelmistotuotantoprojektin ryhm�.
T�m� on ryhm�n toteuttaman pokeripalvelin-ohjelmiston suunnitteludokumentti. Dokumentiss� esitell��n j�rjestelm�n kompponentit, rajapinnat, sek� kuvataan k�ytt�liittym�.

Projektiin liittyv�� materiaalia tulee olemaan saatavilla ryhm�n kotisivulla osoitteessa:

\texttt{http://www.cs.helsinki.fi/group/asdf/}

\subsection{Sanasto}

\begin{figure}[h]
\begin{tabular}{p{3.8cm}|p{11.5cm}}
\textbf{Sana} & \textbf{Selitys} \\ \hline
\textbf{GUI} & Graphical User Interface, graafinen k�ytt�liittym� \\
\textbf{JAXB} & Ohjelmiston toteutuksessa k�ytett�v� valmis komponentti, jota k�ytet��n muuntamaan xml-schema protokollat java-olioiksi sek� toisinp�in. \\
\textbf{Meerkat} & Poker Academyn tarjoama rajapinta, joka yleist�� kommunikaation asiakkaan ja palvelimen v�lill� texas holdem -peliss� sek� mahdollistaa pokeriohjelmiston peluuttaa valmiita tietokonebotteja, jotka kyseisen rajapinnan toteuttavat. Ohjeliston komponentit, jotka rajapinnan toteuttavat sis�lt�v�t pelitilannetietoa sek� pelitoiminnallisuutta texas holdem peliin. Ohjelmisto tulee k��rim��n ja purkamaan xml-schema viesteist� JAXB-kompponetin avulla meerkat rajapinnat toteuttavia pelitilanne- sek� pelaajaolioita.\\

\end{tabular}
\end{figure}

\subsection{Dokumentin rakenne}
T�ss� luvussa on lyhyt kuvaus projektista, dokumentin rakenne sek� sanasto. Luvussa 2 on esitelty
ohjelmiston arkkitehtuuri. Lis�ksi luvussa 2 on esitetty ohjelmiston toiminnallisuutta sanallisesti ja sekvenssikaavioilla. Luvussa 3 on ohjelmiston asiakas- ja palvelinkomponentit  esitetty luokkakaavioina ja sanallisin kuvauksin. Luvussa 4 on esitetty ohjelman k�ytt�liittym�. Luvussa 5 on esitetty xml-schemalla v�litett�vien viestien muoto.
\newpage

\section{Arkkitehtuurikuvaus}
T�ss� luvussa esitell��n ohjelmiston arkkitehtuuri sek� esitell��n osaj�rjestelm�t. Lis�ksi esitet��n sekvenssikaavion ja sanallisesti ohjelmiston toimintoa.
\subsection{Arkkitehtuurikaavio}
\begin{figure}[ht]
     \includegraphics[width=16cm]{jarjestelma.eps}
     \caption{Arkkitehtuurin korkean tason n�kym�.}
\end{figure}
\subsection{Osaj�rjestelm�t}
Ohjelmisto koostuu asiakas- ja palvelinohjelmistosta, ohjelmistot kommunikoivat kesken��n xml-schema viesteill�, joista kerrotaan tarkemmin luvussa 5. Ohjelmisto voidaan jakaa viel� osaj�rjestelmiin palvelin, pelilogiikkamoduulit, tietokanta, peliaula, pelip�yd�t sek� teko�lypelaajat. Tietokanta toteutetaan vasta seuraavassa iteraatiovaiheessa.

Palvelin luo peleist� ilmentymi� ja v�litt�� peliviestej� pelilogiikkailmentymien ja (teko�ly)pelaajien kesken. Palvelin tallentaa my�s tilastotietoa ja k�ytt�j�tiedot. Pelilogiikka on toteutettu itsen�isill� komponenteilla, joille palvelin tarjoaa yleisen rajapinnan ottamatta kantaa niiden toteutukseen. 

Asiakasohjelmisto on loppuk�ytt�j�n koneella py�riv� graafinen komponentti.
Asiakasohjelmisto muodostuu peliaulasta sek� pelip�ydist�. Molemmat kommunikoivat yleisen yhteysrajapinnan 
kautta palvelimen kanssa. Peliaula toteuttaa: sis��nkirjaantumisen, uusien pelien luonnin, pelien selaamisen sek� pelip�ytiin siirtymisen. Pelip�yt� toteuttaa: jonkin pelilogiikan pelin pelaamisen tarvittavan graafisen ymp�rist�n johon pelaaja voi liitty� tai liitt�� tietokonepelaajia. 
\newpage
\subsection{Ohjelman p��toiminnallisuuksien kuvaukset}
Seuraavassa on k�yty l�pi pokeriohjelmiston toiminnallisuuksien l�pivienti�. Toiminnot on esitetty sanallisesti sek� sekvenssikaavioilla.

\subsubsection{Pelin etsiminen}

\subsubsection{Peliin siirtyminen}
\subsubsection{Pelitapahtuman v�litys}
\subsubsection{Uudenpelin luonti}


\subsubsection{Meerkat}
Poker Academyn tarjoama rajapinta, joka yleist�� kommunikaation asiakkaan ja palvelimen v�lill� texas holdem -peliss� sek� mahdollistaa pokeriohjelmiston peluuttaa valmiita tietokonebotteja, jotka kyseisen rajapinnan toteuttavat. Ohjeliston komponentit, jotka rajapinnan toteuttavat sis�lt�v�t pelitilannetietoa sek� pelitoiminnallisuutta texas holdem peliin. Ohjelmisto tulee k��rim��n ja purkamaan xml-schema viesteist� JAXB-kompponetin avulla meerkat rajapinnat toteuttavia pelitilanne- sek� pelaajaolioita.


\newpage
\section{Komponentit}
Luvussa k�yd��n l�pi ohjelman komponentit. Komponenteista on annettu kuvaus, luokkakaavio sek� lyhyet luokkien kuvaukset.

\subsection{Asiakas}
Asiakas on loppuk�ytt�j�n koneella py�riv� graafinen komponentti. Asiakaskomponentin avulla loppuk�ytt�j� voi tehd�, poistaa ja pelata pelej�. K�ytt�liittym� toteuttaa my�s teko�lypelaajien hallinnoinnin ja pelauttamisen.
K�ytt�liittym�komponenttien arkkitehtuurissa on pyritty soveltamaan Model-View-Controller suunnittelumallia, jonka tarkoituksena on k�ytt�liittym�n erottaminen sovellusaluetiedosta.
\begin{figure}[ht]
     \includegraphics[width=15cm]{Asiakas.eps}
\end{figure}

\subsubsection{Table}
Peliohjelmien yl�luokka, jossa kaikissa peleiss� toteutettava yhteinen toiminnallisuus.
\subsubsection{TexasHoldenTable}
Aulasta k�ynnistetty ilmentym� texasholdem pelip�yd�st�. Keskitt�� toiminnot mallin ja yhteysrajapinnan v�lill�. Yll�pit�� pelitilannetta GameModel-oliossa, ja vastaa bottipelaajien pelikyselyihin sek� tarjoaa graafiselle k�ytt�liittym�lle tiedon pelitilanteesta.
\subsubsection{GameController}
Meerkat action rajapinnat toteuttava texasholdemclientin apuluokka, joka aktivoi tietokone- ja ihmispelaajia ja ker�� tilannetietoja.
\subsubsection{GameModel}
Meerkat gameinfo rajapinnan toteuttava tieto pelitilanteesta. Lis�ksi muuta tietoa pelitilanteesta, kuten varatut paikat. GameState sis�lt�� kaiken tarpeellisen tiedon pelitilanteen esitt�miseen.
\subsubsection{AbstractPlayer}
Meerkat pelaaja rajapinnat toteuttava yl�luokka pelaajista.
\subsubsection{Ourplayer}
meerkat rajapinnat toteuttava pelaajaolio, joka istuu t�ss� p�yd�ss�.
\subsubsection{Botplayer}
Meerkat rajapinnat toteuttava teko�lytietokoneohjelma, joita voidaan k�ynnist�� pelaamaan p�yt��n. Viestii ja kommunikoi pelin kanssa TexasHoldemClient-komponentin kautta GameControllerin viestien mukaan.
\subsubsection{GameView}
Asiakasohjelman graafiset k�ytt�liittym� komponenttien yl�luokka yhdelle pelip�yd�lle, toteuttaa erillaisten
panelien avulla n�kym�n pelip�yd�st� ja pelitilanteista, kts. kuva X k�ytt�liittym�kuvauksesta.
\subsubsection{Lobby}
Ilmentym� aulasta, joka k�ynnistet��n haluttaessa k�ytt�� ohjelmistoa, luo n�kym�n aulasta ja sen kautta
l�hdet��n liittym��n peleijin ja hakemaan pelej�.
\subsubsection{LobbyView}
 Asiakasohjelman graafinen k�ytt�liittym� komponenttien yl�luokka peliaulalle, toteuttaa paneelien
 avulla, pelin hakemisen, pelilistat, yksityiskohdat pelist� sek� uuden pelin luomisen.
\subsubsection{Connection}
Rajapintaluokka joka kuvaa yhteydenpitoon palvelimelle asiakkaan tarjoamat palvelut.
\subsubsection{ConnectionHandler}
V�litt�� xml-pohjaiset viestit palvelimelle sek� kuuntelee palvelimelta tulevia tietoja ja v�litt�� ne eteenp�in headerin mukaan connection rajapinnan toteuttaviin luokkiin, kuten LobbyConnection ja TexasHoldemConnection.
\subsubsection{TexasHoldemConnection}
THC piilottaa viestien parsimisen ja tarkistamisen yksityiskohdat. Tarjoaa rajapinnat viestin l�hett�miselle ja vastaanottamiselle. Luokka k�ytt�� JAXB kirjastoilla automaattisesti generoitua parseria XML viestien muodostamiseen ja lukemiseen. Toteuttaa connection rajapinnan.
\subsubsection{LobbyConnection}
THC:n tavoin LC piilottaa viestien parsimisen ja tarkistamisen yksityiskohdat. Tarjoaa rajapinnat viestin l�hett�miselle ja vastaanottamiselle. Luokka k�ytt�� JAXB kirjastoilla automaattisesti generoitua parseria XML viestien muodostamiseen ja lukemiseen. Toteuttaa connection rajapinnan.
\newpage
\subsection{Palvelin}
Palvelin huolehtii pelilogiikoiden toiminnallisuudesta. Palvelin v�litt�� viestit peli-ilmentymien sek� pelaajien kesken. Palvelin tarjoaa rajapinnat peli-ilmentymille sek� huolehtii niiden eheydest�.
\begin{figure}[ht]
     \includegraphics[width=14cm]{palvelin.eps}
\end{figure}


\subsubsection{Game}
Rajapintaluokka, joka kuvaa yleiset pelien tarjoamat palvelut.
\subsubsection{AbstractGame}
Kaikkien pelien yl�luokka. Kaikkien pelien yhteiset ominaisuudet, pelin kuuntelijat.
\subsubsection{Client}
Pelin kuuntelijoiden yleiset tiedot palvelinta varten.
\subsubsection{Actions}
Kaikkiin peleihin liittyvi� toimintoja.
\subsubsection{PokerActions}
Kaikkiin pokeripeleihin tarvittavat meerkat rajapinnan mukaiset toiminnot.
\subsubsection{TexasholdemActions}
Pelk�st��n Texasholdem liittyv�t pelitoiminnot.
\subsubsection{Search}
K�ytet��n pelikohtaisten hakuehtojen toteutukseen. Luokka alustetaan hakuehdot sis�lt�v�ll� XML-viestill�. Tarjoaa metodin, joka palauttaa vastaako parametrina annettu peli hakuehtoja.
\subsubsection{CardGame}
Abstrakti yl�luokka korttipeleille.
\subsubsection{PokerGame}
Abstrakti yl�luokka pokeripeleille.
\subsubsection{TexasHoldem}
Luokka toteuttamaan ilmentym� texas holdem pelist�. Peli alustetaan odottamaan minimi m��r� pelaajia p�yt��n ja sen j�lkeen peli jatkuu kunnes pelill� ei ole yht��n seuraajaa. Pelin alettua peli etenee jakamalla aktiivisille pelaajille piilokortit, panostuskierros, flop, panostuskierros, turn, panostuskierros, river, panostuskierros, showdown, potinjako. Mik�li panostuskierroksen lopussa on vain yksi pelaaja kierros loppuu siihen. TexasHoldem odottaa panostuskierroksilla aikarajan verran pelitoimintatietoa aktiivisilta pelaajilta, pelitoimintatieto tallennetaan Placeen. Kaikki pelitoiminta l�hetet��n kaikille peli� seuraaville Clienteille, Piilokortit l�hetet��n vain kortin omistajalle sek� superk�ytt�jille.
\subsubsection{Place}
Place toteuttaa pokeripaikan p�yd�ss�. Paikkoja varataan ja niihin sioitetaan pelaajia. Paikka yll�pit�� tilatietoa sijoitetun pelaajan p�yt��n tuomista rahoista sek� peliss� olevasta rahasta. Paikka ottaa vastaan ja yll�pit�� tietoa pelaajan peliin liittyvist� toiminnoista (muck,sitout,action)
\subsubsection{Deck}
Kokoelma korteista, pelipakka josta voidaan jakaa kortteja peleihin.
\subsubsection{Card}
Card toteuttaa yksitt�isen (pokeri)kortin. Parametreina on v�ri, arvo sek� jaetaanko kortti n�kyviin.
\subsubsection{GameServer}
Pelipalvelin, joka py�ritt�� pelej� ja ottaa vastaan asiakkaita ja v�litt�� viestit peli-ilmentymille. 
\subsubsection{ConnectionInfo}
Yhteystiedot asiakkaista.
\subsubsection{ConnectionListener}
Kuuntelee uusia yhteyksi� palvelimelle. Avaa yhteyden asiakkaan ja palvelimen v�lille, kun tulee uusi yhteys.
\subsubsection{Account, Statistics}
Account hoitaa K�ytt�j�n hallinta tiedot, tunnukset ja salasanat. Statistics tilastotiedon. Molemmat korvataan tietokannalla viimeist��n toisessa iteraatio vaiheessa.
\subsubsection{GameFactory}
Luo parametrien mukaan annetun ilmentym�n halutusta pelist�.

\newpage


\section{K�ytt�liittym�}
\subsection{pelip�yt�}
\begin{figure}[htp]
     \includegraphics[width=15cm]{kali.eps}
\caption{Pelip�yt�}
\end{figure}
Kuvassa 2 on esitetty asiakasohjelmiston texas holdem pelip�yd�n alustava k�ytt�liittym�hahmotelma.

K�ytt�liittym�n alareuna on jaettu kolmeen osaan, vasemmalla sijaitsee yleisi� pelitilanteesta riippumattomia nappeja, keskell� chatti-ikkuna. Oikeassa reunassa n�kyy peliss� oleva potti sek� nykyisen kierroksen tarvittava panostusm��r� sek� aktiivisen p�yd�ss� istuvan pelaajan ollessa vuorossa pelitilanteeseen liittyv�t napit: call,fold,check,raise, sek� panoksen m��rittely valikko.

K�ytt�liittym�n yl�osa n�ytt�� p�yt�kortit sek� potin sek� vaihtelevan m��r�n pelaajaistuimia pelist� riippuen.
peli-istuimen l�heisyyteen on toteutettu n�ytett�v�� tietoa kyseisest� pelaajasta, varattu istuin, tai tyhj� istuin. N�ytett�v��n tietoon pelaajasta kuuluu jakajanappi, onko pelaajalla kortit, kierroksen sanallinen toiminto, pelaajan nimi, raham��r�, paljonko rahaa potissa, ja aktiivisen pelaajan kohdalla aikarajan kulumista n�ytt�v� palkki.
\newpage
\subsection{peliaula}
\begin{figure}[htp]
     \includegraphics[width=15cm]{aula2.eps}
\caption{Peliaula, valittu peli.}
\end{figure}
\begin{figure}[htp]
     \includegraphics[width=15cm]{aula1.eps}
\caption{Peliaula, uuden pelin luonti.}
\end{figure}


Kuvassa 3 on esitetty asiakasohjelmiston peliaulan alustava k�ytt�liittym�hahmotelma.

Peliaulan yl�laidassa hoidetaan sis��n- sek� uloskirjautuminen ja n�ytet��n kuka on kirjaantuneena.
Loput ikkunasta on jaettu kolmeen osaan. Vasemmalla sijaitsee pelivalikko palvelimella olevista pelityypeist�. Keskell� ruutua on pelilistaukset aktiivisista peleist� ja listauksien tarkentamista helpottavaa ja j�rjest�v�� toiminnallisuutta. Oikeassa laidassa ruutua on yksityiskohtaista tietoa valitusta pelist�. Mik�li yht��n peli� ei ole valittu on oikeassa reunassa uuden pelin luontiin tarvittavat lomaketiedot (kuva4).

Keskell� olevaa pelilistaustietoa voidaan j�rjest�� laskevaan ja nousevaan j�rjestykseen painamalla harmaan otsakerivin sarakkeiden nimi�. Pelilistoja voidaan my�s etsi� pelaajan tai pelin nimen perusteella. Hakuehtojen rajoitukseen on tarjottu alalaidassa t�ysien ja tyhjien p�ytien piilotukset sek� pelaajam��rien ja panostuksen rajoittamista. Hiiren tuplaklikkaus valitussa peliss� avaa kyseisen pelin pelip�yd�n uuteen ikkunaan.

Oikealla laidassa sijaitsevasta yksityiskohtaisesta pelitiedosta selvi�� kuka pelaa p�yd�ss� miss�kin paikassa ja paljonko heill� on k�ytt�rahaa p�yd�ss�, sek� onko kyseess� tietokone- vai ihmispelaaja. P�yd�n tietojen alla on esitetty pelin kuvaus sek� nappi, joka avaa valitun pelin uuteen ikkunaan.






\newpage
\section{XML-schema protokolla}
%vesalis�� jotain mit� esitteli ja kirjottaa pari korulausetta tjsp.