Shoal Build and Test Instuctionsk

Shoal GMS Build Instructions

Included are all the steps required to obtain and build Shoal GMS sources. The prerequisites are:

Java SE JDK 6.0 or higher
Ant 1.6.5+
Subversion (svn client)
Maven 2.2.1 (or higher)(optional - only needed to build OSGI shoal-gms-api.jar and shoal-gms-impl.jar

With the above prerequisites installed and available in your system environment, create a Shoal GMS workspace:

Next, to check out the trunk source code and developer tests for Shoal :

  % svn checkout https://svn.java.net/svn/shoal~svn/trunk shoal  --username 
java.net-userid

Or to check out a branch of the workspace source code and developer tests for Shoal :

  % svn checkout 
https://svn.java.net/svn/shoal~svn/branches/SHOAL_1_1_ABSTRACTING_TRANSPORT shoal
 --username java.net.userid

After checking out the sources, cd to the shoal/gms directory and you can execute any of the following commands.

ant or ant all
to delete existing built classes and jars and to build sources and assemble jars

ant clean
to only clean the built classes and assembled jars

ant compile
to only compile sources and place built classes in the build directory

ant assemble
to only build jar from already built sources. The built jar "shoal- gms.jar" is placed in dist directory.

You can refresh your local workspace using :

% svn update .

Building and Running Shoal GMS developer tests

Work in progress

In addition to junit test for shoal, there is a semi automated testing mechanism to run developer level testing of the group management services by simulating distributed clients on a single machine. The defaults for the test execution assume a machine with sufficient resources to run 11 clients in parallel. There is a parameter to specify a smaller number of clients for a machine that does not have sufficient memory or processing power.

The test command is in shoal/gms and is called runsimulatecluster.sh. Note that the shoal-gms-test.jar is built as part of ant build. Below is the usage command to illustrate the different options for the test driver.

$ runsimulatecluster.sh -h
usage:
   single machine:
      [-h] [-t grizzly|jxta] [-bia address] [add|stop|kill|rejoin|default] [numberOfMembers(10 is default)] 
   distributed environment:
      -d <-g groupname> [-t grizzly|jxta] [add|stop|kill|rejoin|default]
 
 Examples:
     runsimulatecluster.sh
     runsimulatecluster.sh 5 -bia 129.168.1.4 rejoin
     runsimulatecluster.sh -d -g testgroup
     runsimulatecluster.sh -d -g testgroup rejoin

Test Scenarios

default- start all instances in group and then stop all instances in group
add- start all but one instance in group, wait for all instances to start, then start last instance
stop- start all instances in group, stop an instance (ensure all instances see stop) then stop group
kill- same as stop but substitute kill
rejoin- start all instances in group, kill an instance and restart quicker than gms heartbeat failure detection can detect the failure. The joined and ready notification should contain subevent Rejoin to denote that the instance restarted without ever being reported as failed. Note that the default gms heartbeat failure detection time is 8 seconds.

After running one or more test scenarios, the server log files can be found under LOGS/simulateCluster_scenarioname. The automated verification of the test scenarios is conducted by running analyzelogs.sh test-scenario-name. (there is no name for the default scenario that just start and stops the group.) The analyzelogs.sh verifies that the appropriate GMS event notifications are recorded in the saved server logs and reports if the test passed or failed.

Note that the shoal gms developer tests are not built as part of maven and only exist after running ant.

Shoal Build Instructions using Maven

cd into shoal directory and run mvn install. This will build and run the junit test for both gms and cache.

shoal/gmscache/target/shoal-cache.jar
shoal/gms/api/target/shoal-gms-api.jar
shoal/gms/impl/target/shoal-gms-impl.jar*

* - Only works with Grizzly 1.9.24 and not JXTA 2.5. JXTA 2.5 is not OSGI compatible.

Note that the shoal gms developer tests are not built as part of maven and only exist after running ant.