• General
  • Installation
  • Protocol
  • Server Data
• Tutorials
• JavaDoc (API)

Contents

Since release 0.2.3 of JOGRE, Jogre supports persistent data stored by the server. This data includes user information, such as authentication information. This data also holds user information per game, such as user rating, number of wins, loses, etc. Also, when a game ends, information on individual games is stored (e.g. start time, end time, game results, etc). Finally, a real-time snapshot of each game is stored, describing the number of players and tables currently playing. This enables other applications (e.g. web server) to make use of this information.

In the Jogre server application (jogre/server), all calls to the persistent data must go through an interface. This interface is IServerData. There are 3 implementations of this interface. These are:

1. ServerDataXML - Stores persistent data as XML. No setup necessary.
2. ServerDataDB - Stores persistent data in a database. Setup is necessary.
3. ServerDataJogreDotOrg - Sends / Receives information from a master server on jogre.org (not developed yet).

To control which implementation is used by the Jogre Server this can be easily set in the jogre/server/server.xml configuration file. This is the @server_data attribute which can be "xml", "database" or "jogre.org". Each of these implementations will be discussed in the following sections.

The default persistent data for the Jogre is XML and is the easiest to use. No setup is required apart from manually adding users. To use XML for storage ensure the current attribute of <server_data> in jogre/server/server.xml is set to "xml":

<server_data current="xml"> ...

To ensure that the server is using XML the following should appear in the console when the server loads:

Persistent Data: xml

The XML files are stored in the server under the following directory:

jogre/server/data/xml

There are three files in total which are stored in this directory. These are:

1. games.xml - Stores details on each game which has been played.
2. snapshot.xml - Stores a snapshot of the number of users/tables on each game.
3. users.xml - Users file which contains usernames, password and game summaries.

As mentioned earlier, minimal setup is required with XML. To reset the files, simply delete snapshot.xml and games.xml and the server will generate these files again. The only file which requires manual configuration is the users.xml file. To add a user simply add an empty <user username="A" password="B"> element under <users> where A and B are a unique username and a password. For example, to add "joe" as a user insert the following in users.xml:

<?xml version="1.0" encoding="UTF-8" ?>
<users>
    <user username="bob" password="bob123" />
    <user username="john" password="john123" />
    <user username="joe" password="joe123" />
</users>

XML is good for people using JOGRE as a small scale system. If you wish to use JOGRE on a much larger scale and require more power there is the option to store data on a database. This is explained in the next section.

The database option in Jogre is more powerful than that XML option but harder to setup. To use a database to store data ensure the current attribute of <server_data> in jogre/server/server.xml is set to "database":

<server_data current="database"> ...

There is an additional database element which contains which should be set but we will explain this later.

The following is the current database schema for the JOGRE server database. These HTML tables correspond to actual database tables. Primary keys are denoted in yellow:

1) TABLE: users
username	char (20)	Username of user.
password	char (20)	Password of user.
security_question	integer	Security question to indentify user.
security_answer	char (50)	Security answer to indentify user.
year_of_birth	char (4)	Year user was born.
email	char (100)	Email address of user.
receive_newsletter	char (1)	Boolean to denote if user receives quarterly newsletter.

2) TABLE: game_summary
game_key	char (20)	Game Key (e.g. "chess")
username	char (20)	Username
rating	integer	Rating of user (ELO)
wins	integer	Number of user wins
loses	integer	Number of user loses
draws	integer	Number of user draws
streak	integer	User streak

3) TABLE: snapshots
game_key	char (20)	Game Id (e.g. "chess")
num_of_users	integer	Number of users playing this game.
num_of_tables	integer	Number of tables playing this game.

4) TABLE: game_info
id	integer	Generated ID key
game_key	char (20)	Game Id (e.g. "chess")
players	char (255)	List of space delimited players (e.g. "bob dave")
results	char (50)	List of space delimited results (e.g. "1 2")
start_time	datetime	Date and time game started
end_time	datetime	Date and time game ended
history	char (255)	Optional history string.
score	char (255)	Optional score string.

In theory JOGRE will work with any relational databases which support JDBC and standard SQL. So far we have tested JOGRE with HSQLDB and MySQL, both of which are explained in the following sections.

Running the server using a HSQLDB is very easy as JOGRE includes a HSQLDB database as standard. Ensure the following is in the jogre/server/server.xml configuration file:

<server_data current="database" >
    ...
    <database current="jogre_hsqldb">
        ...
        <connection id="jogre_hsqldb"
                       driver="org.hsqldb.jdbcDriver"
                       url="jdbc:hsqldb:hsql://localhost/jogre_hsqldb"
                       username="sa" password="" />
        ...
    </database>
</server>

The HSQLDB database must first of all be started. Run the following file to start it: -

\jogre\server\data\database\hsqldb\hsqldb.bat (Windows)

/jogre/server/data/database/hsqldb/hsqldb.sh (Linux)

If you restart the JOGRE Server it should recognise the HSQLDB database. If the database tables dont exist then the JOGRE server will run a load script file to create them and 4 default users. The load script is in :-

/jogre/server/data/database/create_db_hsqldb.sql

To use a MySQL database for database storage ensure that the MySQL database is installed (version 4+).

Edit the server.xml configuration file again to the following: -

<server_data current="database" >
    ...
    <database current="jogre_mysql">
        ...
        <connection id="jogre_mysql"
                       driver="com.mysql.jdbc.Driver"
                       url="jdbc:mysql://localhost/jogre_mysql"
                       username="admin" password="admin" />
        ...
    </database>
</server>

Restart the server and JOGRE will automatically run a load script to popuate and use the MySQL database.

/jogre/server/data/database/create_db_mysql.sql

This currently hasn't been implemented yet but should require minimal configuration.

This concludes the current state of the Jogre server persistent data engine. This work is still in progress so keep watching this document for updates. If you have any comments then contact its author Bob Marks.