Package org.openhab.core.thing.binding

Class BaseThingHandler

java.lang.Object
org.openhab.core.thing.binding.BaseThingHandler
All Implemented Interfaces:
ThingHandler
Direct Known Subclasses:
BaseBridgeHandler, ConfigStatusThingHandler, MagicActionModuleThingHandler, MagicBridgedThingHandler, MagicButtonHandler, MagicChattyThingHandler, MagicColorLightHandler, MagicConfigurableThingHandler, MagicContactHandler, MagicDelayedOnlineHandler, MagicDimmableLightHandler, MagicDynamicStateDescriptionThingHandler, MagicExtensibleThingHandler, MagicFirmwareUpdateThingHandler, MagicImageHandler, MagicLocationThingHandler, MagicOnlineOfflineHandler, MagicOnOffLightHandler, MagicPlayerHandler, MagicRollershutterHandler, MagicThermostatThingHandler, MagicTimeSeriesHandler
@NonNullByDefault public abstract class BaseThingHandler extends Object implements ThingHandler
BaseThingHandler provides a base implementation for the ThingHandler interface.

The default behavior for Thing updates is to dispose() this handler first, exchange the Thing and ThingHandler.initialize() it again. Override the method thingUpdated(Thing) to change the default behavior.

It is recommended to extend this abstract base class, because it covers a lot of common logic.

Author:
Dennis Nobel - Initial contribution, Michael Grammling - Added dynamic configuration update, Thomas Höfer - Added thing properties and config description validation, Stefan Bußweiler - Added new thing status handling, refactorings thing/bridge life cycle, Kai Kreuzer - Refactored isLinked method to not use deprecated functions anymore, Christoph Weitkamp - Moved OSGI ServiceTracker from BaseThingHandler to ThingHandlerCallback, Jan N. Klug - added time series support

  • Field Details

  • Constructor Details

    • BaseThingHandler

      public BaseThingHandler(Thing thing)
      Creates a new instance of this class for the Thing.
      Parameters:
      thing - the thing that should be handled, not null

  • Method Details

    • handleRemoval

      public void handleRemoval()
      Description copied from interface: ThingHandler
      This method is called before a thing is removed. An implementing class can handle the removal in order to trigger some tidying work for a thing.

      The framework expects this method to be non-blocking and return quickly. For longer running tasks, the implementation has to take care of scheduling a separate job.

      The Thing is in ThingStatus.REMOVING when this method is called. Implementations of this method must signal to the framework that the handling has been completed by setting the Things state to ThingStatus.REMOVED. Only then it will be removed completely.

      Specified by:
      handleRemoval in interface ThingHandler

    • handleConfigurationUpdate

      public void handleConfigurationUpdate(Map<String,Object> configurationParameters)
      Description copied from interface: ThingHandler
      Handles a configuration update.

      Note: An implementing class needs to persist the configuration changes if necessary.

      Specified by:
      handleConfigurationUpdate in interface ThingHandler
      Parameters:
      configurationParameters - map of changed configuration parameters

    • isModifyingCurrentConfig

      protected boolean isModifyingCurrentConfig(Map<String,Object> configurationParameters)
      Checks whether a given list of parameters would mean any change to the existing Thing configuration if applied to it. Note that the passed parameters might be a subset of the existing configuration.
      Parameters:
      configurationParameters - the parameters to check against the current configuration
      Returns:
      true if the parameters would result in a modified configuration, false otherwise

    • dispose

      public void dispose()
      Description copied from interface: ThingHandler
      Disposes the thing handler, e.g. deallocate resources.

      The framework expects this method to be non-blocking and return quickly.

      Specified by:
      dispose in interface ThingHandler

    • getThing

      public Thing getThing()
      Description copied from interface: ThingHandler
      Returns the Thing, which belongs to the handler.
      Specified by:
      getThing in interface ThingHandler
      Returns:
      Thing, which belongs to the handler

    • thingUpdated

      public void thingUpdated(Thing thing)
      Description copied from interface: ThingHandler
      Notifies the handler about an updated Thing.

      This method will only be called once the ThingHandler.initialize() method returned.

      Specified by:
      thingUpdated in interface ThingHandler
      Parameters:
      thing - the Thing, that has been updated

    • setCallback

      public void setCallback(@Nullable ThingHandlerCallback thingHandlerCallback)
      Description copied from interface: ThingHandler
      Sets the ThingHandlerCallback of the handler, which must be used to inform the framework about changes.

      The callback is added after the handler instance has been tracked by the framework and before ThingHandler.initialize() is called. The callback is removed (set to null) after the handler instance is no longer tracked and after ThingHandler.dispose() is called.

      Specified by:
      setCallback in interface ThingHandler
      Parameters:
      thingHandlerCallback - the callback (can be null)

    • getCallback

      protected @Nullable ThingHandlerCallback getCallback()
      Get the ThingHandlerCallback instance.
      Returns:
      the ThingHandlerCallback instance. Only returns null while the handler is not initialized.

    • channelLinked

      public void channelLinked(ChannelUID channelUID)
      Description copied from interface: ThingHandler
      Notifies the handler that a channel was linked.

      This method is only called, if the thing has been initialized (status ONLINE/OFFLINE/UNKNOWN).

      Specified by:
      channelLinked in interface ThingHandler
      Parameters:
      channelUID - UID of the linked channel

    • channelUnlinked

      public void channelUnlinked(ChannelUID channelUID)
      Description copied from interface: ThingHandler
      Notifies the handler that a channel was unlinked.

      This method is only called, if the thing has been initialized (status ONLINE/OFFLINE/UNKNOWN).

      Specified by:
      channelUnlinked in interface ThingHandler
      Parameters:
      channelUID - UID of the unlinked channel

    • validateConfigurationParameters

      protected void validateConfigurationParameters(Map<String,Object> configurationParameters)
      Validates the given configuration parameters against the configuration description.
      Parameters:
      configurationParameters - the configuration parameters to be validated
      Throws:
      ConfigValidationException - if one or more of the given configuration parameters do not match their declarations in the configuration description

    • getConfigDescription

      protected @Nullable ConfigDescription getConfigDescription()
      Get the ConfigDescription of the thing
      Returns:
      the config description (or null if not found or handler disposed)

    • getConfigDescription

      protected @Nullable ConfigDescription getConfigDescription(ChannelTypeUID channelTypeUID)
      Get the ConfigDescription for a ChannelTypeUID
      Returns:
      the config description (or null if not found or handler disposed)

    • getConfig

      protected Configuration getConfig()
      Returns the configuration of the thing.
      Returns:
      configuration of the thing

    • getConfigAs

      protected <T> T getConfigAs(Class<T> configurationClass)
      Returns the configuration of the thing and transforms it to the given class.
      Parameters:
      configurationClass - configuration class
      Returns:
      configuration of thing in form of the given class

    • updateState

      protected void updateState(ChannelUID channelUID, State state)
      Updates the state of the thing.
      Parameters:
      channelUID - unique id of the channel, which was updated
      state - new state

    • updateState

      protected void updateState(String channelID, State state)
      Updates the state of the thing. Will use the thing UID to infer the unique channel UID from the given ID.
      Parameters:
      channelID - id of the channel, which was updated
      state - new state

    • sendTimeSeries

      protected void sendTimeSeries(ChannelUID channelUID, TimeSeries timeSeries)
      Send a time series to the channel. This can be used to transfer historic data or forecasts.
      Parameters:
      channelUID - unique id of the channel
      timeSeries - the TimeSeries that is sent

    • sendTimeSeries

      protected void sendTimeSeries(String channelID, TimeSeries timeSeries)
      Send a time series to the channel. This can be used to transfer historic data or forecasts.
      Parameters:
      channelID - id of the channel
      timeSeries - the TimeSeries that is sent

    • triggerChannel

      protected void triggerChannel(ChannelUID channelUID, String event)
      Emits an event for the given channel.
      Parameters:
      channelUID - UID of the channel over which the event will be emitted
      event - Event to emit

    • triggerChannel

      protected void triggerChannel(String channelID, String event)
      Emits an event for the given channel. Will use the thing UID to infer the unique channel UID from the given ID.
      Parameters:
      channelID - ID of the channel over which the event will be emitted
      event - Event to emit

    • triggerChannel

      protected void triggerChannel(String channelUID)
      Emits an event for the given channel. Will use the thing UID to infer the unique channel UID.
      Parameters:
      channelUID - UID of the channel over which the event will be emitted

    • triggerChannel

      protected void triggerChannel(ChannelUID channelUID)
      Emits an event for the given channel. Will use the thing UID to infer the unique channel UID.
      Parameters:
      channelUID - UID of the channel over which the event will be emitted

    • postCommand

      protected void postCommand(String channelID, Command command)
      Sends a command for a channel of the thing.
      Parameters:
      channelID - id of the channel, which sends the command
      command - command

    • postCommand

      protected void postCommand(ChannelUID channelUID, Command command)
      Sends a command for a channel of the thing.
      Parameters:
      channelUID - unique id of the channel, which sends the command
      command - command

    • updateStatus

      protected void updateStatus(ThingStatus status, ThingStatusDetail statusDetail, @Nullable String description)
      Updates the status of the thing.
      Parameters:
      status - the status
      statusDetail - the detail of the status
      description - the description of the status

    • updateStatus

      protected void updateStatus(ThingStatus status, ThingStatusDetail statusDetail)
      Updates the status of the thing.
      Parameters:
      status - the status
      statusDetail - the detail of the status

    • updateStatus

      protected void updateStatus(ThingStatus status)
      Updates the status of the thing. The detail of the status will be 'NONE'.
      Parameters:
      status - the status

    • editThing

      protected ThingBuilder editThing()
      Creates a thing builder, which allows to modify the thing. The method updateThing(Thing) must be called to persist the changes.
      Returns:
      ThingBuilder which builds an exact copy of the thing (not null)

    • updateThing

      protected void updateThing(Thing thing)
      Informs the framework, that a thing was updated. This method must be called after the configuration or channels was changed. Any method overriding this method has to make sure that only things with valid configurations are passed to the callback. This can be achieved by calling ThingHandlerCallback.validateConfigurationParameters(Thing, Map). It is also necessary to ensure that all channel configurations are valid by calling ThingHandlerCallback.validateConfigurationParameters(Channel, Map).
      Parameters:
      thing - thing, that was updated and should be persisted

    • editConfiguration

      protected Configuration editConfiguration()
      Returns a copy of the configuration, that can be modified. The method updateConfiguration(Configuration) must be called to persist the configuration.
      Returns:
      copy of the thing configuration (not null)

    • updateConfiguration

      protected void updateConfiguration(Configuration configuration)
      Updates the configuration of the thing and informs the framework about it. Any method overriding this method has to make sure that only valid configurations are passed to the callback. This can be achieved by calling ThingHandlerCallback.validateConfigurationParameters(Thing, Map).
      Parameters:
      configuration - configuration, that was updated and should be persisted

    • editProperties

      protected Map<String,String> editProperties()
      Returns a copy of the properties map, that can be modified. The method updateProperties(Map) must be called to persist the properties.
      Returns:
      copy of the thing properties (not null)

    • updateProperties

      protected void updateProperties(@Nullable Map<String,String> properties)
      Informs the framework, that the given properties map of the thing was updated. This method performs a check, if the properties were updated. If the properties did not change, the framework is not informed about changes.
      Parameters:
      properties - properties map, that was updated and should be persisted (all properties cleared if null)

    • updateProperty

      protected void updateProperty(String name, @Nullable String value)

      Updates the given property value for the thing that is handled by this thing handler instance. The value is only set for the given property name if there has not been set any value yet or if the value has been changed. If the value of the property to be set is null then the property is removed. This method also informs the framework about the updated thing, which in fact will persists the changes. So, if multiple properties should be changed at the same time, the editProperties() method should be used.

      Parameters:
      name - the name of the property to be set
      value - the value of the property

    • getBridge

      protected @Nullable Bridge getBridge()
      Returns the bridge of the thing.
      Returns:
      returns the bridge of the thing or null if the thing has no bridge

    • isLinked

      protected boolean isLinked(String channelId)
      Returns whether at least one item is linked for the given channel ID.
      Parameters:
      channelId - channel ID (must not be null)
      Returns:
      true if at least one item is linked, false otherwise

    • isLinked

      protected boolean isLinked(ChannelUID channelUID)
      Returns whether at least one item is linked for the given UID of the channel.
      Parameters:
      channelUID - UID of the channel (must not be null)
      Returns:
      true if at least one item is linked, false otherwise

    • isInitialized

      protected boolean isInitialized()
      Returns whether the handler has already been initialized.
      Returns:
      true if handler is initialized, false otherwise

    • bridgeStatusChanged

      public void bridgeStatusChanged(ThingStatusInfo bridgeStatusInfo)
      Description copied from interface: ThingHandler
      Notifies the handler that the bridge's status has changed.

      This method is called, when the status of the bridge has been changed to ThingStatus.ONLINE, ThingStatus.OFFLINE or ThingStatus.UNKNOWN, i.e. after a bridge has been initialized. If the thing of this handler does not have a bridge, this method is never called.

      If the bridge's status has changed to ThingStatus.OFFLINE, the status of the handled thing must be updated to ThingStatus.OFFLINE with detail ThingStatusDetail.BRIDGE_OFFLINE. If the bridge returns to ThingStatus.ONLINE, the thing status must be changed at least to ThingStatus.OFFLINE with detail ThingStatusDetail.NONE.

      Specified by:
      bridgeStatusChanged in interface ThingHandler
      Parameters:
      bridgeStatusInfo - the status info of the bridge

    • changeThingType

      protected void changeThingType(ThingTypeUID thingTypeUID, Configuration configuration)