From 9ceed1b5ee9861ceefa193557ac67c413c0892a6 Mon Sep 17 00:00:00 2001 From: "Jan N. Klug" Date: Sun, 18 Dec 2022 20:53:13 +0100 Subject: [PATCH] javadoc Signed-off-by: Jan N. Klug --- .../service/WatchServiceFactoryImpl.java | 4 +- .../internal/service/WatchServiceImpl.java | 2 +- .../openhab/core/service/WatchService.java | 73 ++++++++++++++++++- .../core/service/WatchServiceFactory.java | 22 +++++- 4 files changed, 91 insertions(+), 10 deletions(-) diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/internal/service/WatchServiceFactoryImpl.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/internal/service/WatchServiceFactoryImpl.java index 34518f7633e..a4228c097ae 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/internal/service/WatchServiceFactoryImpl.java +++ b/bundles/org.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 = watchServices.remove(name); if (watchService != null) { watchService.dispose(); - return true; } - return false; } } diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/internal/service/WatchServiceImpl.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/internal/service/WatchServiceImpl.java index 3266ab0bb62..ba8f450e63f 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/internal/service/WatchServiceImpl.java +++ b/bundles/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 index 396d82f1ef2..094feccf0a5 100644 --- 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} + *

+ * 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} + *

+ * 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 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} + *

+ * 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} + *

+ * 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 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 index 088a9e158a7..a848692efe2 100644 --- 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); }