When Nucleus starts, it is passed the names of directories where all configuration properties files are located. The configuration path specifies a list of one or more configuration directories to be searched when Nucleus needs a property configuration file.
For example, if Nucleus is started like this:
java atg.nucleus.Nucleus config
then config is used as the configuration directory. If Nucleus needs the configuration for the /services/SunnyWeather service, it will look for the file config/services/SunnyWeather.properties.
The configuration path (CONFIGPATH) is determined by the ATG-Config-Path attribute of the application modules you include in your Nucleus-based application. This attribute is set in the ATG-Config-Path line of the manifest file for each module. For information about how the ATG platform uses application modules, see the Working with Application Modules chapter of this guide.
For example, the manifest used by the DAS module is located at <ATG2007.3dir>/DAS/META-INF/MANIFEST.MF. It includes this line:
ATG-Config-Path: config/config.jar
This sets the configuration path to include <ATG2007.3dir>/DAS/config/config.jar. In addition, the application assembly scripts append <ATG2007.3dir>/home/localconfig to the configuration path. When Nucleus needs to find the configuration for /services/SunnyWeather, it first looks for the file config/services/Sunnyweather.properties in the DAS module, gathering any property values it finds there. It then does the same with any directories specified in the manifests of the other modules in the application. Finally, Nucleus looks for localconfig/services/SunnyWeather.properties, gathering any property values it finds there. The final result is a combination of all the property values found in all of those files.
Left-to-Right Behavior
The ATG platform reads the entire CONFIGPATH from left to right. If the same property value is defined in two properties files, then the last value is used. Thus, values found later in the CONFIGPATH override values found earlier.
The ATG CONFIGPATH behavior is different from Java’s CLASSPATH behavior. With CLASSPATH, .class files found earlier in the path replace files found later. With CONFIGPATH, configuration files are merged, not replaced, and the order of precedence is the opposite from CLASSPATH. Unlike CLASSPATH, ATG doesn’t stop with the first matching property it finds in the CONFIGPATH. Instead, it examines the entire CONFIGPATH and uses the last-defined value.
Note: You should not place any .class files in any directory that is part of the ATG CONFIGPATH. Doing so may result in errors, because the .class files may interfere with Nucleus’ ability to resolve component names.
Flexible Configuration Structure
The services/SunnyWeather.properties file does not need to be present in every element of the configuration path. If Nucleus does not find the file in a particular configuration directory, then it will skip that directory and move on to the next. Nucleus will only declare an error if the configuration file is not found in any of the configuration directories.
Note that in our examples, the directories are separated by the : character. The actual character that should be used depends on your system. On most UNIX systems the directories are separated by : characters. On Windows systems the directories are separated by ; characters.
Configuration paths are useful when you want to start with some base configuration, but then want to override certain properties files without actually modifying any properties files in the base configuration. To do this, you would create a “local” configuration directory that comes after the “base” configuration directory in the configuration path. Any properties files you want to override can then be placed in the local configuration directory without having to touch the base configuration directory.
The application assembly scripts implement this by building in the default configuration path: config/config.jar:localconfig. See Separating Configuration Layers.
