From cb933acaa516483c1e92904cb1019fbe627cbb4f Mon Sep 17 00:00:00 2001
From: Ravi Nadahar <nadahar@rediffmail.com>
Date: Sat, 25 Oct 2025 23:01:56 +0200
Subject: [PATCH] Add AbstractThingHandlerDiscoveryService constructor for
 tests to use a different executor, some JavaDocs, and made ThingHandler type
 generic

Signed-off-by: Ravi Nadahar <nadahar@rediffmail.com>
---
 .../AbstractThingHandlerDiscoveryService.java | 77 ++++++++++++++++++-
 1 file changed, 76 insertions(+), 1 deletion(-)

diff --git a/bundles/org.openhab.core.config.discovery/src/main/java/org/openhab/core/config/discovery/AbstractThingHandlerDiscoveryService.java b/bundles/org.openhab.core.config.discovery/src/main/java/org/openhab/core/config/discovery/AbstractThingHandlerDiscoveryService.java
index 9d47c471552..8b34176c6ca 100644
--- a/bundles/org.openhab.core.config.discovery/src/main/java/org/openhab/core/config/discovery/AbstractThingHandlerDiscoveryService.java
+++ b/bundles/org.openhab.core.config.discovery/src/main/java/org/openhab/core/config/discovery/AbstractThingHandlerDiscoveryService.java
@@ -14,6 +14,7 @@
 
 import java.util.Map;
 import java.util.Set;
+import java.util.concurrent.ScheduledExecutorService;
 
 import org.eclipse.jdt.annotation.NonNull;
 import org.eclipse.jdt.annotation.NonNullByDefault;
@@ -45,6 +46,21 @@ public abstract class AbstractThingHandlerDiscoveryService<T extends ThingHandle
     // initialized when the type is generic, so we have to initialize it with "something"
     protected @NonNullByDefault({}) T thingHandler = (@NonNull T) null;
 
+    /**
+     * Creates a new instance of this class with the specified parameters.
+     *
+     * @param thingClazz the {@link ThingHandler} class.
+     * @param supportedThingTypes the list of Thing types which are supported (can be {@code null}).
+     * @param timeout the discovery timeout in seconds after which the discovery
+     *            service automatically stops its forced discovery process (>= 0).
+     * @param backgroundDiscoveryEnabledByDefault defines, whether the default for this discovery service is to
+     *            enable background discovery or not.
+     * @param scanInputLabel the label of the optional input parameter to start the discovery or null if no input
+     *            parameter supported.
+     * @param scanInputDescription the description of the optional input parameter to start the discovery or null if no
+     *            input parameter supported.
+     * @throws IllegalArgumentException if {@code timeout < 0}.
+     */
     protected AbstractThingHandlerDiscoveryService(Class<T> thingClazz, @Nullable Set<ThingTypeUID> supportedThingTypes,
             int timeout, boolean backgroundDiscoveryEnabledByDefault, @Nullable String scanInputLabel,
             @Nullable String scanInputDescription) throws IllegalArgumentException {
@@ -53,20 +69,79 @@ protected AbstractThingHandlerDiscoveryService(Class<T> thingClazz, @Nullable Se
         this.backgroundDiscoveryEnabled = backgroundDiscoveryEnabledByDefault;
     }
 
+    /**
+     * Creates a new instance of this class with the specified parameters and with {@code scanInputLabel} and
+     * {@code scanInputDescription} set to {@code null}.
+     *
+     * @param thingClazz the {@link ThingHandler} class.
+     * @param supportedThingTypes the list of Thing types which are supported (can be {@code null}).
+     * @param timeout the discovery timeout in seconds after which the discovery
+     *            service automatically stops its forced discovery process (>= 0).
+     * @param backgroundDiscoveryEnabledByDefault defines, whether the default for this discovery service is to
+     *            enable background discovery or not.
+     * @throws IllegalArgumentException if {@code timeout < 0}.
+     */
     protected AbstractThingHandlerDiscoveryService(Class<T> thingClazz, @Nullable Set<ThingTypeUID> supportedThingTypes,
             int timeout, boolean backgroundDiscoveryEnabledByDefault) throws IllegalArgumentException {
         this(thingClazz, supportedThingTypes, timeout, backgroundDiscoveryEnabledByDefault, null, null);
     }
 
+    /**
+     * Creates a new instance of this class with the specified parameters and with {@code scanInputLabel} and
+     * {@code scanInputDescription} set to {@code null}, and {@code backgroundDiscoveryEnabledByDefault} enabled.
+     *
+     * @param thingClazz the {@link ThingHandler} class.
+     * @param supportedThingTypes the list of Thing types which are supported (can be {@code null}).
+     * @param timeout the discovery timeout in seconds after which the discovery
+     *            service automatically stops its forced discovery process (>= 0).
+     * @throws IllegalArgumentException if {@code timeout < 0}.
+     */
     protected AbstractThingHandlerDiscoveryService(Class<T> thingClazz, @Nullable Set<ThingTypeUID> supportedThingTypes,
             int timeout) throws IllegalArgumentException {
         this(thingClazz, supportedThingTypes, timeout, true);
     }
 
+    /**
+     * Creates a new instance of this class with the specified parameters and with {@code scanInputLabel} and
+     * {@code scanInputDescription} set to {@code null}, without any {@code supportedThingTypes}, and
+     * {@code backgroundDiscoveryEnabledByDefault} enabled.
+     *
+     * @param thingClazz the {@link ThingHandler} class.
+     * @param timeout the discovery timeout in seconds after which the discovery
+     *            service automatically stops its forced discovery process (>= 0).
+     * @throws IllegalArgumentException if {@code timeout < 0}.
+     */
     protected AbstractThingHandlerDiscoveryService(Class<T> thingClazz, int timeout) throws IllegalArgumentException {
         this(thingClazz, null, timeout);
     }
 
+    /**
+     * Creates a new instance of this class with the specified parameters.
+     * <p>
+     * <b>For use by tests only</b>, allows setting a different {@link ScheduledExecutorService} like
+     * {@link org.openhab.core.util.SameThreadExecutorService} for synchronous behavior during testing.
+     *
+     * @param thingClazz the {@link ThingHandler} class.
+     * @param supportedThingTypes the list of Thing types which are supported (can be {@code null}).
+     * @param timeout the discovery timeout in seconds after which the discovery
+     *            service automatically stops its forced discovery process (>= 0).
+     * @param backgroundDiscoveryEnabledByDefault defines, whether the default for this discovery service is to
+     *            enable background discovery or not.
+     * @param scanInputLabel the label of the optional input parameter to start the discovery or null if no input
+     *            parameter supported.
+     * @param scanInputDescription the description of the optional input parameter to start the discovery or null if no
+     *            input parameter supported.
+     * @throws IllegalArgumentException if {@code timeout < 0}.
+     */
+    protected AbstractThingHandlerDiscoveryService(ScheduledExecutorService scheduler, Class<T> thingClazz,
+            @Nullable Set<ThingTypeUID> supportedThingTypes, int timeout, boolean backgroundDiscoveryEnabledByDefault,
+            @Nullable String scanInputLabel, @Nullable String scanInputDescription) throws IllegalArgumentException {
+        super(scheduler, supportedThingTypes, timeout, backgroundDiscoveryEnabledByDefault, scanInputLabel,
+                scanInputDescription);
+        this.thingClazz = thingClazz;
+        this.backgroundDiscoveryEnabled = backgroundDiscoveryEnabledByDefault;
+    }
+
     @Override
     protected abstract void startScan();
 
@@ -82,7 +157,7 @@ public void setThingHandler(ThingHandler handler) {
     }
 
     @Override
-    public @Nullable ThingHandler getThingHandler() {
+    public @Nullable T getThingHandler() {
         return thingHandler;
     }