• Release History
• Installation

Contents

• Basic Installation
• Run Server and Play Games
• Server Administrator
• Configure Server to use Database
• Deploying on Web Server (Windows Binary)
• Deploying on Web Server (Linux Binary)
• Building JOGRE From Source
• Programming JOGRE with Eclipse

The easiest way to install JOGRE is to download the binary distribution from the download page and extract it using a zip program such as winzip.

For example, if you unzip in Windows in the root of the C drive you should have a folder c:\jogre and 5 sub directories - api, games, server, util and webapp.

If you installing on Linux it is best to unzip into the /opt folder so that JOGRE is stored in /opt/jogre.

JOGRE runs "out of the box" i.e. you simply unzip the binary ZIP file and you can start a server and start playing straight away with no configuration. To do this run the following file:

\jogre\server\server.bat (Windows)

/jogre/server/server.sh (Linux)

This should show the following: -

As you can see the "Persistent Data" is set to xml. The JOGRE server stores in data in 2 forms (XML and database). The default is XML which requires no setup. Data is stored as XML files in the following folder.

\jogre\server\data\xml

JOGRE comes with 4 default users to get started in the users.xml in the xml data folder. These users are:

dave bob john sharon

... with the following passwords for each (<username>123) ...

dave123 bob123 john123 sharon123

To run a game e.g. chess run the following file: -

\jogre\games\chess\client.bat (Windows)

/jogre/games/chess/client.sh (Linux)

The chess client should appear with a logon screen. Use one of the previous usernames e.g. dave and you should be logged in something like the following: -

To play a game, load up another client and log in using a different username e.g. bob. To create a game table, click New Game on one of the clients. On the other client click the Join button to join the table. Sit down either using the Sit button or by clicking on a coloured box on the table. Once both players are seated then a game can be started by clicking the Start button. Once both players click Start the game is then in progress and the game can be played.

Games can also be played as applets, this is discussed in a later section.

Configuring the JOGRE server can be done in 1 of two ways:

1. By editing the /jogre/server/server.xml configuration file.
2. By running the JOGRE Administrator client which updates the server.xml file.

The JOGRE Administrator is a GUI client which can be launched by running the following file: -

\jogre\server\administrator.bat (Windows)

/jogre/server/server/administrator.sh (Linux)

This will load up the "JOGRE Server Aministrator" which requires a username and password, which is admin / admin by default. The Administrator client shows a real-time view of the state including any messages going in / out of the server.

To configure the server, select the menu "Server - Server Properties" item. This should bring up the following dialog: -

There are 3 sections: -

• Configuration - Admin username/password, server port, level of user logon and max users etc.
• Games - Config game hosting, players, elo rating setting and custom game tags.
• Server Data - Config data to be stored as XML/database and config database connections.

NOTE: It is recommended that you change the default admin username and/or password. Also, for the changes to take effect the JOGRE server must be restarted. Currently a server cant be restarted from the administrator.

The JOGRE Server uses XML as its default data storage. The advantages of using XML is that it requires no setup. Its disadvantages is that it lacks the same power as a dedicated database which is required to run JOGRE on a webserver.

JOGRE should support any database which has a JDBC driver and supports the following databases with minimal setup: -

http://hsqldb.org/	http://www.mysql.com/
HSQLDB is an open source database programmed entirely in Java. JOGRE comes bundled with HSQLDB so there is no need to download it.	MySQL is a very popular and powerful open source database which is fast, robust and requires minimal setup.

The easiest database to use with JOGRE is the HSQLDB database. If you require more power (e.g. deploying on webserver) then the MySQL database is recommended. Once your database is running, ensure the JOGRE server points to the correct database URL.

This is stored in the /jogre/server/server.xml configuration file which can be editted manually or by using the administrator client discussed previously.

HSQLDB

Run the following file to start the HSQLDB database up: -

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

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

An easy way to test this default HSQLDB database connection is to ensure the JOGRE server is running and load the JOGRE Administrator. Select the menu "Server - Server Properties" item and click on the "Server Data" tab.Click the "Database" tab and select "jogre_hsqldb" on the database connections list. It should have the following connection details.

• ID: jogre_hsqldb
• Driver: org.hsqldb.jdbcDriver
• URL: jdbc:hsqldb:hsql://localhost/jogre_hsqldb
• Username: sa
• Password:

To test this database connection, click on the "Test" button. A message should appear - "Database connection successful".

To set up the JOGRE database to use this connection ensure the "Current Persistent Data Type" is set to "Database". Also ensure the "Current database connection" is set to "jogre_hsqldb". Clicking "OK" updates the server.xml on the JOGRE server to the following: -

...
<server_data current="database">

    <!-- XML data source (default) -->
    <xml location="data/xml"/>

    <!-- List of database connections -->
    <database current="jogre_hsqldb">

        ...

        <!-- JOGRE HSQLDB connection -->
        <connection id="jogre_hsqldb"
                    driver="org.hsqldb.jdbcDriver"
                    url="jdbc:hsqldb:hsql://localhost/jogre_hsqldb"
                    username="sa"
                    password=""/>

    </database>

</server_data>
...                

Note: You may wish to edit the /jogre/server/server.xml yourself if you are comfortable with XML - its a matter of preference.

The first time you restart the JOGRE server it does a check to see if the database tables exist. If not the JOGRE server will run a database load script file. There are two loads scripts at present: -

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

When you restart the JOGRE server now you should have something like the following: -

MySQL

Setting up a JOGRE server using MySQL database is very similar to HSQLDB. A default entry exists in the server.xml file. Update it so looks something similar to the following: -

...
<server_data current="database">

    <!-- XML data source (default) -->
    <xml location="data/xml"/>

    <!-- List of database connections -->
    <database current="jogre_mysql">

        ...

        <!-- MySQL database connection details -->
        <connection id="jogre_mysql"
                    driver="com.mysql.jdbc.Driver"
                    url="jdbc:mysql://localhost/jogre_mysql"
                    username="admin"
                    password="admin"/>

   </database>

</server_data>
...                

If the password is different then change the server.xml file accordingly. When the JOGRE server is restarted using MySQL for the first time the create_db_mysql.sql load script will be executed.

Other JDBC Compatible Database

It is possible for a JOGRE server to work with other JDBC compatible databases such as Oracle, etc. What you will be required to do is load the tables manually using a program such as SQuirreL SQL Client or software included with the respective database. Check out the load scripts (e.g. create_db_hsqldb.sql) in the /jogre/server/data/database folder - chances are the SQL will be very similar.

You may need to put a specific database JDBC driver JAR file in the /jogre/server/lib folder (e.g. Oracle uses a jar named classes12.jar). You will also have to update the CLASSPATH in the /jogre/server/server.bat and /jogre/server/server.sh files to point to the JDBC driver.

Since Beta 0.3, JOGRE can be deployed on a webserver. Deploying on a webserver can be tricky and requires a JOGRE server saving its data to a database (see previous section).

The JOGRE web application has been tested with the following open-source webservers on windows: -

http://tomcat.apache.org	http://jetty.mortbay.com	http://www.jboss.org/jbossas/
Apache Tomcat is an implementation of the Java Servlet and JavaServer Pages technologies and is widely used.	Jetty is a light-weight web server capable of running Java web applications which itself is written 100% in Java.	JBoss Application Server is the #1 most widely used Java application server on the market and is very powerful / stable.

First of all ensure a JOGRE Server is running and using a database as its persistent database.

The JOGRE web application consists of WAR (web archive) file and a properties file(/jogre/webapp/webapp.properties). Update the properties file so it points to the same database connection that the JOGRE server is using: -

...
# Database connection
database.driver=org.hsqldb.jdbcDriver
database.url=jdbc:hsqldb:hsql://localhost/jogre_hsqldb
database.username=sa
database.password=

# JOGRE Server connection
jogre.server.host=127.0.0.1
jogre.server.port=1790
...                

The next step is to install your web server of choice and set an environment variable JOGRE_WEBAPP.

Tomcat

Download Tomcat (e.g. apache-tomcat-6.0.14.zip) and unzip it to a location of your choice (e.g. c:\tomcat). Copy the JOGRE WAR file (\jogre\webapp\jogreweb.war) to the tomcat deploy folder (i.e. c:\tomcat\webapps).

The next step is to set the JOGRE_WEBAPP environment variable which points to the location of the properties file. There are various ways to do this, my preferred choice is to search for the following line to the \tomcat\bin\catalina.bat batch file.

set JAVA_OPTS= .... 

Add the following to the end of this line (must point ot the folder of the jogreweb.properites file): -

-DJOGRE_WEBAPP="c:\jogre\webapp"

Start up Tomcat by executing the \tomcat\bin\startup.bat batch file.

Type the following into your Internet Browser: -

http://localhost:8080/jogreweb/Main.do

If everything is successful you should see something like the following on your browser:-

You should now be able to register, sign in, view games currently playing etc and load a game up in applet form.

Jetty

Jetty is a 100% pure Java server. Download, unzip it and copy the JOGRE WAR file to the Jetty deploy folder. The JOGRE_WEB environment variable can be passed in at the command prompt as follows: -

java -DJOGRE_WEBAPP="c:\jogre\webapp" -jar start.jar

JBoss

JBoss is more than just a web server, its a fully blown and rebost J2EE application server. It may be overkill for hosting JOGRE at present but if you want its power then download (e.g. jboss-4.0.4.GA.zip) and unzip it somewhere on your file system (e.g. c:\jboss). Copy the JOGRE WAR file to the Jboss deploy folder (i.e. C:\jboss\server\default\deploy).

Open the c:\jboss\bin\run.bat and search for the set JAVA_OPTS= ... line. Add the following to the end of that line (similar to Tomcat).

-DJOGRE_WEBAPP="c:\jogre\webapp"

Start the JBoss server (run the c:\jboss\bin\run.bat script). It can be accessed using a web browser using the same URL as before (i.e. http://localhost:8080/jogreweb/Main.do).

See /jogre/webapp/installing on linux.txt.

To build JOGRE from source, download the source distribution from the download page and extract it on your file system.

It is essential that you have build utility Apache ANT downloaded and installed.

JOGRE consists of many ANT build files including one for the API, server, webapp, util and one for each game. Each part of JOGRE can be built seperately although most projects (apart from the API) will depend on one or more projects (usually the API and sometimes the server).

There also exists a global build file which calls on the other build files in the correct order. To run the global build file open a command prompt, change directory to /jogre and run the following:

ant

This will build the entire JOGRE project. JOGRE is now ready to be used in much the same way as the binary download with added flexibility that code, etc can be changed if required. Complete global build list options include:

ant          Runs default "package" target in all sub projects.
ant clean    Runs "clean" target in all sub projects
ant compile  Runs "compile" target in all sub projects
ant package  Runs "package" target in all sub projects
ant deploy   Runs "deploy" target - only used in the webapp project.
ant test     Runs "test" target in all sub projects
ant report   Runs "test" target and generates global test report.
ant view     Runs "report" target displays report using web browser.
ant all      Runs "clean", "package", "test" and "report" targets in this file.

NOTE: If the ANT build fails with JUnit errors you may have to copy the junit.jar (in /jogre/api/test) jar file into the lib directory of ANT e.g. (C:/Program Files/apache-ant-1.7.0/lib).

If you wish to do some programming with JOGRE it is highly recommended you download the open source IDE Eclipse. The source distribution of JOGRE comes with Eclipse .project and .classpath files. Load up Eclipse and select the menu option ".File - Import.". From the list select ".Existing Projects into Workspace.".

Browse to the /jogre/api folder and import it into Eclipse. If the menu option "Project - Build Automatically" is selected then Eclipse should have already built the JOGRE API. Repeat the import steps for the Server, Util and Webapp projects. Finally import a game/s of your choice (e.g. JOGRE Chess).

Eclipse should look something like the following: -

You are now ready to do some JOGRE programming!

If you have any comments on this intallation guide or have other questions, then feel free to contact its author Bob Marks.