30.3 Configuration Files

Properties are usually set in a configuration file. A configuration file contains a number of name–value pairs, with each pair on a separate line. Empty lines and lines consisting entirely of white space characters are ignored. The # character introduces a comment that extends to the end of the current line.

Here is a simple configuration file:

# Example config file for Ice

Ice.MessageSizeMax = 2048    # Largest message size is 2MB
Ice.Trace.Network=3          # Highest level of tracing for network
Ice.Trace.Protocol=          # Disable protocol tracing

Leading and trailing white space is always ignored for property names (whether the white space is escaped or not), but white space within property values is preserved.

For property values, you can indicate leading and trailing whitespace by escaping the white space with a backslash. For example:

# White space example

My.Prop = a property               # Value is "a property"
My.Prop =     a     property       # Value is "a     property"
My.Prop = \ \ a     property\ \    # Value is "  a     property  "
My.Prop = \ \ a  \ \  property\ \  # Value is "  a     property  "
My.Prop = a \\ property               # Value is "a \ property"

This example shows that leading and trailing white space for property values is ignored unless escaped with a backslash whereas, white space that is surrounded by non-white space characters is preserved exactly, whether it is escaped or not. As usual, you can insert a literal backslash into a property value by using a double backslash (\\).

If you set the same property more than once, the last setting prevails and over­rides any previous setting. Note that assigning nothing to a property clears that property (that is, sets it to the empty string).

A property that contains the empty string (such as Ice.Trace.Protocol in the preceding example) is indistinguishable from a property that is not mentioned at all. This is because the API to retrieve the property value returns the empty string for non-existent properties (see page 869).

One of the simplest ways of loading a configuration file is to pass the command-line option --Ice.Config to an Ice program, for example:

$ ./server --Ice.Config=/opt/Ice/default_config

This causes the server to read its property settings from the configuration file in /opt/Ice/default_config. Section 30.5 discusses this option in more detail.

Property values can include characters from non-English alphabets. The Ice run time expects the configuration file to use UTF‑8 encoding for such characters. (With C++, you can specify a string converter when you read the file. See page 870, Section 32.3, and Section 32.24.)

30.3.1 The ICE_CONFIG Environment Variable

Another way to load a configuration file is to set the ICE_CONFIG environment variable to the relative or absolute path name of the file, for example:

$ export ICE_CONFIG=/opt/Ice/default_config
$ ./server

 

This causes the server to read its property settings from the configuration file in /opt/Ice/default_config.

Note that, for this to work, the server must call an overload of Ice::initialize (or the equivalent in other languages) that accepts an argu­ment vector. Overloads of initialize that do not accept an argument vector ignore ICE_CONFIG.

Note: In Java, the value of ICE_CONFIG can refer to class loader resources as well as regular files.

 

30.3.2 Special Characters

The characters = and # have special meaning in a configuration file:

• = marks the end of the property name and the beginning of the property value

• # starts a comment that extends to the end of the line

These characters must be escaped when they appear in a property name. Consider the following examples:

foo\=bar=1        Name is “foo=bar”, value is “1”
foo\#bar   = 2    Name is “foo#bar”, value is “2”
foo bar  =3       Name is “foo bar”, value is “3”

In a property value, a # character must be escaped to prevent it from starting a comment, but an = character does not require an escape. Consider these examples:

A=1           Name is “A”, value is “1”
B= 2 3 4      Name is “B”, value is “2 3 4”
C=5=\#6 # 7   Name is “C”, value is “5=#6”

Note that, two successive backslashes in a property value become a single back­slash. To get two consecutive backslashes, you must escape each one with another backslash:

AServer=\\\\server\dir    Value is “\\server\dir”
BServer=\\server\\dir   Value is “\server\dir”

The preceding example also illustrates that, if a backslash is not followed by \, #, or =, the backslash and the character following it are both preserved.