Enabling Real-time Simulation Updates with ICEUpdater

(Please note that the ICEUpdater library and this article are currently under development)

ICEUpdater is a library written in C++ which enables users of ICE to transmit real-time updates of an ongoing simulation to the ICECore and monitor these updates via the ICE Client. By integrating the library into their simulation codes, ICE users can utilize the ICEUpdater's API to transmit custom text messages, monitor convergence and progress status and be notified when files are created, modified and deleted. This article details how to build, test, package and utilize the ICEUpdater library. It assumes that all of the steps listed in the Getting ICE wiki article have been completed successfully. These steps include downloading all of the ICE source from the ICE Repository.

Building ICEUpdater

In order to build the ICEUpdater, your system must:

• Have a C++ compiler available
• Be able to resolve the following dependencies: cURL, Boost 1.4, and CMake 2.8
• In addition, the ICEUpdater tests require:
  • QtTest
  • A web server equipped with PHP 5.2 or greater.

ICEUpdater uses the CMake build system to compile and install a static library, a shared library and the header files to a local directory. The CMake system also sets up the ICEUpdater tests, generates the ICEUpdater API documentation, and uses CPack to create binary distributions. The first step in building ICEUpdater is to execute the cmake_build_script shell script found in the top level directory in gov.ornl.ice.iceupdater. You may wish to modify the INSTALL_PREFIX path variable prior to executing this script. The ICEUpdater libraries and header files will be installed in the lib and include subdirectories of this path. Its value is set to your home directory by default. When you execute the script, a new directory gov.ornl.ice.iceupdater.build will be created alongside the gov.ornl.ice.iceupdater directory. Although an Eclipse environment is not required to build the ICEUpdater and execute its tests, this script will generate an Eclipse project in gov.ornl.ice.iceupdater.build.

To import this project, open Eclipse and select File > Import > General > Existing Projects into Workspace then choose the gov.ornl.ice.iceupdater.build directory.

In order to compile the ICEUpdater library from command line, simply change directory to the gov.ornl.ice.iceupdater.build directory and execute the command make all

From Eclipse, you must first import the gov.ornl.ice.iceupdater.build project into your workspace, as instructed earlier in this section. Then open the Make Target view by going to Window > Show View > Other and selecting Make > Make Target. From the Make Target view, open the gov.ornl.ice.iceupdater.build tree node and double-click on all target.

Installing the ICEUpdater Libraries and Headers

ICEUpdater can be installed locally as a static library or a shared library accompanied by several header files. From command line, simply change directory to the gov.ornl.ice.iceupdater.build directory and execute the command make install

From Eclipse, you must first import the gov.ornl.ice.iceupdater.build project into your workspace as instructed in the "Building ICEUpdater" section of this article. Then open the Make Target view by going to Window > Show View > Other and selecting Make > Make Target. From the Make Target view, open the gov.ornl.ice.iceupdater.build tree node and double-click on install target. This command will install both libraries in the lib subdirectory and the header files in the include subdirectory of the path assigned to INSTALL_PREFIX in the cmake_build_script file. Please see the "Building ICEUpdater" section of this article for more details concerning the INSTALL_PREFIX variable.

Using ICEUpdater to Post Simulation Updates

The ICEUpdater requires a properly formatted niceupdater.properties file as input. This properties file is in the Java properties format as a set of 3 <name>=<value> pairs separated by a new line character. The properties are:

• item_id - provides the item id for the simulation's plug-in
• client_key - provides a unique 40 character alpha-numeric session value
• url - provides the url of the running ICECore instance used to accept transmissions from the ICEUpdater.

An example of this file is located in the top level directory of the project. In most instances, this file will be automatically generated by the ICECore and written to the same directory as the executable. In this case, the ICEUpdater's nullary constructor should be used. In some instances, a custom properties file may be required. For this case, the parameterized constructor should be used. This constructor expects an IStream object containing the contents of the custom properties file. When executing the ICEUpdater's tests, set the value of url to point to the location of the ICEUpdaterTester.php file.

For more information on ICEUpdater's testing regime, please see the "Configuring and Executing the ICEUpdater Tests" section of this article. Using the ICEUpdater API in your simulation code is very straight forward. Simply create a new ICEUpdater instance using one of the constructors and call the start() function to begin transmitting your posts every 1000 milliseconds. When you are finished transmitting posts to the ICECore, call the stop() function. As previously mentioned, you can transmit custom plain text messages, progress and convergence status, and messages detailing the creation, modification and deletion of files. Submitted text messages and file paths are limited to 256 characters and will be truncated beyond that limit. The values of progress and convergence must be between 0 and 100. Any submitted progress and convergence values below 0 will be mapped to 0 and any values above 100 will be mapped to 100. The table below lists ICEUpdater's functions and their purpose.

Function	Purpose
postFileCreated(string path)	Transmits a post indicating the creation of the file located at path.
postFileDeleted(string path)	Transmits a post indicating the deletion of the file located at path.
postFileModified(string path)	Transmits a post indicating the modification of the file located at path.
postMessage(string message)	Transmits a post containing a plain text message.
updateConvergence(int status)	Transmits a post containing the convergence status of the user simulation.
updateProgress(int status)	Transmits a post containing the progress status of the user simulation.

Configuring and Executing the ICEUpdater Tests

In order to setup and execute the ICEUpdater tests, you must have read and write access to a directory on a machine that is accessible over HTTP or HTTPS, with PHP installed. You must copy three files to this directory:

• SampleText.txt
• PostTester.php
• ICEUpdaterTester.php

You can find all of these files in the gov.ornl.ice.iceupdater/tests directory. The ICEUpdater tests also require a properties file called iceupdatertests.properties. This properties file is in the Java properties format as a set of 3 <name>=<value> pairs separated by a new line character. The properties are:

• url_path - the path to the directory where you copied the SampleText.txt, PostTester.php, and ICEUpdaterTester.php files.
• max_number_of_posts - The checkPostUpdating1() and checkPostUpdating2() tests in the ICEUpdaterTester class selects a random number of posts between 1 and the max_number_of_posts value.
• max_post_time_interval - The amount of time between each of these random number of posts is another random number between 100 and max_post_time_interval milliseconds.
• The type of each post is randomly selected using a uniform distribution. In addition, you will have to configure the the url parameter listed in the iceupdater.properties file, located in the same directory, to point to the location of the ICEUpdaterTester.php file.

Please see the "Using NiCEUpdater to Post Simulation Updates" section in this article for more details.

After the files have been copied and the iceupdatertests.properties configured, you can execute the tests.

• From the command line, change directory to the gov.ornl.ice.iceupdater.build directory
• Execute the command make test
• From Eclipse, import the gov.ornl.nice.niceupdater.build project into your workspace as instructed in the "Building ICEUpdater section".
• Open the Make Target view by going to Window > Show View > Other and selecting Make > Make Target.
• From the Make Target view, open the gov.ornl.ice.iceupdater.build tree node and double-click on the test target.

Since the ICEUpdaterTester tests execute a random number of transmissions over a randomly selected time frame, the amount of time required to complete the tests will vary according to the values you inserted in the iceupdatertests.properties file. Besides ICEUpdaterTester, the PostTester, and LibcurlUtilsTester classes perform tests as well.

After successfully executing the ICEUpdaterTester tests, the output of the tests will be available in the url_path directory on the remote machine. ICEUpdaterTester.txt contains the <name=value> pairs transmitted to ICEUpdaterTester.php, and ICEUpdaterTester.json contains the raw JSON-formatted output that was parsed to create the ICEUpdaterTester.txt file.