Federate configuration

Configuring Federates

We provide a 3-level parametrization for the Federates. This document summarizes how it should work.

Federate configuration has been implemented in a generic, extensible way so that developers can set up their own parameters/configuration for their own federates.

The configuration framework

The configuration framework can be found in the org.cpswt.config namespace. It defines classes to parse configuration files along with annotations that are used to represent configuration settings in the core and user codebase.

Annotations

FederateParameter is an annotation that should be used with every configuration parameter field in order to indicate the framework that it is an expected/used parameter. When a field is annotated with FederateParameter, you can use it on all levels (see Loading order below).

FederateParameterOptional is an extra annotation that can be used with FederateParameter. It indicates that a parameter is not mandatory and the code will take care of setting its value (i.e.: generate name if not provided).

FederateConfig

The FederateConfig is the bare minimum information that a federate must get through configuration. This includes the following fields:

• federateType
• federationId
• isLateJoiner
• lookAhead
• stepSize
• name [optional]

Extension

The config framework support that you can create your own configuration model for your custom federates.

A working example is FederateConfig -> FederationManagerConfig extension. To create your own custom federate config, simply inherit from FederateConfig and define your own public fields annotated with FederateParameter, everything else is taken care of by the config framework.

IMPORTANT: You must use flat data-structure (no embedded objects/fields) in order to keep these convenience services of the config framework.

FederateConfigParser

This class is responsible for parsing

• the configuration file provided by the user/runtime
• the command-line arguments provided by the user

This parser class will automatically parse and fill those fields that are present in your configuration class. Follow these rules and you won't get any errors:

1. Define your own config class that inherits from FederateConfig (or one of its inherited classes)
2. Define your extra parameters as public. Currently, the supported types are String, Double, Integer, Long, Boolean
3. In your code, provide the configuration class type to the federateConfigParser.parseArgs(args, YOURCONFIGCLASS.class);
4. Create your JSON configuration file that includes all the fields that can be reached from your class (or, that are annotated as FederateParameter) including the fields from the superclass(es) as well!
5. Pass the -configFile <config.json> parameter to the runtime
6. Pass optionally other config parameters to the runtime that will overwrite those defined in the config file (i.e.: -stepSize 1.0)

---

IMPORTANT

The names of the fields that are defined in your config class will be used automatically to inspect command line arguments.

---

Loading order

Level 1

There is a default configuration file that contains all the default parameters. If no other configuration is provided for a federate, this should be loaded.

1. The config framework tries to load a file that resides as a resource in the project that contains the passed configuration class (see step #3 above).

2. If above attempt is unsuccessful, the framework tries to load a file from the path that is defined in the CPSWTNG_FEDERATE_DEFAULT_CONFIG environment variable.

Level 2

If the user provides a valid configuration file that is passed with a special configFile parameter, parameters are going to be read from this file.

Level 3

On top of all other levels, if the user provides named parameters (besides configFile), those parameters overwrite the previously loaded parameters' values.

---

pom.xml requirements

In pom.xml there should be a configFile parameter such that the following command would be valid:

mvn exec:exec -DconfigFile=/path/to/file

---

Default parameters

The config framework will maintain a state while loading the configuration settings and will warn the user if a configuration parameter was not provided as an input but it is indicated on code level that it is expected. If such situation occurs, the default value for the parameter in question will be set by the runtime environment.

Changes from previous versions

In previous versions configuring the federates was through command line arguments and configuring the federation manager was done through command line arguments and a special config file called script.xml. This has been changed with our new config framework.

Federation manager configuration

To configure the federation manager, script.xml is no longer used, but we support JSON-based configuration files. Specifically the configuration for a federation manager includes the following fields:

• federateType
• federationId
• isLateJoiner
• lookAhead
• stepSize
• name [optional]
• bindHost
• port
• controlEndpoint
• federatesEndpoint
• federationEndTime
• realTimeMode
• fedFile
• experimentConfig

Besides the ordinary federation manager specific values, note the last parameter called experimentConfig. This represents a path to another JSON file that holds information about the domain, the experiment that we're running.

The experiment configuration includes the following fields (currently):

• federateTypesAllowed - the list of the federate types that are supported to join the federation
• expectedFederates - the list of the type and number of federates that are considered expected in the federation
• lateJoinerFederates - the list of the type and number of the federates that are considered late joiners in the federation
• pauseTimes - a list of time points when the federation should pause automatically
• coaDefinition - the path to the COA definiton file
• coaSelection - the path to the COA selection file
• terminateOnCOAFinish - whether the federation should terminate after COA execution is finished