2.9. Common configuration settings

In contrast to variables, configuration items have certain restrictions on the values they allow. So for numerical items it is necessary for them to represent a number, which is possibly constrained to a certain range. The acceptable values are normally indicated when starting the application with the -help option. The help for some of the possible configuration items will only be shown when the -debug option is set to true, because they are rarely of interest in normal operation.

Some of the configuration items have an alias in addition to their full name. This alias can be used instead of the full name to shorten the amount of typing on the command line. Either way is equivalent to the other. Note that both the names and the aliases are case sensitive.

Those items which represent a simple yes-or-no flag (Boolean values) support some additional ways on the command line of specifying the values. In case just the items name is given (e.g. “ -verbose ”), the value true is assumed independently of its default value. By specifying “ -no-verbose ” that flag is reversed and false is assumed (again independently of its default value).

In case a specified value is not acceptable for a specific item, the behavior depends on where that value was specified. If it is given in one of the loaded properties files, the application will output a warning message and will continue with the startup process. If the offending value was given as a command line option however, that value is rejected with an error message and the application aborts.

Following is a description of all the common configuration items of the application.

Table 2.4. Informational and usage related configuration items

verbosevBoolean false

Print informational output and more help.  Determines the amount of information produced by the application. This is usually not required for normal application operation but sometimes nice to know. In general this mainly affects command line applications and controls how much feedback is given on the command line about what the program is doing. It also affects how compact or verbose the help screen is when asking for it via -help.

verbose-headervhBoolean true

Display program header in verbose mode.  Controls whether the copyright notice and license information is displayed in verbose mode. Results in a more compact output in verbose mode when this is turned off.

versionVBoolean false

Print version information and quit.  Prevents normal execution of the application and rather just prints the version information and then quits. Can be used to check for the version of the application and ensuring it won't do anything else.

helphBoolean false

Print help and quit.  Only produces a help screen on the console showing the available command line options and some usage examples and then quits without performing any of the normal program operations. Can be used as a quick reference about how to use the application from the command line.

license N/A Boolean false

Print the license of the program and quit.  Prints the license text governing the use of the application to the console and quits. Can be used to extract the license text into a file if the original has been lost somehow.

loop N/A Boolean false

Loop multiple times after user confirmation.  This only applies to certain command line applications and states that the application should run multiple times after querying the user for confirmation after each run. Can be used to prevent the overhead of starting the JVM if it is known in advance that the application should do its job repeatedly with the same configuration.

wait N/A Boolean false

Wait for user to press enter on end.  Prevents the JVM from quitting until the user has confirmed to exit. Can be used to ensure having an opportunity to read application (or logging) output before the process will exit and possibly lose that information as the starting command line shell might disappear too.

Table 2.5. Configuration related configuration items

configcfgString <empty>

Configuration file with settings.  Specifies a standard Java properties file with configuration settings to be loaded. This file will be loaded as the last and thus has the highest priority, overriding settings from all other configuration sources (see General configuration mechanisms).

variablesvarString <empty>

Loads variables from the given file.  Specifies a file to load variables and their respective values from. See Definition and use of Variables for further information about variables.

config-autosave N/A Boolean false

Whether to save config on program exit.  If set to true, will save the configuration settings to the directory which is specified in the config-save option. This will only update the file if any of the configuration items have different values than the ones stored at the given location. Some applications never change any of their settings during execution and will thus never write or update that file.

config-save N/A String ${settings.dir}

Where to save the config file.  Determines the directory which will be used to save settings to. If any settings have to be written, will create that directory if it doesn't yet exist. Already existing settings files in that directory will be updated when saving to them, so care must be taken to prevent multiple applications from writing to the same files or data loss (of the settings) might occur.

config-dump N/A Boolean false

Whether to dump config on program start.  Mainly used for troubleshooting the configuration settings. If set to true, will output all the configuration items and their respective values to the console which started the application. Can be used to track down problems when working with complex configuration setups where settings are loaded from multiple files at multiple locations.

Table 2.6. Console related configuration items

language N/A String ${user.language}

Set the language.  Can be used to override the default language to be used by the application. By default this uses the language that was detected by the JVM (which adapts it from the operating systems locale settings). This can be used to force an application to run in a different language than that of the operating system.

country N/A String ${user.country}

Set the country.  Used to override the detected country. This works only along with the -language option and should be one of the countries supported by the active language.

codepage N/A String ${file.encoding}

Set the codepage for console output.  This enables to force the application to use a given codepage for output to the console. Might be necessary on certain platforms in case the JVM doesn't correctly detect the codepage to use to ensure special characters such as umlauts will be presented correctly on the console output.

codepage-guess N/A Boolean true

Whether to guess the correct console codepage.  Enables to turn off automatic guessing of the codepage to use in case this doesn't provide the desired result. Allows to fix the codepage in use in conjunction with the -codepage option.

Table 2.7. Network configuration items

use-proxy-configproxyBoolean false

Whether to use the proxy configuration settings.  Allows to turn off usage of the settings made in the file for proxy configuration.

proxy-config N/A String ${app.home}/conf/Proxy.properties

Proxy configuration settings.  Specifies a standard java properties file with settings to configure the proxy to use for java network connections.

net-authenticator N/A String

Network authenticator class.  Specifies the name of a class to use as authenticator when access to network resources requires authentication. This class must be a derivation of the standard java.net.Authenticator class and provide a username/password to be used for accessing the protected network resource.

The framework provides the following implementations that can be specified here:

  • net.boarderzone.afw.auth.SilentAppConfigAuthenticator.  A simple authenticator that performs its task silently by providing username and password from the application config items below.

  • net.boarderzone.afw.auth.InteractiveCommandLineAuthenticator.  A simple authenticator that performs its task by interactively querying for username and password on the command line upon each occasion where authentication is requested.

  • net.boarderzone.afw.auth.RememberingCommandLineAuthenticator.  A simple authenticator that performs its task by interactively querying for username and password on the command line and remembering the entered values for reuse on subsequent invocations. It will use the application config items below for remembering the entered credentials.

  • net.boarderzone.gui.auth.InteractiveDialogAuthenticator.  A simple authenticator that performs its task by interactively querying for username and password through a GUI dialog upon each occasion where authentication is requested, but with the possibility to remember the entered credentials. It too will use the application config items below for remembering the entered credentials.

net-username N/A String ${user.name}

Network authentication username.  Specifies the user name to be used for accessing protected network resources which require authentication.

In case that one of the remembering authenticators from above is being used, this is also where the entered user name is remembered.

net-password N/A String

Network authentication password.  Specifies the password to be used for accessing protected network resources which require authentication.

In case that one of the remembering authenticators from above is being used, this is also where the entered password is remembered.

Note that the password will be stored in clear text here!

Table 2.8. Debugging and internal configuration items

debug N/A Boolean false

Print debug output.  Turns on very verbose output in command line applications. Mainly used for troubleshooting. Works in conjunction with the -verbose option and determines the amount of information produced.

logging N/A String ${user.dir}/logging.properties

A logging config file.  Specifies the configuration file which controls the logging framework in use. See Logging Settings for more information.

required-version N/A String ${app.version}

The required application version.  This can be used to ensure that a specific version of the application will be used. By default this is always the version of the running application. When a different version is specified and this doesn't match the one of the starting application, an error message is output and the program quits. This can be used to detect when scripts might need to be updated after the installation of a new (and possibly incompatible) version of the application. The given version is compared one-by-one to the version of the application and only considered a match if each of the components matches exactly (e.g. no compatibility guessing is performed based on whether only the build number changed or such).

invocationCount N/A Integer 0

Counts the number of program invocations.  Just for testing or tracking purposes. Makes only sense with applications which are configured to (and capable of) saving their configuration at program end.