Configuration File Format
A configuration file consists of a sequence of assignments of the form:
keyword=value
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:
- keyword
-
is the name of a property
- value
-
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
- Arrays
-
Array properties can be set by separating the values in the array with commas, for example:
numbersToCheck = 10,20,30,45,70
- Maps
-
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.
Variables
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:
${variable-reference}
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:
component-path/component-name.property-name
For example:
myImportantValue=${/mycomponents/Important.value}
- JNDI references
-
variable-reference can be a reference to any JNDI name. It must have the form:
jndi:jndi-name
For example:
providerUrl=${jndi:java:comp/env/PROVIDER_URL}
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:
env:environment-variable
For example:
importantOsValue=${env:IMPORTANT}
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:
\uxxxx
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:
C:\my\windows\path
will be read as:
C:mywindowspath
unless you repeat the backslashes as follows:
C:\\my\\windows\\path
Example
The following example illustrates some the property types discussed above.
$class = com.mycompany.SomeClass numbersToCheck = 10,20,30,45,70,\ 131,199,343,546 otherComponents = ./Other somePath = ${/ServerConfig.filePublicationRoot}/myroot # Fruits fruit.apple /mycomponents/Apple fruit.orange /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'sfilePublicationRoot
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.