Configuration File Format

A configuration file consists of a sequence of assignments of the form:


Each assignment must appear on a separate line. Lines can however be broken by using the backslash (\) as a continuation character. The use of the equals sign is optional (it can be replaced by white space). Otherwise white space is ignored.

Lines that start with either "#" or "!" are treated as comments and discarded.

In most cases:


is the name of a property


is the value to be assigned to the property

One of the keywords may be the special keyword $class. In this case value must be the fully qualified name of a class. This tells the system to create an object of the specified class: the properties specified in the rest of the file are assigned to this object. A complete property file must in fact include such an assignment, since there must be an object to assign properties to. However, this assignment is always included in the default layer configuration files, so it can usually be omitted from configuration files in higher layers. (Note, however, that if you add a configuration file to one of your layers that does not exist in any of the supplied lower layers, then this class assignment is required.)

Complex Properties

Most properties in the configuration files have simple values such as integers, string or booleans. More complex assignments can be made, however:

Component objects

Components can be "wired together" by means of property assignments. Component A, for example, may have a property that needs to be set to reference component B. This kind of property can be set by an assignment of the following form:

keyword = component-path/component-name

For example:

otherComponent = /mycomponents/Important

The component path does not have to be absolute. You can also specify a path relative to the folder of the current component. For example:

otherComponent = ../../Important

Array properties can be set by separating the values in the array with commas, for example:

numbersToCheck = 10,20,30,45,70

Mapped properties can be set by a series of assignments of the following form:

keyword.key = value

For example:

component.3 = /mycomponents/Important
component.2 = /mycomponents/LessImportant
component.1 = /mycomponents/Unimportant

Note that mapped properties are set in alphabetical key order (1, 2, 3 in this case), not the order in which they appear in property files. This ensures a fixed order of creation even when the assignments are spread across several configuration layers.


The values assigned to properties can include placeholders for variables. When the property is assigned, the placeholder is replaced by the value of the variable it references. The syntax for a variable placeholder is:


Four different kinds of variable reference are supported:

System property references

variable-reference can be the name of any system property. For example:

myUrl = http://${escenic.server}:8080/my/page/
Component property references

variable-reference can be a reference to any component property. It must have the form:


For example:

JNDI references

variable-reference can be a reference to any JNDI name. It must have the form:


For example:


JNDI references are particularly useful as a means of creating configurations that can be used in more than one environment (both a test environment and production environment)

Environment variable references

variable-reference can be a reference to any operating system environment variable. It must have the form:


For example:

Configuration File Encoding

Configuration files, in accordance with the rules for standard Java properties files, must be encoded using the ISO-8859-1 character set. If you need to include characters outside this character set, then you can do so using the following syntax:


where xxxx is the hexadecimal Unicode value of the required character. The use of the backslash as an escape character to introduce Unicode values and as a continuation character means that you must always repeat any backslashes that you want to appear in the file. This Windows path, for example:


will be read as:


unless you repeat the backslashes as follows:


The following example illustrates some the property types discussed above.

$class = com.mycompany.SomeClass
numbersToCheck = 10,20,30,45,70,\
otherComponents = ./Other
somePath = ${/ServerConfig.filePublicationRoot}/myroot
# Fruits    /mycomponents/Apple   /mycomponents/Orange
  fruit.banana   /mycomponents/Banana

It contains the following items:

  • The creation of a component object.

  • An array of numbers, with a line break.

  • A reference to another component called Other in the same folder as this one.

  • A path composed of the value of the ServerConfig component's filePublicationRoot property and the string value /myroot.

  • A comment.

  • A mapped property called 'fruit' with three values. Note that the properties will be created in alphabetical order, not the order which they appear. Also note the omission of the '=' sign, which is not required.