What are properties?

Properties are collections of name-value pairs that are often used to configure programs or program components. Both names (keys) and values are text (type String). From a programmer's perspective, it is an object of type "java.util.Properties", but from a user's perspective, it is a text file as described in the next section. Properties files are often used to configure classes such as time-driven custom classes, preparsers, functions, Integration Units, postexecution, custom classes phase 6.

In the majority of cases, it is sufficient to put each name-value pair in a separate text line. The line starts with the name, followed by an = (equal sign, 3DHex) and the value. If no unallowed characters occur, this rule is sufficient.

In special cases, however, it is necessary to know the exact rules, e.g. if whitespaces or colons cannot be avoided within the name. Since the 'official' description on "http://docs.oracle.com/javase/6/docs/api/java/util/Properties.html#load(java.io.Reader)" is a bit incomprehensible, we try to provide an alternative description.

A properties object corresponds to the abstract data type 'map', which is a collection of key-value pairs. The collection of all names (keys) is a set, i.e. all elements must be unique. The collection of all values is a multiset, i.e. the same value can be assigned to different names. An empty map or a map having only one entry is allowed. But an empty name (no characters) is not permitted. You can access a value by specifying a valid name. This is roughly equivalent to the system variables of an operating system.

Representation of properties in a file

Properties objects can be loaded from a file or written to a file. Such a file is always a text file, in which each line corresponds to a name-value pair. Although it is common to use the file suffix .properties, it is not necessary. The ISO 8859-1 character encoding is required. See "http://www.open-std.org/JTC1/SC2/WG3/docs/n411.pdf".

The following rules apply:

• Every line (there can be several) that is not an empty line or a comment line usually contains a name-value pair.

• A comment line starts with a # (23Hex) and will be ignored when read in.

• An empty line is a line only containing SP (whitespace, 20Hex) or HT (tabulator, 09Hex).

• A property, i.e. a name-value pair, is represented by the following syntax (The separator = is common, but not the only allowed separator): <name>=<value>

• Allowed separators between name and value, according to ISO 8859-1, are the following characters: = (equal sign, 3DHex), SP (whitespace, 20Hex), HT (tabulator, 09Hex), or : (colon, 3AHex). These characters cannot directly be used in names. To disable their effect as a separator, they can be invalidated by using a preceding \ (backslash, 5CHex).

• The backslash is therefore also a special character and has to be invalidated if it shall be used literally. A backslash within a name or a value must, therefore, be written twice.

• Trailing whitespaces and tabulators in front of names are ignored.

• Every combination of separator characters is treated as a single separator character, i.e. whitespaces and tabulators in front of values are ignored even if they are not invalidated.

• Since only the ISO 8859-1 encoding is allowed in properties files, characters that do not exist in this encoding have to be rewritten. This is done by using the suffix \u in front of the two-byte Unicode. The rewriting of allowed characters is permitted. Example: A and \u0041 are equivalent.

Regular expressions in a properties file

Regular expressions in properties files are a particular challenge, especially in names. If the regular expression contains SP (whitespace, 20Hex), = (equal sign, 3DHex), : (colon, 3AHex), or \ (backslash, 5CHex), these characters have to be invalidated by a backslash.

Normal notation of an exemplary regular expression:

Notation in a properties file:

Example

Following an example of a simple properties file for the preparser "EdifactSegmentSplitter" with 2 property lines.

Property editor

The property editor allows easy editing of a properties file. Currently this editor is only available for custom classes in phase 6. All properties that are available for the respective class are automatically displayed.