Class AbstractDiscoveryService

  • All Implemented Interfaces:
    DiscoveryService

    @NonNullByDefault
    public abstract class AbstractDiscoveryService
    extends Object
    implements DiscoveryService
    The AbstractDiscoveryService provides methods which handle the DiscoveryListeners. Subclasses do not have to care about adding and removing those listeners. They can use the protected methods thingDiscovered(DiscoveryResult) and #thingRemoved(String) in order to notify the registered DiscoveryListeners.
    Author:
    Oliver Libutzki - Initial contribution, Kai Kreuzer - Refactored API, Dennis Nobel - Added background discovery configuration through Configuration Admin, Andre Fuechsel - Added removeOlderResults
    • Constructor Detail

      • AbstractDiscoveryService

        public AbstractDiscoveryService​(@Nullable Set<ThingTypeUID> supportedThingTypes,
                                        int timeout,
                                        boolean backgroundDiscoveryEnabledByDefault)
                                 throws IllegalArgumentException
        Creates a new instance of this class with the specified parameters.
        Parameters:
        supportedThingTypes - the list of Thing types which are supported (can be null)
        timeout - the discovery timeout in seconds after which the discovery service automatically stops its forced discovery process (>= 0).
        backgroundDiscoveryEnabledByDefault - defines, whether the default for this discovery service is to enable background discovery or not.
        Throws:
        IllegalArgumentException - if the timeout < 0
      • AbstractDiscoveryService

        public AbstractDiscoveryService​(@Nullable Set<ThingTypeUID> supportedThingTypes,
                                        int timeout)
                                 throws IllegalArgumentException
        Creates a new instance of this class with the specified parameters and background discovery enabled.
        Parameters:
        supportedThingTypes - the list of Thing types which are supported (can be null)
        timeout - the discovery timeout in seconds after which the discovery service automatically stops its forced discovery process (>= 0). If set to 0, disables the automatic stop.
        Throws:
        IllegalArgumentException - if the timeout < 0
      • AbstractDiscoveryService

        public AbstractDiscoveryService​(int timeout)
                                 throws IllegalArgumentException
        Creates a new instance of this class with the specified parameters and background discovery enabled.
        Parameters:
        timeout - the discovery timeout in seconds after which the discovery service automatically stops its forced discovery process (>= 0). If set to 0, disables the automatic stop.
        Throws:
        IllegalArgumentException - if the timeout < 0
    • Method Detail

      • getScanTimeout

        public int getScanTimeout()
        Returns the amount of time in seconds after which the discovery service automatically stops its forced discovery process.
        Specified by:
        getScanTimeout in interface DiscoveryService
        Returns:
        the discovery timeout in seconds (>= 0).
      • isBackgroundDiscoveryEnabled

        public boolean isBackgroundDiscoveryEnabled()
        Description copied from interface: DiscoveryService
        Returns true if the background discovery mode is enabled, otherwise false.
        Specified by:
        isBackgroundDiscoveryEnabled in interface DiscoveryService
        Returns:
        true if the background discovery mode is enabled, otherwise false
      • addDiscoveryListener

        public void addDiscoveryListener​(@Nullable DiscoveryListener listener)
        Description copied from interface: DiscoveryService
        Adds a DiscoveryListener to the listeners' registry.

        Directly after registering the listener, it will receive DiscoveryListener.thingDiscovered(DiscoveryService, DiscoveryResult) notifications about all devices that have been previously discovered by the service already (tracker behaviour). This is also done, if the listener has already been registered previously.

        When a DiscoveryResult is created while the discovery process is active (e.g. by starting a scan or through the enabled background discovery mode), the specified listener is notified.

        This method returns silently if the specified listener is null.

        Specified by:
        addDiscoveryListener in interface DiscoveryService
        Parameters:
        listener - the listener to be added (could be null)
      • removeDiscoveryListener

        public void removeDiscoveryListener​(@Nullable DiscoveryListener listener)
        Description copied from interface: DiscoveryService
        Removes a DiscoveryListener from the listeners' registry.

        When this method returns, the specified listener is no longer notified about a created DiscoveryResult while the discovery process is active (e.g. by forcing the startup of the discovery process or while enabling the auto discovery mode)

        This method returns silently if the specified listener is null or has not been registered before.

        Specified by:
        removeDiscoveryListener in interface DiscoveryService
        Parameters:
        listener - the listener to be removed (could be null)
      • startScan

        public void startScan​(@Nullable ScanListener listener)
        Description copied from interface: DiscoveryService
        Triggers this service to start an active scan for new devices.
        This method must not block any calls such as DiscoveryService.abortScan() and must return fast.

        If started, any registered DiscoveryListener must be notified about DiscoveryResults.

        If there is already a scan running, it is aborted and a new scan is triggered.

        Specified by:
        startScan in interface DiscoveryService
        Parameters:
        listener - a listener that is notified about errors or termination of the scan
      • abortScan

        public void abortScan()
        Description copied from interface: DiscoveryService
        Stops an active scan for devices.
        This method must not block any calls such as #startScan() and must return fast.

        After this method returns, no further notifications about DiscoveryResults are allowed to be sent to any registered listener, exceptional the background discovery mode is active.

        This method returns silently, if the scan has not been started before.

        Specified by:
        abortScan in interface DiscoveryService
      • startScan

        protected abstract void startScan()
        This method is called by the {@link #startScan(ScanListener))} implementation of the AbstractDiscoveryService. The abstract class schedules a call of stopScan() after getScanTimeout() seconds. If this behavior is not appropriate, the {@link #startScan(ScanListener))} method should be overridden.
      • stopScan

        protected void stopScan()
        This method cleans up after a scan, i.e. it removes listeners and other required operations.
      • thingDiscovered

        protected void thingDiscovered​(DiscoveryResult discoveryResult)
        Notifies the registered DiscoveryListeners about a discovered device.
        Parameters:
        discoveryResult - Holds the information needed to identify the discovered device.
      • thingRemoved

        protected void thingRemoved​(ThingUID thingUID)
        Notifies the registered DiscoveryListeners about a removed device.
        Parameters:
        thingUID - The UID of the removed thing.
      • removeOlderResults

        protected void removeOlderResults​(long timestamp)
        Call to remove all results of all supportedThingTypes that are older than the given timestamp. To remove all left over results after a full scan, this method could be called getTimestampOfLastScan() as timestamp.
        Parameters:
        timestamp - timestamp, older results will be removed
      • removeOlderResults

        protected void removeOlderResults​(long timestamp,
                                          @Nullable ThingUID bridgeUID)
        Call to remove all results of all supportedThingTypes that are older than the given timestamp. To remove all left over results after a full scan, this method could be called getTimestampOfLastScan() as timestamp.
        Parameters:
        timestamp - timestamp, older results will be removed
        bridgeUID - if not null only results of that bridge are being removed
      • removeOlderResults

        protected void removeOlderResults​(long timestamp,
                                          @Nullable Collection<ThingTypeUID> thingTypeUIDs,
                                          @Nullable ThingUID bridgeUID)
        Call to remove all results of the given types that are older than the given timestamp. To remove all left over results after a full scan, this method could be called getTimestampOfLastScan() as timestamp.
        Parameters:
        timestamp - timestamp, older results will be removed
        thingTypeUIDs - collection of ThingTypes, only results of these ThingTypes will be removed; if null then DiscoveryService.getSupportedThingTypes() will be used instead
        bridgeUID - if not null only results of that bridge are being removed
      • activate

        protected void activate​(@Nullable Map<String,​@Nullable Object> configProperties)
        Called on component activation, if the implementation of this class is an OSGi declarative service and does not override the method. The method implementation calls startBackgroundDiscovery() if background discovery is enabled by default and not overridden by the configuration.
        Parameters:
        configProperties - configuration properties
      • modified

        protected void modified​(@Nullable Map<String,​@Nullable Object> configProperties)
        Called when the configuration for the discovery service is changed. If background discovery should be enabled and is currently disabled, the method startBackgroundDiscovery() is called. If background discovery should be disabled and is currently enabled, the method stopBackgroundDiscovery() is called. In all other cases, nothing happens.
        Parameters:
        configProperties - configuration properties
      • deactivate

        protected void deactivate()
        Called on component deactivation, if the implementation of this class is an OSGi declarative service and does not override the method. The method implementation calls stopBackgroundDiscovery() if background discovery is enabled at the time of component deactivation.
      • startBackgroundDiscovery

        protected void startBackgroundDiscovery()
        Can be overridden to start background discovery logic. This method is called when AbstractDiscoveryService#setBackgroundDiscoveryEnabled(boolean) is called with true as parameter and when the component is being activated (see AbstractDiscoveryService#activate().
      • stopBackgroundDiscovery

        protected void stopBackgroundDiscovery()
        Can be overridden to stop background discovery logic. This method is called when AbstractDiscoveryService#setBackgroundDiscoveryEnabled(boolean) is called with false as parameter and when the component is being deactivated (see deactivate().
      • getTimestampOfLastScan

        protected long getTimestampOfLastScan()
        Get the timestamp of the last call of startScan().
        Returns:
        timestamp as long