Package org.openhab.core.config.discovery

Class AbstractDiscoveryService

java.lang.Object
org.openhab.core.config.discovery.AbstractDiscoveryService
All Implemented Interfaces:
DiscoveryService
Direct Known Subclasses:
AbstractThingHandlerDiscoveryService, SddpDiscoveryService
@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(ThingUID) 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, Laurent Garnier - Added discovery with an optional input parameter

  • Field Details

  • Constructor Details

    • AbstractDiscoveryService

      protected AbstractDiscoveryService(@Nullable Set<ThingTypeUID> supportedThingTypes, int timeout, boolean backgroundDiscoveryEnabledByDefault, @Nullable String scanInputLabel, @Nullable String scanInputDescription) 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.
      scanInputLabel - the label of the optional input parameter to start the discovery or null if no input parameter supported
      scanInputDescription - the description of the optional input parameter to start the discovery or null if no input parameter supported
      Throws:
      IllegalArgumentException - if timeout < 0

    • AbstractDiscoveryService

      protected AbstractDiscoveryService(ScheduledExecutorService scheduler, @Nullable Set<ThingTypeUID> supportedThingTypes, int timeout, boolean backgroundDiscoveryEnabledByDefault, @Nullable String scanInputLabel, @Nullable String scanInputDescription) throws IllegalArgumentException
      Creates a new instance of this class with the specified parameters.

      For use by tests only, allows setting a different ScheduledExecutorService like SameThreadExecutorService for synchronous behavior during testing.

      Parameters:
      scheduler - the ScheduledExecutorService to use.
      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.
      scanInputLabel - the label of the optional input parameter to start the discovery or null if no input parameter supported
      scanInputDescription - the description of the optional input parameter to start the discovery or null if no input parameter supported
      Throws:
      IllegalArgumentException - if timeout < 0

    • AbstractDiscoveryService

      protected AbstractDiscoveryService(@Nullable Set<ThingTypeUID> supportedThingTypes, int timeout, boolean backgroundDiscoveryEnabledByDefault) throws IllegalArgumentException
      Creates a new instance of this class with the specified parameters and no input parameter supported to start the discovery.
      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 timeout < 0

    • AbstractDiscoveryService

      protected AbstractDiscoveryService(@Nullable Set<ThingTypeUID> supportedThingTypes, int timeout) throws IllegalArgumentException
      Creates a new instance of this class with the specified parameters and background discovery enabled and no input parameter supported to start the discovery.
      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 timeout < 0

    • AbstractDiscoveryService

      protected AbstractDiscoveryService(int timeout) throws IllegalArgumentException
      Creates a new instance of this class with the specified parameters and background discovery enabled and no input parameter supported to start the discovery.
      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 timeout < 0

  • Method Details

    • getSupportedThingTypes

      public Set<ThingTypeUID> getSupportedThingTypes()
      Returns the list of Thing types which are supported by the DiscoveryService.
      Specified by:
      getSupportedThingTypes in interface DiscoveryService
      Returns:
      the list of Thing types which are supported by the discovery service (not null, could be empty)

    • isScanInputSupported

      public boolean isScanInputSupported()
      Description copied from interface: DiscoveryService
      Returns true if the discovery supports an optional input parameter to run, otherwise false.
      Specified by:
      isScanInputSupported in interface DiscoveryService
      Returns:
      true if the discovery supports an optional input parameter to run, otherwise false

    • getScanInputLabel

      public @Nullable String getScanInputLabel()
      Description copied from interface: DiscoveryService
      Returns the label of the supported input parameter to start the discovery.
      Specified by:
      getScanInputLabel in interface DiscoveryService
      Returns:
      the label of the supported input parameter to start the discovery or null if input parameter not supported

    • getScanInputDescription

      public @Nullable String getScanInputDescription()
      Description copied from interface: DiscoveryService
      Returns the description of the supported input parameter to start the discovery.
      Specified by:
      getScanInputDescription in interface DiscoveryService
      Returns:
      the description of the supported input parameter to start the discovery or null if input parameter not supported

    • 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

    • startScan

      public void startScan(String input, @Nullable ScanListener listener)
      Description copied from interface: DiscoveryService
      Triggers this service to start an active scan for new devices using an input parameter for that.
      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:
      input - an input parameter to be used during discovery scan
      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 DiscoveryService.startScan(org.openhab.core.config.discovery.ScanListener) 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 startScan(ScanListener) implementation of the AbstractDiscoveryService. The abstract class schedules a call of stopScan() after getScanTimeout() seconds. If this behavior is not appropriate, the startScan(ScanListener) method should be overridden.

    • startScan

      protected void startScan(String input)

    • 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(Instant 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(Instant 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(Instant 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,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,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 if background discovery is enabled when the component is being activated (see activate(java.util.Map<java.lang.String, java.lang.Object>).

    • stopBackgroundDiscovery

      protected void stopBackgroundDiscovery()
      Can be overridden to stop background discovery logic. This method is called if background discovery is enabled when the component is being deactivated (see deactivate().

    • getTimestampOfLastScan

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

    • getLocalizedDiscoveryResult

      protected DiscoveryResult getLocalizedDiscoveryResult(DiscoveryResult discoveryResult, @Nullable org.osgi.framework.Bundle bundle)