Click on the title image to go to the main page
 Main Page
 Contact Logo
JOGRE Server Persistent Data
Last Updated: 13th Nov 2008, 12:52 GMT



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 (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 "". Each of these implementations will be discussed in the following sections.

[ top ]
XML Data

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:


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" ?>
    <user username="bob" password="bob123" />
    <user username="john" password="john123" />
    <user username="joe" password="joe123" />

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.

[ top ]
Database Data

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.

[ top ]
Database Schema

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.

[ top ]

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/ (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 :-

[ top ]

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.

[ top ]
Master Server Connection

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

[ top ]

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.

[ top ]
Copyright 2004-2008, JOGRE API and JOGRE Games, by Bob Marks