Software Design Document Ruben Tytgat Software Engineering Groep 3 Table 1: Document history Versie Datum Auteur Beschrijving 2.0 20/05/2011 Ruben Tytgat Update naar huidige model 1.0 08/04/2011 Ruben Tytgat & Georgi Nikolov Update naar huidige model 0.2 25/03/2011 Ruben Tytgat Revisie 0.1 14/12/2010 Ruben Tytgat Eerste versie
Contents 1 Introductie 1 1.1 Doel.................................. 1 1.2 Bereik................................. 1 1.3 Definities & acroniemen....................... 1 2 Referenties 1 3 Architectuur 1 3.1 Three-tier model........................... 1 3.2 Gebruikte technologieën....................... 1 3.3 Softwarearchitectuur......................... 2 4 Decompositie 3 4.1 Klassenmodel............................. 3 4.1.1 Templates........................... 3 4.1.2 Parameters.......................... 4 4.1.3 Game Data.......................... 5 4.1.4 Users............................. 6 4.1.5 Utilities............................ 7 4.2 Database-structuur.......................... 9 4.3 Sessies................................. 10 5 Gebruikersinterface 10 5.1 User registration........................... 10 5.2 Edit profile.............................. 11 5.3 Game List............................... 12 5.4 Game details............................. 13 5.5 Template editor............................ 14 5.6 Template gallery........................... 15 5.7 New game............................... 16 5.8 Game management.......................... 17 5.9 My games............................... 18 5.10 User management........................... 18 5.11 Friends list.............................. 19 5.12 Berichten............................... 20 5.13 Structuur JSP frontend....................... 21
1 Introductie 1.1 Doel Dit document beschrijft de volledige architectuur van de te ontwikkelen software voor het software engineering-project van SE3. De structuur van dit document is gebaseerd op de IEEE 1016-1998 standaard voor SDD s. 1.2 Bereik Dit document is gericht naar de groepsleden van SE3, m.a.w. de ontwikkelaars en testers van het softwareproject. 1.3 Definities & acroniemen SE3: Software Engineering Groep 3 2 Referenties Software Engineering An Object-Oriented Perspective, Eric J. Braude (2001) IEEE Standard for Software Design Descriptions, IEEE Std. 1016-1998 3 Architectuur 3.1 Three-tier model Voor de algemene architectuur van het project zullen we gebruik maken van het three-tier model. Dit model zorgt voor een scheiding van belangen tussen data, business code, en presentatie door deze te splitsen in 3 lagen. De presentatielaag zorgt voor de interactie met de gebruiker door de resultaten van de businesslaag weer te geven in een voor de gebruiker leesbare vorm en input van de gebruiker te valideren en door te sturen naar de businesslaag. Dit is met andere woorden de user interface. De businesslaag verwerkt de input van de gebruiker, combineert deze met data uit de datalaag en stuurt de resultaten terug naar de presentatie- en datalaag. De datalaag slaat de door het systeem benodigde data op. 3.2 Gebruikte technologieën In ons systeem zal de presentatielaag worden geïmplementeerd met JSP pagina s in XHTML. De layout van de geproduceerde webpagina s zal in CSS stylesheets worden vastgelegd. De Tomcat applicatieserver zal de pagina s aan de gebruiker presenteren en de link leggen tussen de presentatielaag en de businesslaag. Voor de businesslaag zullen wij Java gebruiken, de datalaag bestaat uit een MySQL database. 1
3.3 Softwarearchitectuur Het design van onze software is vooral gericht op een hoge flexibiliteit, zonder daarbij de gebruiksvriendelijkheid uit het oog te verliezen. Om deze hoge flexibiliteit te behalen is er voor een softwarearchitectuur gekozen waarbij elke mogelijke reactie op het scannen van een QR-tag door de gebruiker kan worden geprogrammeerd aan de hand van eenvoudige bouwstenen, die we in ons project Actions noemen. Gebruikers kunnen hun spel data laten bijhouden door middel van een equivalent voor variabelen, die opgedeeld zijn in per-spel en per-speler data. Een spel bestaat dus uiteindelijk uit een boom van Actions die na elkaar uitgevoerd worden wanneer een gebruiker een tag scant. Er zijn verschillende soorten Actions: Print: Stuurt output naar de gebruiker. Multiple actions: Encapsulates multiple actions in 1 action. This action will be hidden from the user with a form of syntactic sugar. ShowImage: Toont een afbeelding aan de gebruiker. Set variable: Wijst een waarde aan een variabele toe. Check variable: If-test die een variabele met een waarde vergelijkt. Compare variable: If-test die 2 variabelen vergelijkt. Math operation variables: Wiskundige bewerking doen op 2 variabelen. Math operation variable and value: Wiskundige bewerking doen op een variabele en een waarde. Show location: Toon een locatie op een Google Maps kaartje. Show path: Toon een pad van een locatie naar een andere locatie op een Google Maps kaartje. Finish: Spel beëindigen. End game: Onmogelijk maken om het spel verder te spelen. 2
4 Decompositie 4.1 Klassenmodel 4.1.1 Templates Templates zijn sjablonen voor games. Deze kunnen aangemaakt worden door members. Een template bestaat uit een collectie events: objecten die getriggerd worden als naar de overeenstemmende URL gesurft wordt door een gebruiker (dit gebeurt wanneer de gebruiker de QR-tag inscant waar deze URL in geëncodeerd is). De Template klasse verzorgt requirement 17. Aan elke event is 1 Action gebonden. Wanneer een event getriggerd wordt, wordt de geassocieerde Action uitgevoerd: execute() wordt opgeroepen. Actions zijn bouwblokken die elk een eigen bewerking voorstellen (bvb verhoog de spelvariabele gevonden tags met 1). De gebruiker kan met behulp van deze 3
bouwblokken beslissen hoe het spel zich zal gedragen wanneer een specifieke QR-tag ingescand wordt. Alle actions zijn pregedefinieerd en hebben een aantal Parameters die de gebruiker kan aanpassen. Ook Templates kunnen parameters hebben. Zij verwijzen deze door naar een parameter in een Action, door deze parameter in te vullen met een ProxyParam, dewelke vervolgens gelinkt wordt aan de template-parameter. Templates hebben deze functie om gebruikers toe te laten gemakkelijk games van een bepaald type aan te maken. Wanneer een gebruiker een nieuwe Game aanmaakt op basis van een Template, worden alle Events en Actions van deze template naar de nieuwe Game gekopieerd, door middel vande clone() functie, die een recursie door de Actionboom teweegbrengt. 4.1.2 Parameters Parameters aan Actions zijn bereikbaar via instanties van de Parameter-klassen. Parameter-klassen zijn containers voor klassen van het type ParamValue (een parameterwaarde). Gewone Params bevatten 1 waarde, terwijl ArrayParams 4
een lijst van waarden bevatten. Aan ParamValue kan gevraagd worden om zijn waarde als een bepaald type te interpreteren. Standard(Array)Params slaan echte data op, terwijl Proxy(Array)Params calls naar zichzelf doorverwijzen naar de (Array)Param die aan hen gelinkt is. 4.1.3 Game Data Games worden voorgesteld door de klasse Game. Deze klasse behandelt de requirements 4, 8, 9, 10, 12, 13 en 14 Elke game heeft een centrale GlobalGameData structuur die de statistieken van het spel bijhoudt. Voor elke user die meespeelt in het spel wordt er ook nog een aparte UserGameData-structuur bijgehouden. Deze datastructuren zijn subklassen van een HashMap. 5
4.1.4 Users Over de spelers zelf worden standaard gegevens (voornaam, achternaam, nickname, e-mail) bijgehouden. De User klasse behandelt requirements 1, 2, 3, 5, 6, 7, 10, 11, 12, 13 en 14 6
4.1.5 Utilities Dit zijn utility-klassen. Met Mailer kan een mail gestuurd worden, met QRTagGenerator kan een bij een Event horende QR Tag gegenereerd worden. Database zorgt voor de link met de database-tier. 7
8
4.2 Database-structuur 9
4.3 Sessies De volgende informatie wordt bijgehouden door middel van server-side session cookies: een flag die aangeeft of de gebruiker ingelogd is (i.e. of hij al dan niet als Guest user de site bezoekt). de nickname van de gebruiker, indien deze ingelogd is. 5 Gebruikersinterface 5.1 User registration Bij de registratie wordt aan de gebruiker enkele persoonlijke gegevens gevraagd. De belangrijkste informatie hier is de Nickname van de gebruiker en zijn Paswoord. Voor het paswoord wordt er een verificatie gevraagd. Hierdoor zijn we zeker dat een gebruiker niet per ongeluk een fout antwoordt ingeeft. Hiernaast wordt ook zijn/haar email gevraagd, die we nodig hebben voor het zenden en ontvangen van invites voor de verschillende spellen. 10
5.2 Edit profile Elke geregistreerde gebruiker kan op eenders welk moment aan zijn/haar gegevens. Die bevinden zich op de Edit Profile pagina. De gebruiker kan zijn/haar voornaam, achternaam of email veranderen of laten zoals ze zijn. Hij/zij kan ook een nieuw paswoord invoeren voor zijn/haar account. Om dat te doen, moet de gebruiker eerst zijn oud en nieuw paswoord ingeven, alsook een verificatie. Daarna kan de gebruiker zijn/haar gegevens updaten, waarbij alle gegevens worden opgeslaan en de volgende keer als de gebruiker naar zijn/haar profiel pagina gaat kan hij/zij de gegevens met de veranderingen bekijken. 11
5.3 Game List De Game List toont alle lopende spellen. Wanneer de gebruiker hier een spel selecteert komt hij/zij in het Game details scherm terecht. 12
5.4 Game details Hier zijn een beschrijving van het betreffende spel en allerhande statistieken te vinden. De gebruiker kan op deze pagina ook beslissen om deel te nemen aan het spel. 13
5.5 Template editor Met de template editor kunnen gebruikers nieuwe soorten spellen creëren. 14
5.6 Template gallery Opgeslagen templates komen terecht in de template gallery. Hier kunnen andere gebruikers (of de auteur zelf) games maken op basis van deze templates. Door op een template te klikken komt men terecht op de New game pagina. 15
5.7 New game Op deze pagina worden de gegevens ingevuld die nodig zijn voor het maken van een nieuw spel. Template parameters worden hier ook ingevuld. Wanneer het spel succesvol is aangemaakt, wordt de gebruiker doorgestuurd naar de Game management pagina voor dit spel. 16
5.8 Game management Op deze pagina kan de eigenaar van het spel een aantal eigenschappen veranderen (zoals de beschrijving en de template parameters). Ook kunnen hier de QR tags voor het spel uitgeprint worden. 17
5.9 My games Dit is een lijst van spellen waarvan de ingelogde gebruiker de beheerder is. De gebruiker kan van hieruit de management pagina van deze spellen bereiken. 5.10 User management Hier kunnen gebruikers hun persoonlijke gegevens aanpassen en een premium account aankopen. (requirements 5, 6, 7 en 16) 18
5.11 Friends list Een gebruiker heeft de keuze om alleen aan spellen deel te nemen, of samen met zijn/haar vrienden. Om het tweede geval te vereenvoudigen, kan elke geregistreerde gebruiker andere gebruikers toevoegen aan zijn/haar friends list. Deze lijst bevat alle bevriende spelers van de gebruiker, voor snelle toegang tot hun profiel. Met behulp van de friends list kan een gebruiker snel en zonder veel moeite andere mensen uitnodigen om deel te nemen aan spellen of een rating te geven aan een template. Er is ook een mogelijkheid om naar een speler te zoeken volgens zijn nickname. Zo kan de gebruiker mensen die hij leert kennen tijdens een of ander spel toevoegen als vrienden. 19
5.12 Berichten Gebruikers kunnen elkaar berichten sturen. Dit zorgt voor een open communicatie tussen de verschillende gebruikers. Zo kunnen spelers makkelijker ideen wisselen of meer informatie krijgen over een of meerdere spellen. De mailbox van elke gebruiker zal ook alle invites voor de verschillende spellen ontvangen. 20
5.13 Structuur JSP frontend Voor elk van de user interfaces in sectie 5 wordt een aparte JSP pagina voorzien. Alle JSP pagina s includen de pagina header.jsp, dewelke de login/logout-bar en het menu definieert, aangezien dit hetzelfde blijft voor elke pagina van de applicatie. 21