Unified Configuration Model

Before Starmapper can do anything, it needs to be told what to do. That's what the command line and configuration files are for. Each config file contains description of one drawing session, with information such as location of files to read, output image size and format, the Plotter to use, and so on (strictly speaking the file is just a persistent version of parameters passed from command line, but I'll get to it). Then Starmapper needs to read this file and start processing. But since Starmapper is just a library, handling of config files is not really in scope; previous versions delegated this work to applications, which were supposed to collect the data and give it to Starmapper. This resulted in much duplication and differences between each application's format (well, not really, but the duplication was bad anyway).

So that's why Starmapper3 switched to so-called Unified Configuration Model. It consists of two things:

• The common hierarchy of properties, embodied in the jezuch.utils.starmapper3.config∞ package and the classes Config∞, Path∞ and Setting∞.
• A straightforward mapping from this hierarchy to several formats - there are implementations for XML, INI and .properties in package jezuch.utils.starmapper3.app.common∞ in classes IniConfig∞, XmlConfig∞ and PropertiesConfig∞. There's also an additional format implemented in FileSystemConfig∞, which represents the property hierarchy in directory structure.

The properties form a hierarchy and each property is accessible via a path, for example regions.reg1.name - the path is usually given in dotted notation, where the leftmost part is the topmost (most general) in the hierarchy, but that's purely for human convenience; see javadocs for Config∞ class for details how it's handled internally - the only thing you need to know is that there's a hierarchy, unless you want programmatic access to the configuration API.

There's no common interface for formats - each format class needs to have a public constructor that takes a String∞ (the config's location) and implement Iterable∞<Pair∞<Path∞, String∞>>, which returns an Iterator∞ of pairs of path-in-hierarchy and value (in textual form, the conversions - and validations - are done later). There needs to be one item returned from the Iterator per configuration property (in any order). Most of the formats perform direct, or almost direct, mapping, so the implementation is really easy.

For particular formats the mappings are as follows:

• XML: the element hierarchy is simply mapped to property hierarchy; one result is that where there is a list of indexed properties, e.g. regions, the XML elements in the config file also are indexed, while they could just sit next to each other (so it's <reg01/><reg02/><reg03/> instead of simply <reg/><reg/><reg/>);
• INI: the topmost path element of the property is mapped to INI section, the rest is joined with dot as a separator and makes a key name (which means that properties with dots in names are frowned upon); so e.g. regions.reg1.name is mapped to a key reg1.name in section [regions];
• .properties: the whole path is joined with dot as a separator and makes a key in .properties file;
• File system: the path is mapped to a directory structure and the value is stored in a file at the deepest level - the file's contents (all of them) are the property's value; because there can't be a file and a directory with the same name at the same level, no property can have "subproperties" - e.g. if there's a value for property regions.reg1.name, then there can't be another property regions.reg1.name.stupid.

One warning, though: the values are converted to proper type and validated, but the system is assumed to be extensible, so it doesn't complain if you set a value for a property that Starmapper doesn't use (should it?...).

The command line and stuff

The command line (of starmapper-app-cli) also is part of the Unified Configuration Model. The values given from command line overwrite values read from a config file (which in turn overwrite defaults). Each property is set by passing the path in dotted notation prefixed with minus sign and followed by the value, e.g. -regions.reg1.name Elezi. All such "switches" should be given before the config file's name (not after, because first non-switch argument is taken as a file name and all arguments that follow are region numbers).

Config values

The list of config values/paths recognized by Starmapper is documented in javadocs for Config∞ class (look for public static fields named SET_*). The list, along with additional settings from various components, is repeated on AvailableSettings page.