11.1 Introduction to Configuration
KineticFusion is an Java application and uses the built-in Java mechanisms to specify configuration options. There are several mechanisms for configuring KineticFusion and these are detailed below.
Java applications are normally configured using java properties. A Java property is a simple name-value pair. The name is specific to the application and so is often specified as a compound name with the application name prefixing the property name. For KineticFusion all property names take the form 'kinesis.SomeProperty'. The values assigned to these properties are used to configure the application and determine how the application processes RVML and SWF documents. If a configuration value is not specified, then the default value is used.
The simplest means of specifying a property to a Java application is using the application command-line. Java application command-lines generally have the following format:
java [-classpath 'Class path for locating application modules'] [-DPropertyName=PropertyValue] applicationName [ApplicationParameters]
Note: On Windows javaw is often used instead of java as it does not cause a new console window to open.
Java properties are specified with the -D flag and must be between the classpath argument and the com.kinesis.KineticFusion application name. There should never be a space between the -D flag and the name of the property you are changing. For KineticFusion Developer Edition, the standard Windows startup file contains the following command:
javaw -classpath "$INSTALL_PATH/KFDeveloper.jar" com.kinesis.KineticFusion %1 %2 %3 %4 %5 %6
To specify one or more properties on the command-line, this startup file could be modified to:
javaw -classpath "$INSTALL_PATH/KFDeveloper.jar" -Dkinesis.preload=true -Dkinesis.xml.validate=true com.kinesis.KineticFusion %1 %2 %3 %4 %5 %6
Listing properties on the application command-line is not very practical, however, when many options are being set. For this reason, the most common means of configuring KineticFusion is through a Java properties file. A properties file is a standard text file and consists of a number of lines of the format:
Blanks lines or lines beginning with the '#' character are ignored and may be used for comments. Backslashes are interpreted as escape characters - to embed Windows paths that contain backslashes either use a double backslash or convert windows paths to use forward slashes. For example:
Property values that are can be split over multiple lines by ending the line in a single backslash and continuing on the next line. Finally, property values should always be specified without quotes.
KineticFusion can use up to two different configuration files: a system-wide configuration file, and a user-specific configuration file that overrides the system-wide values. When the KineticFusion application starts, it attempts to read in the system configuration properties from KineticFusion.properties file located in the installation 'config' folder. This is the default name and location for the file though these can be changed as follows:
- The application tries to read the property kinesis.configDirectory . This property must be specified on the command-line as detailed above and specifies the directory in which the property file resides. For example:
java -Dkinesis.configDirectory=c:/config -jar KFDeveloper.jar
- If this directory exists and contains a file called KineticFusion.properties then the application configuration is taken from this file
- If the application is still unable to find a KineticFusion.properties file, the application will check on the application class path, the path defined for the application specifying the location of library files.
- If the file has not been found, the KineticFusion.properties file from the installation 'config' folder is used.
Every KineticFusion installation has a KineticFusion.properties file located in the installation 'config' directory. To change a property in the file, simply edit the file with your default text editor, alter any values you feel necessary, save the file and restart the application.
If multiple users are using the same KineticFusion installation, or if a user does not have write access to the system configuration file, it may be preferable for users to manage their own properties file instead. In addition to reading the system-wide configuration options, KineticFusion will also look for a file called '.kfproperties' in the users home directory. If found, all properties defined in this file will override the properties defined in the system configuration file.
As mentioned above, if user-local properties are found then these properties will override the global properties. There are four possible locations available to KineticFusion to resolve a single configuration option. These locations are, in decreasing order of importance:
- Session Options
- Most important - this is the set of options specified on the command line. This allows users to override a property for a single session. Properties defined on the command line of the application using the -D flag override any other possible value of the property and the value cannot be changed during a session.
- User-specific configuration file
- This is the configuration file located in the users home folder. Properties defined in this file override properties of the same name defined in the global configuration file. This enables user-specific configuration options. Options can be added, modified or removed from this file during a session and the application willl pick up the changes automatically.
- System configuration file
- This is the system configuration file normally located in the installation 'config' folder. These options are global to all users of the application. Options can be added, modified or removed from this file during a session and the application willl pick up the changes automatically.
- Internal Default
- Least important - this is an immutable default stored directly within the KineticFusion application
KineticFusion maintains four sets of options, one for each of the above locations. When the value of a configuration parameter is used, the value will be taken from the highest level that contains a value for the option. This mean that options specified on the command-line can never be overridden by options stored in configuration files.
KineticFusion checks all external configuration files for changes before running a command. When KineticFusion detects that a configuration option has changed in an external file, it will update the value of the property at the corresponding level. The application will immediately see the new value of the option if , and only if, the option is not also defined at a higher level.
Copyright 2003-2005 Kinesis Software. All rights reserved.