---
title: "The Properties Facet"
url: https://docs.zeroc.com/ice/3.8/administration/administrative-facility/properties-facet
docs_index: https://docs.zeroc.com/llms.txt
---

> For an index of every page, see [llms.txt](https://docs.zeroc.com/llms.txt).

# The Properties Facet

Parts of this page are for some programming languages only, and name them. For one language's text alone, see [C++](https://docs.zeroc.com/ice/3.8/administration/administrative-facility/properties-facet/cpp.md), [C#](https://docs.zeroc.com/ice/3.8/administration/administrative-facility/properties-facet/csharp.md), [Java](https://docs.zeroc.com/ice/3.8/administration/administrative-facility/properties-facet/java.md), [JavaScript](https://docs.zeroc.com/ice/3.8/administration/administrative-facility/properties-facet/js.md), [MATLAB](https://docs.zeroc.com/ice/3.8/administration/administrative-facility/properties-facet/matlab.md), [PHP](https://docs.zeroc.com/ice/3.8/administration/administrative-facility/properties-facet/php.md), [Python](https://docs.zeroc.com/ice/3.8/administration/administrative-facility/properties-facet/python.md), [Ruby](https://docs.zeroc.com/ice/3.8/administration/administrative-facility/properties-facet/ruby.md), and [Swift](https://docs.zeroc.com/ice/3.8/administration/administrative-facility/properties-facet/swift.md).

The `Properties` facet lets an administrative client read and update the [configuration properties](https://docs.zeroc.com/ice/3.8/runtime/properties-and-configuration.md) of a running program's communicator. It implements the `Ice::PropertiesAdmin` ([C++](https://code.zeroc.com/ice/3.8/api/cpp/classIce_1_1PropertiesAdminPrx.html), [C#](https://code.zeroc.com/ice/3.8/api/csharp/api/Ice.PropertiesAdminPrx.html), [Java](https://code.zeroc.com/ice/3.8/api/java/com.zeroc.ice/com/zeroc/Ice/PropertiesAdminPrx.html), [JavaScript](https://code.zeroc.com/ice/3.8/api/javascript/Ice/PropertiesAdminPrx.html), [Python](https://code.zeroc.com/ice/3.8/api/python/Ice.PropertiesAdminPrx.html), [Ruby](https://code.zeroc.com/ice/3.8/api/ruby/Ice/PropertiesAdminPrx.html), and [Swift](https://code.zeroc.com/ice/3.8/api/swift/documentation/ice/propertiesadminprx)) 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](https://docs.zeroc.com/ice/3.8/runtime/properties-and-configuration/properties-overview.md#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](https://docs.zeroc.com/ice/3.8/property-reference/ice-trace-properties.md#ice.trace.admin.properties) to trace the changes that `setProperties` makes.

> **Note**
>
> Changing a property generally does not reconfigure an initialized Ice component. When the Metrics facet is also enabled, updates to `IceMX.Metrics.*` through this facet reconfigure the metrics views. Application properties take effect when the application reads them again or handles a property update callback.

> **C++, C#, Java, Python, and Swift**
>
> ## 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.

> **C++**
>
> The servant that implements this facet is a [NativePropertiesAdmin](https://code.zeroc.com/ice/3.8/api/cpp/classIce_1_1NativePropertiesAdmin.html). You can retrieve this servant by calling `findAdminFacet`:
>
> ```cpp
> // 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:
>
> ```cpp
> auto removeCallback = propertiesAdmin->addUpdateCallback(
>     [](const Ice::PropertyDict& changes) { /* Apply application settings. */ });
> // When notifications are no longer needed:
> removeCallback();
> ```

> **C#**
>
> The servant that implements this facet is a [NativePropertiesAdmin](https://code.zeroc.com/ice/3.8/api/csharp/api/Ice.NativePropertiesAdmin.html). You can retrieve this servant by calling `findAdminFacet`:
>
> ```csharp
> 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`:
>
> ```csharp
> Action<Dictionary<string, string>> callback = changes => { /* Apply application settings. */ };
> propertiesAdmin.addUpdateCallback(callback);
> // When notifications are no longer needed:
> propertiesAdmin.removeUpdateCallback(callback);
> ```

> **Java**
>
> The servant that implements this facet is a [NativePropertiesAdmin](https://code.zeroc.com/ice/3.8/api/java/com.zeroc.ice/com/zeroc/Ice/NativePropertiesAdmin.html). 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);
> ```

> **JavaScript, MATLAB, PHP, and Ruby**
>
> Use a `PropertiesAdmin` proxy to access another communicator's `Properties` facet [remotely](https://docs.zeroc.com/ice/3.8/administration/administrative-facility/using-the-admin-object.md).

> **Python**
>
> `findAdminFacet` returns a [NativePropertiesAdmin](https://code.zeroc.com/ice/3.8/api/python/Ice.NativePropertiesAdmin.html) wrapper that provides access to the update callbacks of this facet. `removeAdminFacet` returns `None` for this facet.
>
> ```py
> 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`:
>
> ```py
> def onUpdate(changes: dict[str, str]) -> None:
>     """Apply updated application settings."""
>     ...
>
> propertiesAdmin.addUpdateCallback(onUpdate)
> # When notifications are no longer needed:
> propertiesAdmin.removeUpdateCallback(onUpdate)
> ```

> **Swift**
>
> The servant that implements this facet is a [NativePropertiesAdmin](https://code.zeroc.com/ice/3.8/api/swift/documentation/ice/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()
> ```

## See Also

- [Properties and Configuration](https://docs.zeroc.com/ice/3.8/runtime/properties-and-configuration.md)
- [IceGrid](https://docs.zeroc.com/ice/3.8/services/icegrid.md)
- [Using the admin Object](https://docs.zeroc.com/ice/3.8/administration/administrative-facility/using-the-admin-object.md)
