javadoc

Signed-off-by: Jan N. Klug <github@klug.nrw>
openhab · Dec 20, 2022 · 9ceed1b · 9ceed1b
1 parent 21403b3
commit 9ceed1b
Show file tree

Hide file tree

Showing 4 changed files with 91 additions and 10 deletions.
diff --git a/...openhab.core/src/main/java/org/openhab/core/internal/service/WatchServiceFactoryImpl.java b/...openhab.core/src/main/java/org/openhab/core/internal/service/WatchServiceFactoryImpl.java
@@ -81,12 +81,10 @@ public WatchService getWatchService(String name, Path basePath) {
     }
 
     @Override
-    public boolean removeWatchService(String name) {
+    public void removeWatchService(String name) {
         ComponentInstance<WatchService> watchService = watchServices.remove(name);
         if (watchService != null) {
             watchService.dispose();
-            return true;
         }
-        return false;
     }
 }
diff --git a/...es/org.openhab.core/src/main/java/org/openhab/core/internal/service/WatchServiceImpl.java b/...es/org.openhab.core/src/main/java/org/openhab/core/internal/service/WatchServiceImpl.java
@@ -35,7 +35,7 @@
 import io.methvin.watcher.DirectoryWatcher;
 
 /**
- * The {@link WatchServiceImpl} is a
+ * The {@link WatchServiceImpl} is the implementation of the {@link WatchService}
  *
  * @author Jan N. Klug - Initial contribution
  */

diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/service/WatchService.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/service/WatchService.java
@@ -18,9 +18,13 @@
 import org.eclipse.jdt.annotation.NonNullByDefault;
 
 /**
- * The {@link WatchService} defines the interface for the configuration watch service. It allows registering
+ * The {@link WatchService} defines the interface for a general watch service. It allows registering
  * listeners for subdirectories of the openHAB configuration directory. The reported path in the event is relative to
- * the registered path
+ * the registered path. Watch services are created by the {@link WatchServiceFactory#getWatchService(String, Path)}.
+ *
+ * For files in the openHAB configuration folder a watch service with the name {@link WatchService#CONFIG_WATCHER_NAME}
+ * is registered. For convenience, an OSGi target filter for referencing this watch service is provided
+ * {@link WatchService#CONFIG_WATCHER_FILTER}.
  *
  * @author Jan N. Klug - Initial contribution
  */
@@ -31,23 +35,84 @@ public interface WatchService {
     String CONFIG_WATCHER_NAME = "configWatcher";
     String CONFIG_WATCHER_FILTER = "(" + SERVICE_PROPERTY_NAME + "=" + CONFIG_WATCHER_NAME + ")";
 
+    /**
+     * Register a listener for this {@link WatchService}
+     *
+     * The given listener will be notified about all events related to files and directories (including subdirectories)
+     * in the given {@link Path}
+     * <p />
+     * Listeners must unregister themselves before they are disposed
+     *
+     * @param watchEventListener the listener for this configuration
+     * @param path a {@link Path} that the listener is interested in, relative to the base path of the watch service
+     */
     default void registerListener(WatchEventListener watchEventListener, Path path) {
         registerListener(watchEventListener, List.of(path), true);
     }
 
+    /**
+     * Register a listener for this {@link WatchService}
+     *
+     * The given listener will be notified about all events related to files and directories (including subdirectories)
+     * in the given {@link Path}
+     * <p />
+     * Listeners must unregister themselves before they are disposed
+     *
+     * @param watchEventListener the listener for this configuration
+     * @param paths a list of {@link Path} that the listener is interested in, relative to the base path of the watch
+     *            service
+     */
     default void registerListener(WatchEventListener watchEventListener, List<Path> paths) {
         registerListener(watchEventListener, paths, true);
     }
 
-    default void registerListener(WatchEventListener watchEventListener, Path path, boolean withSubdirectories) {
-        registerListener(watchEventListener, List.of(path), withSubdirectories);
+    /**
+     * Register a listener for this {@link WatchService}
+     *
+     * The given listener will be notified about all events related to files and directories in the given {@link Path}
+     * <p />
+     * Listeners must unregister themselves before they are disposed
+     *
+     * @param watchEventListener the listener for this configuration
+     * @param path the{@link Path} that the listener is interested in, relative to the base path of the watch service
+     * @param withSubDirectories whether subdirectories of the given path should also be watched
+     */
+    default void registerListener(WatchEventListener watchEventListener, Path path, boolean withSubDirectories) {
+        registerListener(watchEventListener, List.of(path), withSubDirectories);
     }
 
+    /**
+     * Register a listener for this {@link WatchService}
+     *
+     * The given listener will be notified about all events related to files and directories in the given list of
+     * {@link Path}
+     * <p />
+     * Listeners must unregister themselves before they are disposed
+     *
+     * @param watchEventListener the listener for this configuration
+     * @param paths a list of {@link Path} that the listener is interested in, relative to the base path of the watch
+     *            service
+     * @param withSubDirectories whether subdirectories of the given paths should also be watched
+     */
     void registerListener(WatchEventListener watchEventListener, List<Path> paths, boolean withSubDirectories);
 
+    /**
+     * Unregister a listener from this {@link WatchService}
+     *
+     * The listener will no longer be notified of watch events
+     *
+     * @param watchEventListener the listener to unregister
+     */
     void unregisterListener(WatchEventListener watchEventListener);
 
+    @FunctionalInterface
     interface WatchEventListener {
+        /**
+         * Notify Listener about watch event
+         *
+         * @param kind the {@link Kind} of this event
+         * @param path the relative path of the file associated with this event
+         */
         void processWatchEvent(Kind kind, Path path);
     }
 

diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/service/WatchServiceFactory.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/service/WatchServiceFactory.java
@@ -18,14 +18,32 @@
 import org.eclipse.jdt.annotation.NonNullByDefault;
 
 /**
- * The {@link WatchServiceFactory} is a
+ * The {@link WatchServiceFactory} is used to create {@link WatchService} instances.
+ *
+ * For files in the openHAB configuration folder a watch service with the name {@link WatchService#CONFIG_WATCHER_NAME}
+ * is registered. For convenience, an OSGi target filter for referencing this watch service is provided
+ * {@link WatchService#CONFIG_WATCHER_FILTER}.
  *
  * @author Jan N. Klug - Initial contribution
  */
 @NonNullByDefault
 public interface WatchServiceFactory {
 
+    /**
+     * Create a new {@link WatchService} service component with the given name and path or return the already existing
+     * instance if a {@link WatchService} with the given name was created before.
+     *
+     * @param name the name of the service to create/get (must follow the conventions of an OSGi service name)
+     * @param basePath the base path of the watch service (path is created if it does not exist)
+     * @return a {@link WatchService} with the given configuration
+     * @throws IOException if the {@link WatchService} could not be instantiated
+     */
     WatchService getWatchService(String name, Path basePath) throws IOException;
 
-    boolean removeWatchService(String name);
+    /**
+     * Dispose the {@link WatchService} service component
+     *
+     * @param name the name of the {@link WatchService}
+     */
+    void removeWatchService(String name);
 }