Interface ThingHandler

    • Method Detail

      • 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
      • handleUpdate

        @Deprecated
        void handleUpdate​(ChannelUID channelUID,
                          State newState)
        Deprecated.
        in favor of using a "slave" profile. Will be removed before a 1.0 release. Bindings must not implement this method!
        Handles a State update 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 on which the update was performed
        newState - the new State
      • 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
      • 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