README.txt

GETTING STARTED

GIT

Multi-Game uses Git for version control. If you are not familiar with Git, you can 
learn about how to use it (after downloading a distribution) with the following
tutorial on GitHub:

http://try.github.com/levels/1/challenges/1

The top-level project (MultiGame) and all public submodules are stored on GitHub: 

https://github.com/ecosur-sistemas-complejos/MultiGame

All releases are tagged and two main branches exist: Master and Development. The Master
branch always contains the latest "released" code, while development contains the working
branch.


SUBMODULES

Multi-Game uses git submodules to reference the dependent projects that make it work.  
We have split off the project into four separate aspects: Deploy, Engine, Games and
Research.  Each submodule contains it's entire history from the onset of the project, with
all history prior to the division into submodules held in the top-level project.

To get started, simply do the following from the top of this project (MultiGame) after
your successful clone:

    $git submodule init
    $git submodule update

Then checkout the development branch in the module you want and you're ready to contribute!

    $cd "SUB_MODULE"
    $git checkout -B development

If you're using git-flow, you could then start work on "featureName" with the following:

    $git flow init
    $git flow feature start "featureName"

NOTE: Be sure to use "git submodule update" when moving in-between branches at the top-level.


JBOSS AS6 CONFIGURATION

1. MySQL-DS.xml and Persistence.xml.

   Hibernate is the default database provider for JBoss BUT Multi-Game is configured to run
   with MySQL.

   For convenience, we have placed a sample mysql-ds.xml file in the resources of the
   EcosurJPA module, which can be used with a properly configured MySQL server
   
   NOTE:  Users may also use the default hibernate dialect to work with the default JBoss
   database (hsql) by modifying the marked and commented areas of the persistence.xml file
   and commenting out the mysql specific locations.

2. Please add the following to the "login-config.xml" file located in the "conf" directory
   fo the domain you are deploying to. In our case, this is the "default" domain:

   <!-- Custom JDBC Security Module for MultiGame -->
   <application-policy name="multigame">
      <authentication>
          <login-module code="org.jboss.security.auth.spi.DatabaseServerLoginModule" flag="required">
              <module-option name="dsJndiName">java:/MySQLDS</module-option>
              <module-option name="principalsQuery">select password from user where username=?</module-option>
              <module-option name="rolesQuery">select name, 'Roles' from role where username=?</module-option>
              <module-option name="hashAlgorithm">MD5</module-option>
              <module-option name="hashEncoding">HEX</module-option>
          </login-module>
      </authentication>
   </application-policy>

   Users can be added to the database by means of the provided registration page, or with a
   SQL insert statement against MySQL using the MD5() function:

   >insert into user (id, name, password) values ( 1, 'test', md5('test'));

   Please use ids that make sense for your user schema.

3. Topics and ConnectionFactory. The file "hornetq-jms.xml" contains the definitions of the
   two Topics that the game subscribes to. This file is included in the WAR file generated by
   this project and included in the deployable EAR.


MYSQL DATABASE CONFIGURATION

   In order to use MySQL with MultiGame you will need to do the following on the server
   where your application server is installed.

   1. Install MySQL.
   2. Connect to local MySQL server as root, and create the database "multigame".
   3. Create and Grant all rights to user 'mg'@'localhost' on multigame:
            grant all on multigame.* to 'mg'@'localhost' identified by 'secret'
   4. Add the mysql-connector jar to the default lib directory. For example, on JBoss:
            mv mysql-connector-java-5.1.17-bin.jar $JBOSS_HOME/server/default/lib
   5. Start the server and deploy the ear generated by the EcosurEAR project. Note: the 
      tables will be created by JPA on deploy, wiping out any previous data that may have 
      been in the database.

   Note:  If you change the username or password in step 3, please update the
      deployed mysql-ds.xml and restart the JBoss server.


GLASSFISH 3.1 CONFIGURATION

NOTE: Glassfish is no longer officially supported, but the following instructions
have worked on previous releases.


The following configuration changes must be made on the Glassfish server to which
the EAR file is being deployed:

1.  Persistence.xml.

    Hibernate must be configured as the provider in the persistence.xml file.
    In addition, the correct datasource name must be specified. Please make changes to
    the persistence.xml file to reflect your environment by modifying the marked
    and commented sections.

2.  A JMS connection factory must be created with the following details:
    a) "Name" set to "MultiGameConnectionFactory"
    b) "Resource Type" set to "java.jmx.TopicConnectionFactory"
    b) "Transaction Support" set to "XATransaction"

3.  A new JMS "destination resource" must be created with the following details:
    a) "JNDI Name" set to "MultiGame"
    b) "Physical Destination Name" set to "MultiGame"
    c) "Resource Type" set to "javax.jms.Topic"
    d) All other fields may remain in default state.

4.  A new JMS "destination resource" must be created with the following details:
    a) "JNDI Name" set to "Lobby"
    b) "Physical Destination Name" set to "Lobby"
    c) "Resource Type" set to "javax.jms.Topic"
    d) All other fields may remain in default state.

5.  Security

    A.  The "Default Principal to role mapping" option must be checked on the security
        configuration screen.
    B.  A JMS user must be created in the file-realm for secure messaging.
        1.  Click on the "file" security realm.
        2.  Click on manage existing users.
        3.  Add the user "j2ee" with any password (authentication is not checked
            by password for a MessageBean.
    C.  At least one user must be created in the "file-realm" of JAAS for logging in
        and playing the games.
        1.  Click on the "file" security realm.
        2.  Click on manage existing users.
        3.  Add a user with the group MultiGame, the username you want and the password.

    Note:  security can be modified within the build to work with any other JAAS
    components available on the Server.  The "j2ee" user is required for the
    message bean to be able to receive messages and message other secured EJB
    components.

6.  Hibernate

    We use two non-jpa specific Hibernate annotations in the internal ordering of several
    entity collections, and therefore, must use hibernate as a persistence provider.
    To deploy on Glassfish, you will need to install and enable it via the "Update Tool"
    provided on the bottom-left hand side of the Admin screen.  Select and check "hibernate"
    from the available frameworks and click install.

    You will need to restart the server to make hibernate available for the application.

6.  Database.

    **** IMPORTANT ****
    Before deployment, the local Glassfish Derby database must be up and running:

    %> asadmin start-database

    if you use the "_default" Glassfish Derby datasource.


FLEX CONFIGURATION

BLAZEDS

Two jar files from the "blazeds-3.3 turnkey distribution" are required to be placed in an accessible
"lib" directory on the JBoss server (this has not been tested on Glassfish). These files are
"flex-tomcat-common.jar" and "flex-tomcat-server.jar". They are used by BLAZEDS to perform remote
authentication for the AdobeAIR/mobile client.

On my development machine, I place both files into the <<JBOSS_HOME>>/server/default/lib folder.

As the 2.1 project evolves, these files will be placed/located into a suitable maven repository
for downstream use.

Please see the following link for context:

    http://livedocs.adobe.com/blazeds/1/blazeds_devguide/help.html?content=services_security_2.html

And the following link to download the "turnkey" install:

    http://opensource.adobe.com/wiki/display/blazeds/download+blazeds+3


FLEXMOJOS INTERNATIONALIZATION CONFIGURATION

 This project is internationalized in English and Spanish, so it requires access to
 the Spanish flex framework locale files.  

 Unfortunately flex mojos requires localized versions of the flashplayer core libraries. 
 These must be imported from the us_US bundle. (Please replace "${flex-version}" below
 with the current version as defined in the games-module POM.)

 mvn install:install-file -DgroupId=com.adobe.flex.framework -DartifactId=flash-integration
     -Dversion=${flex-version} -Dclassifier=es_ES -Dpackaging=rb.swc
     -Dfile=/path/to/flex-sdk/frameworks/locale/en_US/flash-integration_rb.swc

 mvn install:install-file -DgroupId=com.adobe.flex.framework -DartifactId=playerglobal
    -Dversion=${flex-version} -Dclassifier=es_ES -Dpackaging=rb.swc
    -Dfile=/path/to/flex-sdk/frameworks/locale/en_US/playerglobal_rb.swc

 For more information:
    http://groups.google.com/group/flex-mojos/browse_thread/thread/5b5ff62290d1cb56/d7013abdae604828


FLEX MOBILE THEME

The "mobile" theme is available with the Flex SDK, under the frameworks/mobile path. Please install the correct
version with the install plugin.  The following works well (please replace {flex-version} with the current
version):

mvn install:install-file -Dfile=mobile.swc -DgroupId=com.adobe.flex.framework -DartifactId=mobile
    -Dpackaging=swc -Dversion={flex-version}  -DgeneratePom=true


FLEX UNIT 4

  We are currently using FlexUnit 4 for the Flex based part of our unit tests. In order
  to run these tests (and have the build successfully complete), you will need the flash
  player on your build path, referenced as "flashplayer". There is an excellent write-up on
  what to do if you have any troubles, especially if you're using OSX, in the following blog
  post:

  http://seanp33.wordpress.com/2010/09/16/flexmojos-mac-osx-and-the-stand-alone-flash-player-debugger/


**  All other dependencies are managed by means of Maven and repositories included in 
    the top-level pom.xml. **