PIATTAFORMA DI SERVIZI PER GIOCHI GEOLOCALIZZATI

Transcript

1 POLITECNICO DI MILANO FACOLTÀ INGEGNERIA DELL INFORMAZIONE PROGETTO DI TECNOLOGIE DEI SERVIZI 1 PIATTAFORMA DI SERVIZI PER GIOCHI GEOLOCALIZZATI Roberto Mereghetti

2 SOMMARIO Introduzione... 3 Obiettivi... 3 Requisiti... 4 Attori... 4 Casi d uso... 4 Tecnologie adottate... 6 Architettura dell applicazione... 8 Schema e documentazione della base dati Manuale di installazione e uso... 15

3 INTRODUZIONE Partendo dall idea iniziale di creare un gioco sociale online basato sui servizi, abbiamo iniziato a progettare sia il lato generico, ossia la creazione di tutti i dati e servizi di supporto al gioco vero e proprio, sia il lato specifico che consiste in un insieme di regole e una meccanica di gioco che utilizzi i servizi esposti. Dopo diverse proposte concrete di regole e meccaniche di gioco, abbiamo notato che la struttura di base di ogni gioco è sempre molto simile e può essere ridotta al fattor comune della creazione di un tabellone. Il gioco in sé può essere una qualsiasi applicazione web e per questo motivo il nostro sistema deve essere molto robusto per potersi interfacciare in modo generico con altre applicazioni: il paradigma a servizi si adatta in modo perfetto a questa situazione e soddifsa le nostre necessità. Inoltre il tabellone con i territori non può bastare come supporto per un gioco reale perché non c è diversificazione tra un territorio e gli altri. La diversificazione tra territori viene creata a partire da dei dati geolocalizzati che concorrono alla definizione del valore dei territori. Abbiamo quindi deciso di trasformare il progetto nel servizio che crea e gestisce tabelloni di gioco, con territori e dati diversi, cercando metodi standard per aggregare le informazioni sulla mappa, tenendo sempre presente che il nostro risultato finale dovrà essere pronto per l ideazione di un gioco completo. OBIETTIVI Lo scopo principale del progetto è quello di creare un applicazione web a servizi che sia in grado di generare un tabellone di gioco, configurato per essere utilizzato come base per lo sviluppo di un socialgame su mappa. Nel processo di generazione bisogna tenere conto del trade-off che c è tra genericità e personalizzabilità del tabellone: da qui nascono diversi obiettivi che riguardano vari aspetti del problema. Il primo obiettivo da raggiungere è quello di poter generare dei territori (o caselle) che siano solo localizzate sulla mappa sottostante, in questo modo possiamo mantenere il concetto di territorio generico, lasciando che sia la mappa, il gioco in sé oppure i giocatori a dargli un significato. Per fare in modo che la mappa inizi a dare un valore ai territori è necessario che questi vengano riempiti di informazioni che dipendono da essa; inoltre la presenza di tali informazioni è un obiettivo del progetto, perché i territori da soli non bastano per poter utilizzare il tabellone. L utilizzo della mappa del mondo reale infatti, è sia parte della soluzione dei punti precedenti sia obiettivo in sé, in quanto consentirà di sviluppare un gioco su qualcosa di esistente, creando un collegamento tra reale e virtuale che è una caratteristica importante nello sviluppo di un futuro socialgame. Questo collegamento è esteso alla necessità per il sistema di reperire informazioni reali geolocalizzate sulla mappa reale attraverso servizi esterni ed aggregarle in termini di territori del tabellone creato. L utente dell applicazione dovrà però avere spazio per la personalizzazione del proprio tabellone, da qui l obiettivo di dare la possibilità di modificare alcuni parametri significativi in fase di creazione.

4 Ulteriore obiettivo è quello di fornire servizi di supporto per la gestione di utenti, giocatori e dati necessari per lo sviluppo e gestione del social-game (ad esempio le bandierine segnaposto). REQUISITI L applicazione espone alcuni servizi che corrispondono ai vari requisiti e che possiamo raggruppare in 3 categorie: 1. Gestione utenti: in questa categoria troviamo la creazione, eliminazione, modifica, autenticazione di tutti gli utenti, siano essi creatori di tabelloni o semplici giocatori 2. Gestione tabelloni: creazione, eliminazione e modifica di tabelloni, le modifiche riguardanti l associazione giocatore/territorio e la richiesta dei dati di un tabellone 3. Gestione bandierine: creazione, eliminazione, modifica e richiesta di bandierine segnaposto; il loro utilizzo è lasciato all inventiva del creatore del social-game. Tutte le altre funzionalità non sono esposte e consentono dialogare coi servizi esterni per tenere aggiornato il db e di effettuare tutti i calcoli topologici necessari. ATTORI Il sistema, per sua natura, è sia fornitore di un servizio che fruitore di servizi esterni; in questo scenario entrano in gioco alcuni attori anche molto diversi tra loro. In quanto fruitore di servizi esterni, il sistema comunica con diverse entità automatiche, che sono ovviamente altri servizi esposti in rete. Come fornitore di servizi, lo spettro è più diversificato: esisteranno attori fisici che potranno usare il servizio perché vi è stato implementato un gioco e vorranno essere utenti o giocatori, altri che utilizzeranno il servizio per creare un social-game; non mancheranno altre entità automatiche che vogliono solo utilizzare il nostro servizio per mappare dei dati grezzi su porzioni particolari della mappa. CASI D USO L utilizzo del sistema è diversificato per i vari attori, anche se ovviamente alcune delle funzionalità sono condivise tra gli attori. Vediamo i possibili casi d uso: - Servizio esterno: Il sistema è in grado di reperire informazioni geolocalizzate da altri webservices. In questo caso l applicazione chiamerà in modo pianificato o su richiesta alcuni servizi per reperire le informazioni da mappare sui territori. Di questa categoria fa parte anche il servizio da cui prendiamo la mappa del mondo reale. - Utente fisico (creatore di social-game): la persona fisica in questione è un utente esperto in grado di utilizzare i servizi da noi esposti e programmare un server di gioco.

5 - Server di gioco: tale server impone diversi requisiti per il corretto funzionamento del gioco stesso: gestione dei giocatori, gestione dei tabelloni, modifica delle associazioni tra territori e giocatori, refresh dai dati geolocalizzati e gestione delle flag segnaposto. Sarà l utente non fisico principale nella vita del social-game in quanto si preoccuperà di mettere in comunicazione utenti e giocatori con il database della nostra applicazione. - Utente fisico (creatore di tabelloni): in questo scenario è stato già implementato un social-game utilizzando il nostro servizio per costruire tabelloni di gioco. L utente che vorrà creare un tabellone dovrà autenticarsi attraverso il server di gioco sulla nostra applicazione e poi sarà libero di personalizzare e creare il tabellone, che potrà essere utilizzato su una o più partite. - Utente fisico (giocatore): in questo scenario è stato già implementato un social-game utilizzando il nostro servizio per costruire tabelloni di gioco. Dopo l autenticazione il giocatore sarà guidato dal server di gioco che gli darà la possibilità di partecipare alle partite esistenti. - Utente automatico: questo utente è rappresentato da un applicazione esterna che non è strettamente correlata all idea di gioco, ma intende utilizzare il nostro servizio per mappare o raggruppare i dati grezzi su caselle o porzioni di mappa particolari.

6 TECNOLOGIE ADOTTATE RESTFUL WEB SERVICE Per realizzare un applicazione con servizi REST, la documentazione ufficiale di Java enterprise edition 6 ( offre una tecnologia di riferimento: Project Jersey is the production-ready reference implementation for the JAX-RS specification. Jersey implements support for the annotations defined in the JAX-RS specification, making it easy for developers to build RESTful web services with Java and the Java VirtualMachine (JVM). ( The Java EE 6Tutorial, pagina 338) Abbiamo quindi scelto le librerie del progetto Jersey per realizzare il layer di servizi web di questa applicazione. Abbiamo utilizzato Jersey e le annotazioni JAX-RS per realizzare i seguenti requisiti: a. binding tra il Path delle Request e i metodi di una classe Java b. l injection dei parametri della request nelle variabili dei metodi c. marshalling e unmarshalling in JSON INTERROGAZIONE WEB SERVICE ESTERNI TS1A deve interrogare diversi servizi esterni, esposti in diversi formati. La nostra scelta cade sulle tecnologie seguenti: a. per interrogare di web service che espongono un WSDL, utilizziamo JAX-WS, come specificato nella documentazione J2EE 6: Java API for XML Web Services (JAX-WS) is a technology for building web services and clients that communicate using XML. JAX-WS allows developers to write message-oriented as well as Remote Procedure Call-oriented (RPC-oriented) web services. ( The Java EE 6Tutorial, pagina 341) Maven espone una funzionalità di generazione di un Web Services client di tipo Jax-Ws a partire da un file wsdl. La funzionalità è fornita dal plugin JAX-WS Maven Plugin.

7 b. per interrogare un servizio su http (REST con formato di scambio XML o JSON), utilizziamo le librerie org.apache.httpcomponents.httpclient. Per effettuare il marhalling/unmarshalling con l XML utilizziamo Xstream, una libreria facilmente configurabile. Per ora non abbiamo dovuto interfacciarci con servizi che espongono un formato JSON. PERSISTENZA La base dati è stata realizzata con la libreria HsqlDb. Il db viene generato all avvio dell applicazione. Lo stile SQL utilizzato è quello Oracle (ad es, sono state utilizzate delle Sequence per generare gli id delle tabelle). La scelta di HsqlDb è stata fatta per semplicità e velocità di sviluppo, ma per un ambiente di produzione sarà preferibile migrare su un dbms con maggiori strumenti di monitoraggio (ad esempio Oracle). Se l applicazione dovesse poi supportare un carico eccessivo, si potrebbe prendere in considerazione la denormalizzazione della base dati e l adozione di un db non relazionale (Cassandra? Couch Db?) che sembra garantire una scalabilità maggiore. L utilizzo di un db relazionale ci ha permesso comunque una maggiore facilità di modellazione dei dati. La persistenza all interno dell applicazione è stata realizzata tramite MyBatis. Questa libreria supporta molto bene l implementazione del pattern DAO e permette un ottima pulizia del codice. DEPENDENCY INJECTION Google ha sviluppato una libreria molto efficiente per realizzare la dependency injection. Guice viene configurato all avvio dell applicazione e costruisce il grafo delle dipendenze tra le classi; viene inoltre configurato il binding tra interfacce e implementazioni dell applicazione. Guice ha delle librerie di integrazione con Jersey che permettono l Injection delle dipendenze nelle classi gestite da Jersey. Guice ha anche una libreria di integrazione con MyBatis, che permette di iniettare i Dao di MyBatis nelle altre classi dell applicazione; inoltre abilita il supporto delle transazioni tramite l ELABORAZIONE DATI GEOMETRICI Per eseguire alcuni calcoli sul posizionamento relativo di punti e poligoni è stata utilizzata la libreria JTS.

8 ARCHITETTURA DELL APPLICAZIONE L applicazione TS1A è strutturata internamente in layers ben definiti, separati da interfacce. Poiché si tratta di un applicazione a servizi, non abbiamo chiamato Presentation Layer o User Interface il Layer che genera la risposta; abbiamo preferito parlare di Web Controllers. La struttura delle cartelle del progetto rispecchia lo standard utilizzato da Maven. src/main/java src/main/resources src/main/webapp src/test/java src/test/resources sorgenti Java file di properties e di configurazione file html, jsp, javascript sorgenti per i test file di properties e di configurazione per i test Di seguito sono elencati i diversi layer applicativi. DATA ACCESS LAYER Il livello di accesso ai dati è sviluppato secondo il pattern DAO DTO. I DAO (data access objects) espongono i metodi per l accesso a db e restituiscono i risultati delle interrogazioni in oggetti fortemente tipizzati (DTO, data transfer objects). L utilizzo di Mybatis ha permesso di non implementare le interfacce dei DAO, l implementazione viene generata a runtime dalle librerie di Mybatis. Inoltre, le interfacce e i file xml necessari sono stati generati tramite un generatore di codice realizzato da noi, che ha preso come input il DDL della nostra base dati. BUSINESS LOGIC LAYER Il livello di Business Logic è definito tramite le interfacce del package it.jpbworks.ts.service. Queste interfacce sono implementate dalle classi del package it.jpbworks.ts.service.impl. L unica classe che abbia accesso ai DAO è PersistenceService. Questa classe è istanziata per Dependency Injection da Guice, come Singleton. I Dao sono a loro volta istanziati come Singleton da Guice, tramite Dependency Injection. Le altre classi di business logic usano PersistenceService per accedere al DB.

9 WEB CONTROLLERS Le classi sotto il package it.jpbworks.ts.controller hanno il compito di ricevere tutte le richieste HTTP (in formato JSON o con parametri in query string), chiamare il servizio di business corrispondente e restituire in formato JSON la risposta. La lettura dei parametri in request viene eseguita tramite dependency injection e tramite le annotazioni di Javax.ws.rs. Le istanze delle classi di Business Logic sono iniettate tramite Guice. HELPERS E stata utilizzata una classe con metodi statici per l implementazione della creazione dei Gameboard secondo dei pattern geometrici. LISTENERS All avvio dell applicazione, è prevista l esecuzione delle operazioni contenute in un ServletContextListener. Le operazioni effettuate all avvio sono le seguenti: a. creazione del db tramite uno script DDL b. configurazione dell Injector di Guice c. creazione della griglia di campionamento delle Features d. creazione di un tabellone di esempio e. creazione dei dati di esempio delle Features CLASSI PER IL MARSHALLING/UNMARSHALLING La creazione del Json è mediata dalle classi contenute in it.jpbworks.ts.resource. Queste classi contengono esclusivamente i dati e le annotazioni per il binding tra gli attributi della classe e gli oggetti JSON. E stato scelto di creare una classe base per tutte le risposte, contenente le informazioni sullo stato applicativo (ad es: { codice : 200 ; descrizione : OK }). Tutte le classi usate per generare le risposte estendono questa e contengono quindi un codice e una descrizione dello stato applicativo. ECCEZIONI E stato creato un package per alcune eccezioni specifiche di questa applicazione.

10 FILE HTML E JS E stata realizzata una pagina di test, per verificare facilmente il funzionamento dei servizi e il formato dei dati scambiati. E stata creata una pagina html con una applicazione javascript che utilizza i servizi dell applicazione TS1A e si integra con i servizi esposti da Google Maps. Vedi anche l ultimo paragrafo (Manuale di installazione e uso)

11 SCHEMA E DOCUMENTAZIONE DELLA BASE DATI. La base dati risponde alle esigenze del dominio applicativo, che è la gestione di dati statistici legati a coordinate geografiche, per offrire un servizio a diversi tipi di giochi geolocalizzati. Gli utenti del sistema possono configurare il sistema per aggregare i dati statistici su un tabellone di gioco. Infine, gli utenti possono utilizzare il tabellone per giocare. La figura seguente mostra lo schema fisico del db. Come si può notare, il sistema è stato suddiviso in due grossi sottosistemi: 1. La parte superiore rappresenta i dati necessari alla creazione e alla gestione di una partita. 2. La parte inferiore rappresenta la modellazione delle caselle e dei punti dei tabelloni di gioco (tabelle Hole, Polygon, PolygonsPoints, Point) e di una griglia di campionamento delle statistiche del territorio (tabelle GridPoints, GridValues, Features, HoleGridPoints). Figura 1. Schema generale del DB

12 Nelle pagine seguenti, lo schema è spiegato in dettaglio, secondo la divisione in diversi sottosistemi che permettono l implementazione di diverse funzionalità. SOTTOSISTEMA USER Uno User rappresenta un account utente sull applicazione TS1A. Ogni User può creare uno o più Gameboard e può giocare una o più partite. Per ogni partita, lo User dovrà creare un proprio Player e associarlo a un tabellone di gioco Gameboard). Figura 2. Sottosistema User SOTTOSISTEMA GAMEBOARD Un gameboard rappresenta un tabellone di gioco relativo ad un unica partita. Un gameboard è formato dall aggregazione di caselle di gioco (GameboardHoles). Ogni casella di gioco (GameboardHole) è associata ad una sola casella fisica (Hole). La casella fisica (Hole) può essere condivisa tra più tabelloni di gioco. Ogni casella fisica può essere costituita da uno o più poligoni (Polygon). Si pensi ad esempio all Italia, che è costituita dalla penisola, da Sicilia e Sardegna; la casella Italia sarà costituita quindi da tre poligoni. Per i tabelloni più semplici, ogni casella (Hole) sarà costituita da un solo poligono (Polygon). Ogni poligono è formato da un insieme ordinato di punti. I punti (Points) sono associati ai poligoni tramite la tabella PolygonsPoints. I punti rappresentano coordinate geografiche, e sono condivisi tra i diversi poligoni.

13 Figura 3. Sottosistema Gameboard SOTTOSISTEMA GAMEBOARDFEATURES Le features rappresentano l elenco dei tipi di dati geolocalizzati disponibili. Da questi dati reali, è possibile calcolare il valore delle caselle del tabellone sulla mappa. Le features utilizzate da un gameboard sono elencate nella tabella GameboardsFeatures. L associazione delle Features al Gameboard è un operazione contestuale alla creazione del nuovo Gameboard. Figura 4. Sottosistema GameboardFeatures

14 SOTTOSISTEMA GRID I GridPoints sono un insieme di coordinate sulle quali sarà campionato il valore delle features. La tabella GridValues contiene i valori delle diverse Features per ogni punto della griglia di campionamento. La tabella HolesGridPoints contiene l elenco dei punti di campionamento contenuti in una casella fisica (Hole). Tramite questo dato, viene calcolato il valore aggregato di ogni feature di ogni casella. Questo valore è contenuto nella GameboardHoleFeatures. Figura 5. Sottosistema Grid SOTTOSISTEMA FLAG Una Flag (bandierina) rappresenta un qualsiasi elemento del gioco, da posizionare e visualizzare sulla mappa. La Flag può appartenere ad un giocatore e / o a una casella (GameboardHole). Ogni Flag può essere di tipo diverso (FlagType): in questo modo è possibile differenziare la grafica e la logica di utilizzo delle Flags. Le operazioni di creazione, spostamento, assegnamento delle Flags vengono effettuate all inizio della partita e a partita in corso, e rappresentano un astrazione di molti tipi di gioco (ad es: nel gioco Risiko ogni flag potrebbe rappresentare un carro armato; in Monopoli potrebbe rappresentare il segnalino del giocatore o le costruzioni; ecc...).

15 Figura 6. Sottosistema Flag MANUALE D INSTALLAZIONE E USO Figura 7. Schema di deploy Requisiti di installazione per la demo: JDK 6 Tomcat 6 Google Chrome (preferibilmente) o Firefox

16 L installazione sul server viene effettuata copiando il file TS1A.war nella cartella webapps, all interno della cartella di installazione di Tomcat. Al termine della copia, effettuare lo start di Tomcat (l avvio di Tomcat dipende dal tipo di installazione di Tomcat utilizzato, vedi anche la documentazione su Se necessario, aumentare il timeout di avvio del Tomcat (l applicazione impiega quasi un minuto per avviarsi). Per navigare sulla pagina welcome dell applicazione, se il tomcat è installato con le impostazioni di default, è sufficiente aprire il browser sulla pagina localhost:8080/ts1a/. La pagina di welcome presenta i link verso la pagina di test, la mappa e la documentazione. Figura 8. Pagina Welcome E necessario utilizzare la pagina di test per creare il primo tabellone, successivamente è possibile visualizzarlo nella mappa.

17 Figura 9. Pagina di test dei servizi Cliccando sulla mappa, è possibile visualizzare informazioni sulle caselle, sulle Flags e sui punti di campionameno delle features. La griglia dei punti di campionamento viene visualizzata se si clicca sul pulsante Get samples grid.

18 Figura 10. Screenshot della pagina di prova dell'applicazione Figura 11. Screenshot della pagina di prova dell'applicazione