Package org.openhab.core.thing.binding

Interface ThingHandler

All Known Subinterfaces:
BridgeHandler
All Known Implementing Classes:
BaseBridgeHandler, BaseThingHandler, ConfigStatusBridgeHandler, ConfigStatusThingHandler, MagicActionModuleThingHandler, MagicBridgedThingHandler, MagicBridgeHandler, MagicButtonHandler, MagicChattyThingHandler, MagicColorLightHandler, MagicConfigurableThingHandler, MagicContactHandler, MagicDelayedOnlineHandler, MagicDimmableLightHandler, MagicDynamicStateDescriptionThingHandler, MagicExtensibleThingHandler, MagicFirmwareUpdateThingHandler, MagicImageHandler, MagicLocationThingHandler, MagicOnlineOfflineHandler, MagicOnOffLightHandler, MagicPlayerHandler, MagicRollershutterHandler, MagicThermostatThingHandler, MagicTimeSeriesHandler
@NonNullByDefault public interface ThingHandler
A ThingHandler handles the communication between the openHAB framework and an entity from the real world, e.g. a physical device, a web service, etc. represented by a Thing.

The communication is bidirectional. The framework informs a thing handler about commands, state and configuration updates, and so on, by the corresponding handler methods. The handler can notify the framework about changes like state and status updates, updates of the whole thing, by a ThingHandlerCallback.

Author:
Dennis Nobel - Initial contribution, Michael Grammling - Added dynamic configuration update, Thomas Höfer - Added config description validation exception to handleConfigurationUpdate operation, Stefan Bußweiler - API changes due to bridge/thing life cycle refactoring, Stefan Triller - added getServices method

  • Method Details

    • getThing

      Thing getThing()
      Returns the Thing, which belongs to the handler.
      Returns:
      Thing, which belongs to the handler

    • initialize

      void initialize()
      Initializes the thing handler, e.g. update thing status, allocate resources, transfer configuration.

      This method is only called, if the Thing contains all required configuration parameters.

      Only Things with status ThingStatus.UNKNOWN, ThingStatus.ONLINE or ThingStatus.OFFLINE are considered as initialized by the framework. To achieve that, the status must be reported via ThingHandlerCallback.statusUpdated(Thing, ThingStatusInfo).

      The framework expects this method to be non-blocking and return quickly. For longer running initializations, the implementation has to take care of scheduling a separate job which must guarantee to set the thing status eventually.

      Any anticipated error situations should be handled gracefully and need to result in ThingStatus.OFFLINE with the corresponding status detail (e.g. *COMMUNICATION_ERROR* or *CONFIGURATION_ERROR* including a meaningful description) instead of throwing exceptions.

    • dispose

      void dispose()
      Disposes the thing handler, e.g. deallocate resources.

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

    • setCallback

      void setCallback(@Nullable ThingHandlerCallback thingHandlerCallback)
      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 initialize() is called. The callback is removed (set to null) after the handler instance is no longer tracked and after dispose() is called.

      Parameters:
      thingHandlerCallback - the callback (can be null)

    • handleCommand

      void handleCommand(ChannelUID channelUID, Command command)
      Handles a command for a given channel.

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

      Parameters:
      channelUID - the ChannelUID of the channel to which the command was sent
      command - the Command

    • handleConfigurationUpdate

      void handleConfigurationUpdate(Map<String,Object> configurationParameters)
      Handles a configuration update.

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

      Parameters:
      configurationParameters - map of changed configuration parameters
      Throws:
      ConfigValidationException - if one or more of the given configuration parameters do not match their declarations in the configuration description

    • thingUpdated

      void thingUpdated(Thing thing)
      Notifies the handler about an updated Thing.

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

      Parameters:
      thing - the Thing, that has been updated

    • channelLinked

      void channelLinked(ChannelUID channelUID)
      Notifies the handler that a channel was linked.

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

      Parameters:
      channelUID - UID of the linked channel

    • channelUnlinked

      void channelUnlinked(ChannelUID channelUID)
      Notifies the handler that a channel was unlinked.

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

      Parameters:
      channelUID - UID of the unlinked channel

    • bridgeStatusChanged

      void bridgeStatusChanged(ThingStatusInfo bridgeStatusInfo)
      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.

      Parameters:
      bridgeStatusInfo - the status info of the bridge

    • handleRemoval

      void handleRemoval()
      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.

    • getServices

      default Collection<Class<? extends ThingHandlerService>> getServices()
      This method provides a list of classes which should be registered as services by the framework
      Returns:
      - list of classes that will be registered as OSGi services