Class BaseThingHandler

    • Constructor Detail

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

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

        @Deprecated
        public void handleUpdate​(ChannelUID channelUID,
                                 State newState)
        Deprecated.
        Description copied from interface: ThingHandler
        Handles a State update for a given channel.

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

        Specified by:
        handleUpdate in interface ThingHandler
        Parameters:
        channelUID - the ChannelUID of the channel on which the update was performed
        newState - the new State
      • initialize

        @Deprecated
        public void initialize()
        Deprecated.
        Description copied from interface: ThingHandler
        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.

        Specified by:
        initialize in interface ThingHandler
      • 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)
      • 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
      • 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:
        channel - ID id of the channel, which was updated
        state - new state
      • 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.
        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.
        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 BaseThingHandler#updateProperties(Map properties) must be called to persist the properties.
        Returns:
        copy of the thing properties (not null)
      • updateProperties

        protected void updateProperties​(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
      • updateProperty

        protected void updateProperty​(String name,
                                      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