Package org.matsim.core.config

Packages
package	consistency
package	groups

Classes
class	CommandLine
class	Config
class	ConfigAliases
class	ConfigGroup
class	ConfigReader
class	ConfigReaderMatsimV1
class	ConfigReaderMatsimV2
class	ConfigUtils
class	ConfigV2XmlNames
class	ConfigWriter
class	ConfigWriterHandler
class	ConfigWriterHandlerImplV1
class	ConfigWriterHandlerImplV2
class	ReflectiveConfigGroup

Detailed Description

The configuration can be used to change the behavior of MATSim in some well-defined places. Users may know best the configuration-files for MATSim, XML-files in which several parameters and corresponding values can be entered. The config-package is responsible to store these parameters in memory during runs.

Each parameter is part of exactly one org.matsim.core.config.groups config-group}. Such a group collects similar parameters, or different parameters for one specific part of MATSim. The config-groups defined in the subpackage org.matsim.core.config.groups are considered "core" config-groups, which should change only if really needed. Often it is better to add additional config-paramters for new functionality as a new config-group (see Custom Config-Parameters below).

Custom Config-Parameters

One can add custom parameters any time to a configuration file, but they have to be in an additional "group" (in the XML representation, a "group" is specified as module. This may change in the future to have consistent names). As an example, you could add the following code to your configuration file:

  <module name="my-settings">
    <param name="my-value1" value="1" />
    <param name="my-value2" value="2.3" />
    <param name="my-value3" value="foo-bar" />
  </module>

These settings are then stored in an instance of org.matsim.core.config.ConfigGroup, which just stores all the parameters in a map. You could access such parameters with:

Config config;
// ... init/read config
String val1 = config.getModule("my-settings).getParam("my-value1");

This works out-of-the-box, but it has the downside of only providing String-values. In some cases, when this string value must be converted into an int or double many times, this can be very inefficient. In such cases, it may be of advantage to offer a custom config-group to store the parameters with their native types.

To write a custom config-group, extend org.matsim.core.config.ConfigGroup. This allows you to convert the parsed values from the configuration file only once and then store the parameters in their native type. Just provide the corresponding getters and setters for your parameters, and overwrite the following methods:

• org.matsim.core.config.ConfigGroup#addParam(String, String) to store the values read from a configuration file.
• org.matsim.core.config.ConfigGroup#getParams() to return a map containing all the parameter names and their values to be stored in a configuration file.
• org.matsim.core.config.ConfigGroup#getValue(String) should be implemented as well for compatibility reasons. You can implement it with an UnsupportedOperationException if you are sure that you will never call this method.
• org.matsim.core.config.ConfigGroup#getName() should return the name of your config-group, as it appears in the configuration file.
• Optionally: org.matsim.core.config.ConfigGroup#checkConsistency(Config) to check that all the settings make some sense together after being read from a file.

The custom config-group must be org.matsim.core.config.Config::addModule(ConfigGroup) added} to the org.matsim.core.config.Config-object before the configuration is read from file, because otherwise a generic org.matsim.core.config.ConfigGroup will be created for these settings. The org.matsim.core.controler controler-documenation} has an example of how to use custom config-groups with additional functionality provided by org.matsim.core.controler.listener.ControlerListeners in the "Best Practices" section.

Author

mrieser