The application can be configured in many ways, the exact nature and selection of configuration items is application specific. The general mechanisms to determine the active configuration is independent of that however. This section describes how these mechanisms work.

Configuration items are individual settings which can be modified or specified by the user to influence how the application behaves for certain operations or in specific areas. Each application has its own unique set of supported configuration items, but some of them are shared among many applications because they are of a very general nature (such as the configuration of the logging capabilities for example).

To make for a comfortable user experience, these settings can be saved to a file and will be used upon subsequent application usages as the default settings. To allow for a maximum of flexibility in a multitude of scenarios, there are several locations where such settings files can be located on disk. And as a further convenience all of the configuration items settings can be overridden on the command line when starting the application.

When the application starts, all of the supported locations are examined and any supported settings files will be loaded and combined into the set of active configuration items. After all the settings have been loaded and combined, the startup process continues.

The following is the order from where the settings will be loaded:

For a configuration item to be loaded from the system properties, the corresponding property has to be set already. So it might be necessary to specify a property on the command line when invoking the Java Virtual Machine using the -D option. However, it is also possible to modify system properties using the loading of configuration settings by marking a property in the loaded file by prefixing it with System.setProperty., e.g. to set the system property settings.dir via a loaded propery file for subsequent usage it will have to be specified as System.setProperty.settings.dir in that property file. Only make use of this mechanism if you know exactly what you're doing, however, as it might confuse the loading process if crucial system properties are modified in an unsupported way.

The mechanism to set system properties can be very useful for example to set the file locations for Kerberos JAAS login configuration in a convenient way:

When loading the individual files, each step overrides the settings of the previous step(s). This results in the command line having almost the highest priority as it gets parsed last. Only the property file defined in the settings itself has higher priority. This could be understood as a job-settings file. This is also the only property file that will trigger an error if it is not available.

AppName is standing for the base class name of an application. E.g. if the applications main class is named foo.bar.MyApp.java, then AppName will be MyApp. Thus the looked for property file should be named MyApp.properties. For BoarderZone applications the corresponding jar file will commonly be named MyApp.jar.

If a system property (e.g. AppName.home) is not available, the step will be skipped. If a property file at one of the locations is not found, this doesn't matter.

The system properties AppName.home and settings.dir are meant to provide a mechanism to set up some common settings for a machine (e.g. defining local paths and so on) which should be valid for all users on that machine. AppName.home is meant to be pointing to the installation directory of an application and settings.dir to some folder containing system wide settings (e.g. the /etc folder on unix systems).

settings.dir is set to ${user.home}/.boarderzone if not defined otherwise. app.home is set to the directory containing the applications main jar file.

The system properties user.home and user.dir are standard java system properties and represent the users home directory (for per user settings) respectively the current working directory of the user (for per invocation settings).

If an application supports saving its settings itself (either automatically or explicitly by the user), it will do so only to one single location. Where that location is can be specified by the configuration item config-save. By default this is set to ${settings.dir} which by default points to a subdirectory of the users home directory. This ensures each user has the necessary privileges to write to the settings file. This might have to be tweaked if the settings.dir points to a system wide directory to which normal users may not write.

Some of the configuration items might contain file system paths. To allow the same settings file to be used by different users (as a machine wide default) it is not advisable to use absolute paths for those items which should be set to individual files or directories for each user. To support this, it is allowed to use either the names of system properties or variables to represent portions of such file system paths. E.g. the configuration item dialog-properties with its default value of ${settings.dir}/${app.name}Dialog.properties can be used by all users and will resolve to different files for different users by default (e.g. to /home/users/jdo/.boarderzone/MyAppDialog.properties for a user named jdo on a unix machine).

A small set of variables are available through the application itself, for example app.name will contain the base name of the application. If more variables are needed for configuration purposes, these can be loaded through a file which can be specified in the configuration item variables. This is either a standard java properties file or an XML file which conforms to a specific XML schema. The XML version allows sophisticated structures to be imported from other XML files, which can be used to combine different sets of variables from various locations. For further information about the use of variables see Definition and use of Variables.

With all these possibilities from where configurations can be loaded, it is sometimes difficult to determine what a setting now actually is. To track down problems in the configuration the item config-dump will dump the values of all configuration items to the console after the loading of the configuration is complete but before continuing the startup process.