setProperty operation on the
Properties interface sets a property to the specified value:
You can clear a property by setting it to the empty string.
For properties that control the Ice run time and its services (that is, properties that start with one of the reserved prefixes), this operation is useful only if you call it before you call
initialize. This is because property values are usually read by the Ice run time only once, when you call
initialize, so the Ice run time does not pay attention to a property value that is changed after you have initialized a communicator. Of course, this begs the question of how you can set a property value and have it also recognized by a communicator.
To permit you to set properties before initializing a communicator, the Ice run time provides an overloaded helper function called
createProperties that creates a property set. In C++, the function is in the
StringConverter parameter allows you to parse properties whose values contain non-ASCII characters and to correctly convert these characters into the native codeset. The converter that is passed to
createProperties remains attached to the returned property set for the life time of the property set.
The function is overloaded to accept either an
argv pair or a
StringSeq, to aid in parsing properties.
In Java, the functions are static methods of the
Util class inside the
In C#, the
Util class in the
Ice namespace supplies equivalent methods:
The Python and Ruby methods reside in the
In PHP, use the
createProperties strips Ice-related command-line options from the passed argument vector. (For Java, only the versions that accept a
StringSeqHolder do this.)
The functions behave as follows:
- The parameter-less version of
createPropertiessimply creates an empty property set. It does not check
ICE_CONFIGfor a configuration file to parse.
- The other overloads of
createPropertiesaccept an argument vector and a default property set. The returned property set contains all the property settings that are passed as the default, plus any property settings in the argument vector. If the argument vector sets a property that is also set in the passed default property set, the setting in the argument vector overrides the default. The overloads that accept an argument vector also look for the
--Ice.Configoption; if the argument vector specifies a configuration file, the configuration file is parsed. The order of precedence of property settings, from lowest to highest, is:
- Property settings passed in the default parameter
- Property settings set in the configuration file
- Property settings in the argument vector.
The overloads that accept an argument vector also look for the setting of the
ICE_CONFIGenvironment variable and, if that variable specifies a configuration file, parse that file. (However, an explicit
--Ice.Configoption in the argument vector or the
defaultsparameter overrides any setting of the
createProperties is useful if you want to ensure that a property is set to a particular value, regardless of any setting of that property in a configuration file or in the argument vector. Here is an example:
The equivalent Java code looks as follows:
We first convert the argument array to an initialized
StringSeqHolder. This is necessary so
createProperties can strip Ice-specific settings. In that way, we first obtain an initialized property set, then override the settings for the two tracing properties, and then set the properties in the
The equivalent Python code is shown next:
This is the equivalent code in Ruby:
Finally, we present the code in PHP: