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

\section{Johdanto}

Asdf on Helsingin yliopiston tietojenk�sittelytieteenlaitoksen ohjelmistotuotantoprojektin 2008 kev��n ryhm�,
joka toteutti asiakkaan tilaaman yleisk�ytt�isen pokeripalvelinohjelmiston. T�ss� dokumentissa k�yd��n l�pi 
projektiryhm�n tuottamaa ohjelmistoa, asennusta, yll�pitoa sek� ohjelmistoon liittyvi� ominaisuuksia, 
ratkaisu- ja toteutusmalleja. Dokumentti on tarkoitettu ohjelmiston yll�pitoa varten. Projektissa 
keskityttiin toteuttamaan monipuolinen ja hyvin laajennettava palvelin-asiakas peliohjelmisto. Pokeripalvelin 
ja rajapinnat on toteutettu yleisk�ytt�iseksi ja soveltuu sellaisenaan kaikkien mahdollisten vuoropohjaisten pelien tukemiseen, ja dokumentissa on painotettu ohjelmiston jatkok�ytt�� sek� laajentamisen mahdollisuutta ja sen k�yt�nn�n toteuttamista.

Projektin puitteissa ohjelmistoon toteutettiin palvelinohjelmisto, tietoliikenne sek�
asiakasohjelmisto. Asiakasohjelmisto toteuttaa peliaulan�kym�n sek� pokeripeleihin soveltuvan pelip�yt�n�kym�n. Peliaula hakee dynaamisesti palvelimelta sinne toteutetut pelit ja mahdollistaa niihin liittymisen sek� Serverille kirjautumisen. Kaikki viestienv�litys palvelimen ja asiakasohjelmiston v�lill� on XML-skeemalla m��ritelty. M��rittelyist� luodaan pelien viestinv�lityksen j�lkeen pelien tarvitsemia luokkia JAXB-XML-sidontaa k�ytt�en. 


Pokeripalvelin ohjelmiston tarkoitus on toimia yleisk�ytt�isen� ymp�rist�n� testattaessa erilaisia 
teko�lysovelluksia. Projektin puitteessa kuitenkin toteutettiin vain ymp�rist� ja rajapinnat Texas Hold'em 
pelaamiseen, sek� suoraviivainen toteutusmahdollisuus muille pokeripeleille. Rajapintojen suunnitteluun 
panostettiin erityisen paljon.


Ohjelmisto koostuu useista osaj�rjestelmist�, sek� useista valmiista projektissa hy�dynnetyist� 
komponenteista. Luvussa 2 k�yd��n l�pi ohjelmiston yleiskuvaus. Luvussa 3 k�yd��n l�pi toteuttamatta j��neet 
toiminnallisuudet. Luvussa 4 kerrotaan ohjelmiston asennuksesta sek� k�ytt��notosta. Luvuissa 5-8 k�yd��n 
l�pi ja kuvataan ohjelman komponentit. Komponentit on kuvattu yll�pit�j�n ja/tai jatkokehittelij�n 
tarvitsemalla tarkkuudella. Komponentteihin liittyv�st� koodista l�ytyy yksityiskohtaiset kommentit ohjelman toiminnasta sek� Java-dokumentaatio kommentit. Luvussa 9. annetaan sanalliset kuvaukset 
ohjelmiston k�ytt�mist� rajapinnoista. Liitteeksi 1. on ohjelmiston XML-protokollakuvaukset. Liite 2. on ohjelmiston asennusohje. Liite 3 on liit�nn�isten kehitysohje.

Ohjelmiston Java-dokumentaatiot l�ytyv�t osoitteesta: 

texttt{http://www.cs.helsinki.fi/group/asdf/javadoc}
\newpage
\subsection{Sanasto}

\textbf{Sessio} - Asiakkaan yhden loogisen kommunikointitarvekokonaisuuden tunniste. Erimerkiksi peliaulalla on oma 
sessiotunniste, ja jokaisella pelill� johon asiakas on liittynyt on oma sessiotunniste.
\newline
\textbf{Pelilogiikka} - Kuvaus pelitilanteesta ja sen muutoksista asiakkaiden k�ytt�ytymisen funktiona.
\newline
\textbf{JAXB} - Java Architecture for XML Binding. Luo Java-luokista XML-skeeman ja XML-viestist� skeeman mukaan tuo 
takaisin Java-luokaksi.
\newline
\textbf{XML} - Projektissa k�ytetty kuvauskieli tiedonv�lityksess� osaj�rjestelmien v�lill�.
\newline
\textbf{NIO} - Ohjelmistossa k�ytetty Javan valmis verkko-I/O toteutus. Tulee sanoista New I/O. 
\newpage
\section{Ohjelmiston yleiskuvaus}

J�rjestelm� koostuu palvelimesta, sen kanssa keskustelevista asiakkaista ja erill��n palvelimesta toimivista 
pelilogiikkaluokista. Palvelin pit�� kirjaa asiakasyhteyksist� sek� sessioista, ja lis�ksi yll�pit�� 
rakennetta k�ynniss� olevista peleist�. Palvelin vastaa asiakkaiden pyynt�ihin ja v�litt�� pelipyynn�t 
oikeille peli-instansseille. Palvelin osaa mm. luetella palvelimelta l�ytyv�t pelityypit, ja palvelimen 
tuntemat aktiiviset pelit.

Asiakas on loppuk�ytt�j�n k�ytt�m� j�rjestelm�, jolla otetaan yhteys TCP/IP protokollalla palvelimeen. 
Asiakkaan tulee luoda itselleen k�ytt�j�tunnus ja kirjautua sis��n ennen kuin pelaaminen on mahdollista. 
Asiakas voi kirjautumisen j�lkeen pyyt�� palvelimelta peliluetteloa, tai luoda uusia palvelimen tuntemia 
pelej�.

Pelilogiikka toimii palvelinohjelmistossa. Pelilogiikan tulee toteuttaa projektin tuottamat 
pelirajapinnat. Pelilogiikka ladataan dynaamisesti palvelimella eik� peli-instanssit p��se muokkaaman 
palvelimen tietoja.

Asiakkaan on t�rke�� kyet� n�ytt�m��n pelitilanne, ja t�m�n vaatima logiikka on asiakkaalla t�rke�� olla. 
Kuitenkaan pisteytyst� tai lopputuloksen laskentaa ei suoriteta asiakkaalla, koska tiedot voivat v��rink�ytt�j�n tapauksessa olla ep�rehtej�, eik� niit� siksi suositella 
palvelimen pelilogiikassa noteeraamaan. Palvelin tallentaa pisteytykset k�ytt�jien tileille.
Kuvassa 1. on esitetty Peliohjelmiston komponenttien yhteistoimintakuvaus.

\begin{figure}[pht]
     \includegraphics[width=16cm]{clientserver.eps}
     \caption{Peliohjelmiston yhteistoimintakuvaus.}
\end{figure}

\newpage
\section{Toteuttamatta j��neet toiminnallisuudet}
\begin{itemize}
\item (V6) Pelaajan nimen perusteella pelihakua ei toteutettu.
\item (V12) Yleinen pelihistorian tallennus.
\item (V15) Pelaajatilej� ei voi poistaa muuten kuin suoraan tietokannasta.

\end{itemize}
\subsection*{Parannusehdotukset}
Pisteyksen tallennus tietokantaan uusille peleille on hankalaa, sill� se vaatii tietokantataulujen muokkausta tai list�yst�. T�h�n voisi pohtia vaihtoehtoisia menetelmi�.

Peliohjelmat voisi ladata dynaamisesti palvelimelta, niin niiden levitt�minen olisi helpompaa ja turvallisempaa sek� palvelimen toiminnallisuudelle, ett� k�ytt�jien mukavuudelle.

GameControllereita asiakasohjelmistossa ei poisteta poistuessa pelist�. T�m� hukkaa muistia, mik�li k�ytt�j�ll� ei ole botteja pelaamassa peliss�. GameControllerin poistaminen aiheuttaa kaikkien pelaajan lis��mien bottien kuolemisen kyseisest� pelist�, joten sit� ei pit�isi tehd� ennen kuin kaikki pelaajan agentit ovat pelist� poistettu tai poistuneet.

Tyhjien pelien poistaminen palvelimelta ei toimi GameTimer-luokassa tapahtuvan ajastimen peruuttamisen vuoksi. T�m� tulisi korjata.

Pokerilogiikan tilannep�ivityksess� l�hetet��n tilatieto-olio, joka v�litt�� kaiken julkisen tiedon pelitilanteesta. T�m� on verrattain raskasta, ja tietoa voisikin l�hett�� p�ivitysten muodossa, j�tt�en muuttumattomat tiedot l�hett�m�tt�.

Liukulukujen k�ytt� rahaliikenteess� on V��rin(tm). Pit�isi olla t�sm�pistelukuesitys. Liukulukuvirheit� voisi my�s harkita korjaavan py�ristyksill�, mik�li on kyvykk�ist� ihmisist� pulaa.



\newpage
\section{Ohjelmiston toimintaymp�rist� ja k�ytt��notto}
Sek� palvelin ett� asiakas vaativat Java 6 tai uudemman toimiakseen. K�ytt�j�rjestelm� voi kummassakin 
tapauksessa olla mik� vain, jossa on Java 6 tai uudempi, mutta palvelimen tapauksessa suositus on Linux 
j�rjestelm�, eik� toiminnan eheydelle anneta mit��n takeita muissa j�rjestelmiss�.

Seuraavassa k�sitell��n palvelimen asentamista uuteen tietoj�rjestelm��n, sek� asiakkaan asentamista toiseen 
tietoj�rjestelm��n. 

Tietokannan asennus onnistuu asentamalla PostgreSQL tietokanta mielivaltaiseen j�rjestelm��n, johon on mahdollista ottaa TCP/IP yhteys. Lis�ksi t�ytyy asettaa k�ytt�j�tunnus ja osoite -kent�t tietokantaa vastaaviksi server.conf tiedostoon.

Palvelimen asentaminen onnistuu purkamalla Server.zip:n sis�lt� haluttuun koneeseen ja k�ynnist�m�ll� runServer.sh linux -j�rjestelm�ss� tai runServer.bat windows -j�rjestelm�ss�. Palvelin tarvitsee my�s asennetun tietokannan (katso edellinen kohta) ja konfiguraatiotiedoston.

Asiakas l�ytyy Client.zip tiedoston sis�lt�. Pura t�m� hakemiston path\_from\_root\_to\_target alihakemistoon client. Aja samaisesta kansiosta nyt runPokerClient.sh (linux -j�rjestelm�) tai runPokerClient.bat (windows -j�rjestelm�).

\newpage

\section{Palvelin}
Palvelimen komponenttien yhteistoimintakuvaus esiteltiin luvussa 2. Seuraavassa on selitetty komponentteihin 
liittyvi� ominaisuuksia.

\begin{itemize} 


\item Main


T�m� luokka k�ynnist�� Server -luokan ja asettaa lokiin kirjaamisen.

\item Server


Alustaa Java.nio pistokkeet yhteyksien kuuntelemiselle ja hyv�ksymiselle. Luokka py�rii jatkuvassa silmukassa 
run-metodissa, jossa kutsutaan toistuvasti valitsijaluokan select metodia. Luokka huolehtii my�s erilaisten 
managerien alustamisesta ja v�litt�misest� muille luokille. Server-luokka alustaa uuden ClientConnection-luokan jokaista uutta hyv�ksytty� yhteytt� kohti.

\item ClientConnection


Edustaa yksitt�ist� pistokeyhteytt�. Luokka tarjoaa metodit viestien l�hett�miseen ja sis�lt�� vastaanotetun 
viestin k�sittelylogiikan. ClientConnection alustaa MessageHandler-luokan ilmentym�n, joka tekee viestin 
korkean tason k�sittelyn.

\item MessageHandler


Huolehtii viestien k�sittelyst�. Luokka huolehtii sessiotunnisteiden k�yt�st�, jotta yhdistetyt asiakkaat 
eiv�t voi yritt�� huijata eiv�tk� v�litetyt viestit mene v��rille vastaanottajille. MessageHandler k�ytt�� 
Serverin omistamien managereiden palveluita.

\item AccountManager, Account


Sis�lt�� k�ytt�j�tunnusten luonnin, poiston ja muutokset. My�s autentikointi on tehty t�ss� luokassa. Luokka 
k�ytt�� tietokantaa autentikointiin. Jokaista kirjautunutta k�ytt�j�� kohti alustetaan Account ja se 
talletetaan luokan ClientConnection j�senmuuttujaan, josta se voidaan hakea kun halutaan tiet�� k�ytt�j�n 
autentikoinnin tilanne ja mahdolliset k�ytt�j�oikeudet.

\item SessionManager


Pit�� kirjaa yhteyksien sek� sessiotunnisteiden k�yt�st�. t�ll�in voidaan tarkistaa, ett� yhteydet yrit� 
k�ytt�� toistensa sessiotunnisteita.

\item GameManager


Sis�lt�� pelien luontiin liittyv�t toiminnot. T�m�n luokan kautta kulkevat kaikki peleille menev�t viestit. 
GameManagerilla on lista pelej� ja se k�ytt�� GameFactorya uusien pelien luontiin.

\item GameTimer


GameTimer on peliliit�nn�isille tarjottu ajastinrajapinta. Luokka on hyvin samantapainen kuin Timer-luokka, 
jonka se perii. GameTimer synkronoi ajastettujen tapahtumien toimitukset peleille, kun palvelin saattaa olla 
eri s�ikeest� k�sittelem�ss� peli� samaan aikaan.

\item Configuration


Lukee k�ytt�j�n asetukset server.conf tiedostosta ty�hakemistosta ja tarjoaa ne staattisten metodien 
v�lityksell� kysyjille.
\end{itemize}

Seuraavassa on kuvattu tarkemmin uuden pelin lis��minen palvelimelle, autentikoinnin toteutus sek� palvelimen 
s�ikeistyksest�.

\subsection{Tietokanta}
Palvelin k�ytt�� autentikointiin PostgreSQL-tietokantaa. Tietokannan yhteysmerkkijono ja k�ytt�j�tunnukset 
tulee m��ritell� server.conf tiedostoon. Autentikointitietokannan taulun voi luoda seuraavalla SQL-lauseella:

\begin{verbatim}
CREATE TABLE account (
name varchar(256),
password char(32),
type short,
balance decimal,
PRIMARY KEY(name)
);
\end{verbatim}
Salasana-kent�n sis�lt� on MD5-hajautusarvo k�ytt�j�tunnuksen ja selv�kielisen salasanan yhdisteest� 
heksadesimaalimerkkijonona.


\subsection{S�ikeistys}
Palvelin on toteutettu kahden s�ikeen avulla. Ensimm�inen s�ie on vastuussa Java.nio luokkien 
yhteysoperaatioiden k�sittelyst� ja toinen ajastimien hallinnasta. Ajastimia tarjotaan liit�nn�isille. 
Synkronointi s�ikeiden v�lill� tapahtuu liit�nn�ist� kutsuttaessa ja liit�nn�isest� ulosp�in l�hteviss� 
kutsuissa.
	
\newpage
\section{Tiedonsiirto}
\subsection{JAXB, XML}
Asiakkaan ja palvelimen tiedonv�lityksess� on hy�dynnetty valmista JAXB-pakettia, joka muuntaa Java-luokkia 
XML-muotoiseksi informaatioksi, ja takaisin. Viestit k��rit��n XML Schema kielell� m��riteltyihin 
viestiluokkiin, jotka voivat m��rittelyn mukaan olla (kirjoittamisen hetkell�) kysely-, vastaus- tai tilannep�ivitystyyppisi� 
viestej�. N�m� viestityypit taas jakautuvat erilaisiin viestityyppeihin, kuten 
peliviesteihin tai autentikointi-viesteihin. Katsaus k�ytettyihin viestiluokkiin l�ytyy mukaan liitetyst� XML-skeemasta ja Javadoc -dokumentaatioista. Viestien m��rittely on hoidettu XML-skeemalla niin, ett� skeema 
j�tt�� prosessoimatta valittujen viestityyppien tietynnimiset alielementit. T�m�n avulla ohjelmiston 
liit�nn�isten avulla tehdyt laajennukset voivat m��ritt�� omat valinnaiset viestityyppien parametrit, mutta 
viestin eheys pystyt��n kuitenkin tarkistamaan luotettavasti ennen liit�nn�isille luovuttamista. Jaxb 
ty�kalujen k�ytt�� rohkaistaan my�s liit�nn�isten kehittelyss� sill� etuna on protokollan v��rintulkitsemisen 
tai -k�ytt�misen huomaaminen jo k��nt�misvaiheessa, sill� viestin k�sittely tapahtuu perinteisten 
Java-luokkien kaltaisten metodien kutsuilla.
\subsection{java.nio}
Tietoliikennepistokkeiden kanssa k�ytet��n Javan New I/O (Java.nio) luokkia. Luokat mahdollistavat 
asynkronisten pistokkeiden k�ytt�misen, jolla voidaan ehk�ist� tilannetta, jossa jokaista asiakasyhteytt� 
varten on oma s�ie. Asiakkaan ja palvelimen v�linen liikenne on toteutettu niin, ett� asiakas pit�� koko 
session ajan yhteytt� auki palvelimeen. Yhteyden ollessa auki kumpi tahansa p�� pystyy her�tt�m��n 
keskustelukumppanin jonkin tapahtuman sattuessa. Jatkuvasti auki olevan yhteyden takia viestinv�lityksess� 
l�hetet��n ensin viestin koko ja sitten vasta itse viesti. Viestin koko l�hetet��n 32-bittisen� 
kokonaislukuna, jonka tavuj�rjestys noudattaa tietoliikenteess� k�ytetty� Big-Endian (Network Byte Order) 
tavuj�rjestyst�. 

\subsection{Tietoliikenneprotokolla}
Protokolla on jaettu kolmeen yl�tyyppiin p�ivitys, kysely, vastaus. Seuraavassa on selitetty mihin kutakin 
tyyppi� on k�ytetty.
Toteutettu protokolla l�ytyy liitteest� 2 tarkempine selityksineen.
\subsubsection{P�ivitys}
P�ivitys on serverin l�hett�m� pelitilanteen p�ivitt�miseen k�ytetty viesti. Sis�lt�v�t p�ivitetyt tiedot 
pelitilanteesta, kuten pelitilanneolion, keskusteluviestit ja muun pelintilannesis�lt��n liittyv�n tiedon.
\subsubsection{Kysely}
Kysely on asiakasohjelmiston pelip�yt��n sek� peliaulan k�ytt�m�t viestit. Sis�lt�v�t viestipyynn�t, joiden 
avulla asiakasohjelmisto pyyt�� palvelinta suorittamaan eri toimintoja. Peliaulan toimintoihin kuuluu 
pelilistausten ja pelitietojen pyyt�minen, pelin luominen ja pelip�yt��n liittyminen, palvelimelle 
kirjautuminen sek� uusien tilien luonti. Pelip�yt� l�hett�� keskusteluviestit, penkin varaukset sek� peliin 
liittymisen kyselyviestin�. Mahdollista on my�s ett� pelilogiikka pyyt�� asiakkaalta kysely�.
\subsubsection{Vastaus}
Palvelin k�ytt�� vastausviestej� vastausviestein� pelip�yd�n sek� peliaulan pyynt�ihin. Lis�ksi 
pelip�yd�st� v�litett�v�t pelitapahtumat l�hetet��n palvelimelle vastausviestein�. 

\subsection{Pokeripeliss� k�ytetty protokolla}
Asiakkaan ohjelmiston pokeripeli viestii palvelimella py�riv�n pelilogiikan kanssa k�ytt�m�ll� spesifist� 
pokeripeleille tehty� protokollaa. Protokollan mukaiset viestit kulkevat yll� esitetyn prokollan mukaisten 
otsakkeiden alla. Viestien sis�lt� on sijoitettu erityiseen parametrielementiin, joka voi sis�lt�� mit� 
tahansa. Viestit sis�lt�v�t pelitilanne-, p�ivitys-, k�sikortti- sek� pelitapahtumaviestej�. 

\newpage
\section{Pelilogiikka}
Pelilogiikkamoduulit sijaitsevat palvelimella mutta ne on eroteltu itsen�isiksi moduuleiksi. 
Pelilogiikkamoduulien t�ytyy toteuttaa Game-rajapinta. Pelilogiikkamoduulit toteuttavat itse oman 
toiminnallisuutensa. Logiikkamoduuleilla on mahdollisuus k�ytt�� palvelimen valittuja palveluita abstraktin 
Game-luokan tarjoamien metodien kautta. Ajastinpalveluita on pakko k�ytt�� t�t� kautta, jotta synkronointi 
toimii oikein.

\subsection{Pokeripeli: GameModel}
Projektin yhteydess� toteutettuun TexasHoldem peliin liittyv� peli-informaatio-objekti, joka toteuttaa 
gameinfo rajapinnan. GameModel sis�lt�� pelin kaiken julkisen tiedon ja aksessorit niiden muunteluun. 
Aksessoreilla pelilogiikka p�ivitt�� pelitilannetta. Pelilogiikan ulkopuolelle pelitieto-olio (GameInfo) 
l�hetet��n ilman tietosis�lt�� muuttavia aksessoreita. Olioiden tietosis�lt�n� on kaikki pelin esitt�miseen 
tarvittava tilatieto. Metodeista kuvaukset l�ytyv�t Javadoc-liitteest�.


\subsection{Pokerilogiikka}

Kuvassa 2 on esitelty ohjelmiston k�ytt�m� yleisk�ytt�inen pokeripelilogiikka tilakoneena. Sen lis�ksi ett� 
uusia pelej� voidaan toteuttaa luomalla pelej�, jotka toteuttavat game-rajapinnan voidaan uusia pokeripelej� 
peri�
pokerilogiikasta vaihtelemalla jako-, panostus- sek� kortinvaihtokierrostilojen m��r�� ja j�rjestyst�. 
Lis�ksi uuteen peliin tulee toteuttaa voittajanlaskenta sek� potinjakoalgoritmi, mik�li kyseiset algoritmit 
poikkeavat valmiista toteutuksesta.

Tilakoneessa usein edellinen tila asettaa seuraavaksi toimivan pelaajan kohdalleen, jotta itse��n toistavat 
tilat voidaan suorittaa useasti per�j�lkeen.
	
\begin{figure}[pht]
     \includegraphics[width=10cm]{overall.eps}
     \caption{Pokerilogiikkatilakone}
\end{figure}
	

\subsection*{Toimintaviestit asiakasohjelmistosta}
Pokerilogiikkatilakoneen tiloihin, kuten sokkopanosten ker�ys, panostuskierrokset, ja korttienvaihto, liittyy 
vuorovaikutus asiakkaan kanssa. Edell� mainituissa tiloissa pelilogiikka pyyt�� palvelimelta ajastinpalvelua, 
jonka ajan odotellaan pelaajalta pelitilanteeseen liittyv�� toimintoa. Lis�ksi on viestej� jotka voivat tulla 
miss� tahansa tilakoneen tilassa, kuten peliin liittyminen, pelist� poistuminen. Kuvassa 3 on yleiskuva 
viesteist�, jotka voivat tulla mihin tahansa aikaan. Lis�ksi kunkin tilan kuvassa on tietoa kyseisen tilan toiminnasta ja siihen liittyv�st� viestinn�st�.
\begin{figure}[pht]
     \includegraphics[width=13cm]{anytimemessage.eps}
    \caption{Pokerilogiikka: Yleiset toimintaviestit}
\end{figure}
\subsection*{waitplayers} 
Waitplayers on tila, jossa odotellaan minimim��r� pelaajia eik� peli ole k�ynniss�. Aina pelin alkaessa 
pelaajien minimim��r�ksi asetetaan kaksi. Pelin alkaessa odotuksen j�lkeen arvotaan uusi jakaja.

\subsection*{blind round}
Blind round on tila, joka suoritetaan jokaiselle aktiiviselle pelaajalle p�yd�ss�. Pelaajalta kysyt��n kuvan 
4 mukaisesti maksettavia panostuksia. Lis�ksi kysyt��n sakkopanokset tauolta palanneilta pelaajilta sek� 
peliin liittymiseen liittyvi� panostuksia.
\begin{figure}[pht]
     \includegraphics[width=13cm]{blindround.eps}
    \caption{Pokerilogiikka: blind round}
\end{figure}
\subsection*{new deal}
Jakokierros suoritetaan pelin alussa ja aloitetaan luomalla uusi korttipakka. Korttipakasta jaetaan 
aktiivisille pelaajille k�sikortit. K�sitiedoista paljastetaan pelaajille vain kortit, jotka ovat kyseiselle 
pelaajalle julkista tai henkil�kohtaista tietoa. Muista korteista esitet��n vain tausta.
Jakokierroksen lopussa asetetaan pelitilaolion aktiiviseksi pelaajaksi panostuskierroksella ensimm�ist� 
edellinen pelaaja.
\subsection*{bet round}
Panostuskierroksella ker�t��n panoksia kuvan 5 algoritmin mukaan. Tila on iteratiivinen ja suoritetaan 
jokaiselle aktiiviselle pelaajalle vuorollaan kunnes p��st��n lopputilaan. Lopputilassa kaikki ovat joko 
maksaneet vaaditut panostukset, heitt�neet kortit pois tai panostaneet kaikkensa. T�m�n j�lkeen siirryt��n 
seuraavaan tilaan. Mik�li peliss� on vain yksi pelaaja, on sekin lopputila ja siirryt��n 
less-than-two-players tilaan.
\begin{figure}[pht]
     \includegraphics[width=13cm]{betround.eps}
     \caption{pokerilogiikka: bet round}
\end{figure}
\subsection*{discard round}
Discard round eli korttienvaihtokierros ei kuulu texas holdemiin, mutta pokerilogiikka toteuttaa kyseisen 
tilan muita pelej� varten. Tilassa k�yd��n kaikki aktiiviset pelaajat kerran l�pi ja jaetaan poisheitettyjen 
korttien tilalle uudet kortit. Tilan vaiheet on esitetty kuvassa 6.

\begin{figure}[pht]
     \includegraphics[width=13cm]{discard.eps}
    \caption{Pokerilogiikka: discard round}
\end{figure}
	
\subsection*{deal card round}
Korttienjako -tiloissa jaetaan p�yt��n tai pelaajille lis�� kortteja, t�m�n j�lkeen asetetaan pelitilaolion 
aktiiviseksi pelaajaksi seuraavassa tilassa ensimm�isen� toimivaa pelaajaa edellinen pelaaja. Pelaajan 
asetuksessa huomattavaa on, ett� \textit{heads up} tilanteessa ei ensimm�isen� toimiva pelaaja ole aina buttonista 
seuraava aktiivinen pelaaja.
\subsection*{Less than two players}
T�h�n tilanteeseen tulessa peliss� on v�hemm�n kuin kaksi pelaajaa. Tilanteeseen voidaan p��st� kahdesta eri 
tilasta, sokkopanoskierrokselta tai panostuskierroksilta. Sokkopanoskierrokselta tultaessa joko kukaan ei ole 
liittynyt peliin tai pelk�st��n toinen sokkopanoksista on maksettu, t�ll�in sokkopanos palautetaan ja 
siirryt��n eteenp�in showdown tilaan.

Panostuskierrokselta tultaessa t�h�n tilaan peliss� on en�� yksi pelaaja joka voittaa kierroksen. Voittajaa 
varten asetetaan ajastin, jonka ajan h�nell� on mahdollisuus n�ytt�� tai piilottaa voittokortit muilta 
pelaajilta. Mik�li ajastin laukeaa, kortteja ei n�ytet�. Ajastimen laukeamisen tai korttien 
n�ytt�misp��t�ksen j�lkeen siirryt��n showdown tilaan.
\subsection*{winnings}
Viiden kortin pokerik�den arvon laskemiseen on k�ytetty nimimerkill� ''Cactus Kev'' esiintyv�n henkil�n 
kehitt�m�� algoritmia, jonka kuvaus l�ytyy osoitteesta:

 \texttt{http://www.suffecool.net/poker/evaluator.html}


Paras pokerik�si seitsem�st� kortista on laskettu sijoittamalla vuorotellen kaikki mahdolliset viiden kortin 
yhdistelm�t algoritmiin. Kun pokerik�det on saatu, arvoj�rjestykseen jaetaan potti voittajien kesken kuvan 7 
algoritmia k�ytt�en.
\begin{figure}[pht]
     \includegraphics[width=16cm]{winnings.eps}
    \caption{Pokerilogiikka: kuinka voitto potti jaetaan}
\end{figure}


\subsection*{muck round}
Voittajan ratkomisen j�lkeen h�vi�jille suodaan viel� mahdollisuus k�tke� tai n�ytt�� korttinsa 
muck-ajastimen ajan, jonka j�lkeen siirryt��n showdown-tilaan.
\subsection*{showdown}
Showdown-tilassa l�hetet��n kaikille peli� seuraaville p�ivitetty pelitilanneolio ja odotetaan 4s, jotta ihmispelaajilla on aikaa omaksua lopputulos. Samalla ker�t��n tieto asiakasohjelmilta, ketk� pelaajista eiv�t osallistu seuraavalle kierrokselle.

\newpage
\section{Asiakasohjelmisto}
Asiakasohjelmisto on loppuk�ytt�j�n koneella py�riv� komponentti. Asiakasohjelmisto koostuu palvelimelle 
kirjautumisesta, peliaulasta, pelip�yd�st� sek� pelip�yt��n ja aulaan liittyvist� ohjain-olioista 
(GameController, LobbyController). Peliaula sek� pelip�yt� toteuttavat ohjelmiston k�ytt�liittym�n javan 
swing kirjastolla. Tietosis�lt� on upotettu Controller-olioihin, jotka kommunikoivat yleisen yhteysrajapinnan 
kautta palvelimen ja k�ytt�tym� komponenttien v�lill�.

\subsection{Peliaula}
K�ytt�j�n kirjauduttua palvelimelle saavutaan peliaulaan.
Peliaulan yl�laidassa hoidetaan uusien k�ytt�jienluonti, sis�- ja uloskirjautuminen sek� n�ytet��n kuka on 
kirjautunut aulaan.  Loput ikkunasta on jaettu kolmeen osaan. Vasemmalla sijaitsee pelivalikko
palvelimella olevista pelityypeist�. Keskell� ruutua ovat pelilistaukset aktiivisista peleist� sek� 
listauksien tarkentamista helpottavaa ja toiminnallisuutta. Oikeassa laidassa ruutua on yksityiskohtaista 
tietoa valitusta pelist�. Jos yht��n peli� ei ole valittu, on oikeassa reunassa uuden pelin luontiin 
tarvittavat lomaketiedot.
Keskell� olevaa pelilistaustietoa voidaan j�rjest�� laskevaan ja nousevaan j�rjestykseen painamalla harmaan 
otsakerivin sarakkeiden nimi�. Lis�ksi tyhj�t ja t�ydet p�yd�t pystyt��n piilottamaan pelilistauksesta.
	
Oikealla laidassa sijaitsevasta yksityiskohtaisesta pelitiedosta selvi�� kuka pelaa valitussa p�yd�ss� miss�kin 
paikassa ja paljonko heill� p�yd�ss� rahaa. Pelitietojen alla on esitetty pelin kuvaus sek� 
pelinliittymispainike, joka avaa valitun pelin uuteen ikkunaan. Kuvassa 8 on esitetty peliaulan graafisten 
komponenttien suhteet aulanhallinta-olioon sek� esitetty miten k�ytt�liittym�paneelit sijoittuvat kehykseen. 
Kuvassa 9 on kuva itse peliaulasta.

Seuraavassa on kuvattu lyhyesti asiakasohjelmiston eri komponentit. Javadoc -dokumentaatio sis�lt�� tarkemmat kuvaukset luokista.

\begin{itemize}
\item ConnectionHandler

Java NIO -kirjastoa hy�dynt�v� yhteysluokka. Py�rii itsen�isess� s�ikeess� kuunnellen sockettiin tulevaa dataa ja sockettiin l�hetett�v�n datan pyynt�j�. K�ytt�� avukeseen ChangeRequest olioita ohjatakseen socketin toimintaa lukemisen ja kirjoittamisen v�lill�. Sis�lt�� metodit viestien l�hett�miseen ja metodin viestien kuuntelijaksi rekister�itymiseen. Rekister�ityneille kuuntelijoille v�litet��n viestej� niiden sessionID:n perusteella. 

\item Message

Rajapinta, joka mahdollistaa ConnectionHandlerille saapuvien viestien kuuntelijaksi rekister�itymisen. Sis�lt�� rajapinta metodit, joiden avulla viestien v�litt�minen kuuntelijalle onnistuu.

\item LobbyController

Asiakasohjelmiston aulaa ja pelihakua hallinnoiva osio. T�m�n luokan kautta kulkevat viestit k�ytt�liittym�luokasta LobbyFrame palvelimelle ja takaisin. Huolehtii my�s peliohjelmien k�ynnist�misest�. 

\item LobbyModel

Pit�� yll� aulaohjelman tietosis�lt��. Tallettaa tuoreimmat p�ivitykset pelilistoista ja pit�� yll� asiakkaan kirjautumista. Sis�lt�� apumetodeita LobbyControllerille tietojen kaivamiseen palvelimelta l�hetetyist� viesteist�. Tietoja k�ytt�j�st� yll�pidet��n luokan User avulla.

\item LobbyFrame

Graafinen k�ytt�liittym� aulaohjelmalle. Komennot k�ytt�liittym�st� kulkevat LobbyControllerille. Rakentuu useista osapaneeleista.

\item PluginLoader

Apuluokka, joka huolehtii luokkien dynaamisesta lataamisesta. K�ytet��n muun muassa peliohjelmien dynaamiseen lataamiseen ja pokeripeliss� teko�lypelaajien lataamiseen. Configuration luokka pit�� yll� hakemistot, joista lis�osat ja teko�lypelaajat tulee ladata.

\item GameController

Abstrakti yl�luokka, jota laajentamalla voidaan toteuttaa uusia peliohjelmia, jotka aulaohjelma osaa ladata dynaamisesti. Sis�lt�� useita valmiiksi toteutettuja metodeita ja abstraktit metodit, joiden avulla kommunikointi palvelimen v�lill� ConnectionHandler luokan kautta tulee tapahtumaan. Toteuttaa Message -rajapinnan. 

\end{itemize}


\begin{figure}[pht]
     \includegraphics[width=13cm]{lobby.eps}
     \caption{Peliaulan komponenttien suhteet toisiinsa.}
\end{figure}
\begin{figure}[pht]
     \includegraphics[width=13cm]{lobbyscreenshot.eps}
     \caption{Kuvankaappaus peliaulasta.}
\end{figure}

\newpage
\subsection{Pelip�yt�}
Ohjelmistossa on toteutettu pelip�yt� pokeripeleille. Pelinhallintaolio v�litt�� ajantasaista pelitietoa 
k�ytt�liittym�komponenteille kuvan 10 esitt�m�ll� tavalla. Pelitilanteen hallintaan liittyv�t 
graafiset komponentit on sijoitettu Javan Layoutmanagerien avulla. Kuitenkin pelin�kym��n liittyv�t 
peli-istuimet ja niihin l�heisesti liittyv�t informaatiota sis�lt�vien tietorakenteiden esitykset, kuten 
ajastimet, jakajanapit, kortit, paikanvarausnapit sek� panostukset on sijoitettu kerrostusruutuun 
(JLayeredPane). Kerrostusruudun k�ytt� mahdollistaa dynaamisen istuimien sijoittelun sek� pelaajille 
jaettavan korttim��r�n vaihtelun. My�s pelikuvakkeet kuten kortit, jakajanapit, jne. skaalauntuvat 
peli-ikkunan koonmuutosten mukaan, mahdollistaen useamman pelip�yd�n sovittamisen pienellekin n�yt�lle.

Pelip�yd�n k�ytt�liittym�n alareuna on jaettu kolmeen osaan. Vasemmanlaidan valintaruudut sis�lt�v�t 
etuk�teistietoa sokkopanosten maksusta, \textit{sitoutista} sek� voittavien ja h�vi�vien korttien pois heitosta. 
Vasemmanlaidan painikkeista saa peliaulan n�kyviin, tai suljettua pelip�yd�n. Keskell� alareunassa sijaitsee 
keskusteluviesti-ikkuna. Oikeassa alareunassa on n�kyviss� peliss� oleva potti sek� nykyisen kierroksen 
tarvittava panostusm��r� sek� pelitilanteeseen liittyv�t toimintapainikkeet. Toimintapainikkeita liittyy 
panostuskierrokseen, sokkopanoskierrokseen sek� pelaajan ollessa sitout tilassa. Oikeassa laidassa sijaitsee 
my�s valintaruudut, joilla pelaaja voi antaa etuk�teistietoa miten aikoo toimia omalla kierroksellaan. 
Kuvassa 11 on kuva pelip�yd�st�

\begin{figure}[pht]
     \includegraphics[width=13cm]{gameview.eps}
     \caption{Pelip�yd�n komponenttien suhteet toisiinsa.}
\end{figure}
\begin{figure}[pht]
     \includegraphics[width=13cm]{gameviewscreenshot.eps}
     \caption{Kuvankaappaus pelip�yd�st�.}
\end{figure}

\newpage
\section{Rajapintakuvaukset}
\begin{itemize}
\item Game: Game -rajapinta m��rittelee tavan, jolla yleisen pelin tulisi tehd� yhteisty�t� palvelimen 
kanssa. Rajapinnan m��rittelem�t metodit antavat pelille mahdollisuuden k�sitell� palvelimelta saapuvia 
viestej� ja l�hett�� niihin vastauksia. Lis�ksi rajapinta ohjeistaa selke�ll� tavalla kuinka pelaajia tulee 
liittym��n peliin ja miten pelaajat voivat peliin vaikuttaa. Rajapinnan metodit peliohjelmoijan tulee
kuitenkin toteuttaa itse.

\item PokerGame: Rajapinta toteuttaa kaikkien pokeripelien haluamat toiminnot. Laajentamalla t�t� luokkaa, 
voidaan helposti toteuttaa muita pokeripelej�.

\item MessageHandler: Rajapinta, joka mahdollistaa asiakasp��ss� olevien peliasiakasohjelmien kommunikoinnin 
palvelimen kanssa ConnectionHandler luokan kautta. MessageHandler rajapinnan toteuttavat luokat voivat 
rekister�ity� niille rajapinnan kautta annettuun yhteisolioon. T�ll�in niille v�litet��n yhteys oliolle 
tulleita viestej� niiden sessiotunnisteen perusteella.
\item GameController: Rajapinta m��rittelee tavan, jolla peliaulasta voidaan k�ynnist�� tietynpelin 
asiakasohjelma sek� miten viestinv�litys asiakasohjelman ja palvelimella toimivan pelilogiikan v�lill� 
tapahtuu. GameController toteuttaa MessageHandler -rajapinnan.
\item PlayerInfo: Tarjoaa metodit pelaajakohtaisen julkisen tiedon pyyt�miseen.
\item GameModel: Tarjoaa metodit pelikohtaisen julkisen tiedon pyyt�miseen.

\end{itemize}


