From cececf35a376349fb25078d277b3309bd1f6cdf2 Mon Sep 17 00:00:00 2001 From: Christoph Weitkamp Date: Mon, 16 Dec 2019 20:39:50 +0100 Subject: [PATCH] Added information about 'ItemStatePredictedEvent' and 'GroupItemStateChangedEvent' (#1100) - Added information about `ItemStatePredictedEvent` and `GroupItemStateChangedEvent` - Applied some linter Signed-off-by: Christoph Weitkamp --- developers/utils/events.md | 94 ++++++++++++++++++-------------------- 1 file changed, 45 insertions(+), 49 deletions(-) diff --git a/developers/utils/events.md b/developers/utils/events.md index eea549d3a..a6c6803fb 100644 --- a/developers/utils/events.md +++ b/developers/utils/events.md @@ -28,74 +28,79 @@ The `EventSubscriber` defines the callback interface to receive events of speci The EventPublisher and the EventSubscribers are registered as OSGi services. An event subscriber can provide an `EventFilter` in order to filter events based on the topic or the content. If there is no filter all subscribed event types are received. -The event itself will be subclassed for each event type, which exists in the System (e.g. ItemCommandEvent, ItemUpdatedEvent, ThingStatusInfoEvent). +The event itself will be subclassed for each event type, which exists in the System (e.g. `ItemCommandEvent`, `ItemUpdatedEvent`, `ThingStatusInfoEvent`). ### The Core Events This section lists the core events provided by openHAB which can be divided into the categories _Item Events_, _Thing Events_ and _Inbox Events_. An event consists of a `topic`, a `type`, a `payload` and a `source`. -The payload can be serialized with any String representation and is determined by its concrete event type implementation (e.g. ItemCommandEvent, ItemUpdatedEvent). +The payload can be serialized with any String representation and is determined by its concrete event type implementation (e.g. `ItemCommandEvent`, `ItemUpdatedEvent`). The payloads of the openHAB core events are serialized with JSON. Each event implementation provides the payload as high level methods as well, usually presented by a data transfer object (DTO). A topic clearly defines the target of the event and its structure is similar to a REST URI, except the last part, the action. The topics of openHAB events are divided into the following four parts: `{namespace}/{entityType}/{entity}/{action}`, e.g. `smarthome/items/{itemName}/command`. -The type of an event is represented by a string, usually the name of the concrete event implementation class, e.g. ItemCommandEvent, ItemUpdatedEvent. +The type of an event is represented by a string, usually the name of the concrete event implementation class, e.g. `ItemCommandEvent`, `ItemUpdatedEvent` . This string type presentation is used by event subscribers for event subscription (see chapter "Receive Events") and by the framework for the creation of concrete event instances. The event source is optional and represents the name of the source identifying the sender. #### Item Events -| Event |Description |Topic | -|-----------------------|-------------------------------------------------|----------------------------------------| -| ItemAddedEvent |An item has been added to the item registry. |smarthome/items/{itemName}/added | -| ItemRemovedEvent |An item has been removed from the item registry. |smarthome/items/{itemName}/removed | -| ItemUpdatedEvent |An item has been updated in the item registry. |smarthome/items/{itemName}/updated | -| ItemCommandEvent |A command is sent to an item via a channel. |smarthome/items/{itemName}/command | -| ItemStateEvent |The state of an item is updated. |smarthome/items/{itemName}/state | -| ItemStateChangedEvent |The state of an item has changed. |smarthome/items/{itemName}/statechanged | +| Event | Description | Topic | +|----------------------------|---------------------------------------------------------|------------------------------------------------------| +| ItemAddedEvent | An item has been added to the item registry. | smarthome/items/{itemName}/added | +| ItemRemovedEvent | An item has been removed from the item registry. | smarthome/items/{itemName}/removed | +| ItemUpdatedEvent | An item has been updated in the item registry. | smarthome/items/{itemName}/updated | +| ItemCommandEvent | A command is sent to an item via a channel. | smarthome/items/{itemName}/command | +| ItemStateEvent | The state of an item is updated. | smarthome/items/{itemName}/state | +| ItemStatePredictedEvent | The state of an item predicted to be updated. | smarthome/items/{itemName}/statepredicted | +| ItemStateChangedEvent | The state of an item has changed. | smarthome/items/{itemName}/statechanged | +| GroupItemStateChangedEvent | The state of a group item has changed through a member. | smarthome/items/{itemName}/{memberName}/statechanged | -**Note:** The ItemStateEvent is always sent if the state of an item is updated, even if the state did not change. -ItemStateChangedEvent is sent only if the state of an item was really changed. +**Note:** The `ItemStateEvent` is always sent if the state of an item is updated, even if the state did not change. +`ItemStateChangedEvent` is sent only if the state of an item was really changed. It contains the old and the new state of the item. +The `GroupItemStateChangedEvent` is sent only if the state of a group item was changed by a member. +It contains the old and the new state of the group item as well as the member. + #### Thing Events -| Event |Description |Topic | -|-----------------------|-------------------------------------------------|-----------------------------------| -| ThingAddedEvent |A thing has been added to the thing registry. |smarthome/things/{thingUID}/added | -| ThingRemovedEvent |A thing has been removed from the thing registry.|smarthome/things/{thingUID}/removed| -| ThingUpdatedEvent |A thing has been updated in the thing registry. |smarthome/things/{thingUID}/updated| -| ThingStatusInfoEvent |The status of a thing is updated. |smarthome/things/{thingUID}/status | -| ThingStatusInfoChangedEvent |The status of a thing changed. |smarthome/things/{thingUID}/statuschanged | +| Event | Description | Topic | +|-----------------------------|---------------------------------------------------|-------------------------------------------| +| ThingAddedEvent | A thing has been added to the thing registry. | smarthome/things/{thingUID}/added | +| ThingRemovedEvent | A thing has been removed from the thing registry. | smarthome/things/{thingUID}/removed | +| ThingUpdatedEvent | A thing has been updated in the thing registry. | smarthome/things/{thingUID}/updated | +| ThingStatusInfoEvent | The status of a thing is updated. | smarthome/things/{thingUID}/status | +| ThingStatusInfoChangedEvent | The status of a thing changed. | smarthome/things/{thingUID}/statuschanged | -**Note:** The ThingStatusInfoEvent is always sent if the status info of a thing is updated, even if the status did not change. -ThingStatusInfoChangedEvent is sent only if the status of a thing was really changed. +**Note:** The `ThingStatusInfoEvent` is always sent if the status info of a thing is updated, even if the status did not change. +`ThingStatusInfoChangedEvent` is sent only if the status of a thing was really changed. It contains the old and the new status of the thing. #### Inbox Events -| Event |Description |Topic | -|-----------------------|---------------------------------------------------|-----------------------------------| -| InboxAddedEvent |A discovery result has been added to the inbox. |smarthome/inbox/{thingUID}/added | -| InboxRemovedEvent |A discovery result has been removed from the inbox. |smarthome/inbox/{thingUID}/removed | -| InboxUpdateEvent |A discovery result has been updated in the inbox. |smarthome/inbox/{thingUID}/updated | +| Event | Description | Topic | +|-----------------------|-----------------------------------------------------|------------------------------------| +| InboxAddedEvent | A discovery result has been added to the inbox. | smarthome/inbox/{thingUID}/added | +| InboxRemovedEvent | A discovery result has been removed from the inbox. | smarthome/inbox/{thingUID}/removed | +| InboxUpdateEvent | A discovery result has been updated in the inbox. | smarthome/inbox/{thingUID}/updated | #### Link Events -| Event |Description |Topic | -|-----------------------------|---------------------------------------------------------|------------------------------------------------| -| ItemChannelLinkAddedEvent |An item channel link has been added to the registry. |smarthome/links/{itemName}-{channelUID}/added | -| ItemChannelLinkRemovedEvent |An item channel link has been removed from the registry. |smarthome/links/{itemName}-{channelUID}/removed | +| Event | Description | Topic | +|-----------------------------|----------------------------------------------------------|-------------------------------------------------| +| ItemChannelLinkAddedEvent | An item channel link has been added to the registry. | smarthome/links/{itemName}-{channelUID}/added | +| ItemChannelLinkRemovedEvent | An item channel link has been removed from the registry. | smarthome/links/{itemName}-{channelUID}/removed | #### Channel Events -| Event |Description |Topic | -|-----------------------------|---------------------------------------------------------|------------------------------------------------| -| ChannelTriggeredEvent |A channel has been triggered. |smarthome/channels/{channelUID}/triggered | +| Event | Description | Topic | +|-----------------------------|----------------------------------------------------------|-------------------------------------------------| +| ChannelTriggeredEvent | A channel has been triggered. | smarthome/channels/{channelUID}/triggered | ## Receive Events @@ -145,7 +150,7 @@ To subscribe to all available event types, use the public member `ALL_EVENT_TYPE The event subscriber provides a `TopicEventFilter` which is a default openHAB `EventFilter` implementation that ensures filtering of events based on a topic. The argument of the filter is a [Java regular expression](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html). -The filter method `EventFilter.apply()` will be called for each event on the event bus to which the event subscriber is subscribed (in the example above ItemStateEvent and ItemCommandEvent). +The filter method `EventFilter.apply()` will be called for each event on the event bus to which the event subscriber is subscribed (in the example above `ItemStateEvent` and `ItemCommandEvent`). If the filter applies (in the given example for all item events with the item name "ItemX"), the event will be received by the `EventSubscriber.receive()` method. Received events can be cast to the event implementation class for further processing. @@ -165,7 +170,7 @@ The listing below summarizes some best practices in order to implement event sub - To subscribe to only one event type openHAB provides the `org.eclipse.smarthome.core.events.AbstractTypedEventSubscriber` implementation. To receive an already cast event the `receiveTypedEvent(T)` method must be implemented. To provide an event filter the method `getEventFilter()` can be overridden. -- openHAB provides an `AbstractItemEventSubscriber` class in order to receive ItemStateEvents and ItemCommandEvents (more information can be obtained in the next chapter). +- openHAB provides an `AbstractItemEventSubscriber` class in order to receive `ItemStateEvents` and `ItemCommandEvents` (more information can be obtained in the next chapter). - To filter events based on a topic the `org.eclipse.smarthome.core.events.TopicEventFilter` implementation from the openHAB core bundle can be used. The filtering is based on [Java regular expression](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html). - The subscribed event types and the filter should be stored as class members (see example above) due to performance reasons. @@ -177,10 +182,9 @@ Thrown exceptions will be handled in the framework by logging an error message w - The receive method should terminate quickly, since it blocks other event subscribers. Create a thread for long running operations. - ### Receive ItemStateEvents and ItemCommandEvents -Due to the fact that receiving ItemStateEvents and ItemCommandEvents is a common use case, openHAB provides an abstract event subscriber implementation via the core bundle. +Due to the fact that receiving `ItemStateEvents` and `ItemCommandEvents` is a common use case, openHAB provides an abstract event subscriber implementation via the core bundle. The class `org.eclipse.smarthome.core.items.events.AbstractItemEventSubscriber` provides two methods `receiveUpdate(ItemStateEvent)` and `receiveCommand(ItemCommandEvent)` which can be implemented in order to receive and handle such events. ```java @@ -207,8 +211,8 @@ public class SomeItemEventSubscriber extends AbstractItemEventSubscriber { ## Send Events Usually the core events are only sent by the openHAB framework. -However, it is possible to sent events explicitly, e.g. ItemCommandEvents and ItemStateEvents. -The Java snippet below illustrates how to send events via the EventPublisher. +However, it is possible to sent events explicitly, e.g. `ItemCommandEvent`s and `ItemStateEvent`s. +The Java snippet below illustrates how to send events via the `EventPublisher`. The openHAB core events can only be created via the corresponding event factory. ```java @@ -230,15 +234,7 @@ public class SomeComponentWantsToPost { } ``` -The EventPublisher will be injected via OSGi Declarative Services. - -```xml - - - - -``` +The `EventPublisher` will be injected via OSGi Declarative Services. ## Define new Event Types