Package org.matsim.core.config

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 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 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 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:

• ConfigGroup.addParam(String, String) to store the values read from a configuration file.
• ConfigGroup.getParams() to return a map containing all the parameter names and their values to be stored in a configuration file.
• 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.
• ConfigGroup.getName() should return the name of your config-group, as it appears in the configuration file.
• Optionally: 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 added to the Config-object before the configuration is read from file, because otherwise a generic ConfigGroup will be created for these settings. The controler-documenation has an example of how to use custom config-groups with additional functionality provided by ControlerListeners in the "Best Practices" section.

Author:

mrieser

Class Summary

Class	Description
CommandLine	This class provides functionality to configure (MATSim) applications via the command line.
CommandLine.Builder	Fluent builder to create a command line interpreter for MATSim applications.
Config	Stores all configuration settings specified in a configuration file and provides access to the settings at runtime.
ConfigGroup	Implements a generic config-group that stores all parameters in a simple Map.
ConfigReader	A reader for config-files of MATSim.
ConfigUtils
ConfigWriter
ReflectiveConfigGroup	A module using reflection for easy implementation of config groups.

Enum Summary

Enum	Description
ConfigWriter.Verbosity

Exception Summary

Exception	Description
CommandLine.ConfigurationException
ReflectiveConfigGroup.InconsistentModuleException

Annotation Types Summary

Annotation Type	Description
ReflectiveConfigGroup.DoNotConvertNull	Setters for which the "null" string should NOT be converted to the null pointer, and getter from which a null pointer should NOT be accepted and converted to the "null" string, should be annotated with this.
ReflectiveConfigGroup.StringGetter	use to annotate the methods which should be used to get the string values.
ReflectiveConfigGroup.StringSetter	use to annotate the methods which should be used to read the string values.