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.
Reading and Updating Properties
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.
Receiving Property Updates
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:
// It's nullptr when the facet is not enabledIce::NativePropertiesAdminPtr propertiesAdmin = communicator->findAdminFacet<Ice::NativePropertiesAdmin>("Properties");addUpdateCallback accepts a std::function<void(const Ice::PropertyDict&)> and returns a function that unregisters the callback:
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:
if (communicator.findAdminFacet("Properties") is Ice.NativePropertiesAdmin propertiesAdmin){ ...}// else, the facet is not enabledRegister an Action<Dictionary<string, string>> with addUpdateCallback. Retain the delegate to unregister it with removeUpdateCallback:
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:
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.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.
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:
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:
if let propertiesAdmin = communicator.findAdminFacet("Properties") as? NativePropertiesAdmin { ...}addUpdateCallback(_:) accepts a (PropertyDict) -> Void closure and returns a PropertiesAdminRemoveCallback closure that unregisters it:
let removeCallback = propertiesAdmin.addUpdateCallback { changes in // Apply application settings.}// When notifications are no longer needed:removeCallback()