Added documentation of 'ChannelDescriptionChangedEvent's (#1610)

* Added documantation of 'ChannelDescriptionChangedEvent's

Signed-off-by: Christoph Weitkamp <github@christophweitkamp.de>

* Replaced Sets.newHashSet(...) by Set.of(...)

Signed-off-by: Christoph Weitkamp <github@christophweitkamp.de>

developers/bindings/thing-xml.md

@@ -301,7 +301,7 @@ These providers allow to provide a `StateDescription` (or `CommandDescription` r
 
 Also implement this interface if you want to provide dynamic state / command options.
 The original `StateDescription`/`CommandDescription` is available for modification and enhancement.
-The framework provides two abstract implementations for bindings to support translation and other basic features: `BaseDynamicStateDescriptionProvider` and `BaseDynamicCommandDescriptionProvider`.
+The framework provides two abstract implementations for bindings to support translation, publishing `ChannelDescriptionChangedEvent`s and other basic features: `BaseDynamicStateDescriptionProvider` and `BaseDynamicCommandDescriptionProvider`.
 
 The `StateDescriptionFragmentBuilder` (and `CommandDescriptionBuilder`) can be used to only provide the information which is available at the time of construction.
 
@@ -350,16 +350,14 @@ public class ExampleDynamicStateDescriptionProvider implements DynamicStateDescr
 @Component(service = { DynamicStateDescriptionProvider.class, ExampleDynamicStateDescriptionProvider.class })
 public class ExampleDynamicStateDescriptionProvider extends BaseDynamicStateDescriptionProvider {
 
-    @Reference
-    protected void setChannelTypeI18nLocalizationService(
-            final ChannelTypeI18nLocalizationService channelTypeI18nLocalizationService) {
+    @Activate
+    public ExampleDynamicStateDescriptionProvider(final @Reference EventPublisher eventPublisher, //
+            final @Reference ItemChannelLinkRegistry itemChannelLinkRegistry, //
+            final @Reference ChannelTypeI18nLocalizationService channelTypeI18nLocalizationService) {
+        this.eventPublisher = eventPublisher;
+        this.itemChannelLinkRegistry = itemChannelLinkRegistry;
         this.channelTypeI18nLocalizationService = channelTypeI18nLocalizationService;
     }
-
-    protected void unsetChannelTypeI18nLocalizationService(
-            final ChannelTypeI18nLocalizationService channelTypeI18nLocalizationService) {
-        this.channelTypeI18nLocalizationService = null;
-    }
 }
 ```
 
@@ -401,8 +399,12 @@ Therefore the `ThingHandlerFactory` has to reference the bundle instance and pas
 ```java
 public class ExampleHandlerFactory extends BaseThingHandlerFactory {
 
-    @Reference
-    private ExampleDynamicStateDescriptionProvider stateDescriptionProvider;
+    private final ExampleDynamicStateDescriptionProvider stateDescriptionProvider;
+
+    @Activate
+    public ExampleHandlerFactory(final @Reference ExampleDynamicStateDescriptionProvider stateDescriptionProvider) {
+        this.stateDescriptionProvider = stateDescriptionProvider;
+    }
 
     @Override
     protected ThingHandler createHandler(Thing thing) {

developers/utils/events.md

@@ -102,9 +102,12 @@ It contains the old and the new status of the thing.
 
 #### Channel Events
 
-| Event                       | Description                                              | Topic                                         |
-|-----------------------------|----------------------------------------------------------|-----------------------------------------------|
-| ChannelTriggeredEvent       | A channel has been triggered.                            | openhab/channels/{channelUID}/triggered       |
+| Event                          | Description                                                   | Topic                                            |
+|--------------------------------|---------------------------------------------------------------|--------------------------------------------------|
+| ChannelDescriptionChangedEvent | A dynamic `CommandDescription` or `StateDescription` has changed. | openhab/channels/{channelUID}/descriptionchanged |
+| ChannelTriggeredEvent          | A channel has been triggered.                                 | openhab/channels/{channelUID}/triggered          |
+
+The `ChannelDescriptionChangedEvent` will be delivered automatically through the openHAB event bus if the binding implements a `BaseDynamicStateDescriptionProvider` or `BaseDynamicCommandDescriptionProvider` (see [Dynamic State / Command Description section](../bindings/thing-xml.html#dynamic-state-command-description)).
 
 ## Receive Events
 
@@ -116,7 +119,8 @@ Therefore, the `EventSubscriber` interface must be implemented.
 
 ```java
 public class SomeItemEventSubscriber implements EventSubscriber {
-    private final Set<String> subscribedEventTypes = ImmutableSet.of(ItemStateEvent.TYPE, ItemCommandEvent.TYPE);
+
+    private final Set<String> subscribedEventTypes = Set.of(ItemStateEvent.TYPE, ItemCommandEvent.TYPE);
     private final EventFilter eventFiter = new TopicEventFilter("openhab/items/ItemX/.*");
 
     @Override
@@ -192,6 +196,7 @@ The class `org.openhab.core.items.events.AbstractItemEventSubscriber` provides t
 
 ```java
 public class SomeItemEventSubscriber extends AbstractItemEventSubscriber {
+
     private final EventFilter eventFiter = new TopicEventFilter("openhab/items/ItemX/.*");
 
     @Override
@@ -220,21 +225,18 @@ The openHAB core events can only be created via the corresponding event factory.
 
 ```java
 public class SomeComponentWantsToPost {
-    private EventPublisher eventPublisher;
+
+    private final EventPublisher eventPublisher;
+
+    @Activate
+    public SomeComponentWantsToPost(final @Reference EventPublisher eventPublisher) {
+        this.eventPublisher = eventPublisher;
+    }
 
     public void postSomething() {
         ItemCommandEvent itemCommandEvent = ItemEventFactory.createCommandEvent("ItemX", OnOffType.ON);
         eventPublisher.post(itemCommandEvent);
     }
-
-    @Reference
-    public void setEventPublisher(EventPublisher eventPublisher) {
-        this.eventPublisher = eventPublisher;
-    }
-
-    public void unsetEventPublisher(EventPublisher eventPublisher) {
-        this.eventPublisher = null;
-    }
 }
 ```
 
@@ -300,7 +302,7 @@ public class SunEventFactory extends AbstractEventFactory {
     private static final String SUNRISE_EVENT_TOPIC = "openhab/sun/{time}/sunrise";
 
     public SunEventFactory() {
-        super(Sets.newHashSet(SunriseEvent.TYPE);
+        super(Set.of(SunriseEvent.TYPE));
     }
 
     @Override