(IEEE-1516e) The Portico Java Example Federate This file contains information on the IEEE-1516e Portico Java example federate and how to compile and run it. NOTE: Knowledge of the HLA is assumed, but if you are just getting started out, there are some resources contained at the end of this README that you may find helpful. Table of Contents: 1. Getting Started 2. Supported Platforms 3. Compiling and Running the Example Federate 4. Writing your own Federate (with Resources) ------------------------------------------------------------------------------- 1. Getting Started ------------------------------------------------------------------------------- This example application provides the basic template code for a very simple HLA federate. It is not intended to be an impression display of what you can do with the HLA, but rather just a display of how to use the most common parts of the HLA API. The example federate consists of three main files: * src/ieee1516e/ExampleFederate.java // the bulk of the federate code * src/ieee1516e/ExampleFederateAmbassador.java // example Federate Ambassador (callbacks) The bulk of the federate code is contained inside the Example13Federate class. This class pretty basic structure and flow designed to show you, in very simple terms, code for performing common HLA actions. The main workflow of the federate is as follows: a. Create the RTIambassador b. Create the Federation (skip if one exists) c. Join the Federation d. Initialize all handles e. Announce a Synchronization Point f. Wait for the user to press Enter g. Achieve the Synchronization Point h. Enable federate's time settings i. Publish and Subscribe j. Register an Object Instance k. Loop 20 times, doing the following each step: * Update the object's attributes (timestampped and receive order) * Send an Interaction (timestampped and receive order) * Request a time advance of 1.0 l. Delete the object instance m. Resign from the Federation n. Destroy the Federation (if possible) The actual design of the federate is very basic. It just registers an object and loops around 20 times, updating its attributes, sending an interaction and moving time forward (this is actually optional). In addition to publishing information, the federate also subscribes to the same data. When it is run in the same federation as another example federate, any information it receives it will print to stdout. ------------------------------------------------------------------------------- 2. Supported Platforms ------------------------------------------------------------------------------- The Portico Java example federate is officially supported on: * Java JDK 7 (version 7u17+) * Ubuntu 12.04 LTS for 32 and 64-bit * Mac OS X Mountain Lion (10.8)+ for 64-bit * Windows 7 32/64-bit --- JDK Requirements --- Please note that you need to have a JDK installed on your system and have the environment variable JAVA_HOME set to point to it in order to compile the example federates. Portico ships with a JRE, but this only supports running Java applications, not compiling them. --- JDK Version --- Portico has been built against Java 7 and requires a Java 7 JDK to compile federates for. If you are deploying against a Java 6 environment The federate may work happily with earlier versions of Java, but these are not officially supported, and if you are targeting a Java v6 platform, may require a recompile of the RTI from source. ------------------------------------------------------------------------------- 3. Compiling and Running the Example Federate ------------------------------------------------------------------------------- To help with the process of compilng and running the federate, a number of helper scripts have been provided: * windows.bat // Compile and run on Windows * linux.sh // Compile and run on Ubuntu 12.04 LTS * macos.sh // Compile and run on Mac OS X 10.8+ Each of the scripts takes the same basic commands: * compile // Compile the example federate * execute // Run the example federate * clean // Remove all generated executables Running on Windows ------------------- To run on Windows, you must have an appropriate JDK installed and have the environment variable JAVA_HOME set up to point to it. To use the helper you open a command prompt, change into the example directory and run the batch file from there: * [Open Command Prompt] * cd %RTI_HOME%\examples\java\ieee1516e * windows compile * windows execute Running on Unbuntu 12.04 LTS ----------------------------- To run on Ubuntu, ensure you an appropriate JDK installed and have the environment variable JAVA_HOME set up to point at it. From a prompt, change into the directory, compile and run using the script: * cd $RTI_HOME/examples/java/ieee1516e * ./linux.sh compile * ./linux.sh execute Running on Mac OS X 10.8+ -------------------------- To run on Mac OS X, ensure you an appropriate JDK installed and have the environment variable JAVA_HOME set up to point at it. From a prompt, change into the directory, compile and run using the script: * cd $RTI_HOME/examples/java/ieee1516e * ./macos.sh compile * ./macos.sh execute Running more than one Federate ------------------------------- To watch more than one federate interact, you can issue a second command to the "execute" for each of the helper scripts. This will be the federate name: * Start the first example federate (don't hit enter when it says so) * Start a second example federate * windows execute secondFederate * ./linux.sh execute secondFederate * ./macos.sh execute secondFederate * Wait until the second federate is ready, then hit enter in both screens. Each example federate will wait until you hit enter to tell the RTI that the synchronization point it uses has been achieved. This way, you have time for a number of other federates to start and enter the federation. ------------------------------------------------------------------------------- 4. Writing Your Own Federate (with Resources) ------------------------------------------------------------------------------- Now that you have some grounding, you can start to write your own federates. To figure out which commands you need to compile with and properly link to the RTI, see the various execution helper scripts. You can also consult the documentation online at http://www.porticoproject.org. Visual Studio Compiler Support ------------------------------- If you want to use a different version of the Visual Studio compiler, you can. You should try to match the version of the RTI libraries with the version of Visual Studio you use. Libraries for VC10 (2010), VC9 (2008) and VC8 (2005) are provided. See the appropriate subdirectories of [RTI_HOME]\bin and lib. Resources to get you started ----------------------------- If you are learning the HLA for the first time, there are a number of resources available: * Ask your question on the Portico forums at http://forums.porticoproject.org * Pitch Technologies (Commercial RTI vendor) has produced an "HLA Tutorial" that can be freely downloaded: http://www.pitch.se/hlatutorial