The Properties Facet

3 min read

3 min read

3 min read

2 min read

2 min read

2 min read

3 min read

2 min read

3 min read

The Properties facet lets an administrative client read and update the configuration properties of a running program's communicator. It implements the Ice::PropertiesAdminIce::PropertiesAdminIce::PropertiesAdminIce::PropertiesAdminIce::PropertiesAdminIce::PropertiesAdminIce::PropertiesAdminIce::PropertiesAdmin interface.

An administrative client reads properties with getProperty and getPropertiesForPrefix, and updates them with setProperties. setProperties merges the properties it receives into the communicator's properties: it adds or changes each property that has a value, and removes each property whose value is empty. The other properties keep their values.

setProperties applies property validation to each property it adds, changes or removes. The update is not all or nothing: when validation rejects a property, the properties that setProperties applied before it keep their new values. Set Ice.Trace.Admin.Properties to trace the changes that setProperties makes.

An application can register callbacks that the Properties facet calls after each successful setProperties call. A callback receives the added and changed properties with their new values, and the removed properties with empty values; the dictionary is empty when the call changed nothing. Direct calls to Properties.setProperty do not invoke these callbacks.

The servant that implements this facet is a NativePropertiesAdmin. You can retrieve this servant by calling findAdminFacet:

C++
// It's nullptr when the facet is not enabled
Ice::NativePropertiesAdminPtr propertiesAdmin =
communicator->findAdminFacet<Ice::NativePropertiesAdmin>("Properties");

addUpdateCallback accepts a std::function<void(const Ice::PropertyDict&)> and returns a function that unregisters the callback:

C++
auto removeCallback = propertiesAdmin->addUpdateCallback(
[](const Ice::PropertyDict& changes) { /* Apply application settings. */ });
// When notifications are no longer needed:
removeCallback();

The servant that implements this facet is a NativePropertiesAdmin. You can retrieve this servant by calling findAdminFacet:

C#
if (communicator.findAdminFacet("Properties") is
Ice.NativePropertiesAdmin propertiesAdmin)
{
...
}
// else, the facet is not enabled

Register an Action<Dictionary<string, string>> with addUpdateCallback. Retain the delegate to unregister it with removeUpdateCallback:

C#
Action<Dictionary<string, string>> callback = changes => { /* Apply application settings. */ };
propertiesAdmin.addUpdateCallback(callback);
// When notifications are no longer needed:
propertiesAdmin.removeUpdateCallback(callback);

The servant that implements this facet is a NativePropertiesAdmin. You can retrieve this servant by calling findAdminFacet:

Java
com.zeroc.Ice.Object obj = communicator.findAdminFacet("Properties");
if (obj != null) { // It's null when the facet is not enabled
var propertiesAdmin = (com.zeroc.Ice.NativePropertiesAdmin)obj;
...
}

Register a Consumer<Map<String, String>> with addUpdateCallback. Retain the callback to unregister it with removeUpdateCallback:

Java
java.util.function.Consumer<java.util.Map<String, String>> callback =
changes -> { /* Apply application settings. */ };
propertiesAdmin.addUpdateCallback(callback);
// When notifications are no longer needed:
propertiesAdmin.removeUpdateCallback(callback);

Use a PropertiesAdmin proxy to access another communicator's Properties facet remotely.

findAdminFacet returns a NativePropertiesAdmin wrapper that provides access to the update callbacks of this facet. removeAdminFacet returns None for this facet.

Python
propertiesAdmin = communicator.findAdminFacet("Properties")
if propertiesAdmin is not None:
assert isinstance(propertiesAdmin, Ice.NativePropertiesAdmin)
...

addUpdateCallback accepts a callable that takes a dict[str, str] and returns None. Retain the callable to unregister it with removeUpdateCallback:

Python
def onUpdate(changes: dict[str, str]) -> None:
"""Apply updated application settings."""
...
propertiesAdmin.addUpdateCallback(onUpdate)
# When notifications are no longer needed:
propertiesAdmin.removeUpdateCallback(onUpdate)

The servant that implements this facet is a NativePropertiesAdmin. You can retrieve this servant by calling findAdminFacet:

Swift
if let propertiesAdmin = communicator.findAdminFacet("Properties") as?
NativePropertiesAdmin {
...
}

addUpdateCallback(_:) accepts a (PropertyDict) -> Void closure and returns a PropertiesAdminRemoveCallback closure that unregisters it:

Swift
let removeCallback = propertiesAdmin.addUpdateCallback { changes in
// Apply application settings.
}
// When notifications are no longer needed:
removeCallback()