Added information about 'ItemStatePredictedEvent' and 'GroupItemStateChangedEvent' (#1100)
- Added information about `ItemStatePredictedEvent` and `GroupItemStateChangedEvent` - Applied some linter Signed-off-by: Christoph Weitkamp <github@christophweitkamp.de>pull/1103/head
Christoph Weitkamp
Jerome Luckenbach
parent
3a001d850b
commit
cececf35a3
|
|
@ -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
|
||||
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" immediate="true" name="SomeComponentWantsToPost">
|
||||
<!-- ... -->
|
||||
<reference bind="setEventPublisher" cardinality="1..1" interface="org.eclipse.smarthome.core.events.EventPublisher"
|
||||
name="EventPublisher" policy="static" unbind="unsetEventPublisher"/>
|
||||
</scr:component>
|
||||
```
|
||||
The `EventPublisher` will be injected via OSGi Declarative Services.
|
||||
|
||||
## Define new Event Types
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue