diff --git a/README.md b/README.md index 4cd471444e3..06b306d29ac 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,6 @@ [![Jenkins Build Status](https://ci.openhab.org/job/openHAB-Core/badge/icon)](https://ci.openhab.org/job/openHAB-Core/) [![EPL-2.0](https://img.shields.io/badge/license-EPL%202-green.svg)](https://opensource.org/licenses/EPL-2.0) [![Crowdin](https://badges.crowdin.net/openhab-core/localized.svg)](https://crowdin.com/project/openhab-core) -[![Bountysource](https://www.bountysource.com/badge/tracker?tracker_id=28054058)](https://www.bountysource.com/teams/openhab/issues?tracker_ids=28054058) This project contains core bundles of the openHAB runtime. diff --git a/bundles/org.openhab.core.addon.marketplace/src/main/java/org/openhab/core/addon/marketplace/AbstractRemoteAddonService.java b/bundles/org.openhab.core.addon.marketplace/src/main/java/org/openhab/core/addon/marketplace/AbstractRemoteAddonService.java index 4aa5f4dc7be..3ce55c4f6cd 100644 --- a/bundles/org.openhab.core.addon.marketplace/src/main/java/org/openhab/core/addon/marketplace/AbstractRemoteAddonService.java +++ b/bundles/org.openhab.core.addon.marketplace/src/main/java/org/openhab/core/addon/marketplace/AbstractRemoteAddonService.java @@ -136,7 +136,7 @@ public void refreshSource() { } /** - * Add a {@link MarketplaceAddonHandler) to this service + * Add a {@link MarketplaceAddonHandler} to this service * * This needs to be implemented by the addon-services because the handlers are references to OSGi services and * the @Reference annotation is not inherited. @@ -147,7 +147,7 @@ public void refreshSource() { protected abstract void addAddonHandler(MarketplaceAddonHandler handler); /** - * Remove a {@link MarketplaceAddonHandler) from this service + * Remove a {@link MarketplaceAddonHandler} from this service * * This needs to be implemented by the addon-services because the handlers are references to OSGi services and * unbind methods can't be inherited. diff --git a/bundles/org.openhab.core.addon/src/main/java/org/openhab/core/addon/AddonEvent.java b/bundles/org.openhab.core.addon/src/main/java/org/openhab/core/addon/AddonEvent.java index e5b49aba0f9..40d084f8438 100644 --- a/bundles/org.openhab.core.addon/src/main/java/org/openhab/core/addon/AddonEvent.java +++ b/bundles/org.openhab.core.addon/src/main/java/org/openhab/core/addon/AddonEvent.java @@ -17,7 +17,8 @@ import org.openhab.core.events.AbstractEvent; /** - * This is an {@link Event} that is sent on add-on operations, such as installing and uninstalling. + * This is an {@link org.openhab.core.events.Event} that is sent on add-on operations, such as installing and + * uninstalling. * * @author Kai Kreuzer - Initial contribution */ diff --git a/bundles/org.openhab.core.addon/src/main/java/org/openhab/core/addon/AddonEventFactory.java b/bundles/org.openhab.core.addon/src/main/java/org/openhab/core/addon/AddonEventFactory.java index 9465d7fa17c..ff5ee032abf 100644 --- a/bundles/org.openhab.core.addon/src/main/java/org/openhab/core/addon/AddonEventFactory.java +++ b/bundles/org.openhab.core.addon/src/main/java/org/openhab/core/addon/AddonEventFactory.java @@ -25,7 +25,7 @@ * This is an {@link EventFactory} for creating add-on events. The following event types are supported by this * factory: * - * {@link AddonEventFactory#TYPE} + * {@link AddonEvent#TYPE} * * @author Kai Kreuzer - Initial contribution */ diff --git a/bundles/org.openhab.core.audio/src/main/java/org/openhab/core/audio/AudioFormat.java b/bundles/org.openhab.core.audio/src/main/java/org/openhab/core/audio/AudioFormat.java index 0eeb7ab2e2b..21f94ef9f14 100644 --- a/bundles/org.openhab.core.audio/src/main/java/org/openhab/core/audio/AudioFormat.java +++ b/bundles/org.openhab.core.audio/src/main/java/org/openhab/core/audio/AudioFormat.java @@ -44,7 +44,7 @@ public class AudioFormat { null, null); /** - * {@link AudioCodec} encoded data without any container header or footer, + * {@code AudioCodec} encoded data without any container header or footer, * e.g. MP3 is a non-container format */ public static final String CONTAINER_NONE = "NONE"; diff --git a/bundles/org.openhab.core.audio/src/main/java/org/openhab/core/audio/AudioHTTPServer.java b/bundles/org.openhab.core.audio/src/main/java/org/openhab/core/audio/AudioHTTPServer.java index d74b88ef989..57e1f55c105 100644 --- a/bundles/org.openhab.core.audio/src/main/java/org/openhab/core/audio/AudioHTTPServer.java +++ b/bundles/org.openhab.core.audio/src/main/java/org/openhab/core/audio/AudioHTTPServer.java @@ -37,7 +37,7 @@ public interface AudioHTTPServer { * * @param stream the stream to serve on HTTP * @return the relative URL to access the stream starting with a '/' - * @deprecated Use {@link AudioHTTPServer#serve(AudioStream, int, boolean, CompletableFuture)} + * @deprecated Use {@link AudioHTTPServer#serve(AudioStream, int, boolean)} */ @Deprecated String serve(AudioStream stream); @@ -54,7 +54,7 @@ public interface AudioHTTPServer { * @param stream the stream to serve on HTTP * @param seconds number of seconds for which the stream is available through HTTP * @return the relative URL to access the stream starting with a '/' - * @deprecated Use {@link AudioHTTPServer#serve(AudioStream, int, boolean, CompletableFuture)} + * @deprecated Use {@link AudioHTTPServer#serve(AudioStream, int, boolean)} */ @Deprecated String serve(AudioStream stream, int seconds); diff --git a/bundles/org.openhab.core.audio/src/main/java/org/openhab/core/audio/utils/AudioWaveUtils.java b/bundles/org.openhab.core.audio/src/main/java/org/openhab/core/audio/utils/AudioWaveUtils.java index 815564cd428..f6d0df3db59 100644 --- a/bundles/org.openhab.core.audio/src/main/java/org/openhab/core/audio/utils/AudioWaveUtils.java +++ b/bundles/org.openhab.core.audio/src/main/java/org/openhab/core/audio/utils/AudioWaveUtils.java @@ -42,7 +42,7 @@ public class AudioWaveUtils { /** * - * @param InputStream an inputStream of a wav file to analyze. The InputStream must have a fmt header + * @param inputStream an InputStream of a wav file to analyze. The InputStream must have a fmt header * and support the mark/reset method * @return The audio format, or the default audio format if an error occured * @throws IOException If i/o exception occurs, or if the InputStream doesn't support the mark/reset @@ -84,7 +84,7 @@ public static AudioFormat parseWavFormat(InputStream inputStream) throws IOExcep * as if it is a pure PCM stream, it could try to play it and will * do a "click" noise at the beginning. * - * @param audio A wav container in an InputStream + * @param data A wav container in an InputStream * @throws IOException */ public static void removeFMT(InputStream data) throws IOException { diff --git a/bundles/org.openhab.core.audio/src/test/java/org/openhab/core/audio/internal/AudioManagerTest.java b/bundles/org.openhab.core.audio/src/test/java/org/openhab/core/audio/internal/AudioManagerTest.java index e4f505f3199..860d817e270 100644 --- a/bundles/org.openhab.core.audio/src/test/java/org/openhab/core/audio/internal/AudioManagerTest.java +++ b/bundles/org.openhab.core.audio/src/test/java/org/openhab/core/audio/internal/AudioManagerTest.java @@ -273,7 +273,7 @@ private PercentType getSinkMockVolume(PercentType initialVolume) throws IOExcept /** * - * @param param - either default source or default sink + * @param param either default source or default sink */ private void assertAddedParameterOption(String param, Locale locale) { String id = ""; diff --git a/bundles/org.openhab.core.automation.module.script.rulesupport/src/main/java/org/openhab/core/automation/module/script/rulesupport/loader/AbstractScriptFileWatcher.java b/bundles/org.openhab.core.automation.module.script.rulesupport/src/main/java/org/openhab/core/automation/module/script/rulesupport/loader/AbstractScriptFileWatcher.java index 5c4faa40c90..1177fd5c280 100644 --- a/bundles/org.openhab.core.automation.module.script.rulesupport/src/main/java/org/openhab/core/automation/module/script/rulesupport/loader/AbstractScriptFileWatcher.java +++ b/bundles/org.openhab.core.automation.module.script.rulesupport/src/main/java/org/openhab/core/automation/module/script/rulesupport/loader/AbstractScriptFileWatcher.java @@ -62,7 +62,7 @@ * * @author Simon Merschjohann - Initial contribution * @author Kai Kreuzer - improved logging and removed thread pool - * @author Jonathan Gilbert - added dependency tracking & per-script start levels; made reusable + * @author Jonathan Gilbert - added dependency tracking and per-script start levels; made reusable * @author Jan N. Klug - Refactored dependency tracking to script engine factories */ @NonNullByDefault diff --git a/bundles/org.openhab.core.automation.module.script/src/main/java/org/openhab/core/automation/module/script/defaultscope/ScriptBusEvent.java b/bundles/org.openhab.core.automation.module.script/src/main/java/org/openhab/core/automation/module/script/defaultscope/ScriptBusEvent.java index 61bf878e5c3..01d5ba319ea 100644 --- a/bundles/org.openhab.core.automation.module.script/src/main/java/org/openhab/core/automation/module/script/defaultscope/ScriptBusEvent.java +++ b/bundles/org.openhab.core.automation.module.script/src/main/java/org/openhab/core/automation/module/script/defaultscope/ScriptBusEvent.java @@ -28,7 +28,7 @@ * Items should not be updated directly (setting the state property), but updates should * be sent to the bus, so that all interested bundles are notified. * - * Note: This class is a copy from the {@link org.openhab.core.model.script.actions.BusEvent} class + * Note: This class is a copy from the {@code org.openhab.core.model.script.actions.BusEvent} class * * @author Kai Kreuzer - Initial contribution * @author Jan N. Klug - Refactored to interface diff --git a/bundles/org.openhab.core.automation.module.script/src/main/java/org/openhab/core/automation/module/script/defaultscope/ScriptThingActions.java b/bundles/org.openhab.core.automation.module.script/src/main/java/org/openhab/core/automation/module/script/defaultscope/ScriptThingActions.java index d2c10361c61..69555e1e7d2 100644 --- a/bundles/org.openhab.core.automation.module.script/src/main/java/org/openhab/core/automation/module/script/defaultscope/ScriptThingActions.java +++ b/bundles/org.openhab.core.automation.module.script/src/main/java/org/openhab/core/automation/module/script/defaultscope/ScriptThingActions.java @@ -19,7 +19,7 @@ /** * The methods of this class are made available as functions in the scripts. * - * Note: This class is a copy from the {@link org.openhab.core.model.script.internal.engine.action.ThingActionService} + * Note: This class is a copy from the {@code org.openhab.core.model.script.internal.engine.action.ThingActionService} * class * * @author Kai Kreuzer - Initial contribution diff --git a/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/ModuleHandlerCallback.java b/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/ModuleHandlerCallback.java index 97cc7ea963b..7acd1f0ef1b 100644 --- a/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/ModuleHandlerCallback.java +++ b/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/ModuleHandlerCallback.java @@ -33,12 +33,12 @@ public interface ModuleHandlerCallback { * This method gets enabled {@link RuleStatus} for a {@link Rule}. * The enabled rule statuses are {@link RuleStatus#UNINITIALIZED}, {@link RuleStatus#IDLE} and * {@link RuleStatus#RUNNING}. - * The disabled rule status is {@link RuleStatus#DISABLED}. + * The disabled rule status is {@link RuleStatusDetail#DISABLED}. * * @param ruleUID UID of the {@link Rule} * @return {@code true} when the {@link RuleStatus} is one of the {@link RuleStatus#UNINITIALIZED}, * {@link RuleStatus#IDLE} and {@link RuleStatus#RUNNING}, {@code false} when it is - * {@link RuleStatus#DISABLED} and {@code null} when it is not available. + * {@link RuleStatusDetail#DISABLED} and {@code null} when it is not available. */ @Nullable Boolean isEnabled(String ruleUID); @@ -47,7 +47,7 @@ public interface ModuleHandlerCallback { * This method is used for changing enabled state of the {@link Rule}. * The enabled rule statuses are {@link RuleStatus#UNINITIALIZED}, {@link RuleStatus#IDLE} and * {@link RuleStatus#RUNNING}. - * The disabled rule status is {@link RuleStatus#DISABLED}. + * The disabled rule status is {@link RuleStatusDetail#DISABLED}. * * @param uid the unique identifier of the {@link Rule}. * @param isEnabled a new enabled / disabled state of the {@link Rule}. @@ -59,7 +59,7 @@ public interface ModuleHandlerCallback { * * @param ruleUID UID of the {@link Rule} * @return {@link RuleStatusInfo} object containing status of the looking {@link Rule} or null when a rule with - * specified UID does not exists. + * specified UID does not exist. */ @Nullable RuleStatusInfo getStatusInfo(String ruleUID); @@ -69,7 +69,7 @@ public interface ModuleHandlerCallback { * * @param ruleUID UID of the {@link Rule} * @return {@link RuleStatus} object containing status of the looking {@link Rule} or null when a rule with - * specified UID does not exists. + * specified UID does not exist. */ @Nullable RuleStatus getStatus(String ruleUID); @@ -79,7 +79,7 @@ public interface ModuleHandlerCallback { * This should always be possible unless an action has a mandatory input that is linked to a trigger. * In that case the action is skipped and the rule engine continues execution of rest actions. * - * @param ruleUID id of the rule whose actions have to be executed. + * @param uid id of the rule whose actions have to be executed. */ void runNow(String uid); @@ -87,7 +87,7 @@ public interface ModuleHandlerCallback { * Same as {@link #runNow(String)} with the additional option to enable/disable evaluation of * conditions defined in the target rule. The context can be set here, too, but also might be {@code null}. * - * @param ruleUID id of the rule whose actions have to be executed. + * @param uid id of the rule whose actions have to be executed. * @param considerConditions if {@code true} the conditions of the rule will be checked. * @param context the context that is passed to the conditions and the actions of the rule. */ diff --git a/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/Rule.java b/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/Rule.java index f2b8de3b78e..31bb633c398 100644 --- a/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/Rule.java +++ b/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/Rule.java @@ -27,8 +27,8 @@ * * * @author Yordan Mihaylov - Initial contribution diff --git a/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/type/CompositeActionType.java b/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/type/CompositeActionType.java index 84fb140ec72..94d628030f3 100644 --- a/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/type/CompositeActionType.java +++ b/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/type/CompositeActionType.java @@ -43,7 +43,6 @@ public class CompositeActionType extends ActionType { * @param uid the {@link ActionType}'s identifier, or {@code null} if a random identifier should be * generated. * @param configDescriptions describing meta-data for the configuration of the future {@link Action} instances. - * @param children is a {@link List} of {@link Action}s. * @param inputs a {@link List} with {@link Input} meta-information descriptions of the future * {@link Action} instances. * @param outputs a {@link List} with {@link Output} meta-information descriptions of the future diff --git a/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/type/ModuleType.java b/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/type/ModuleType.java index 4956188e8d1..5a411c8bbd4 100644 --- a/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/type/ModuleType.java +++ b/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/type/ModuleType.java @@ -28,9 +28,10 @@ /** * This class provides common functionality for creating {@link ModuleType} instances. Each {@link ModuleType} instance * defines the meta-information needed for creation of a {@link Module} instance which is a building block for a - * {@link Rule}. The meta-information describes the {@link Configuration} of a {@link Module} providing list with - * {@link ConfigDescriptionParameter}s, {@link Input}s and {@link Output}s of a {@link Module}. Each {@link ModuleType} - * instance owns a unique id which is used as reference in the {@link Module}s, to find their meta-information. + * {@link Rule}. The meta-information describes the {@link org.openhab.core.config.core.Configuration} of a + * {@link Module} providing list with {@link ConfigDescriptionParameter}s, {@link Input}s and {@link Output}s of a + * {@link Module}. Each {@link ModuleType} instance owns a unique id which is used as reference in the {@link Module}s, + * to find their meta-information. *

* Whether the {@link ModuleType}s can be used by anyone, depends from their {@link Visibility} value, but they can be * modified only by their creator. diff --git a/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/type/ModuleTypeRegistry.java b/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/type/ModuleTypeRegistry.java index f1b69f8c359..ba59cedbab8 100644 --- a/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/type/ModuleTypeRegistry.java +++ b/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/type/ModuleTypeRegistry.java @@ -77,7 +77,7 @@ public interface ModuleTypeRegistry extends Registry { * This method is used for getting the {@link ModuleType}s filtered by tags. * * @param locale used for localization of the {@link ModuleType}. - * @param moduleTypeTag specifies the filter for getting the {@link ModuleType}s, if it is {@code null} then returns + * @param tags specifies the filter for getting the {@link ModuleType}s, if it is {@code null} then returns * all {@link ModuleType}s. * @param the type of the required object. * @return the {@link ModuleType}s, which correspond to the filter. diff --git a/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/util/ReferenceResolver.java b/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/util/ReferenceResolver.java index 7c4c365ec5b..44ffc8dd261 100644 --- a/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/util/ReferenceResolver.java +++ b/bundles/org.openhab.core.automation/src/main/java/org/openhab/core/automation/util/ReferenceResolver.java @@ -75,7 +75,6 @@ public class ReferenceResolver { * try to find values for {{firstName}} and {{lastName}} in the given context and replace them. References that are * not found in the context - are not replaced. * - * @param module module that is directly part of Rule or part of CompositeModule * @param context containing Rule configuration or Composite configuration values. */ public static void updateConfiguration(Configuration config, Map context, Logger logger) { diff --git a/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/ConfigDescriptionParameter.java b/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/ConfigDescriptionParameter.java index b01e4675b18..464636e2264 100644 --- a/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/ConfigDescriptionParameter.java +++ b/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/ConfigDescriptionParameter.java @@ -25,7 +25,7 @@ * concrete configuration parameter. Such parameter descriptions are collected * within the {@link ConfigDescription} and can be retrieved from the {@link ConfigDescriptionRegistry}. * - * This class defines available configuration parameter types in {@link ConfigDescriptionParameter#Type}, + * This class defines available configuration parameter types in {@link ConfigDescriptionParameter.Type}, * it defines available unit types in {@link ConfigDescriptionParameter#UNITS} and available * contexts (see {@link ConfigDescriptionParameter#getContext()}). * diff --git a/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/ConfigDescriptionParameterGroup.java b/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/ConfigDescriptionParameterGroup.java index aae976b6be6..52e46762749 100644 --- a/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/ConfigDescriptionParameterGroup.java +++ b/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/ConfigDescriptionParameterGroup.java @@ -21,7 +21,7 @@ * be displayed together in the UI (eg in a single tab). *

* A {@link ConfigDescriptionParameter} instance must also contain the groupName. It should be permissible to use the - * groupId in the {@link ConfigDesctiptionParameter} without supplying a corresponding + * groupId in the {@link ConfigDescriptionParameter} without supplying a corresponding * {@link ConfigDescriptionParameterGroup} - in this way the UI can group the parameters together, but doesn't have the * group information. * diff --git a/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/ConfigOptionProvider.java b/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/ConfigOptionProvider.java index 3c10579a194..778e16fcebb 100644 --- a/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/ConfigOptionProvider.java +++ b/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/ConfigOptionProvider.java @@ -30,7 +30,7 @@ public interface ConfigOptionProvider { /** - * Provides a collection of {@link ParameterOptions}s. + * Provides a collection of {@link ParameterOption}s. * * @param uri the uri of the config description * @param param the parameter name for which the requested options shall be returned diff --git a/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/Configuration.java b/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/Configuration.java index 50d15021043..07a4ddd7daf 100644 --- a/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/Configuration.java +++ b/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/Configuration.java @@ -26,7 +26,7 @@ import org.eclipse.jdt.annotation.Nullable; /** - * This class is a wrapper for configuration settings of {@link Thing}s. + * This class is a wrapper for configuration settings of {@code org.openhab.core.thing.Thing}s. * * @author Dennis Nobel - Initial contribution * @author Kai Kreuzer - added constructors and normalization diff --git a/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/status/ConfigStatusInfo.java b/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/status/ConfigStatusInfo.java index 3b850cef6cf..e040e359f7f 100644 --- a/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/status/ConfigStatusInfo.java +++ b/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/status/ConfigStatusInfo.java @@ -42,7 +42,7 @@ public ConfigStatusInfo() { } /** - * Creates a new {@link ConfigStatusInfo} with the given {@link ConfigStatusMessages}. + * Creates a new {@link ConfigStatusInfo} with the given {@link ConfigStatusMessage}s. * * @param configStatusMessages the configuration status messages to be added */ diff --git a/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/xml/util/ConverterValueMap.java b/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/xml/util/ConverterValueMap.java index d67175c8bad..39dc4f9a02a 100644 --- a/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/xml/util/ConverterValueMap.java +++ b/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/xml/util/ConverterValueMap.java @@ -54,7 +54,7 @@ public ConverterValueMap(HierarchicalStreamReader reader, UnmarshallingContext c * Creates a new instance of this class with the specified parameters. * * @param reader the reader to be used to read-in all children (must not be null) - * @param numberOfValues the number of children to be read-in (< 0 = until end of section) + * @param numberOfValues the number of children to be read-in ({@code< 0} = until end of section) * @param context * @throws ConversionException if not all children could be read-in */ @@ -78,7 +78,7 @@ public Map getValueMap() { * Reads-in {@code N} children in a key-value map and returns it. * * @param reader the reader to be used to read-in the children - * @param numberOfValues the number of children to be read in (< 0 = until end of section) + * @param numberOfValues the number of children to be read in ({@code < 0} = until end of section) * @param context * @return the key-value map containing the read-in children (not null, could be empty) * @throws ConversionException if not all children could be read-in diff --git a/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/xml/util/XmlDocumentReader.java b/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/xml/util/XmlDocumentReader.java index 4345a3130c7..5c2754c6f6f 100644 --- a/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/xml/util/XmlDocumentReader.java +++ b/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/xml/util/XmlDocumentReader.java @@ -46,9 +46,9 @@ public abstract class XmlDocumentReader<@NonNull T> { * The default constructor of this class initializes the {@code XStream} object by calling: * *

    - *
  1. {@link #configureSecurity()}
    2. - *
  2. {@link #registerConverters()}
    3. - *
  3. {@link #registerAliases()}
    4. + *
  4. {@link #configureSecurity}
    5. + *
  5. {@link #registerConverters}
    6. + *
  6. {@link #registerAliases}
    7. *
*/ public XmlDocumentReader() { diff --git a/bundles/org.openhab.core.config.discovery/src/main/java/org/openhab/core/config/discovery/AbstractDiscoveryService.java b/bundles/org.openhab.core.config.discovery/src/main/java/org/openhab/core/config/discovery/AbstractDiscoveryService.java index 094ab1f484b..4427b84bec6 100644 --- a/bundles/org.openhab.core.config.discovery/src/main/java/org/openhab/core/config/discovery/AbstractDiscoveryService.java +++ b/bundles/org.openhab.core.config.discovery/src/main/java/org/openhab/core/config/discovery/AbstractDiscoveryService.java @@ -41,7 +41,7 @@ * The {@link AbstractDiscoveryService} provides methods which handle the {@link DiscoveryListener}s. * * Subclasses do not have to care about adding and removing those listeners. - * They can use the protected methods {@link #thingDiscovered(DiscoveryResult)} and {@link #thingRemoved(String)} in + * They can use the protected methods {@link #thingDiscovered(DiscoveryResult)} and {@link #thingRemoved(ThingUID)} in * order to notify the registered {@link DiscoveryListener}s. * * @author Oliver Libutzki - Initial contribution @@ -83,7 +83,7 @@ public abstract class AbstractDiscoveryService implements DiscoveryService { * 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 the timeout < 0 + * @throws IllegalArgumentException if {@code timeout < 0} */ public AbstractDiscoveryService(@Nullable Set supportedThingTypes, int timeout, boolean backgroundDiscoveryEnabledByDefault) throws IllegalArgumentException { @@ -102,7 +102,7 @@ public AbstractDiscoveryService(@Nullable Set supportedThingTypes, * @param 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 + * @throws IllegalArgumentException if {@code timeout < 0} */ public AbstractDiscoveryService(@Nullable Set supportedThingTypes, int timeout) throws IllegalArgumentException { @@ -115,7 +115,7 @@ public AbstractDiscoveryService(@Nullable Set supportedThingTypes, * @param 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 + * @throws IllegalArgumentException if {@code timeout < 0} */ public AbstractDiscoveryService(int timeout) throws IllegalArgumentException { this(null, timeout); @@ -221,10 +221,10 @@ public synchronized void abortScan() { } /** - * This method is called by the {@link #startScan(ScanListener))} implementation of the + * This method is called by the {@link #startScan(ScanListener)} implementation of the * {@link AbstractDiscoveryService}. * The abstract class schedules a call of {@link #stopScan()} after {@link #getScanTimeout()} seconds. If this - * behavior is not appropriate, the {@link #startScan(ScanListener))} method should be overridden. + * behavior is not appropriate, the {@link #startScan(ScanListener)} method should be overridden. */ protected abstract void startScan(); @@ -401,9 +401,8 @@ protected void deactivate() { /** * Can be overridden to start background discovery logic. This method is - * called when {@link AbstractDiscoveryService#setBackgroundDiscoveryEnabled(boolean)} is called with true as - * parameter and when the component is being - * activated (see {@link AbstractDiscoveryService#activate()}. + * called if background discovery is enabled when the component is being + * activated (see {@link AbstractDiscoveryService#activate}. */ protected void startBackgroundDiscovery() { // can be overridden @@ -411,8 +410,7 @@ protected void startBackgroundDiscovery() { /** * Can be overridden to stop background discovery logic. This method is - * called when {@link AbstractDiscoveryService#setBackgroundDiscoveryEnabled(boolean)} is called with false as - * parameter and when the component is being + * called if background discovery is enabled when the component is being * deactivated (see {@link AbstractDiscoveryService#deactivate()}. */ protected void stopBackgroundDiscovery() { diff --git a/bundles/org.openhab.core.config.discovery/src/main/java/org/openhab/core/config/discovery/DiscoveryResultBuilder.java b/bundles/org.openhab.core.config.discovery/src/main/java/org/openhab/core/config/discovery/DiscoveryResultBuilder.java index b35e3a26b23..c64dd0392f0 100644 --- a/bundles/org.openhab.core.config.discovery/src/main/java/org/openhab/core/config/discovery/DiscoveryResultBuilder.java +++ b/bundles/org.openhab.core.config.discovery/src/main/java/org/openhab/core/config/discovery/DiscoveryResultBuilder.java @@ -89,7 +89,7 @@ public DiscoveryResultBuilder withProperties(@Nullable Map prope /** * Adds a property to the desired result. * - * @param property of the desired result + * @param key property of the desired result * @return the updated builder */ public DiscoveryResultBuilder withProperty(String key, Object value) { diff --git a/bundles/org.openhab.core.config.discovery/src/main/java/org/openhab/core/config/discovery/DiscoveryService.java b/bundles/org.openhab.core.config.discovery/src/main/java/org/openhab/core/config/discovery/DiscoveryService.java index d32596de015..8d3f5058713 100644 --- a/bundles/org.openhab.core.config.discovery/src/main/java/org/openhab/core/config/discovery/DiscoveryService.java +++ b/bundles/org.openhab.core.config.discovery/src/main/java/org/openhab/core/config/discovery/DiscoveryService.java @@ -89,7 +89,7 @@ public interface DiscoveryService { /** * Stops an active scan for devices.
- * This method must not block any calls such as {@link #startScan()} and must + * This method must not block any calls such as {@link #startScan} and must * return fast. *

* After this method returns, no further notifications about {@link DiscoveryResult}s are allowed to be sent to any diff --git a/bundles/org.openhab.core.config.discovery/src/main/java/org/openhab/core/config/discovery/inbox/Inbox.java b/bundles/org.openhab.core.config.discovery/src/main/java/org/openhab/core/config/discovery/inbox/Inbox.java index ebcee6a9840..048e9e0be01 100644 --- a/bundles/org.openhab.core.config.discovery/src/main/java/org/openhab/core/config/discovery/inbox/Inbox.java +++ b/bundles/org.openhab.core.config.discovery/src/main/java/org/openhab/core/config/discovery/inbox/Inbox.java @@ -95,7 +95,7 @@ public interface Inbox { * case the result object should be regarded as known by the system so that * further processing should be skipped. *

- * If the specified flag is {@code null}, {@link DiscoveryResultFlag.NEW} is set by default. + * If the specified flag is {@code null}, {@link DiscoveryResultFlag#NEW} is set by default. * * @param flag the flag of the given thingUID result to be set (could be null) */ diff --git a/bundles/org.openhab.core.ephemeris/src/main/java/org/openhab/core/ephemeris/EphemerisManager.java b/bundles/org.openhab.core.ephemeris/src/main/java/org/openhab/core/ephemeris/EphemerisManager.java index 4ffb3417b09..1b7c92880d2 100644 --- a/bundles/org.openhab.core.ephemeris/src/main/java/org/openhab/core/ephemeris/EphemerisManager.java +++ b/bundles/org.openhab.core.ephemeris/src/main/java/org/openhab/core/ephemeris/EphemerisManager.java @@ -57,7 +57,7 @@ public interface EphemerisManager { * Tests given day status against given userfile * * @param date observed day - * @param url bundle resource file containing holiday definitions + * @param resource bundle resource file containing holiday definitions * @return whether the day is bank holiday or not */ boolean isBankHoliday(ZonedDateTime date, URL resource); @@ -66,7 +66,7 @@ public interface EphemerisManager { * Tests given day status against given userfile * * @param date observed day - * @param source absolute or relative path to the file on local file system + * @param filename absolute or relative path to the file on local file system * @return whether the day is bank holiday or not * @throws FileNotFoundException */ @@ -85,7 +85,7 @@ public interface EphemerisManager { * Get given day name from given userfile * * @param date observed day - * @param url bundle resource file containing holiday definitions + * @param resource bundle resource file containing holiday definitions * @return name of the day or null if no corresponding entry */ @Nullable @@ -95,7 +95,7 @@ public interface EphemerisManager { * Get given day name from given userfile * * @param date observed day - * @param source absolute or relative path to the file on local file system + * @param filename absolute or relative path to the file on local file system * @return name of the day or null if no corresponding entry * @throws FileNotFoundException */ @@ -115,7 +115,7 @@ public interface EphemerisManager { * Gets the first next to come holiday in a 1 year time window * * @param startDate first day of the time window - * @param url bundle resource file containing holiday definitions + * @param resource bundle resource file containing holiday definitions * @return next coming holiday */ @Nullable @@ -125,7 +125,7 @@ public interface EphemerisManager { * Gets the first next to come holiday in a 1 year time window * * @param startDate first day of the time window - * @param source absolute or relative path to the file on local file system + * @param filename absolute or relative path to the file on local file system * @return next coming holiday * @throws FileNotFoundException */ @@ -135,7 +135,7 @@ public interface EphemerisManager { /** * Gets the localized holiday description * - * @param holidayName code of searched holiday + * @param holiday code of searched holiday * @return localized holiday description */ @Nullable @@ -155,7 +155,7 @@ public interface EphemerisManager { * * @param from first day of the time window * @param searchedHoliday name of the searched holiday - * @param url bundle resource file containing holiday definitions + * @param resource bundle resource file containing holiday definitions * @return difference in days, -1 if not found */ long getDaysUntil(ZonedDateTime from, String searchedHoliday, URL resource); @@ -165,7 +165,7 @@ public interface EphemerisManager { * * @param from first day of the time window * @param searchedHoliday name of the searched holiday - * @param source absolute or relative path to the file on local file system + * @param filename absolute or relative path to the file on local file system * @return difference in days, -1 if not found * @throws FileNotFoundException */ diff --git a/bundles/org.openhab.core.id/src/main/java/org/openhab/core/id/InstanceUUID.java b/bundles/org.openhab.core.id/src/main/java/org/openhab/core/id/InstanceUUID.java index ae05c09554a..7162133ab2a 100644 --- a/bundles/org.openhab.core.id/src/main/java/org/openhab/core/id/InstanceUUID.java +++ b/bundles/org.openhab.core.id/src/main/java/org/openhab/core/id/InstanceUUID.java @@ -38,7 +38,7 @@ public class InstanceUUID { static String uuid; /** - * Retrieves a unified unique id, based on {@link java.util.UUID.randomUUID()} + * Retrieves a unified unique id, based on {@link java.util.UUID#randomUUID()} * * @return a UUID which identifies the instance or null, if uuid cannot be persisted */ diff --git a/bundles/org.openhab.core.io.console/src/main/java/org/openhab/core/io/console/ConsoleCommandCompleter.java b/bundles/org.openhab.core.io.console/src/main/java/org/openhab/core/io/console/ConsoleCommandCompleter.java index 5e73093f76a..49518392908 100644 --- a/bundles/org.openhab.core.io.console/src/main/java/org/openhab/core/io/console/ConsoleCommandCompleter.java +++ b/bundles/org.openhab.core.io.console/src/main/java/org/openhab/core/io/console/ConsoleCommandCompleter.java @@ -17,8 +17,8 @@ import org.eclipse.jdt.annotation.NonNullByDefault; /** - * Implementing this interface allows a {@link ConsoleCommandExtension} to - * provide completions for the user as they write commands. + * Implementing this interface allows a {@link org.openhab.core.io.console.extensions.ConsoleCommandExtension} + * to provide completions for the user as they write commands. * * @author Cody Cutrer - Initial contribution */ diff --git a/bundles/org.openhab.core.io.http/src/main/java/org/openhab/core/io/http/Handler.java b/bundles/org.openhab.core.io.http/src/main/java/org/openhab/core/io/http/Handler.java index 6721fdbf696..a9d38b566e0 100644 --- a/bundles/org.openhab.core.io.http/src/main/java/org/openhab/core/io/http/Handler.java +++ b/bundles/org.openhab.core.io.http/src/main/java/org/openhab/core/io/http/Handler.java @@ -22,7 +22,7 @@ * HTTP. Handlers are called before servlet who will receive request, thus they can not mutate servlet response, but * they can generate its own response depending on actual needs. * Pay attention to error handling - as a proper executions might report exceptions, but fault path handled in - * {@link #handleError(HttpServletRequest, HttpServletResponse, HandlerContext) method must remain silent and take care + * {@link #handleError(HttpServletRequest, HttpServletResponse, HandlerContext)} method must remain silent and take care * of all issues which might occur while handling error. * * @author Łukasz Dywicki - Initial contribution diff --git a/bundles/org.openhab.core.io.rest.sse/src/main/java/org/openhab/core/io/rest/sse/SseResource.java b/bundles/org.openhab.core.io.rest.sse/src/main/java/org/openhab/core/io/rest/sse/SseResource.java index cf56c06ec31..9cbb7bd28cb 100644 --- a/bundles/org.openhab.core.io.rest.sse/src/main/java/org/openhab/core/io/rest/sse/SseResource.java +++ b/bundles/org.openhab.core.io.rest.sse/src/main/java/org/openhab/core/io/rest/sse/SseResource.java @@ -197,8 +197,6 @@ private void handleEventBroadcastTopic(Event event) { /** * Subscribes the connecting client for state updates. It will initially only send a "ready" event with a unique * connectionId that the client can use to dynamically alter the list of tracked items. - * - * @return {@link EventOutput} object associated with the incoming connection. */ @GET @Path("/states") diff --git a/bundles/org.openhab.core.io.rest/src/main/java/org/openhab/core/io/rest/LocaleService.java b/bundles/org.openhab.core.io.rest/src/main/java/org/openhab/core/io/rest/LocaleService.java index c41e565e461..5f84e8b0742 100644 --- a/bundles/org.openhab.core.io.rest/src/main/java/org/openhab/core/io/rest/LocaleService.java +++ b/bundles/org.openhab.core.io.rest/src/main/java/org/openhab/core/io/rest/LocaleService.java @@ -28,7 +28,7 @@ public interface LocaleService { /** * Returns the locale in respect to the given "Accept-Language" HTTP header. * - * @param language value of the "Accept-Language" HTTP header (can be null). + * @param acceptLanguageHttpHeader value of the "Accept-Language" HTTP header (can be null). * @return Locale for the "Accept-Language" HTTP header or default locale if * header is not set or can not be parsed. */ diff --git a/bundles/org.openhab.core.io.rest/src/main/java/org/openhab/core/io/rest/RESTConstants.java b/bundles/org.openhab.core.io.rest/src/main/java/org/openhab/core/io/rest/RESTConstants.java index 7f3c5b5affb..73a7c68474a 100644 --- a/bundles/org.openhab.core.io.rest/src/main/java/org/openhab/core/io/rest/RESTConstants.java +++ b/bundles/org.openhab.core.io.rest/src/main/java/org/openhab/core/io/rest/RESTConstants.java @@ -27,5 +27,15 @@ public class RESTConstants { public static final String JAX_RS_NAME = "openhab"; - public static final String API_VERSION = "5"; + /** + * Version of the openHAB API + * + * Version 1: initial version + * Version 2: include invisible widgets into sitemap response (#499) + * Version 3: Addition of anyFormat icon parameter (#978) + * Version 4: OH3, refactored extensions to addons (#1560) + * Version 5: transparent charts (#2502) + * Version 6: extended chart period parameter format (#3863) + */ + public static final String API_VERSION = "6"; } diff --git a/bundles/org.openhab.core.io.transport.mdns/src/main/java/org/openhab/core/io/transport/mdns/MDNSService.java b/bundles/org.openhab.core.io.transport.mdns/src/main/java/org/openhab/core/io/transport/mdns/MDNSService.java index 28331c81d22..a87d46a79ff 100644 --- a/bundles/org.openhab.core.io.transport.mdns/src/main/java/org/openhab/core/io/transport/mdns/MDNSService.java +++ b/bundles/org.openhab.core.io.transport.mdns/src/main/java/org/openhab/core/io/transport/mdns/MDNSService.java @@ -24,14 +24,14 @@ public interface MDNSService { /** * This method registers a service to be announced through Bonjour/MDNS * - * @param serviceDescription the {@link ServiceDescription} instance with all details to identify the service + * @param description the {@link ServiceDescription} instance with all details to identify the service */ void registerService(ServiceDescription description); /** * This method unregisters a service not to be announced through Bonjour/MDNS * - * @param serviceDescription the {@link ServiceDescription} instance with all details to identify the service + * @param description the {@link ServiceDescription} instance with all details to identify the service */ void unregisterService(ServiceDescription description); } diff --git a/bundles/org.openhab.core.io.transport.mdns/src/main/java/org/openhab/core/io/transport/mdns/ServiceDescription.java b/bundles/org.openhab.core.io.transport.mdns/src/main/java/org/openhab/core/io/transport/mdns/ServiceDescription.java index 3e456c67b6c..727230c99ab 100644 --- a/bundles/org.openhab.core.io.transport.mdns/src/main/java/org/openhab/core/io/transport/mdns/ServiceDescription.java +++ b/bundles/org.openhab.core.io.transport.mdns/src/main/java/org/openhab/core/io/transport/mdns/ServiceDescription.java @@ -33,7 +33,6 @@ public class ServiceDescription { * @param serviceName String service name, like "openHAB" * @param servicePort Int service port, like 8080 * @param serviceProperties Hashtable service props, like url = "/rest" - * @param serviceDescription String service description text, like "openHAB REST interface" */ public ServiceDescription(String serviceType, String serviceName, int servicePort, Hashtable serviceProperties) { diff --git a/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusBitUtilities.java b/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusBitUtilities.java index be2ca28b505..92894fa36b8 100644 --- a/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusBitUtilities.java +++ b/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusBitUtilities.java @@ -240,7 +240,6 @@ public static byte extractSInt8(byte[] bytes, int registerIndex, boolean hiByte) * - it is assumed that each high and low byte is encoded in most significant bit first order * * @param bytes registers represented by sequence of bytes - * @param registerIndex index of register. First register has index of 0. * @param index index of the byte in registers * @return 0 when bit is set, 1 otherwise * @throws IllegalArgumentException when index is out of bounds @@ -272,7 +271,6 @@ public static short extractUInt8(byte[] bytes, int registerIndex, boolean hiByte * - it is assumed that each high and low byte is encoded in most significant bit first order * * @param bytes registers represented by sequence of bytes - * @param registerIndex index of register. First register has index of 0. * @param index index of the byte in registers * @return 0 when bit is set, 1 otherwise * @throws IllegalArgumentException when index is out of bounds @@ -735,8 +733,8 @@ public static ModbusRegisterArray commandToRegisters(Command command, ModbusCons /** * Converts command to a boolean * - * true value is represented by {@link OnOffType.ON}, {@link OpenClosedType.OPEN}. - * false value is represented by {@link OnOffType.OFF}, {@link OpenClosedType.CLOSED}. + * true value is represented by {@link OnOffType#ON}, {@link OpenClosedType#OPEN}. + * false value is represented by {@link OnOffType#OFF}, {@link OpenClosedType#CLOSED}. * Furthermore, {@link DecimalType} are converted to boolean true if they are unequal to zero. * * @param command to convert to boolean diff --git a/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusCommunicationInterface.java b/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusCommunicationInterface.java index 27f72d7301f..9fa775c47b9 100644 --- a/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusCommunicationInterface.java +++ b/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusCommunicationInterface.java @@ -45,8 +45,8 @@ public interface ModbusCommunicationInterface extends AutoCloseable { * background. * * @param request request to send - * @param callback callback to call with data - * @param callback callback to call in case of failure + * @param resultCallback callback to call with data + * @param failureCallback callback to call in case of failure * @return future representing the polled task * @throws IllegalStateException when this communication has been closed already */ @@ -62,8 +62,8 @@ Future submitOneTimePoll(ModbusReadRequestBlueprint request, ModbusReadCallba * @param request request to send * @param pollPeriodMillis poll interval, in milliseconds * @param initialDelayMillis initial delay before starting polling, in milliseconds - * @param callback callback to call with data - * @param callback callback to call in case of failure + * @param resultCallback callback to call with data + * @param failureCallback callback to call in case of failure * @return poll task representing the regular poll * @throws IllegalStateException when this communication has been closed already */ @@ -86,8 +86,8 @@ PollTask registerRegularPoll(ModbusReadRequestBlueprint request, long pollPeriod * background. * * @param request request to send - * @param callback callback to call with response - * @param callback callback to call in case of failure + * @param resultCallback callback to call with response + * @param failureCallback callback to call in case of failure * @return future representing the task * @throws IllegalStateException when this communication has been closed already */ diff --git a/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusConstants.java b/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusConstants.java index 3bcb701399f..fa7fc83e88c 100644 --- a/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusConstants.java +++ b/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusConstants.java @@ -24,12 +24,12 @@ * * Maximum number of registers that are allowed to be read. * - * The Modbus protocol has many intepretation on maximum data size of messages. Good reference is here: - * https://wingpath.co.uk/manpage.php?product=modtest&page=message_limits.html + * The Modbus protocol has many intepretation on maximum data size of messages. Good reference is + * here. * - * We try to follow modern specification here (V1.1B3): - * https://modbus.org/docs/Modbus_Application_Protocol_V1_1b3.pdf. See section 4.1 Protocol Specification in the - * specification. + * We try to follow + * modern specification here (V1.1B3). + * See section 4.1 Protocol Specification in the specification. * * According to V1.1B3, maximum size for PDU is 253 bytes, making maximum ADU size 256 (RTU) or 260 (TCP). * @@ -40,7 +40,7 @@ * * * Reads are limited by response PDU size. - * Writes (FC15 & FC16) are limited by write request ADU size. + * Writes (FC15 and FC16) are limited by write request ADU size. * * * @author Sami Salonen - Initial contribution diff --git a/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusFailureCallback.java b/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusFailureCallback.java index 28d2fff22ea..b5531c34817 100644 --- a/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusFailureCallback.java +++ b/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusFailureCallback.java @@ -25,7 +25,7 @@ public interface ModbusFailureCallback { /** * Callback handling response with error * - * @param asyncModbusFailure details of the failure + * @param failure details of the failure */ void handle(AsyncModbusFailure failure); } diff --git a/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusRegisterArray.java b/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusRegisterArray.java index 63902f8d1e1..6e1a840b5cb 100644 --- a/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusRegisterArray.java +++ b/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusRegisterArray.java @@ -39,7 +39,6 @@ public ModbusRegisterArray(byte... bytes) { * Construct plain ModbusRegisterArray array from register values * * @param registerValues register values, each int corresponding to one register - * @return */ public ModbusRegisterArray(int... registerValues) { bytes = new byte[registerValues.length * 2]; diff --git a/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusWriteCallback.java b/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusWriteCallback.java index d14d3caee58..a23b7521837 100644 --- a/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusWriteCallback.java +++ b/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusWriteCallback.java @@ -26,7 +26,7 @@ public interface ModbusWriteCallback extends ModbusResultCallback { /** * Callback handling response data * - * @param asyncModbusWriteResult result of the write operation + * @param result result of the write operation */ void handle(AsyncModbusWriteResult result); } diff --git a/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusWriteCoilRequestBlueprint.java b/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusWriteCoilRequestBlueprint.java index 99ed9ae2078..8753294db14 100644 --- a/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusWriteCoilRequestBlueprint.java +++ b/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusWriteCoilRequestBlueprint.java @@ -35,8 +35,8 @@ public class ModbusWriteCoilRequestBlueprint extends ModbusWriteRequestBlueprint * @param slaveId slave id to write to * @param reference reference address * @param data bit to write - * @param writeMultiple whether to use {@link ModbusWriteFunctionCode.WRITE_MULTIPLE_COILS} over - * {@link ModbusWriteFunctionCode.WRITE_COIL} + * @param writeMultiple whether to use {@link ModbusWriteFunctionCode#WRITE_MULTIPLE_COILS} over + * {@link ModbusWriteFunctionCode#WRITE_COIL} * @param maxTries maximum number of tries in case of errors, should be at least 1 */ public ModbusWriteCoilRequestBlueprint(int slaveId, int reference, boolean data, boolean writeMultiple, @@ -50,8 +50,8 @@ public ModbusWriteCoilRequestBlueprint(int slaveId, int reference, boolean data, * @param slaveId slave id to write to * @param reference reference address * @param data bit(s) to write - * @param writeMultiple whether to use {@link ModbusWriteFunctionCode.WRITE_MULTIPLE_COILS} over - * {@link ModbusWriteFunctionCode.WRITE_COIL}. Useful with single bit of data. + * @param writeMultiple whether to use {@link ModbusWriteFunctionCode#WRITE_MULTIPLE_COILS} over + * {@link ModbusWriteFunctionCode#WRITE_COIL}. Useful with single bit of data. * @param maxTries maximum number of tries in case of errors, should be at least 1 * @throws IllegalArgumentException in case data is empty, writeMultiple is * false but there are many bits to write. diff --git a/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusWriteRegisterRequestBlueprint.java b/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusWriteRegisterRequestBlueprint.java index b21f207a6eb..895ea0679e0 100644 --- a/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusWriteRegisterRequestBlueprint.java +++ b/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ModbusWriteRegisterRequestBlueprint.java @@ -35,8 +35,8 @@ public class ModbusWriteRegisterRequestBlueprint extends ModbusWriteRequestBluep * @param slaveId slave id to write to * @param reference reference address * @param registers register(s) to write - * @param writeMultiple whether to use {@link ModbusWriteFunctionCode.WRITE_MULTIPLE_COILS} over - * {@link ModbusWriteFunctionCode.WRITE_COIL}. Useful with single register of data. + * @param writeMultiple whether to use {@link ModbusWriteFunctionCode#WRITE_MULTIPLE_COILS} over + * {@link ModbusWriteFunctionCode#WRITE_COIL}. Useful with single register of data. * @param maxTries maximum number of tries in case of errors, should be at least 1 * @throws IllegalArgumentException in case data is empty, writeMultiple is * false but there are many registers to write. diff --git a/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/PollTask.java b/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/PollTask.java index c7ece74b99b..4c962bda9ca 100644 --- a/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/PollTask.java +++ b/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/PollTask.java @@ -22,7 +22,7 @@ * * @author Sami Salonen - Initial contribution * - * @see ModbusManager.registerRegularPoll + * @see ModbusCommunicationInterface#registerRegularPoll */ @NonNullByDefault public interface PollTask extends diff --git a/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ValueBuffer.java b/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ValueBuffer.java index ed7e869223a..fdbe674dbb0 100644 --- a/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ValueBuffer.java +++ b/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/ValueBuffer.java @@ -165,7 +165,7 @@ public ValueBuffer get(byte[] dst) { * Extract signed 8-bit integer at current position, and advance position. * * @return signed 8-bit integer (byte) - * @see ModbusBitUtilities.extractSInt8 + * @see ModbusBitUtilities#extractSInt8 * @throws IllegalArgumentException when there are not enough bytes in this ValueBuffer */ public byte getSInt8() { @@ -176,7 +176,7 @@ public byte getSInt8() { * Extract unsigned 8-bit integer at current position, and advance position. * * @return unsigned 8-bit integer - * @see ModbusBitUtilities.extractUInt8 + * @see ModbusBitUtilities#extractUInt8 * @throws IllegalArgumentException when there are not enough bytes in this ValueBuffer */ public short getUInt8() { @@ -187,7 +187,7 @@ public short getUInt8() { * Extract signed 16-bit integer at current position, and advance position. * * @return signed 16-bit integer (short) - * @see ModbusBitUtilities.extractSInt16 + * @see ModbusBitUtilities#extractSInt16 * @throws IllegalArgumentException when there are not enough bytes in this ValueBuffer */ public short getSInt16() { @@ -198,7 +198,7 @@ public short getSInt16() { * Extract unsigned 16-bit integer at current position, and advance position. * * @return unsigned 16-bit integer - * @see ModbusBitUtilities.extractUInt16 + * @see ModbusBitUtilities#extractUInt16 * @throws IllegalArgumentException when there are not enough bytes in this ValueBuffer */ public int getUInt16() { @@ -209,7 +209,7 @@ public int getUInt16() { * Extract signed 32-bit integer at current position, and advance position. * * @return signed 32-bit integer - * @see ModbusBitUtilities.extractSInt32 + * @see ModbusBitUtilities#extractSInt32 * @throws IllegalArgumentException when there are not enough bytes in this ValueBuffer */ public int getSInt32() { @@ -220,7 +220,7 @@ public int getSInt32() { * Extract unsigned 32-bit integer at current position, and advance position. * * @return unsigned 32-bit integer - * @see ModbusBitUtilities.extractUInt32 + * @see ModbusBitUtilities#extractUInt32 * @throws IllegalArgumentException when there are not enough bytes in this ValueBuffer */ public long getUInt32() { @@ -233,7 +233,7 @@ public long getUInt32() { * This is identical with getSInt32, but with registers swapped. * * @return signed 32-bit integer - * @see ModbusBitUtilities.extractSInt32Swap + * @see ModbusBitUtilities#extractSInt32Swap * @throws IllegalArgumentException when there are not enough bytes in this ValueBuffer */ public int getSInt32Swap() { @@ -246,7 +246,7 @@ public int getSInt32Swap() { * This is identical with getUInt32, but with registers swapped. * * @return unsigned 32-bit integer - * @see ModbusBitUtilities.extractUInt32Swap + * @see ModbusBitUtilities#extractUInt32Swap * @throws IllegalArgumentException when there are not enough bytes in this ValueBuffer */ public long getUInt32Swap() { @@ -257,7 +257,7 @@ public long getUInt32Swap() { * Extract signed 64-bit integer at current position, and advance position. * * @return signed 64-bit integer - * @see ModbusBitUtilities.extractInt64 + * @see ModbusBitUtilities#extractSInt64 * @throws IllegalArgumentException when there are not enough bytes in this ValueBuffer */ public long getSInt64() { @@ -268,7 +268,7 @@ public long getSInt64() { * Extract unsigned 64-bit integer at current position, and advance position. * * @return unsigned 64-bit integer - * @see ModbusBitUtilities.extractUInt64 + * @see ModbusBitUtilities#extractUInt64 * @throws IllegalArgumentException when there are not enough bytes in this ValueBuffer */ public BigInteger getUInt64() { @@ -281,7 +281,7 @@ public BigInteger getUInt64() { * This is identical with getSInt64, but with registers swapped. * * @return signed 64-bit integer - * @see ModbusBitUtilities.extractInt64Swap + * @see ModbusBitUtilities#extractSInt64Swap * @throws IllegalArgumentException when there are not enough bytes in this ValueBuffer */ public long getSInt64Swap() { @@ -294,7 +294,7 @@ public long getSInt64Swap() { * This is identical with getUInt64, but with registers swapped. * * @return unsigned 64-bit integer - * @see ModbusBitUtilities.extractUInt64Swap + * @see ModbusBitUtilities#extractUInt64Swap * @throws IllegalArgumentException when there are not enough bytes in this ValueBuffer */ public BigInteger getUInt64Swap() { @@ -307,7 +307,7 @@ public BigInteger getUInt64Swap() { * Note that this method can return floating point NaN and floating point infinity. * * @return single-precision 32-bit IEEE 754 floating point - * @see ModbusBitUtilities.extractFloat32 + * @see ModbusBitUtilities#extractFloat32 * @throws IllegalArgumentException when there are not enough bytes in this ValueBuffer */ public float getFloat32() { @@ -322,7 +322,7 @@ public float getFloat32() { * Note that this method can return floating point NaN and floating point infinity. * * @return single-precision 32-bit IEEE 754 floating point - * @see ModbusBitUtilities.extractFloat32 + * @see ModbusBitUtilities#extractFloat32 * @throws IllegalArgumentException when there are not enough bytes in this ValueBuffer */ public float getFloat32Swap() { diff --git a/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/json/WriteRequestJsonUtilities.java b/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/json/WriteRequestJsonUtilities.java index 757b3be1d76..3f8ae22bb2d 100644 --- a/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/json/WriteRequestJsonUtilities.java +++ b/bundles/org.openhab.core.io.transport.modbus/src/main/java/org/openhab/core/io/transport/modbus/json/WriteRequestJsonUtilities.java @@ -85,10 +85,10 @@ private WriteRequestJsonUtilities() { * protocol specification * @throws IllegalStateException in case of parsing errors and unexpected json structure * - * @see WriteRequestJsonUtilities.JSON_FUNCTION_CODE - * @see WriteRequestJsonUtilities.JSON_ADDRESS - * @see WriteRequestJsonUtilities.JSON_VALUE - * @see WriteRequestJsonUtilities.JSON_MAX_TRIES + * @see WriteRequestJsonUtilities#JSON_FUNCTION_CODE + * @see WriteRequestJsonUtilities#JSON_ADDRESS + * @see WriteRequestJsonUtilities#JSON_VALUE + * @see WriteRequestJsonUtilities#JSON_MAX_TRIES */ public static Collection fromJson(int unitId, String jsonString) { JsonArray jsonArray = JsonParser.parseString(jsonString).getAsJsonArray(); diff --git a/bundles/org.openhab.core.io.transport.mqtt/src/main/java/org/openhab/core/io/transport/mqtt/MqttWillAndTestament.java b/bundles/org.openhab.core.io.transport.mqtt/src/main/java/org/openhab/core/io/transport/mqtt/MqttWillAndTestament.java index feff499b3f2..9ecc752d372 100644 --- a/bundles/org.openhab.core.io.transport.mqtt/src/main/java/org/openhab/core/io/transport/mqtt/MqttWillAndTestament.java +++ b/bundles/org.openhab.core.io.transport.mqtt/src/main/java/org/openhab/core/io/transport/mqtt/MqttWillAndTestament.java @@ -109,7 +109,7 @@ public class MqttWillAndTestament { } /** - * Create a new {@link} MqttWillAndTestament with at least a topic name. + * Create a new {@link MqttWillAndTestament} with at least a topic name. * * @param topic topic is a normal topic string (no placeholders are allowed) * @param payload The optional payload. Can be null. diff --git a/bundles/org.openhab.core.io.transport.serial/src/main/java/org/openhab/core/io/transport/serial/SerialPort.java b/bundles/org.openhab.core.io.transport.serial/src/main/java/org/openhab/core/io/transport/serial/SerialPort.java index 4d8779cc60e..5d4f629dad2 100644 --- a/bundles/org.openhab.core.io.transport.serial/src/main/java/org/openhab/core/io/transport/serial/SerialPort.java +++ b/bundles/org.openhab.core.io.transport.serial/src/main/java/org/openhab/core/io/transport/serial/SerialPort.java @@ -150,7 +150,7 @@ void setSerialPortParams(int baudrate, int dataBits, int stopBits, int parity) String getName(); /** - * Registers a {@link SerialPortEventListener} object to listen for {@link SerialEvents}. + * Registers a {@link SerialPortEventListener} object to listen for {@link SerialPortEvent}s. * *

* Interest in specific events may be expressed using the notifyOnXXX calls. @@ -266,7 +266,7 @@ void setSerialPortParams(int baudrate, int dataBits, int stopBits, int parity) /** * Sets the flow control mode value. * - * @param flowcontrol The flowcontrol (int) parameter. + * @param flowcontrolRtsctsOut The flowcontrol (int) parameter. * @throws UnsupportedCommOperationException Unsupported Comm Operation Exception. */ void setFlowControlMode(int flowcontrolRtsctsOut) throws UnsupportedCommOperationException; @@ -281,7 +281,7 @@ void setSerialPortParams(int baudrate, int dataBits, int stopBits, int parity) /** * Enable receive threshold with the specified thresh parameter. * - * @param thresh The thresh (int) parameter. + * @param i The thresh (int) parameter. * @throws UnsupportedCommOperationException Unsupported Comm Operation Exception. */ void enableReceiveThreshold(int i) throws UnsupportedCommOperationException; diff --git a/bundles/org.openhab.core.io.transport.upnp/src/main/java/org/openhab/core/io/transport/upnp/UpnpIOService.java b/bundles/org.openhab.core.io.transport.upnp/src/main/java/org/openhab/core/io/transport/upnp/UpnpIOService.java index 36168b44855..69366df89c3 100644 --- a/bundles/org.openhab.core.io.transport.upnp/src/main/java/org/openhab/core/io/transport/upnp/UpnpIOService.java +++ b/bundles/org.openhab.core.io.transport.upnp/src/main/java/org/openhab/core/io/transport/upnp/UpnpIOService.java @@ -28,7 +28,7 @@ public interface UpnpIOService { * Invoke an UPNP Action * * @param participant the participant to invoke the action for - * @param serivceID the UPNP service to invoke the action upon + * @param serviceID the UPNP service to invoke the action upon * @param actionID the Action to invoke * @param inputs a map of {variable,values} to parameterize the Action that will be invoked */ diff --git a/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/CommonWebSocketServlet.java b/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/CommonWebSocketServlet.java index 7937ef0e39b..d1eb7e95523 100644 --- a/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/CommonWebSocketServlet.java +++ b/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/CommonWebSocketServlet.java @@ -30,6 +30,7 @@ import org.openhab.core.auth.AuthenticationException; import org.openhab.core.auth.Role; import org.openhab.core.io.rest.auth.AuthFilter; +import org.openhab.core.io.websocket.event.EventWebSocketAdapter; import org.osgi.service.component.annotations.Activate; import org.osgi.service.component.annotations.Component; import org.osgi.service.component.annotations.Reference; diff --git a/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/WebSocketAdapter.java b/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/WebSocketAdapter.java index 5007e1faf10..ecf9263010b 100644 --- a/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/WebSocketAdapter.java +++ b/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/WebSocketAdapter.java @@ -35,7 +35,7 @@ public interface WebSocketAdapter { /** * Creates a websocket instance. - * It should use the {@link org.eclipse.jetty.websocket.api.annotations} or implement + * It should use the {@code org.eclipse.jetty.websocket.api.annotations} or implement * {@link org.eclipse.jetty.websocket.api.WebSocketListener}. * * @return a websocket instance. diff --git a/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/EventDTO.java b/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/event/EventDTO.java similarity index 98% rename from bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/EventDTO.java rename to bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/event/EventDTO.java index 6038e41c929..87f0138aecc 100644 --- a/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/EventDTO.java +++ b/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/event/EventDTO.java @@ -10,7 +10,7 @@ * * SPDX-License-Identifier: EPL-2.0 */ -package org.openhab.core.io.websocket; +package org.openhab.core.io.websocket.event; import java.util.Objects; diff --git a/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/EventProcessingException.java b/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/event/EventProcessingException.java similarity index 94% rename from bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/EventProcessingException.java rename to bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/event/EventProcessingException.java index b2a504ea61e..a83ab244214 100644 --- a/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/EventProcessingException.java +++ b/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/event/EventProcessingException.java @@ -10,7 +10,7 @@ * * SPDX-License-Identifier: EPL-2.0 */ -package org.openhab.core.io.websocket; +package org.openhab.core.io.websocket.event; import org.eclipse.jdt.annotation.NonNullByDefault; diff --git a/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/EventWebSocket.java b/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/event/EventWebSocket.java similarity index 99% rename from bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/EventWebSocket.java rename to bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/event/EventWebSocket.java index f37bb4cc8e2..f0136dc3532 100644 --- a/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/EventWebSocket.java +++ b/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/event/EventWebSocket.java @@ -10,7 +10,7 @@ * * SPDX-License-Identifier: EPL-2.0 */ -package org.openhab.core.io.websocket; +package org.openhab.core.io.websocket.event; import java.io.IOException; import java.lang.reflect.Type; diff --git a/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/EventWebSocketAdapter.java b/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/event/EventWebSocketAdapter.java similarity index 96% rename from bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/EventWebSocketAdapter.java rename to bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/event/EventWebSocketAdapter.java index 6ef61b804cb..df905c7e3ee 100644 --- a/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/EventWebSocketAdapter.java +++ b/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/event/EventWebSocketAdapter.java @@ -10,7 +10,7 @@ * * SPDX-License-Identifier: EPL-2.0 */ -package org.openhab.core.io.websocket; +package org.openhab.core.io.websocket.event; import java.util.Set; import java.util.concurrent.CopyOnWriteArraySet; @@ -21,6 +21,7 @@ import org.openhab.core.events.Event; import org.openhab.core.events.EventPublisher; import org.openhab.core.events.EventSubscriber; +import org.openhab.core.io.websocket.WebSocketAdapter; import org.openhab.core.items.ItemRegistry; import org.osgi.service.component.annotations.Activate; import org.osgi.service.component.annotations.Component; diff --git a/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/ItemEventUtility.java b/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/event/ItemEventUtility.java similarity index 99% rename from bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/ItemEventUtility.java rename to bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/event/ItemEventUtility.java index e8f1d2b9ec9..547e161d0a0 100644 --- a/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/ItemEventUtility.java +++ b/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/event/ItemEventUtility.java @@ -10,7 +10,7 @@ * * SPDX-License-Identifier: EPL-2.0 */ -package org.openhab.core.io.websocket; +package org.openhab.core.io.websocket.event; import java.util.List; import java.util.regex.Matcher; diff --git a/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/log/LogDTO.java b/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/log/LogDTO.java new file mode 100644 index 00000000000..ff4c0587372 --- /dev/null +++ b/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/log/LogDTO.java @@ -0,0 +1,34 @@ +/** + * Copyright (c) 2010-2023 Contributors to the openHAB project + * + * See the NOTICE file(s) distributed with this work for additional + * information. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License 2.0 which is available at + * http://www.eclipse.org/legal/epl-2.0 + * + * SPDX-License-Identifier: EPL-2.0 + */ +package org.openhab.core.io.websocket.log; + +import java.util.Date; + +import org.eclipse.jdt.annotation.NonNullByDefault; +import org.eclipse.jdt.annotation.Nullable; +import org.openhab.core.io.websocket.event.EventDTO; +import org.osgi.service.log.LogLevel; + +/** + * The {@link EventDTO} is used for serialization and deserialization of events + * + * @author Jan N. Klug - Initial contribution + */ +@NonNullByDefault +public class LogDTO { + public @Nullable String loggerName; + public @Nullable LogLevel level; + public @Nullable Date timestamp; + public long unixtime; + public @Nullable String message; +} diff --git a/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/log/LogWebSocket.java b/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/log/LogWebSocket.java new file mode 100644 index 00000000000..e08cd24536e --- /dev/null +++ b/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/log/LogWebSocket.java @@ -0,0 +1,148 @@ +/** + * Copyright (c) 2010-2023 Contributors to the openHAB project + * + * See the NOTICE file(s) distributed with this work for additional + * information. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License 2.0 which is available at + * http://www.eclipse.org/legal/epl-2.0 + * + * SPDX-License-Identifier: EPL-2.0 + */ +package org.openhab.core.io.websocket.log; + +import java.io.IOException; +import java.util.Date; +import java.util.List; +import java.util.Objects; +import java.util.function.Predicate; +import java.util.regex.Pattern; + +import org.eclipse.jdt.annotation.NonNullByDefault; +import org.eclipse.jdt.annotation.Nullable; +import org.eclipse.jetty.websocket.api.RemoteEndpoint; +import org.eclipse.jetty.websocket.api.Session; +import org.eclipse.jetty.websocket.api.StatusCode; +import org.eclipse.jetty.websocket.api.annotations.OnWebSocketClose; +import org.eclipse.jetty.websocket.api.annotations.OnWebSocketConnect; +import org.eclipse.jetty.websocket.api.annotations.OnWebSocketError; +import org.eclipse.jetty.websocket.api.annotations.OnWebSocketMessage; +import org.eclipse.jetty.websocket.api.annotations.WebSocket; +import org.osgi.service.log.LogEntry; +import org.osgi.service.log.LogListener; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +import com.google.gson.Gson; +import com.google.gson.JsonParseException; +import com.google.gson.reflect.TypeToken; + +/** + * The {@link LogWebSocket} is the WebSocket implementation for logs + * + * @author Jan N. Klug - Initial contribution + */ +@WebSocket +@NonNullByDefault +@SuppressWarnings("unused") +public class LogWebSocket implements LogListener { + @SuppressWarnings("unchecked") + private static final TypeToken> STRING_LIST_TYPE = (TypeToken>) TypeToken + .getParameterized(List.class, String.class); + + private final Logger logger = LoggerFactory.getLogger(LogWebSocket.class); + + private final LogWebSocketAdapter wsAdapter; + private final Gson gson; + + private @Nullable Session session; + private @Nullable RemoteEndpoint remoteEndpoint; + private String remoteIdentifier = ""; + + private List loggerPatterns = List.of(); + + public LogWebSocket(Gson gson, LogWebSocketAdapter wsAdapter) { + this.wsAdapter = wsAdapter; + this.gson = gson; + } + + @OnWebSocketClose + public void onClose(int statusCode, String reason) { + this.wsAdapter.unregisterListener(this); + remoteIdentifier = ""; + this.session = null; + this.remoteEndpoint = null; + } + + @OnWebSocketConnect + public void onConnect(Session session) { + this.session = session; + RemoteEndpoint remoteEndpoint = session.getRemote(); + this.remoteEndpoint = remoteEndpoint; + this.remoteIdentifier = remoteEndpoint.getInetSocketAddress().toString(); + this.wsAdapter.registerListener(this); + } + + @OnWebSocketMessage + public void onText(String message) { + RemoteEndpoint remoteEndpoint = this.remoteEndpoint; + if (session == null || remoteEndpoint == null) { + // no connection or no remote endpoint , do nothing this is possible due to async behavior + return; + } + + try { + loggerPatterns = gson.fromJson(message, STRING_LIST_TYPE).stream().map(Pattern::compile).toList(); + } catch (JsonParseException e) { + logger.warn("Failed to parse '{}' to a list of subscribed loggers", message); + } + } + + @OnWebSocketError + public void onError(Session session, @Nullable Throwable error) { + if (session != null) { + session.close(); + } + + String message = error == null ? "" : Objects.requireNonNullElse(error.getMessage(), ""); + logger.info("WebSocket error: {}", message); + onClose(StatusCode.NO_CODE, message); + } + + private synchronized void sendMessage(String message) throws IOException { + RemoteEndpoint remoteEndpoint = this.remoteEndpoint; + if (remoteEndpoint == null) { + logger.warn("Could not determine remote endpoint, failed to send '{}'.", message); + return; + } + remoteEndpoint.sendString(message); + } + + @Override + public void logged(@NonNullByDefault({}) LogEntry logEntry) { + if (!loggerPatterns.isEmpty() && loggerPatterns.stream().noneMatch(logMatch(logEntry))) { + return; + } + try { + LogDTO logDTO = map(logEntry); + sendMessage(gson.toJson(logDTO)); + } catch (IOException e) { + logger.debug("Failed to send log {} to {}: {}", logEntry, remoteIdentifier, e.getMessage()); + } + } + + private static Predicate logMatch(LogEntry logEntry) { + return pattern -> pattern.matcher(logEntry.getLoggerName()).matches(); + } + + private static LogDTO map(LogEntry logEntry) { + LogDTO logDTO = new LogDTO(); + logDTO.loggerName = logEntry.getLoggerName(); + logDTO.level = logEntry.getLogLevel(); + logDTO.unixtime = logEntry.getTime(); + logDTO.timestamp = new Date(logEntry.getTime()); + logDTO.message = logEntry.getMessage(); + return logDTO; + } +} diff --git a/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/log/LogWebSocketAdapter.java b/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/log/LogWebSocketAdapter.java new file mode 100644 index 00000000000..adbdeac1e9b --- /dev/null +++ b/bundles/org.openhab.core.io.websocket/src/main/java/org/openhab/core/io/websocket/log/LogWebSocketAdapter.java @@ -0,0 +1,73 @@ +/** + * Copyright (c) 2010-2023 Contributors to the openHAB project + * + * See the NOTICE file(s) distributed with this work for additional + * information. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License 2.0 which is available at + * http://www.eclipse.org/legal/epl-2.0 + * + * SPDX-License-Identifier: EPL-2.0 + */ +package org.openhab.core.io.websocket.log; + +import java.util.Set; +import java.util.concurrent.CopyOnWriteArraySet; + +import org.eclipse.jdt.annotation.NonNullByDefault; +import org.eclipse.jetty.websocket.servlet.ServletUpgradeRequest; +import org.eclipse.jetty.websocket.servlet.ServletUpgradeResponse; +import org.openhab.core.io.websocket.WebSocketAdapter; +import org.osgi.service.component.annotations.Activate; +import org.osgi.service.component.annotations.Component; +import org.osgi.service.component.annotations.Deactivate; +import org.osgi.service.component.annotations.Reference; +import org.osgi.service.log.LogReaderService; + +import com.google.gson.Gson; + +/** + * The {@link LogWebSocketAdapter} allows subscription to log events over WebSocket + * + * @author Jan N. Klug - Initial contribution + */ +@NonNullByDefault +@Component(immediate = true, service = { WebSocketAdapter.class }) +public class LogWebSocketAdapter implements WebSocketAdapter { + public static final String ADAPTER_ID = "logs"; + private final Gson gson = new Gson(); + private final Set webSockets = new CopyOnWriteArraySet<>(); + private final LogReaderService logReaderService; + + @Activate + public LogWebSocketAdapter(@Reference LogReaderService logReaderService) { + this.logReaderService = logReaderService; + } + + @Deactivate + public void deactivate() { + webSockets.forEach(logReaderService::removeLogListener); + } + + public void registerListener(LogWebSocket eventWebSocket) { + webSockets.add(eventWebSocket); + logReaderService.addLogListener(eventWebSocket); + } + + public void unregisterListener(LogWebSocket eventWebSocket) { + logReaderService.removeLogListener(eventWebSocket); + webSockets.remove(eventWebSocket); + } + + @Override + public String getId() { + return ADAPTER_ID; + } + + @Override + public Object createWebSocket(ServletUpgradeRequest servletUpgradeRequest, + ServletUpgradeResponse servletUpgradeResponse) { + return new LogWebSocket(gson, LogWebSocketAdapter.this); + } +} diff --git a/bundles/org.openhab.core.io.websocket/src/test/java/org/openhab/core/io/websocket/CommonWebSocketServletTest.java b/bundles/org.openhab.core.io.websocket/src/test/java/org/openhab/core/io/websocket/CommonWebSocketServletTest.java index c7aafb587dc..93df3e456b1 100644 --- a/bundles/org.openhab.core.io.websocket/src/test/java/org/openhab/core/io/websocket/CommonWebSocketServletTest.java +++ b/bundles/org.openhab.core.io.websocket/src/test/java/org/openhab/core/io/websocket/CommonWebSocketServletTest.java @@ -43,6 +43,7 @@ import org.openhab.core.auth.AuthenticationException; import org.openhab.core.io.rest.auth.AnonymousUserSecurityContext; import org.openhab.core.io.rest.auth.AuthFilter; +import org.openhab.core.io.websocket.event.EventWebSocket; import org.osgi.service.http.NamespaceException; /** diff --git a/bundles/org.openhab.core.io.websocket/src/test/java/org/openhab/core/io/websocket/EventWebSocketTest.java b/bundles/org.openhab.core.io.websocket/src/test/java/org/openhab/core/io/websocket/EventWebSocketTest.java index 49eb37596de..01a531e4e94 100644 --- a/bundles/org.openhab.core.io.websocket/src/test/java/org/openhab/core/io/websocket/EventWebSocketTest.java +++ b/bundles/org.openhab.core.io.websocket/src/test/java/org/openhab/core/io/websocket/EventWebSocketTest.java @@ -18,8 +18,8 @@ import static org.mockito.Mockito.times; import static org.mockito.Mockito.verify; import static org.mockito.Mockito.when; -import static org.openhab.core.io.websocket.EventWebSocket.WEBSOCKET_EVENT_TYPE; -import static org.openhab.core.io.websocket.EventWebSocket.WEBSOCKET_TOPIC_PREFIX; +import static org.openhab.core.io.websocket.event.EventWebSocket.WEBSOCKET_EVENT_TYPE; +import static org.openhab.core.io.websocket.event.EventWebSocket.WEBSOCKET_TOPIC_PREFIX; import java.io.IOException; import java.net.InetSocketAddress; @@ -39,6 +39,10 @@ import org.mockito.quality.Strictness; import org.openhab.core.events.Event; import org.openhab.core.events.EventPublisher; +import org.openhab.core.io.websocket.event.EventDTO; +import org.openhab.core.io.websocket.event.EventWebSocket; +import org.openhab.core.io.websocket.event.EventWebSocketAdapter; +import org.openhab.core.io.websocket.event.ItemEventUtility; import org.openhab.core.items.ItemNotFoundException; import org.openhab.core.items.ItemRegistry; import org.openhab.core.items.events.ItemEventFactory; diff --git a/bundles/org.openhab.core.io.websocket/src/test/java/org/openhab/core/io/websocket/ItemEventUtilityTest.java b/bundles/org.openhab.core.io.websocket/src/test/java/org/openhab/core/io/websocket/ItemEventUtilityTest.java index 081c31146cf..63ac9bc63bb 100644 --- a/bundles/org.openhab.core.io.websocket/src/test/java/org/openhab/core/io/websocket/ItemEventUtilityTest.java +++ b/bundles/org.openhab.core.io.websocket/src/test/java/org/openhab/core/io/websocket/ItemEventUtilityTest.java @@ -27,6 +27,9 @@ import org.mockito.junit.jupiter.MockitoSettings; import org.mockito.quality.Strictness; import org.openhab.core.events.Event; +import org.openhab.core.io.websocket.event.EventDTO; +import org.openhab.core.io.websocket.event.EventProcessingException; +import org.openhab.core.io.websocket.event.ItemEventUtility; import org.openhab.core.items.ItemNotFoundException; import org.openhab.core.items.ItemRegistry; import org.openhab.core.items.events.ItemEvent; diff --git a/bundles/org.openhab.core.model.core/src/main/java/org/openhab/core/model/core/ModelRepositoryChangeListener.java b/bundles/org.openhab.core.model.core/src/main/java/org/openhab/core/model/core/ModelRepositoryChangeListener.java index 9b8c736853a..5537b51f9d7 100644 --- a/bundles/org.openhab.core.model.core/src/main/java/org/openhab/core/model/core/ModelRepositoryChangeListener.java +++ b/bundles/org.openhab.core.model.core/src/main/java/org/openhab/core/model/core/ModelRepositoryChangeListener.java @@ -23,7 +23,7 @@ public interface ModelRepositoryChangeListener { /** * Performs dispatch of all binding configs and - * fires all {@link ItemsChangeListener}s if {@code modelName} ends with "items". + * fires all {@link org.openhab.core.items.ItemRegistryChangeListener}s if {@code modelName} ends with "items". */ void modelChanged(String modelName, EventType type); } diff --git a/bundles/org.openhab.core.model.persistence/src/org/openhab/core/model/persistence/formatting/PersistenceFormatter.xtend b/bundles/org.openhab.core.model.persistence/src/org/openhab/core/model/persistence/formatting/PersistenceFormatter.xtend index 3a8a1150e7e..6eeccee93fe 100644 --- a/bundles/org.openhab.core.model.persistence/src/org/openhab/core/model/persistence/formatting/PersistenceFormatter.xtend +++ b/bundles/org.openhab.core.model.persistence/src/org/openhab/core/model/persistence/formatting/PersistenceFormatter.xtend @@ -26,7 +26,7 @@ import org.eclipse.xtext.formatting.impl.FormattingConfig * see : http://www.eclipse.org/Xtext/documentation.html#formatting * on how and when to use it * - * Also see {@link org.eclipse.xtext.xtext.XtextFormattingTokenSerializer} as an example + * Also see {@link org.eclipse.xtext.xtext.XtextFormatter} as an example */ class PersistenceFormatter extends AbstractDeclarativeFormatter { diff --git a/bundles/org.openhab.core.model.rule/src/org/openhab/core/model/rule/formatting/RulesFormatter.xtend b/bundles/org.openhab.core.model.rule/src/org/openhab/core/model/rule/formatting/RulesFormatter.xtend index 693646bb0bd..875940c6c21 100644 --- a/bundles/org.openhab.core.model.rule/src/org/openhab/core/model/rule/formatting/RulesFormatter.xtend +++ b/bundles/org.openhab.core.model.rule/src/org/openhab/core/model/rule/formatting/RulesFormatter.xtend @@ -26,7 +26,7 @@ import org.eclipse.xtext.formatting.impl.FormattingConfig * see : http://www.eclipse.org/Xtext/documentation.html#formatting * on how and when to use it * - * Also see {@link org.eclipse.xtext.xtext.XtextFormattingTokenSerializer} as an example + * Also see {@link org.eclipse.xtext.xtext.XtextFormatter} as an example */ class RulesFormatter extends AbstractDeclarativeFormatter { diff --git a/bundles/org.openhab.core.model.rule/src/org/openhab/core/model/rule/jvmmodel/RulesJvmModelInferrer.xtend b/bundles/org.openhab.core.model.rule/src/org/openhab/core/model/rule/jvmmodel/RulesJvmModelInferrer.xtend index 3e07451252b..2c0d86668ab 100644 --- a/bundles/org.openhab.core.model.rule/src/org/openhab/core/model/rule/jvmmodel/RulesJvmModelInferrer.xtend +++ b/bundles/org.openhab.core.model.rule/src/org/openhab/core/model/rule/jvmmodel/RulesJvmModelInferrer.xtend @@ -73,11 +73,11 @@ class RulesJvmModelInferrer extends ScriptJvmModelInferrer { /** * Is called for each instance of the first argument's type contained in a resource. * - * @param element - the model to create one or more JvmDeclaredTypes from. - * @param acceptor - each created JvmDeclaredType without a container should be passed to the acceptor in order get attached to the + * @param ruleModel the model to create one or more JvmDeclaredTypes from. + * @param acceptor each created JvmDeclaredType without a container should be passed to the acceptor in order get attached to the * current resource. - * @param isPreLinkingPhase - whether the method is called in a pre linking phase, i.e. when the global index isn't fully updated. You - * must not rely on linking using the index if iPrelinkingPhase is true + * @param isPreIndexingPhase whether the method is called in a pre linking phase, i.e. when the global index isn't fully updated. You + * must not rely on linking using the index if isPreIndexingPhase is true */ def dispatch void infer(RuleModel ruleModel, IJvmDeclaredTypeAcceptor acceptor, boolean isPreIndexingPhase) { val className = ruleModel.eResource.URI.lastSegment.split("\\.").head.toFirstUpper + "Rules" diff --git a/bundles/org.openhab.core.model.script/src/org/openhab/core/model/script/actions/CoreUtil.java b/bundles/org.openhab.core.model.script/src/org/openhab/core/model/script/actions/CoreUtil.java index 5b35a55387c..084c286ef85 100644 --- a/bundles/org.openhab.core.model.script/src/org/openhab/core/model/script/actions/CoreUtil.java +++ b/bundles/org.openhab.core.model.script/src/org/openhab/core/model/script/actions/CoreUtil.java @@ -36,6 +36,14 @@ public static int hsbTosRgb(HSBType hsb) { return ColorUtil.hsbTosRgb(hsb); } + public static int[] hsbToRgbw(HSBType hsb) { + return ColorUtil.hsbToRgbw(hsb); + } + + public static PercentType[] hsbToRgbwPercent(HSBType hsb) { + return ColorUtil.hsbToRgbwPercent(hsb); + } + public static double[] hsbToXY(HSBType hsb) { return ColorUtil.hsbToXY(hsb); } diff --git a/bundles/org.openhab.core.model.script/src/org/openhab/core/model/script/formatting/ScriptFormatter.xtend b/bundles/org.openhab.core.model.script/src/org/openhab/core/model/script/formatting/ScriptFormatter.xtend index db71387f9f8..377bf6b9509 100644 --- a/bundles/org.openhab.core.model.script/src/org/openhab/core/model/script/formatting/ScriptFormatter.xtend +++ b/bundles/org.openhab.core.model.script/src/org/openhab/core/model/script/formatting/ScriptFormatter.xtend @@ -26,7 +26,7 @@ import org.eclipse.xtext.formatting.impl.FormattingConfig * see : http://www.eclipse.org/Xtext/documentation.html#formatting * on how and when to use it * - * Also see {@link org.eclipse.xtext.xtext.XtextFormattingTokenSerializer} as an example + * Also see {@link org.eclipse.xtext.xtext.XtextFormatter} as an example */ class ScriptFormatter extends AbstractDeclarativeFormatter { diff --git a/bundles/org.openhab.core.model.script/src/org/openhab/core/model/script/jvmmodel/ScriptJvmModelInferrer.xtend b/bundles/org.openhab.core.model.script/src/org/openhab/core/model/script/jvmmodel/ScriptJvmModelInferrer.xtend index 5d871849367..98d490c2dcc 100644 --- a/bundles/org.openhab.core.model.script/src/org/openhab/core/model/script/jvmmodel/ScriptJvmModelInferrer.xtend +++ b/bundles/org.openhab.core.model.script/src/org/openhab/core/model/script/jvmmodel/ScriptJvmModelInferrer.xtend @@ -98,11 +98,11 @@ class ScriptJvmModelInferrer extends AbstractModelInferrer { /** * Is called for each instance of the first argument's type contained in a resource. * - * @param element - the model to create one or more JvmDeclaredTypes from. - * @param acceptor - each created JvmDeclaredType without a container should be passed to the acceptor in order get attached to the + * @param script the model to create one or more JvmDeclaredTypes from. + * @param acceptor each created JvmDeclaredType without a container should be passed to the acceptor in order get attached to the * current resource. - * @param isPreLinkingPhase - whether the method is called in a pre linking phase, i.e. when the global index isn't fully updated. You - * must not rely on linking using the index if iPrelinkingPhase is true + * @param isPreIndexingPhase whether the method is called in a pre linking phase, i.e. when the global index isn't fully updated. You + * must not rely on linking using the index if isPreIndexingPhase is true */ def dispatch void infer(Script script, IJvmDeclaredTypeAcceptor acceptor, boolean isPreIndexingPhase) { val className = script.eResource.URI.lastSegment.split("\\.").head.toFirstUpper + "Script" diff --git a/bundles/org.openhab.core.model.sitemap/src/org/openhab/core/model/sitemap/formatting/SitemapFormatter.xtend b/bundles/org.openhab.core.model.sitemap/src/org/openhab/core/model/sitemap/formatting/SitemapFormatter.xtend index 3992a31efc1..b0272142f5f 100644 --- a/bundles/org.openhab.core.model.sitemap/src/org/openhab/core/model/sitemap/formatting/SitemapFormatter.xtend +++ b/bundles/org.openhab.core.model.sitemap/src/org/openhab/core/model/sitemap/formatting/SitemapFormatter.xtend @@ -26,7 +26,7 @@ import org.eclipse.xtext.formatting.impl.FormattingConfig * see : http://www.eclipse.org/Xtext/documentation.html#formatting * on how and when to use it * - * Also see {@link org.eclipse.xtext.xtext.XtextFormattingTokenSerializer} as an example + * Also see {@link org.eclipse.xtext.xtext.XtextFormatter} as an example */ class SitemapFormatter extends AbstractDeclarativeFormatter { diff --git a/bundles/org.openhab.core.model.thing/src/org/openhab/core/model/thing/formatting/ThingFormatter.xtend b/bundles/org.openhab.core.model.thing/src/org/openhab/core/model/thing/formatting/ThingFormatter.xtend index 0f30c797157..7f946285220 100644 --- a/bundles/org.openhab.core.model.thing/src/org/openhab/core/model/thing/formatting/ThingFormatter.xtend +++ b/bundles/org.openhab.core.model.thing/src/org/openhab/core/model/thing/formatting/ThingFormatter.xtend @@ -26,7 +26,7 @@ import org.eclipse.xtext.formatting.impl.FormattingConfig * see : http://www.eclipse.org/Xtext/documentation.html#formatting * on how and when to use it * - * Also see {@link org.eclipse.xtext.xtext.XtextFormattingTokenSerializer} as an example + * Also see {@link org.eclipse.xtext.xtext.XtextFormatter} as an example */ class ThingFormatter extends AbstractDeclarativeFormatter { diff --git a/bundles/org.openhab.core.persistence/src/main/java/org/openhab/core/persistence/FilterCriteria.java b/bundles/org.openhab.core.persistence/src/main/java/org/openhab/core/persistence/FilterCriteria.java index 132660ea71b..73964aadf21 100644 --- a/bundles/org.openhab.core.persistence/src/main/java/org/openhab/core/persistence/FilterCriteria.java +++ b/bundles/org.openhab.core.persistence/src/main/java/org/openhab/core/persistence/FilterCriteria.java @@ -24,7 +24,7 @@ *

* It is designed as a Java bean, for which the different properties are constraints on the query result. These * properties include the item name, begin and end date and the item state. A compare operator can be defined to compare - * not only state equality, but also its decimal value (<,>). + * not only state equality, but also its decimal value ({@code <,>}). * *

* Additionally, the filter criteria supports ordering and paging of the result, so the caller can ask to only return diff --git a/bundles/org.openhab.core.semantics/src/main/java/org/openhab/core/semantics/ManagedSemanticTagProvider.java b/bundles/org.openhab.core.semantics/src/main/java/org/openhab/core/semantics/ManagedSemanticTagProvider.java index fbb7be82559..e0df89a68be 100644 --- a/bundles/org.openhab.core.semantics/src/main/java/org/openhab/core/semantics/ManagedSemanticTagProvider.java +++ b/bundles/org.openhab.core.semantics/src/main/java/org/openhab/core/semantics/ManagedSemanticTagProvider.java @@ -27,8 +27,8 @@ /** * {@link ManagedSemanticTagProvider} is an OSGi service, that allows to add or remove - * semantic tags at runtime by calling {@link ManagedSemanticTagProvider#add(SemanticTag)} - * or {@link ManagedSemanticTagProvider#remove(String)}. + * semantic tags at runtime by calling {@link ManagedSemanticTagProvider#add} + * or {@link ManagedSemanticTagProvider#remove}. * An added semantic tag is automatically exposed to the {@link SemanticTagRegistry}. * Persistence of added semantic tags is handled by a {@link StorageService}. * diff --git a/bundles/org.openhab.core.semantics/src/main/java/org/openhab/core/semantics/SemanticTagRegistry.java b/bundles/org.openhab.core.semantics/src/main/java/org/openhab/core/semantics/SemanticTagRegistry.java index 7c84ab65c2c..a009bf7f534 100644 --- a/bundles/org.openhab.core.semantics/src/main/java/org/openhab/core/semantics/SemanticTagRegistry.java +++ b/bundles/org.openhab.core.semantics/src/main/java/org/openhab/core/semantics/SemanticTagRegistry.java @@ -42,7 +42,7 @@ public interface SemanticTagRegistry extends Registry { * Checks if a tag with a given id can be added to the registry. * * To be added, no tag with this id must already exist in the registry, the tag name extracted from this id - * must have a valid syntax, the parent tag extracted from this id must already exists in the registry and + * must have a valid syntax, the parent tag extracted from this id must already exist in the registry and * should be either a default semantic tag or a managed semantic tag, and no tag with a same name must already * exist in the registry. * diff --git a/bundles/org.openhab.core.semantics/src/main/java/org/openhab/core/semantics/SemanticsPredicates.java b/bundles/org.openhab.core.semantics/src/main/java/org/openhab/core/semantics/SemanticsPredicates.java index 6449043f75a..51d932fab23 100644 --- a/bundles/org.openhab.core.semantics/src/main/java/org/openhab/core/semantics/SemanticsPredicates.java +++ b/bundles/org.openhab.core.semantics/src/main/java/org/openhab/core/semantics/SemanticsPredicates.java @@ -68,7 +68,7 @@ public static Predicate isA(Class type) { /** * Creates a {@link Predicate} which can be used to filter {@link Item}s that relates to a given property. * - * @param type the semantic property to filter for + * @param property the semantic property to filter for * @return created {@link Predicate} */ public static Predicate relatesTo(Class property) { diff --git a/bundles/org.openhab.core.storage.json/src/main/java/org/openhab/core/storage/json/internal/JsonStorage.java b/bundles/org.openhab.core.storage.json/src/main/java/org/openhab/core/storage/json/internal/JsonStorage.java index 1d127974ad6..d817999ebfa 100644 --- a/bundles/org.openhab.core.storage.json/src/main/java/org/openhab/core/storage/json/internal/JsonStorage.java +++ b/bundles/org.openhab.core.storage.json/src/main/java/org/openhab/core/storage/json/internal/JsonStorage.java @@ -23,13 +23,15 @@ import java.util.List; import java.util.Map; import java.util.Set; -import java.util.Timer; -import java.util.TimerTask; import java.util.concurrent.ConcurrentHashMap; +import java.util.concurrent.ScheduledExecutorService; +import java.util.concurrent.ScheduledFuture; +import java.util.concurrent.TimeUnit; import java.util.stream.Collectors; import org.eclipse.jdt.annotation.NonNullByDefault; import org.eclipse.jdt.annotation.Nullable; +import org.openhab.core.common.ThreadPoolManager; import org.openhab.core.config.core.Configuration; import org.openhab.core.config.core.ConfigurationDeserializer; import org.openhab.core.config.core.OrderingMapSerializer; @@ -60,6 +62,7 @@ * de-/serialization, keep json structures in map * @author Sami Salonen - ordered inner and outer serialization of Maps, * Sets and properties of Configuration + * @author Jörg Sautter - use a scheduled thread pool */ @NonNullByDefault public class JsonStorage implements Storage { @@ -75,8 +78,8 @@ public class JsonStorage implements Storage { private static final String BACKUP_EXTENSION = "backup"; private static final String SEPARATOR = "--"; - private final Timer commitTimer; - private @Nullable TimerTask commitTimerTask; + private final ScheduledExecutorService scheduledExecutorService; + private @Nullable ScheduledFuture commitScheduledFuture; private long deferredSince = 0; @@ -112,7 +115,7 @@ public JsonStorage(File file, @Nullable ClassLoader classLoader, int maxBackupFi .setPrettyPrinting() // .create(); - commitTimer = new Timer(); + scheduledExecutorService = ThreadPoolManager.getScheduledPool("JsonStorage"); Map inputMap = null; if (file.exists()) { @@ -333,11 +336,11 @@ private void writeDatabaseFile(File dataFile, String data) throws IOException { * require a read and write, and is thus slower). */ public synchronized void flush() { - // Stop any existing timer - TimerTask commitTimerTask = this.commitTimerTask; - if (commitTimerTask != null) { - commitTimerTask.cancel(); - this.commitTimerTask = null; + // Stop any existing scheduled commit + ScheduledFuture commitScheduledFuture = this.commitScheduledFuture; + if (commitScheduledFuture != null) { + commitScheduledFuture.cancel(false); + this.commitScheduledFuture = null; } if (dirty) { @@ -376,41 +379,29 @@ private void cleanupBackups() { } } - private class CommitTimerTask extends TimerTask { - @Override - public void run() { - // Save the database - flush(); - } - } - public synchronized void deferredCommit() { dirty = true; - // Stop any existing timer - TimerTask commitTimerTask = this.commitTimerTask; - if (commitTimerTask != null) { - commitTimerTask.cancel(); - this.commitTimerTask = null; + // Stop any existing scheduled commit + ScheduledFuture commitScheduledFuture = this.commitScheduledFuture; + if (commitScheduledFuture != null) { + commitScheduledFuture.cancel(false); + this.commitScheduledFuture = null; } // Handle a maximum time for deferring the commit. // This stops a pathological loop preventing saving - if (deferredSince != 0 && deferredSince < System.nanoTime() - (maxDeferredPeriod * 1000L)) { + if (deferredSince != 0 && deferredSince < System.currentTimeMillis() - maxDeferredPeriod) { flush(); - // as we committed the database now, there is no need to start a new commit - // timer + // as we committed the database now, there is no need to schedule a new commit return; } if (deferredSince == 0) { - deferredSince = System.nanoTime(); + deferredSince = System.currentTimeMillis(); } - // Create the timer task - commitTimerTask = new CommitTimerTask(); - - // Start the timer - commitTimer.schedule(commitTimerTask, writeDelay); + // Schedule the commit + this.commitScheduledFuture = scheduledExecutorService.schedule(this::flush, writeDelay, TimeUnit.MILLISECONDS); } } diff --git a/bundles/org.openhab.core.test/src/main/java/org/openhab/core/test/SyntheticBundleInstaller.java b/bundles/org.openhab.core.test/src/main/java/org/openhab/core/test/SyntheticBundleInstaller.java index 15fa91b289f..ec97571e823 100644 --- a/bundles/org.openhab.core.test/src/main/java/org/openhab/core/test/SyntheticBundleInstaller.java +++ b/bundles/org.openhab.core.test/src/main/java/org/openhab/core/test/SyntheticBundleInstaller.java @@ -185,7 +185,7 @@ public static Bundle update(BundleContext bundleContext, String bundleToUpdateNa * Updates given bundle into the test runtime (the content is changed, but the symbolic name of the bundles remains * the same) with a new content, prepared in another resources directory. * - * @param bundleContextthe bundle context of the test runtime + * @param bundleContext the bundle context of the test runtime * @param bundleToUpdateName the symbolic name of the bundle to be updated * @param updateDirName the location of the new content, that the target bundle will be updated with * @param extensionsToInclude a list of extension to be included into the synthetic bundle @@ -207,8 +207,6 @@ public static Bundle update(BundleContext bundleContext, String bundleToUpdateNa * @param bundleContext the bundle context of the test runtime * @param testBundleName the name of the sub-directory of {@value #BUNDLE_POOL_PATH}, which contains the files for * the synthetic bundle - * @param extensionsToInclude a list of extension to be included into the synthetic bundle fragment. In order to use - * the list of default extensions ({@link #DEFAULT_EXTENSIONS}) * @return the synthetic bundle representation * @throws Exception thrown when error occurs while installing or starting the synthetic bundle fragment */ diff --git a/bundles/org.openhab.core.test/src/main/java/org/openhab/core/test/TestServer.java b/bundles/org.openhab.core.test/src/main/java/org/openhab/core/test/TestServer.java index 925c04697af..0fda8db4806 100644 --- a/bundles/org.openhab.core.test/src/main/java/org/openhab/core/test/TestServer.java +++ b/bundles/org.openhab.core.test/src/main/java/org/openhab/core/test/TestServer.java @@ -42,7 +42,7 @@ public class TestServer { /** * Creates a new {@link TestServer}. The server is started by {@link #startServer()} and stopped by - * {@link #stopServer()}, preferably in the tests setup & tearDown methods. + * {@link #stopServer()}, preferably in the tests setup and tearDown methods. * * @param host the host this server runs on. * @param port the port this server runs on. Use {@link TestPortUtil} to find a random free port. diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/ManagedThingProvider.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/ManagedThingProvider.java index cab11cad2a8..596a8361829 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/ManagedThingProvider.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/ManagedThingProvider.java @@ -25,8 +25,8 @@ /** * {@link ManagedThingProvider} is an OSGi service, that allows to add or remove - * things at runtime by calling {@link ManagedThingProvider#addThing(Thing)} or - * {@link ManagedThingProvider#removeThing(Thing)}. An added thing is + * things at runtime by calling {@link ManagedThingProvider#add} or + * {@link ManagedThingProvider#remove}. An added thing is * automatically exposed to the {@link ThingRegistry}. * * @author Oliver Libutzki - Initial contribution diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/ThingRegistry.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/ThingRegistry.java index 42cf1c55e51..59a183ba576 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/ThingRegistry.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/ThingRegistry.java @@ -24,7 +24,7 @@ /** * {@link ThingRegistry} tracks all {@link Thing}s from different {@link ThingProvider}s and provides access to them. - * The {@link ThingRegistry} supports adding of listeners (see {@link ThingsChangeListener}) and trackers + * The {@link ThingRegistry} supports adding of listeners (see {@link ThingRegistryChangeListener}) and trackers * (see {@link ThingTracker}). * * @author Dennis Nobel - Initial contribution diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/ThingRegistryChangeListener.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/ThingRegistryChangeListener.java index ffd8aa6a456..5e863487dae 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/ThingRegistryChangeListener.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/ThingRegistryChangeListener.java @@ -17,9 +17,9 @@ /** * {@link ThingRegistryChangeListener} can be implemented to listen for things - * beeing added or removed. The listener must be added and removed via - * {@link ThingRegistry#addRegistryChangeListener(ThingRegistryChangeListener)} and - * {@link ThingRegistry#removeRegistryChangeListener(ThingRegistryChangeListener)}. + * being added or removed. The listener must be added and removed via + * {@link ThingRegistry#addRegistryChangeListener} and + * {@link ThingRegistry#removeRegistryChangeListener}. * * @author Dennis Nobel - Initial contribution * @author Michael Grammling - Added dynamic configuration update diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/ThingUID.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/ThingUID.java index 7ed7baef1b1..da50466ead8 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/ThingUID.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/ThingUID.java @@ -40,7 +40,7 @@ public class ThingUID extends UID { /** * Instantiates a new thing UID. * - * @param thingType the thing type + * @param thingTypeUID the thing type * @param id the id */ public ThingUID(ThingTypeUID thingTypeUID, String id) { @@ -50,7 +50,7 @@ public ThingUID(ThingTypeUID thingTypeUID, String id) { /** * Instantiates a new thing UID. * - * @param thingType the thing type + * @param thingTypeUID the thing type * @param bridgeUID the bridge UID through which the thing is accessed * @param id the id of the thing */ @@ -62,7 +62,7 @@ public ThingUID(ThingTypeUID thingTypeUID, ThingUID bridgeUID, String id) { /** * Instantiates a new thing UID. * - * @param thingType the thing type + * @param thingTypeUID the thing type * @param id the id */ public ThingUID(ThingTypeUID thingTypeUID, String id, String... bridgeIds) { diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/ThingFactory.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/ThingFactory.java index 6a6b86e0de3..640c43e561c 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/ThingFactory.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/ThingFactory.java @@ -63,7 +63,7 @@ public static ThingUID generateRandomThingUID(ThingTypeUID thingTypeUID) { * @param thingType thing type (must not be null) * @param thingUID thindUID (must not be null) * @param configuration (must not be null) - * @param bridge (can be null) + * @param bridgeUID (can be null) * @return thing the thing */ public static Thing createThing(ThingType thingType, ThingUID thingUID, Configuration configuration, diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/ThingHandler.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/ThingHandler.java index c1eba223e54..61f2444cce8 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/ThingHandler.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/ThingHandler.java @@ -154,7 +154,7 @@ public interface ThingHandler { * returns to {@link ThingStatus#ONLINE}, the thing status must be changed at least to {@link ThingStatus#OFFLINE} * with detail {@link ThingStatusDetail#NONE}. * - * @param thingStatusInfo the status info of the bridge + * @param bridgeStatusInfo the status info of the bridge */ void bridgeStatusChanged(ThingStatusInfo bridgeStatusInfo); diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/ThingHandlerCallback.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/ThingHandlerCallback.java index 33763184d25..0450db7354c 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/ThingHandlerCallback.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/ThingHandlerCallback.java @@ -165,7 +165,7 @@ public interface ThingHandlerCallback { /** * Creates a {@link ChannelBuilder} which is preconfigured with values from the given {@link Channel} and allows to - * modify it. The methods {@link BaseThingHandler#editThing(Thing)} and {@link BaseThingHandler#updateThing(Thing)} + * modify it. The methods {@link BaseThingHandler#editThing()} and {@link BaseThingHandler#updateThing(Thing)} * must be called to persist the changes. * * @param thing {@link Thing} (must not be null) diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/builder/ChannelBuilder.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/builder/ChannelBuilder.java index 39da35e9f0d..b7703a19ba6 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/builder/ChannelBuilder.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/builder/ChannelBuilder.java @@ -155,7 +155,7 @@ public ChannelBuilder withLabel(String label) { /** * Sets the channel description. This allows overriding of the default description set in the {@link ChannelType}. * - * @param label the channel label to override the description set in the {@link ChannelType} + * @param description the channel label to override the description set in the {@link ChannelType} * @return channel builder */ public ChannelBuilder withDescription(String description) { diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/firmware/Firmware.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/firmware/Firmware.java index 913993796fd..c3e6c756f5a 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/firmware/Firmware.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/firmware/Firmware.java @@ -45,7 +45,7 @@ *

* The {@link Firmware} implements the {@link Comparable} interface in order to be able to sort firmwares based on their * versions. Firmwares are sorted in a descending sequence, i.e. that the latest firmware will be the first - * element in a sorted result set. The implementation of {@link Firmware#compareTo(Firmware)} splits the firmware + * element in a sorted result set. The implementation of {@link Firmware#compareTo} splits the firmware * version by the delimiters ".", "-" and "_" and compares the different parts of the firmware version. As a result the * firmware version 2-0-1 is newer then firmware version 2.0.0 which again is newer than firmware version * 1-9_9.9_abc. Consequently 2.0-0, 2-0_0 and 2_0.0 represent the same firmware version. diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/firmware/FirmwareUpdateHandler.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/firmware/FirmwareUpdateHandler.java index 60117bfba69..02c705addd5 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/firmware/FirmwareUpdateHandler.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/firmware/FirmwareUpdateHandler.java @@ -15,6 +15,7 @@ import org.eclipse.jdt.annotation.NonNullByDefault; import org.openhab.core.thing.Thing; import org.openhab.core.thing.ThingStatus; +import org.openhab.core.thing.ThingStatusDetail; import org.openhab.core.thing.firmware.FirmwareUpdateService; /** @@ -53,7 +54,7 @@ public interface FirmwareUpdateHandler { /** * Returns true, if this firmware update handler is in a state in which the firmware update can be executed, * otherwise false (e.g. the thing is {@link ThingStatus#OFFLINE} or its status detail is already - * {@link ThingStatusDetail#FIRMWARE_UPDATING.) + * {@link ThingStatusDetail#FIRMWARE_UPDATING}.) * * @return true, if this firmware update handler is in a state in which the firmware update can be executed, * otherwise false diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/firmware/ProgressCallback.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/firmware/ProgressCallback.java index bbcf9c5db5c..70a44312c7f 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/firmware/ProgressCallback.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/firmware/ProgressCallback.java @@ -107,8 +107,9 @@ public interface ProgressCallback { * previous defined sequence. * * @param progress the progress between 0 and 100 - * @throws IllegalArgumentException if given progress is < 0 or > 100 - * @throws IllegalArgumentException if given progress is smaller than old progress + * @throws IllegalArgumentException if given progress is {@code < 0} or {@code > 100} or if given progress is + * smaller than old + * progress * @throws IllegalStateException if update is finished */ void update(int progress); diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/events/ThingEventFactory.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/events/ThingEventFactory.java index ffa8a64a862..6e1c483fa89 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/events/ThingEventFactory.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/events/ThingEventFactory.java @@ -320,7 +320,7 @@ public String getChannel() { * Creates a {@link ChannelTriggeredEvent} * * @param event the event - * @param channel the {@link ChannelUID} + * @param channelUID the {@link ChannelUID} * @return Created {@link ChannelTriggeredEvent} */ public static ChannelTriggeredEvent createTriggerEvent(String event, ChannelUID channelUID) { diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/events/ThingStatusInfoChangedEvent.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/events/ThingStatusInfoChangedEvent.java index ea7ffb92cc3..072585a550d 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/events/ThingStatusInfoChangedEvent.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/events/ThingStatusInfoChangedEvent.java @@ -43,8 +43,8 @@ public class ThingStatusInfoChangedEvent extends AbstractEvent { * @param topic the topic * @param payload the payload * @param thingUID the thing UID - * @param thingStatusInfo the thing status info object - * @param thingStatusInfo the old thing status info object + * @param newThingStatusInfo the thing status info object + * @param oldThingStatusInfo the old thing status info object */ protected ThingStatusInfoChangedEvent(String topic, String payload, ThingUID thingUID, ThingStatusInfo newThingStatusInfo, ThingStatusInfo oldThingStatusInfo) { diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/firmware/FirmwareEventFactory.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/firmware/FirmwareEventFactory.java index 09fad627ef1..9073a9c0919 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/firmware/FirmwareEventFactory.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/firmware/FirmwareEventFactory.java @@ -68,7 +68,6 @@ protected Event createEventByType(String eventType, String topic, String payload * Creates a new {@link FirmwareStatusInfoEvent}. * * @param firmwareStatusInfo the firmware status information (must not be null) - * @param thingUID the thing UID for which the new firmware status info is to be sent (must not be null) * @return the corresponding firmware status info event * @throws IllegalArgumentException if given firmware status info is null */ @@ -86,7 +85,6 @@ public static FirmwareStatusInfoEvent createFirmwareStatusInfoEvent(FirmwareStat * Creates a new {@link FirmwareUpdateProgressInfoEvent}. * * @param progressInfo the progress information of the firmware update process (must not be null) - * @param thingUID the thing UID for which the progress info is to be sent (must not be null) * @return the corresponding progress info event * @throws IllegalArgumentException if given progress info is null */ @@ -105,7 +103,6 @@ public static FirmwareUpdateProgressInfoEvent createFirmwareUpdateProgressInfoEv * Creates a new {@link FirmwareUpdateResultInfoEvent}. * * @param firmwareUpdateResultInfo the firmware update result information (must not be null) - * @param thingUID the thing UID for which the result information is to be sent (must not be null) * @return the corresponding firmware update result info event * @throws IllegalArgumentException if given firmware update result info event is null */ diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/firmware/FirmwareStatusInfo.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/firmware/FirmwareStatusInfo.java index 850d873e4d6..2d1cf20c501 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/firmware/FirmwareStatusInfo.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/firmware/FirmwareStatusInfo.java @@ -58,7 +58,7 @@ private FirmwareStatusInfo(ThingUID thingUID, FirmwareStatus firmwareStatus, @Nu } /** - * Creates a new {@link FirmwareStatusInfo} having {@link FirmwareStatus#UNKNOWN) as firmware status. + * Creates a new {@link FirmwareStatusInfo} having {@link FirmwareStatus#UNKNOWN} as firmware status. * * @return the firmware status info (not null) */ @@ -67,7 +67,7 @@ public static FirmwareStatusInfo createUnknownInfo(ThingUID thingUID) { } /** - * Creates a new {@link FirmwareStatusInfo} having {@link FirmwareStatus#UP_TO_DATE) as firmware status. + * Creates a new {@link FirmwareStatusInfo} having {@link FirmwareStatus#UP_TO_DATE} as firmware status. * * @return the firmware status info (not null) */ @@ -76,7 +76,7 @@ public static FirmwareStatusInfo createUpToDateInfo(ThingUID thingUID) { } /** - * Creates a new {@link FirmwareStatusInfo} having {@link FirmwareStatus#UPDATE_AVAILABLE) as firmware status. + * Creates a new {@link FirmwareStatusInfo} having {@link FirmwareStatus#UPDATE_AVAILABLE} as firmware status. * * @return the firmware status info (not null) */ @@ -85,7 +85,7 @@ public static FirmwareStatusInfo createUpdateAvailableInfo(ThingUID thingUID) { } /** - * Creates a new {@link FirmwareStatusInfo} having {@link FirmwareStatus#UPDATE_EXECUTBALE) as firmware status. The + * Creates a new {@link FirmwareStatusInfo} having {@link FirmwareStatus#UPDATE_EXECUTABLE} as firmware status. The * given firmware version represents the version of the latest updatable firmware for the thing. * * @param firmwareVersion the version of the latest updatable firmware for the thing (must not be null) diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/i18n/ChannelGroupTypeI18nLocalizationService.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/i18n/ChannelGroupTypeI18nLocalizationService.java index 462748b3590..9c9a4459476 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/i18n/ChannelGroupTypeI18nLocalizationService.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/i18n/ChannelGroupTypeI18nLocalizationService.java @@ -37,7 +37,8 @@ * @author Markus Rathgeb - Initial contribution * @author Markus Rathgeb - Move code from XML thing type provider to separate service * @author Laurent Garnier - fix localized label and description for channel group definition - * @author Christoph Weitkamp - factored out from {@link XmlChannelTypeProvider} and {@link XmlChannelGroupTypeProvider} + * @author Christoph Weitkamp - factored out from {@link org.openhab.core.thing.xml.internal.XmlChannelTypeProvider} and + * {@link org.openhab.core.thing.xml.internal.XmlChannelGroupTypeProvider} * @author Henning Treu - factored out from {@link ThingTypeI18nLocalizationService} * @author Christoph Weitkamp - Removed "advanced" attribute */ diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/i18n/ChannelTypeI18nLocalizationService.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/i18n/ChannelTypeI18nLocalizationService.java index 538593e1ddf..5dd98c3ba45 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/i18n/ChannelTypeI18nLocalizationService.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/i18n/ChannelTypeI18nLocalizationService.java @@ -45,7 +45,8 @@ * @author Markus Rathgeb - Initial contribution * @author Markus Rathgeb - Move code from XML thing type provider to separate service * @author Laurent Garnier - fix localized label and description for channel group definition - * @author Christoph Weitkamp - factored out from {@link XmlChannelTypeProvider} and {@link XmlChannelGroupTypeProvider} + * @author Christoph Weitkamp - factored out from {@link org.openhab.core.thing.xml.internal.XmlChannelTypeProvider} and + * {@link org.openhab.core.thing.xml.internal.XmlChannelGroupTypeProvider} * @author Henning Treu - factored out from {@link ThingTypeI18nLocalizationService} */ @Component(service = ChannelTypeI18nLocalizationService.class) diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/i18n/ThingTypeI18nLocalizationService.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/i18n/ThingTypeI18nLocalizationService.java index d6a60251672..0810bd21320 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/i18n/ThingTypeI18nLocalizationService.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/i18n/ThingTypeI18nLocalizationService.java @@ -41,7 +41,8 @@ * @author Markus Rathgeb - Initial contribution * @author Markus Rathgeb - Move code from XML thing type provider to separate service * @author Laurent Garnier - fix localized label and description for channel group definition - * @author Christoph Weitkamp - factored out from {@link XmlChannelTypeProvider} and {@link XmlChannelGroupTypeProvider} + * @author Christoph Weitkamp - factored out from {@link org.openhab.core.thing.xml.internal.XmlChannelTypeProvider} and + * {@link org.openhab.core.thing.xml.internal.XmlChannelGroupTypeProvider} */ @Component(service = ThingTypeI18nLocalizationService.class) @NonNullByDefault diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/internal/ThingRegistryImpl.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/internal/ThingRegistryImpl.java index 7416b310a4f..860fd3999a7 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/internal/ThingRegistryImpl.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/internal/ThingRegistryImpl.java @@ -96,7 +96,7 @@ public void updateConfiguration(ThingUID thingUID, Map configura throw new IllegalStateException("Thing with UID " + thingUID + " has no handler attached."); } } else { - throw new IllegalArgumentException("Thing with UID " + thingUID + " does not exists."); + throw new IllegalArgumentException("Thing with UID " + thingUID + " does not exist."); } } diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/link/ItemChannelLink.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/link/ItemChannelLink.java index fb6ee1d2eaa..274f0288708 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/link/ItemChannelLink.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/link/ItemChannelLink.java @@ -19,7 +19,7 @@ import org.openhab.core.thing.ChannelUID; /** - * {@link ItemChannelLink} defines a link between an {@link Item} and a {@link Channel}. + * {@link ItemChannelLink} defines a link between an {@link Item} and a {@link org.openhab.core.thing.Channel}. * * @author Dennis Nobel - Initial contribution, Added getIDFor method * @author Jochen Hiller - Bugfix 455434: added default constructor, object is now mutable diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/profiles/ProfileTypeBuilder.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/profiles/ProfileTypeBuilder.java index c658500d048..f4a110ff978 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/profiles/ProfileTypeBuilder.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/profiles/ProfileTypeBuilder.java @@ -94,7 +94,7 @@ public ProfileTypeBuilder withSupportedItemTypes(String... itemType) { /** * Declare that the given item type(s) are supported by a profile of this type. * - * @param itemType + * @param itemTypes * @return the builder itself */ public ProfileTypeBuilder withSupportedItemTypes(Collection itemTypes) { diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/type/ChannelGroupTypeProvider.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/type/ChannelGroupTypeProvider.java index baafb526b16..8e95acf3f58 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/type/ChannelGroupTypeProvider.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/type/ChannelGroupTypeProvider.java @@ -29,13 +29,13 @@ public interface ChannelGroupTypeProvider { /** - * @see ChannelTypeRegistry#getChannelGroupType(ChannelGroupTypeUID, Locale) + * @see ChannelGroupTypeRegistry#getChannelGroupType(ChannelGroupTypeUID, Locale) */ @Nullable ChannelGroupType getChannelGroupType(ChannelGroupTypeUID channelGroupTypeUID, @Nullable Locale locale); /** - * @see ChannelTypeRegistry#getChannelGroupTypes(Locale) + * @see ChannelGroupTypeRegistry#getChannelGroupTypes(Locale) */ Collection getChannelGroupTypes(@Nullable Locale locale); } diff --git a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/type/StateChannelTypeBuilder.java b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/type/StateChannelTypeBuilder.java index 33b9935429e..d70192c4ad0 100644 --- a/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/type/StateChannelTypeBuilder.java +++ b/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/type/StateChannelTypeBuilder.java @@ -44,7 +44,7 @@ public interface StateChannelTypeBuilder extends ChannelTypeBuilder getThingTypes(String bindingId) { /** * Returns the channel type for a given channel. * - *

- * Attention: If you iterate over multiple channels to find the according channel types, please - * fetch the thing type first using - * {@link ThingTypeRegistry#getThingType(ThingTypeUID)} and use - * {@link ThingType#getChannelType(ChannelUID)} afterwards. - * * @param channel channel * @return channel type or null if no channel type was found */ @@ -146,12 +139,6 @@ public List getThingTypes(String bindingId) { /** * Returns the channel type for a given channel and locale. * - *

- * Attention: If you iterate over multiple channels to find the according channel types, please - * fetch the thing type first using - * {@link ThingTypeRegistry#getThingType(ThingTypeUID)} and use - * {@link ThingType#getChannelType(ChannelUID)} afterwards. - * * @param channel channel * @param locale locale (can be null) * @return channel type or null if no channel type was found diff --git a/bundles/org.openhab.core.ui.icon/src/main/java/org/openhab/core/ui/icon/IconProvider.java b/bundles/org.openhab.core.ui.icon/src/main/java/org/openhab/core/ui/icon/IconProvider.java index 7d42d51ab88..1974d719b5b 100644 --- a/bundles/org.openhab.core.ui.icon/src/main/java/org/openhab/core/ui/icon/IconProvider.java +++ b/bundles/org.openhab.core.ui.icon/src/main/java/org/openhab/core/ui/icon/IconProvider.java @@ -66,9 +66,9 @@ public interface IconProvider { /** * retrieves the {@link InputStream} of an icon * - * @param iconName the icon name + * @param category the icon category * @param iconSetId the id of the icon set for which the icon is requested - * @param the string representation of the state (for the case that the icon differs for different states) + * @param state the string representation of the state (for the case that the icon differs for different states) * @param format the format of the stream (usually either png or svg) * @return a byte stream of the icon in the given format or null, if no icon exists */ diff --git a/bundles/org.openhab.core.ui/src/main/java/org/openhab/core/ui/components/RootUIComponent.java b/bundles/org.openhab.core.ui/src/main/java/org/openhab/core/ui/components/RootUIComponent.java index 1fcd867c493..59665ea747c 100644 --- a/bundles/org.openhab.core.ui/src/main/java/org/openhab/core/ui/components/RootUIComponent.java +++ b/bundles/org.openhab.core.ui/src/main/java/org/openhab/core/ui/components/RootUIComponent.java @@ -26,7 +26,7 @@ import org.openhab.core.config.core.dto.ConfigDescriptionDTO; /** - * A root component is a special type of {@link Component} at the root of the hierarchy. + * A root component is a special type of {@link UIComponent} at the root of the hierarchy. * It has a number of specific parameters, a set of tags, a timestamp, some configurable * parameters ("props") and is identifiable by its UID (generally a GUID). * @@ -106,7 +106,7 @@ public void setTimestamp(Date date) { } /** - * Updates the timestamp of the component to the current date & time. + * Updates the timestamp of the component to the current date and time. */ public void updateTimestamp() { this.timestamp = new Date(); diff --git a/bundles/org.openhab.core.ui/src/main/java/org/openhab/core/ui/internal/chart/ChartServlet.java b/bundles/org.openhab.core.ui/src/main/java/org/openhab/core/ui/internal/chart/ChartServlet.java index 9464e1c4195..82091f3f92f 100644 --- a/bundles/org.openhab.core.ui/src/main/java/org/openhab/core/ui/internal/chart/ChartServlet.java +++ b/bundles/org.openhab.core.ui/src/main/java/org/openhab/core/ui/internal/chart/ChartServlet.java @@ -12,15 +12,15 @@ */ package org.openhab.core.ui.internal.chart; -import static java.util.Map.entry; - import java.awt.image.BufferedImage; import java.io.IOException; import java.time.Duration; import java.time.LocalDateTime; +import java.time.Period; import java.time.ZonedDateTime; import java.time.format.DateTimeFormatter; import java.time.format.DateTimeParseException; +import java.time.temporal.TemporalAmount; import java.util.Map; import java.util.Objects; import java.util.concurrent.ConcurrentHashMap; @@ -69,6 +69,7 @@ * * @author Chris Jackson - Initial contribution * @author Holger Reichert - Support for themes, DPI, legend hiding + * @author Laurent Garnier - Extend support to ISO8601 format for chart period parameter */ @Component(immediate = true, service = { ChartServlet.class, Servlet.class }, configurationPid = "org.openhab.chart", // property = Constants.SERVICE_PID + "=org.openhab.chart") @@ -101,16 +102,6 @@ public class ChartServlet extends HttpServlet { private static final Duration DEFAULT_PERIOD = Duration.ofDays(1); - private static final Map PERIODS = Map.ofEntries( // - entry("h", Duration.ofHours(1)), entry("4h", Duration.ofHours(4)), // - entry("8h", Duration.ofHours(8)), entry("12h", Duration.ofHours(12)), // - entry("D", Duration.ofDays(1)), entry("2D", Duration.ofDays(2)), // - entry("3D", Duration.ofDays(3)), entry("W", Duration.ofDays(7)), // - entry("2W", Duration.ofDays(14)), entry("M", Duration.ofDays(30)), // - entry("2M", Duration.ofDays(60)), entry("4M", Duration.ofDays(120)), // - entry("Y", Duration.ofDays(365))// - ); - protected static final Map CHART_PROVIDERS = new ConcurrentHashMap<>(); @Activate @@ -233,7 +224,7 @@ protected void doGet(HttpServletRequest req, HttpServletResponse res) throws Ser } // Read out the parameter period, begin and end and save them. - Duration period = periodParam == null ? DEFAULT_PERIOD : PERIODS.getOrDefault(periodParam, DEFAULT_PERIOD); + TemporalAmount period = convertToTemporalAmount(periodParam, DEFAULT_PERIOD); ZonedDateTime timeBegin = null; ZonedDateTime timeEnd = null; @@ -359,4 +350,37 @@ public void init(@Nullable ServletConfig config) throws ServletException { @Override public void destroy() { } + + public static TemporalAmount convertToTemporalAmount(@Nullable String periodParam, TemporalAmount defaultPeriod) { + TemporalAmount period = defaultPeriod; + String convertedPeriod = convertPeriodToISO8601(periodParam); + if (convertedPeriod != null) { + boolean failed = false; + try { + period = Period.parse(convertedPeriod); + } catch (DateTimeParseException e) { + failed = true; + } + if (failed) { + try { + period = Duration.parse(convertedPeriod); + } catch (DateTimeParseException e) { + // Ignored + } + } + } + return period; + } + + private static @Nullable String convertPeriodToISO8601(@Nullable String period) { + if (period == null || period.startsWith("P") || !(period.endsWith("h") || period.endsWith("D") + || period.endsWith("W") || period.endsWith("M") || period.endsWith("Y"))) { + return period; + } + String newPeriod = period.length() == 1 ? "1" + period : period; + if (newPeriod.endsWith("h")) { + newPeriod = "T" + newPeriod.replace("h", "H"); + } + return "P" + newPeriod; + } } diff --git a/bundles/org.openhab.core.ui/src/main/java/org/openhab/core/ui/items/ItemUIProvider.java b/bundles/org.openhab.core.ui/src/main/java/org/openhab/core/ui/items/ItemUIProvider.java index 9303ac87c96..f2acd2891f8 100644 --- a/bundles/org.openhab.core.ui/src/main/java/org/openhab/core/ui/items/ItemUIProvider.java +++ b/bundles/org.openhab.core.ui/src/main/java/org/openhab/core/ui/items/ItemUIProvider.java @@ -38,7 +38,7 @@ public interface ItemUIProvider { /** * Returns the label text to be used for an item in the UI. * - * @param item the name of the item to return the label text for + * @param itemName the name of the item to return the label text for * @return the label text to be used in the UI or null if undefined. */ @Nullable diff --git a/bundles/org.openhab.core.ui/src/main/java/org/openhab/core/ui/items/ItemUIRegistry.java b/bundles/org.openhab.core.ui/src/main/java/org/openhab/core/ui/items/ItemUIRegistry.java index f13c9230259..ba313b6a3fb 100644 --- a/bundles/org.openhab.core.ui/src/main/java/org/openhab/core/ui/items/ItemUIRegistry.java +++ b/bundles/org.openhab.core.ui/src/main/java/org/openhab/core/ui/items/ItemUIRegistry.java @@ -126,7 +126,7 @@ public enum WidgetLabelSource { * this should be used instead of Sitemap.getChildren() as the default * widgets have to be resolved to a concrete widget type. * - * @param w the sitemap to retrieve the children for + * @param sitemap the sitemap to retrieve the children for * @return the children of the sitemap */ EList getChildren(Sitemap sitemap); diff --git a/bundles/org.openhab.core.ui/src/test/java/org/openhab/core/ui/internal/chart/ChartServletPeriodParamTest.java b/bundles/org.openhab.core.ui/src/test/java/org/openhab/core/ui/internal/chart/ChartServletPeriodParamTest.java new file mode 100644 index 00000000000..31e0d642d2c --- /dev/null +++ b/bundles/org.openhab.core.ui/src/test/java/org/openhab/core/ui/internal/chart/ChartServletPeriodParamTest.java @@ -0,0 +1,107 @@ +/** + * Copyright (c) 2010-2023 Contributors to the openHAB project + * + * See the NOTICE file(s) distributed with this work for additional + * information. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License 2.0 which is available at + * http://www.eclipse.org/legal/epl-2.0 + * + * SPDX-License-Identifier: EPL-2.0 + */ +package org.openhab.core.ui.internal.chart; + +import static org.junit.jupiter.api.Assertions.assertEquals; + +import java.time.Duration; +import java.time.temporal.ChronoUnit; +import java.time.temporal.TemporalAmount; + +import org.eclipse.jdt.annotation.NonNullByDefault; +import org.junit.jupiter.api.Test; + +/** + * @author Laurent Garnier - Initial contribution + */ +@NonNullByDefault +public class ChartServletPeriodParamTest { + + @Test + public void convertToTemporalAmountFromNull() { + TemporalAmount period = ChartServlet.convertToTemporalAmount(null, Duration.ZERO); + assertEquals(0, period.get(ChronoUnit.SECONDS)); + } + + @Test + public void convertToTemporalAmountFromHours() { + TemporalAmount period = ChartServlet.convertToTemporalAmount("h", Duration.ZERO); + assertEquals(1 * 60 * 60, period.get(ChronoUnit.SECONDS)); + + period = ChartServlet.convertToTemporalAmount("12h", Duration.ZERO); + assertEquals(12 * 60 * 60, period.get(ChronoUnit.SECONDS)); + } + + @Test + public void convertToTemporalAmountFromDays() { + TemporalAmount period = ChartServlet.convertToTemporalAmount("D", Duration.ZERO); + assertEquals(1, period.get(ChronoUnit.DAYS)); + assertEquals(0, period.get(ChronoUnit.MONTHS)); + assertEquals(0, period.get(ChronoUnit.YEARS)); + + period = ChartServlet.convertToTemporalAmount("4D", Duration.ZERO); + assertEquals(4, period.get(ChronoUnit.DAYS)); + assertEquals(0, period.get(ChronoUnit.MONTHS)); + assertEquals(0, period.get(ChronoUnit.YEARS)); + } + + @Test + public void convertToTemporalAmountFromWeeks() { + TemporalAmount period = ChartServlet.convertToTemporalAmount("W", Duration.ZERO); + assertEquals(7, period.get(ChronoUnit.DAYS)); + assertEquals(0, period.get(ChronoUnit.MONTHS)); + assertEquals(0, period.get(ChronoUnit.YEARS)); + + period = ChartServlet.convertToTemporalAmount("2W", Duration.ZERO); + assertEquals(14, period.get(ChronoUnit.DAYS)); + assertEquals(0, period.get(ChronoUnit.MONTHS)); + assertEquals(0, period.get(ChronoUnit.YEARS)); + } + + @Test + public void convertToTemporalAmountFromMonths() { + TemporalAmount period = ChartServlet.convertToTemporalAmount("M", Duration.ZERO); + assertEquals(0, period.get(ChronoUnit.DAYS)); + assertEquals(1, period.get(ChronoUnit.MONTHS)); + assertEquals(0, period.get(ChronoUnit.YEARS)); + + period = ChartServlet.convertToTemporalAmount("3M", Duration.ZERO); + assertEquals(0, period.get(ChronoUnit.DAYS)); + assertEquals(3, period.get(ChronoUnit.MONTHS)); + assertEquals(0, period.get(ChronoUnit.YEARS)); + } + + @Test + public void convertToTemporalAmountFromYears() { + TemporalAmount period = ChartServlet.convertToTemporalAmount("Y", Duration.ZERO); + assertEquals(0, period.get(ChronoUnit.DAYS)); + assertEquals(0, period.get(ChronoUnit.MONTHS)); + assertEquals(1, period.get(ChronoUnit.YEARS)); + + period = ChartServlet.convertToTemporalAmount("2Y", Duration.ZERO); + assertEquals(0, period.get(ChronoUnit.DAYS)); + assertEquals(0, period.get(ChronoUnit.MONTHS)); + assertEquals(2, period.get(ChronoUnit.YEARS)); + } + + @Test + public void convertToTemporalAmountFromISO8601() { + TemporalAmount period = ChartServlet.convertToTemporalAmount("P2Y3M4D", Duration.ZERO); + assertEquals(4, period.get(ChronoUnit.DAYS)); + assertEquals(3, period.get(ChronoUnit.MONTHS)); + assertEquals(2, period.get(ChronoUnit.YEARS)); + + period = ChartServlet.convertToTemporalAmount("P1DT12H30M15S", Duration.ZERO); + assertEquals(36 * 60 * 60 + 30 * 60 + 15, period.get(ChronoUnit.SECONDS)); + } +} diff --git a/bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/STTService.java b/bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/STTService.java index 5f494e10603..28d0dfdb3cf 100644 --- a/bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/STTService.java +++ b/bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/STTService.java @@ -83,7 +83,7 @@ public interface STTService { * @param locale The {@code Locale} in which the target speech is spoken * @param grammars The JSpeech Grammar Format grammar specifying allowed statements * @return A {@link STTServiceHandle} used to abort recognition - * @throws A {@link SSTException} if any parameter is invalid or a STT problem occurs + * @throws A {@link STTException} if any parameter is invalid or a STT problem occurs */ STTServiceHandle recognize(STTListener sttListener, AudioStream audioStream, Locale locale, Set grammars) throws STTException; diff --git a/bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/text/ASTNode.java b/bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/text/ASTNode.java index fe131534cf8..0602d304534 100644 --- a/bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/text/ASTNode.java +++ b/bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/text/ASTNode.java @@ -110,7 +110,7 @@ public String findValueAsString(String name) { * * @param name the name of the named node to be found * @param cls the node's value has to be assignable to a reference of this class to match during search - * @return the value of the resulting node. Null, if not found or the value does not match {@link cls}. + * @return the value of the resulting node. Null, if not found or the value does not match {@code cls}. */ public Object findValue(String name, Class cls) { ASTNode node = findNode(name); diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/auth/ManagedUser.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/auth/ManagedUser.java index 1728d7c754b..f9f01b3d48d 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/auth/ManagedUser.java +++ b/bundles/org.openhab.core/src/main/java/org/openhab/core/auth/ManagedUser.java @@ -37,7 +37,7 @@ public class ManagedUser implements User { private List apiTokens = new ArrayList<>(); /** - * Constructs a user with a password hash & salt provided by the caller. + * Constructs a user with a password hash and salt provided by the caller. * * @param name the username (account name) * @param passwordSalt the salt to compute the password hash diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/auth/UserRegistry.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/auth/UserRegistry.java index 0a19d071986..3cd62672fe6 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/auth/UserRegistry.java +++ b/bundles/org.openhab.core/src/main/java/org/openhab/core/auth/UserRegistry.java @@ -43,7 +43,7 @@ public interface UserRegistry extends Registry, AuthenticationProv * Change the password for a {@link User} in this registry. The implementation receives the new password and is * responsible for their secure storage (for instance by hashing the password). * - * @param username the username of the existing user + * @param user the username of the existing user * @param newPassword the new password */ void changePassword(User user, String newPassword); diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/auth/client/oauth2/OAuthClientService.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/auth/client/oauth2/OAuthClientService.java index b278343643d..9cf6e0f02d5 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/auth/client/oauth2/OAuthClientService.java +++ b/bundles/org.openhab.core/src/main/java/org/openhab/core/auth/client/oauth2/OAuthClientService.java @@ -105,7 +105,7 @@ public interface OAuthClientService extends AutoCloseable { * the state will be assigned to the requestParams in this case. * @return An authorization URL during the Authorization Code Grant with http request parameters filled in. * e.g Produces a URL string like this: - * https://oauth.provider?response_type=code&client_id=myClientId&redirect_uri=redirectURI&scope=myScope&state=mySecureRandomState + * {@code https://oauth.provider?response_type=code&client_id=myClientId&redirect_uri=redirectURI&scope=myScope&state=mySecureRandomState} * @throws OAuthException if authorizationUrl or clientId were not previously provided (null) */ String getAuthorizationUrl(@Nullable String redirectURI, @Nullable String scope, @Nullable String state) @@ -122,8 +122,12 @@ String getAuthorizationUrl(@Nullable String redirectURI, @Nullable String scope, * returned by the oauth provider. It is encoded in application/x-www-form-urlencoded format * as stated in RFC 6749 section 4.1.2. * To quote from the RFC: + * + * 

{@code
      *            HTTP/1.1 302 Found
      *            Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz
+     *            }
+ * * @return AuthorizationCode This authorizationCode can be used in the call {#getOAuthTokenByAuthCode(String)} * @throws OAuthException If the state from redirectURLwithParams does not exactly match the expectedState, or * exceptions arise while parsing redirectURLwithParams. diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/cache/ExpiringCache.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/cache/ExpiringCache.java index 15cc1b002f1..9263dfba1f2 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/cache/ExpiringCache.java +++ b/bundles/org.openhab.core/src/main/java/org/openhab/core/cache/ExpiringCache.java @@ -43,7 +43,7 @@ public class ExpiringCache { * * @param expiry the duration for how long the value stays valid * @param action the action to retrieve/calculate the value - * @throws IllegalArgumentException For an expire value <=0. + * @throws IllegalArgumentException For an expire {@code value <=0}. */ public ExpiringCache(Duration expiry, Supplier<@Nullable V> action) { if (expiry.isNegative() || expiry.isZero()) { diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/cache/ExpiringCacheAsync.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/cache/ExpiringCacheAsync.java index dcfa30e91c6..110a663a261 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/cache/ExpiringCacheAsync.java +++ b/bundles/org.openhab.core/src/main/java/org/openhab/core/cache/ExpiringCacheAsync.java @@ -40,7 +40,7 @@ public class ExpiringCacheAsync { * Create a new instance. * * @param expiry the duration in milliseconds for how long the value stays valid. Must be positive. - * @throws IllegalArgumentException For an expire value <=0. + * @throws IllegalArgumentException For an expire {@code value <=0}. */ public ExpiringCacheAsync(Duration expiry) { if (expiry.isNegative() || expiry.isZero()) { @@ -53,7 +53,7 @@ public ExpiringCacheAsync(Duration expiry) { * Create a new instance. * * @param expiry the duration in milliseconds for how long the value stays valid. Must be greater than 0. - * @throws IllegalArgumentException For an expire value <=0. + * @throws IllegalArgumentException For an expire {@code value <=0}. */ public ExpiringCacheAsync(long expiry) { this(Duration.ofMillis(expiry)); diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/cache/lru/LRUMediaCache.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/cache/lru/LRUMediaCache.java index da1ce32b974..04b32505566 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/cache/lru/LRUMediaCache.java +++ b/bundles/org.openhab.core/src/main/java/org/openhab/core/cache/lru/LRUMediaCache.java @@ -83,7 +83,7 @@ public class LRUMediaCache { * Constructs a cache system. * * @param storageService Storage service to store metadata - * @param cacheSize Limit size, in byte + * @param maxCacheSize Limit size, in byte * @param pid A pid identifying the cache on disk */ public LRUMediaCache(@Reference StorageService storageService, long maxCacheSize, String pid, diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/common/ThreadPoolManager.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/common/ThreadPoolManager.java index 42e3076f6a1..69c51d2989d 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/common/ThreadPoolManager.java +++ b/bundles/org.openhab.core/src/main/java/org/openhab/core/common/ThreadPoolManager.java @@ -18,7 +18,6 @@ import java.util.Map; import java.util.Map.Entry; import java.util.Set; -import java.util.WeakHashMap; import java.util.concurrent.Callable; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ExecutionException; @@ -74,7 +73,7 @@ public class ThreadPoolManager { protected static final long THREAD_TIMEOUT = 65L; protected static final long THREAD_MONITOR_SLEEP = 60000; - protected static Map pools = new WeakHashMap<>(); + protected static Map pools = new ConcurrentHashMap<>(); private static Map configs = new ConcurrentHashMap<>(); @@ -124,23 +123,17 @@ protected void modified(Map properties) { * @return an instance to use */ public static ScheduledExecutorService getScheduledPool(String poolName) { - ExecutorService pool = pools.get(poolName); - if (pool == null) { - synchronized (pools) { - // do a double check if it is still null or if another thread might have created it meanwhile - pool = pools.get(poolName); - if (pool == null) { - int cfg = getConfig(poolName); - pool = new WrappedScheduledExecutorService(cfg, - new NamedThreadFactory(poolName, true, Thread.NORM_PRIORITY)); - ((ThreadPoolExecutor) pool).setKeepAliveTime(THREAD_TIMEOUT, TimeUnit.SECONDS); - ((ThreadPoolExecutor) pool).allowCoreThreadTimeOut(true); - ((ScheduledThreadPoolExecutor) pool).setRemoveOnCancelPolicy(true); - pools.put(poolName, pool); - LOGGER.debug("Created scheduled thread pool '{}' of size {}", poolName, cfg); - } - } - } + ExecutorService pool = pools.computeIfAbsent(poolName, (name) -> { + int cfg = getConfig(name); + ScheduledThreadPoolExecutor executor = new WrappedScheduledExecutorService(cfg, + new NamedThreadFactory(name, true, Thread.NORM_PRIORITY)); + executor.setKeepAliveTime(THREAD_TIMEOUT, TimeUnit.SECONDS); + executor.allowCoreThreadTimeOut(true); + executor.setRemoveOnCancelPolicy(true); + LOGGER.debug("Created scheduled thread pool '{}' of size {}", name, cfg); + return executor; + }); + if (pool instanceof ScheduledExecutorService service) { return new UnstoppableScheduledExecutorService(poolName, service); } else { @@ -156,21 +149,15 @@ public static ScheduledExecutorService getScheduledPool(String poolName) { * @return an instance to use */ public static ExecutorService getPool(String poolName) { - ExecutorService pool = pools.get(poolName); - if (pool == null) { - synchronized (pools) { - // do a double check if it is still null or if another thread might have created it meanwhile - pool = pools.get(poolName); - if (pool == null) { - int cfg = getConfig(poolName); - pool = QueueingThreadPoolExecutor.createInstance(poolName, cfg); - ((ThreadPoolExecutor) pool).setKeepAliveTime(THREAD_TIMEOUT, TimeUnit.SECONDS); - ((ThreadPoolExecutor) pool).allowCoreThreadTimeOut(true); - pools.put(poolName, pool); - LOGGER.debug("Created thread pool '{}' with size {}", poolName, cfg); - } - } - } + ExecutorService pool = pools.computeIfAbsent(poolName, (name) -> { + int cfg = getConfig(name); + ThreadPoolExecutor executor = QueueingThreadPoolExecutor.createInstance(name, cfg); + executor.setKeepAliveTime(THREAD_TIMEOUT, TimeUnit.SECONDS); + executor.allowCoreThreadTimeOut(true); + LOGGER.debug("Created thread pool '{}' with size {}", name, cfg); + return executor; + }); + return new UnstoppableExecutorService<>(poolName, pool); } @@ -179,9 +166,9 @@ static ThreadPoolExecutor getPoolUnwrapped(String poolName) { return (ThreadPoolExecutor) ret.getDelegate(); } - static ThreadPoolExecutor getScheduledPoolUnwrapped(String poolName) { + static ScheduledThreadPoolExecutor getScheduledPoolUnwrapped(String poolName) { UnstoppableExecutorService ret = (UnstoppableScheduledExecutorService) getScheduledPool(poolName); - return (ThreadPoolExecutor) ret.getDelegate(); + return (ScheduledThreadPoolExecutor) ret.getDelegate(); } protected static int getConfig(String poolName) { diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/common/registry/AbstractManagedProvider.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/common/registry/AbstractManagedProvider.java index de3679885b4..6c14bdf4edf 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/common/registry/AbstractManagedProvider.java +++ b/bundles/org.openhab.core/src/main/java/org/openhab/core/common/registry/AbstractManagedProvider.java @@ -118,7 +118,7 @@ public Collection getAll() { return oldElement; } } else { - logger.warn("Could not update element with key {} in {}, because it does not exists.", key, + logger.warn("Could not update element with key {} in {}, because it does not exist.", key, this.getClass().getSimpleName()); } diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/events/TopicGlobEventFilter.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/events/TopicGlobEventFilter.java index cce421ff13a..9759f07a704 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/events/TopicGlobEventFilter.java +++ b/bundles/org.openhab.core/src/main/java/org/openhab/core/events/TopicGlobEventFilter.java @@ -19,7 +19,7 @@ import org.eclipse.jdt.annotation.NonNullByDefault; /** - * The {@link TopicGlobalEventFilter} is a default openHAB {@link EventFilter} implementation that ensures filtering + * The {@link TopicGlobEventFilter} is a default openHAB {@link EventFilter} implementation that ensures filtering * of events based on an event topic. * * The syntax for the filter is the glob syntax documented at diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/events/TopicPrefixEventFilter.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/events/TopicPrefixEventFilter.java index 34e1eca6320..0227c5ddeba 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/events/TopicPrefixEventFilter.java +++ b/bundles/org.openhab.core/src/main/java/org/openhab/core/events/TopicPrefixEventFilter.java @@ -28,7 +28,7 @@ public class TopicPrefixEventFilter implements EventFilter { /** * Constructs a new topic event filter. * - * @param topicRegex the prefix event topics must start with + * @param topicPrefix the prefix event topics must start with */ public TopicPrefixEventFilter(String topicPrefix) { this.topicPrefix = topicPrefix; diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/internal/events/EventHandler.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/internal/events/EventHandler.java index e2ca6ba6da4..3560b1fb086 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/internal/events/EventHandler.java +++ b/bundles/org.openhab.core/src/main/java/org/openhab/core/internal/events/EventHandler.java @@ -53,6 +53,7 @@ public class EventHandler implements AutoCloseable { private final Map typedEventFactories; private final Map, ExecutorRecord> executors = new HashMap<>(); + private final ScheduledExecutorService watcher; /** * Create a new event handler. @@ -64,12 +65,12 @@ public EventHandler(final Map> typedEventSubscriber final Map typedEventFactories) { this.typedEventSubscribers = typedEventSubscribers; this.typedEventFactories = typedEventFactories; + watcher = Executors.newSingleThreadScheduledExecutor(new NamedThreadFactory("eventwatcher")); } private synchronized ExecutorRecord createExecutorRecord(Class subscriber) { return new ExecutorRecord( Executors.newSingleThreadExecutor(new NamedThreadFactory("eventexecutor-" + executors.size())), - Executors.newSingleThreadScheduledExecutor(new NamedThreadFactory("eventwatcher-" + executors.size())), new AtomicInteger()); } @@ -77,8 +78,8 @@ private synchronized ExecutorRecord createExecutorRecord(Class { r.executor.shutdownNow(); - r.watcher.shutdownNow(); }); + watcher.shutdownNow(); } public void handleEvent(org.osgi.service.event.Event osgiEvent) { @@ -154,13 +155,13 @@ private synchronized void dispatchEvent(final Set eventSubscrib logger.trace("Delegate event to subscriber ({}).", eventSubscriber.getClass()); ExecutorRecord executorRecord = Objects.requireNonNull( executors.computeIfAbsent(eventSubscriber.getClass(), this::createExecutorRecord)); - int queueSize = executorRecord.count().incrementAndGet(); + int queueSize = executorRecord.count.incrementAndGet(); if (queueSize > EVENT_QUEUE_WARN_LIMIT) { logger.warn("The queue for a subscriber of type '{}' exceeds {} elements. System may be unstable.", eventSubscriber.getClass(), EVENT_QUEUE_WARN_LIMIT); } CompletableFuture.runAsync(() -> { - ScheduledFuture logTimeout = executorRecord.watcher().schedule( + ScheduledFuture logTimeout = watcher.schedule( () -> logger.warn("Dispatching event to subscriber '{}' takes more than {}ms.", eventSubscriber, EVENTSUBSCRIBER_EVENTHANDLING_MAX_MS), EVENTSUBSCRIBER_EVENTHANDLING_MAX_MS, TimeUnit.MILLISECONDS); @@ -171,13 +172,13 @@ private synchronized void dispatchEvent(final Set eventSubscrib EventSubscriber.class.getName(), ex.getMessage(), ex); } logTimeout.cancel(false); - }, executorRecord.executor()).thenRun(executorRecord.count::decrementAndGet); + }, executorRecord.executor).thenRun(executorRecord.count::decrementAndGet); } else { logger.trace("Skip event subscriber ({}) because of its filter.", eventSubscriber.getClass()); } } } - private record ExecutorRecord(ExecutorService executor, ScheduledExecutorService watcher, AtomicInteger count) { + private record ExecutorRecord(ExecutorService executor, AtomicInteger count) { } } 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 c77010e37d9..6b987e85cf4 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 @@ -115,7 +115,7 @@ public void modified(WatchServiceConfiguration config) throws IOException { closeWatcherAndUnregister(); if (!Files.exists(basePath)) { - logger.info("Watch directory '{}' does not exists. Trying to create it.", basePath); + logger.info("Watch directory '{}' does not exist. Trying to create it.", basePath); Files.createDirectories(basePath); } diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/items/ManagedItemProvider.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/items/ManagedItemProvider.java index 2a54f1e9b14..450daf73dd6 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/items/ManagedItemProvider.java +++ b/bundles/org.openhab.core/src/main/java/org/openhab/core/items/ManagedItemProvider.java @@ -40,8 +40,8 @@ /** * {@link ManagedItemProvider} is an OSGi service, that allows to add or remove - * items at runtime by calling {@link ManagedItemProvider#addItem(Item)} or {@link ManagedItemProvider#removeItem(Item)} - * . An added item is automatically + * items at runtime by calling {@link #add} or {@link #remove}. + * An added item is automatically * exposed to the {@link ItemRegistry}. Persistence of added Items is handled by * a {@link StorageService}. Items are being restored using the given {@link ItemFactory}s. * diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/items/ManagedMetadataProvider.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/items/ManagedMetadataProvider.java index 6c9f508af8e..d0598d5699e 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/items/ManagedMetadataProvider.java +++ b/bundles/org.openhab.core/src/main/java/org/openhab/core/items/ManagedMetadataProvider.java @@ -29,7 +29,7 @@ public interface ManagedMetadataProvider extends ManagedProvider> getAcceptedCommandTypes() { * http://stackoverflow.com/questions/837872/calculate-distance-in-meters-when-you-know-longitude-and-latitude-in- * java * - * @param away : the point to calculate the distance with + * @param awayItem the point to calculate the distance with * @return distance between the two points in meters */ public DecimalType distanceFrom(@Nullable LocationItem awayItem) { diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/library/types/HSBType.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/library/types/HSBType.java index 676420a35ee..4d3fcff5ca9 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/library/types/HSBType.java +++ b/bundles/org.openhab.core/src/main/java/org/openhab/core/library/types/HSBType.java @@ -65,7 +65,7 @@ public HSBType() { /** * Constructs a HSBType instance with the given values * - * @param h the hue value in the range from 0 <= h < 360 + * @param h the hue value in the range from {@code 0 <= h < 360} * @param s the saturation as a percent value * @param b the brightness as a percent value */ @@ -80,7 +80,7 @@ public HSBType(DecimalType h, PercentType s, PercentType b) { * Constructs a HSBType instance from a given string. * The string has to be in comma-separated format with exactly three segments, which correspond to the hue, * saturation and brightness values. - * where the hue value in the range from 0 <= h < 360 and the saturation and brightness are percent values. + * where the hue value in the range from {@code 0 <= h < 360} and the saturation and brightness are percent values. * * @param value a stringified HSBType value in the format "hue,saturation,brightness" */ diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/library/types/QuantityType.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/library/types/QuantityType.java index 8207e433517..3563fe7305c 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/library/types/QuantityType.java +++ b/bundles/org.openhab.core/src/main/java/org/openhab/core/library/types/QuantityType.java @@ -181,7 +181,7 @@ private QuantityType(Quantity quantity) { } /** - * Static access to {@link QuantityType(double, Unit)}. + * Static access to {@link QuantityType(Number, Unit)}. * * @param value the non-null measurement value. * @param unit the non-null measurement unit. @@ -293,7 +293,7 @@ public Dimension getDimension() { /** * Convert this QuantityType to a new {@link QuantityType} using the given target unit. * - * Implicit conversions using inverse units are allowed (i.e. mired <=> Kelvin). This may + * Implicit conversions using inverse units are allowed (i.e. {@code mired <=> Kelvin}). This may * change the dimension. * * @param targetUnit the unit to which this {@link QuantityType} will be converted to. diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/scheduler/CronScheduler.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/scheduler/CronScheduler.java index a74456dd29e..475660506b1 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/scheduler/CronScheduler.java +++ b/bundles/org.openhab.core/src/main/java/org/openhab/core/scheduler/CronScheduler.java @@ -83,7 +83,7 @@ * @reboot Run at startup @reboot * *

- * Please note that for the constants we follow the Java 8 Date & Time constants. + * Please note that for the constants we follow the Java 8 Date and Time constants. * Major difference is the day number. In Quartz this is 0-6 for SAT-SUN while * here it is 1-7 for MON-SUN. * @@ -112,9 +112,8 @@ public interface CronScheduler { * time, the runnable will be run. The method returns a {@link ScheduledCompletableFuture} * that can be used to stop scheduling. The run method of cronJob takes * an environment object. An environment object is a custom interface where - * the names of the methods are the keys in the properties (see {@link DTOs}). + * the names of the methods are the keys in the properties (see {@link org.openhab.core.items.dto.ItemDTO DTOs}). * - * @param The data type of the parameter for the cron job * @param cronJob The runnable to run * @param cronExpression A cron expression * @return A {@link ScheduledCompletableFuture} to cancel the schedule diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/scheduler/Scheduler.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/scheduler/Scheduler.java index 8e784c5e203..077398730a7 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/scheduler/Scheduler.java +++ b/bundles/org.openhab.core/src/main/java/org/openhab/core/scheduler/Scheduler.java @@ -107,7 +107,7 @@ public interface Scheduler { /** * Schedules the callable once or repeating using the temporalAdjuster to determine the * time the callable should run. Runs until the job is cancelled or if the temporalAdjuster - * method {@link SchedulerTemporalAdjuster#isDone()) returns true. + * method {@link SchedulerTemporalAdjuster#isDone} returns true. * * @param callable Provides the result * @param temporalAdjuster the temperalAdjuster to return the time the callable should run @@ -118,10 +118,10 @@ public interface Scheduler { /** * Schedules the callable once or repeating using the temporalAdjuster to determine the * time the callable should run. Runs until the job is cancelled or if the temporalAdjuster - * method {@link SchedulerTemporalAdjuster#isDone()) returns true. + * method {@link SchedulerTemporalAdjuster#isDone} returns true. * * @param callable Provides the result - * @param an optional identifier for this job + * @param identifier an optional identifier for this job * @param temporalAdjuster the temperalAdjuster to return the time the callable should run * @return A {@link ScheduledCompletableFuture} */ diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/service/ReadyMarkerFilter.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/service/ReadyMarkerFilter.java index fbfc8849f6a..e7015485798 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/service/ReadyMarkerFilter.java +++ b/bundles/org.openhab.core/src/main/java/org/openhab/core/service/ReadyMarkerFilter.java @@ -58,7 +58,7 @@ public ReadyMarkerFilter withType(@Nullable String type) { /** * Returns a {@link ReadyMarkerFilter} restricted to the given identifier. * - * @param type + * @param identifier * @return */ public ReadyMarkerFilter withIdentifier(@Nullable String identifier) { diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/service/ReadyService.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/service/ReadyService.java index 7f6f2bf0480..f107800f07f 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/service/ReadyService.java +++ b/bundles/org.openhab.core/src/main/java/org/openhab/core/service/ReadyService.java @@ -67,7 +67,7 @@ public interface ReadyService { * The provided tracker will get notified about the addition of all existing readyMarkers right away. * * @param readyTracker - * @param readyMarker + * @param filter */ void registerTracker(ReadyTracker readyTracker, ReadyMarkerFilter filter); 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 fea74a0717a..a106e36b3fa 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 @@ -35,7 +35,6 @@ public interface WatchServiceFactory { * * @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 */ void createWatchService(String name, Path basePath) throws IOException; diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/types/TimeSeries.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/types/TimeSeries.java index 709f5ff861f..aa71f00b9fe 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/types/TimeSeries.java +++ b/bundles/org.openhab.core/src/main/java/org/openhab/core/types/TimeSeries.java @@ -93,7 +93,7 @@ public void add(Instant timestamp, State state) { *

* The entries are returned in chronological order, earlier entries before later entries. * - * @return a {@link } with the content of this series. + * @return a {@link Stream} with the content of this series. */ public Stream getStates() { return List.copyOf(states).stream(); diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/util/ColorUtil.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/util/ColorUtil.java index 23295f0e38a..4652cf50906 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/util/ColorUtil.java +++ b/bundles/org.openhab.core/src/main/java/org/openhab/core/util/ColorUtil.java @@ -44,8 +44,10 @@ public class ColorUtil { private static final BigDecimal BIG_DECIMAL_120 = BigDecimal.valueOf(120); private static final BigDecimal BIG_DECIMAL_100 = BigDecimal.valueOf(100); private static final BigDecimal BIG_DECIMAL_60 = BigDecimal.valueOf(60); + private static final BigDecimal BIG_DECIMAL_50 = BigDecimal.valueOf(50); private static final BigDecimal BIG_DECIMAL_5 = BigDecimal.valueOf(5); private static final BigDecimal BIG_DECIMAL_3 = BigDecimal.valueOf(3); + private static final BigDecimal BIG_DECIMAL_2 = BigDecimal.valueOf(2); private static final BigDecimal BIG_DECIMAL_2_POINT_55 = new BigDecimal("2.55"); public static final Gamut DEFAULT_GAMUT = new Gamut(new double[] { 0.9961, 0.0001 }, new double[] { 0, 0.9961 }, @@ -61,7 +63,7 @@ private ColorUtil() { * * This function does rounding to integer valued components. It is the preferred way of doing HSB to RGB conversion. * - * See also: {@link #hsbToRgbPercent(HSBType)}, {@link #hsbTosRgb(HSBType)} + * See also: {@link #hsbToRgbPercent(HSBType)}, {@link #hsbToRgbw(HSBType)}, {@link #hsbTosRgb(HSBType)} * * @param hsb an {@link HSBType} value. * @return array of three int with the RGB values in the range 0 to 255. @@ -72,6 +74,24 @@ public static int[] hsbToRgb(HSBType hsb) { convertColorPercentToByte(rgbPercent[2]) }; } + /** + * Transform HSV based {@link HSBType} to + * sRGB. + * + * This function does rounding to integer valued components. It is the preferred way of doing HSB to RGBW + * conversion. + * + * See also: {@link #hsbToRgbPercent(HSBType)}, {@link #hsbToRgbwPercent(HSBType)}, {@link #hsbTosRgb(HSBType)} + * + * @param hsb an {@link HSBType} value. + * @return array of four int with the RGBW values in the range 0 to 255. + */ + public static int[] hsbToRgbw(HSBType hsb) { + final PercentType[] rgbPercent = hsbToRgbwPercent(hsb); + return new int[] { convertColorPercentToByte(rgbPercent[0]), convertColorPercentToByte(rgbPercent[1]), + convertColorPercentToByte(rgbPercent[2]), convertColorPercentToByte(rgbPercent[3]) }; + } + /** * Transform HSV based {@link HSBType} to * sRGB. @@ -79,7 +99,7 @@ public static int[] hsbToRgb(HSBType hsb) { * This function does not round the components. For conversion to integer values in the range 0 to 255 use * {@link #hsbToRgb(HSBType)}. * - * See also: {@link #hsbToRgb(HSBType)}, {@link #hsbTosRgb(HSBType)} + * See also: {@link #hsbToRgb(HSBType)}, {@link #hsbTosRgb(HSBType)}, {@link #hsbToRgbwPercent(HSBType)} * * @param hsb an {@link HSBType} value. * @return array of three {@link PercentType} with the RGB values in the range 0 to 100 percent. @@ -140,6 +160,55 @@ public static PercentType[] hsbToRgbPercent(HSBType hsb) { return new PercentType[] { red, green, blue }; } + /** + * Transform HSV based {@link HSBType} to RGBW. + * + * See Converting RGB to RGBW. + * + * This function does not round the components. For conversion to integer values in the range 0 to 255 use + * {@link #hsbToRgb(HSBType)}. + * + * See also: {@link #hsbToRgb(HSBType)}, {@link #hsbTosRgb(HSBType)}, {@link #hsbToRgbPercent(HSBType)} + * + * @param hsb an {@link HSBType} value. + * @return array of four {@link PercentType} with the RGBW values in the range 0 to 100 percent. + */ + public static PercentType[] hsbToRgbwPercent(HSBType hsb) { + PercentType[] rgb = hsbToRgbPercent(hsb); + final BigDecimal inRed = rgb[0].toBigDecimal(); + final BigDecimal inGreen = rgb[1].toBigDecimal(); + final BigDecimal inBlue = rgb[2].toBigDecimal(); + // Get the maximum between R, G, and B + final BigDecimal maxColor = inRed.max(inGreen.max(inBlue)); + + // If the maximum value is 0, immediately return pure black. + if (BigDecimal.ZERO.equals(maxColor)) { + return new PercentType[] { PercentType.ZERO, PercentType.ZERO, PercentType.ZERO, PercentType.ZERO }; + } + + // This section serves to figure out what the color with 100% hue is + final BigDecimal multiplier = BIG_DECIMAL_100.divide(maxColor, 0, RoundingMode.DOWN); + final BigDecimal hR = inRed.multiply(multiplier); + final BigDecimal hG = inGreen.multiply(multiplier); + final BigDecimal hB = inBlue.multiply(multiplier); + + // This calculates the Whiteness (not strictly speaking Luminance) of the color + final BigDecimal whitenessMax = hR.max(hG.max(hB)); + final BigDecimal whitenessMin = hR.min(hG.min(hB)); + final BigDecimal luminance = ((whitenessMax.add(whitenessMin).divide(BIG_DECIMAL_2).subtract(BIG_DECIMAL_50)) + .multiply(BIG_DECIMAL_100.divide(BIG_DECIMAL_50))).divide(multiplier); + + // check range + BigDecimal outRed = inRed.subtract(luminance).max(BigDecimal.ZERO); + BigDecimal outGreen = inGreen.subtract(luminance).max(BigDecimal.ZERO); + BigDecimal outBlue = inBlue.subtract(luminance).max(BigDecimal.ZERO); + BigDecimal outWhite = luminance.max(BigDecimal.ZERO); + + return new PercentType[] { new PercentType(outRed), new PercentType(outGreen), new PercentType(outBlue), + new PercentType(outWhite) }; + } + /** * Transform HSV based {@link HSBType} * to the RGB value representing the color in the default @@ -211,23 +280,69 @@ public static double[] hsbToXY(HSBType hsb, Gamut gamut) { * Transform sRGB color format to * HSV based {@link HSBType}. * - * @param rgb array of three int with the RGB values in the range 0 to 255. + * @param rgbw array of three or four int with the RGB(W) values in the range 0 to 255. * @return the corresponding {@link HSBType}. * @throws IllegalArgumentException when input array has wrong size or exceeds allowed value range. */ - public static HSBType rgbToHsb(int[] rgb) throws IllegalArgumentException { - if (rgb.length != 3 || !inByteRange(rgb[0]) || !inByteRange(rgb[1]) || !inByteRange(rgb[2])) { + public static HSBType rgbToHsb(int[] rgbw) throws IllegalArgumentException { + if (rgbw.length == 4) { + return rgbwToHsb(rgbw); + } + if (rgbw.length != 3 || !inByteRange(rgbw[0]) || !inByteRange(rgbw[1]) || !inByteRange(rgbw[2])) { throw new IllegalArgumentException("RGB array only allows values between 0 and 255"); } - return rgbToHsb(new PercentType[] { convertByteToColorPercent(rgb[0]), convertByteToColorPercent(rgb[1]), - convertByteToColorPercent(rgb[2]) }); + return rgbToHsb(new PercentType[] { convertByteToColorPercent(rgbw[0]), convertByteToColorPercent(rgbw[1]), + convertByteToColorPercent(rgbw[2]) }); + } + + /** + * Transform HSV based {@link HSBType} to RGBW. + * + * See Converting RGB to RGBW. + * + * This function does not round the components. For conversion to integer values in the range 0 to 255 use + * {@link #hsbToRgb(HSBType)}. + * + * See also: {@link #hsbToRgb(HSBType)}, {@link #hsbTosRgb(HSBType)}, {@link #hsbToRgbPercent(HSBType)} + * + * @param rgbw array of four int with the RGBW values in the range 0 to 255. + * @return hsb an {@link HSBType} value. + * + */ + private static HSBType rgbwToHsb(int[] rgbw) { + if (rgbw.length != 4 || !inByteRange(rgbw[0]) || !inByteRange(rgbw[1]) || !inByteRange(rgbw[2]) + || !inByteRange(rgbw[3])) { + throw new IllegalArgumentException("RGBW array only allows values between 0 and 255 with 4 values"); + } + + BigDecimal luminance = BigDecimal.valueOf(rgbw[3]); + BigDecimal inRed = BigDecimal.valueOf(rgbw[0]).add(luminance); + BigDecimal inGreen = BigDecimal.valueOf(rgbw[1]).add(luminance); + BigDecimal inBlue = BigDecimal.valueOf(rgbw[2]).add(luminance); + + // Get the maximum between R, G, and B + final BigDecimal maxColor = BIG_DECIMAL_255.min(inRed.max(inGreen.max(inBlue)).max(BigDecimal.ZERO)); + + // If the maximum value is 0, immediately return pure black. + if (BigDecimal.ZERO.compareTo(maxColor) == 0) { + return HSBType.BLACK; + } + + final BigDecimal multiplier = BIG_DECIMAL_255.divide(maxColor, 0, RoundingMode.DOWN); + + BigDecimal outRed = inRed.divide(multiplier).min(BIG_DECIMAL_255).max(BigDecimal.ZERO); + BigDecimal outGreen = inGreen.divide(multiplier).min(BIG_DECIMAL_255).max(BigDecimal.ZERO); + BigDecimal outBlue = inBlue.divide(multiplier).min(BIG_DECIMAL_255).max(BigDecimal.ZERO); + + return HSBType.fromRGB(outRed.intValue(), outGreen.intValue(), outBlue.intValue()); } /** * Transform sRGB color format to * HSV based {@link HSBType}. * - * @param rgb array of three {@link PercentType] with the RGB values in the range 0 to 100 percent. + * @param rgb array of three {@link PercentType} with the RGB values in the range 0 to 100 percent. * @return the corresponding {@link HSBType}. * @throws IllegalArgumentException when input array has wrong size or exceeds allowed value range. */ diff --git a/bundles/org.openhab.core/src/main/java/org/openhab/core/util/StringUtils.java b/bundles/org.openhab.core/src/main/java/org/openhab/core/util/StringUtils.java index 8cbcf485bf6..eac40ac6328 100644 --- a/bundles/org.openhab.core/src/main/java/org/openhab/core/util/StringUtils.java +++ b/bundles/org.openhab.core/src/main/java/org/openhab/core/util/StringUtils.java @@ -65,13 +65,13 @@ public class StringUtils { * Simple method to escape XML special characters in String. * There are five XML special characters which needs to be escaped: * - * 

+     * 
{@code
      * & - &
      * < - <
      * > - >
      * " - "
      * ' - '
-     * 

+     * }
* * @param str the input xml as String to escape, may be null * @return the escaped xml as String, may be null @@ -96,7 +96,7 @@ public class StringUtils { * "'cat'" => "'cat'" * * - * @param val the String to capitalize, may be null + * @param str the String to capitalize, may be null * @return the capitalized String, may be null */ public static @Nullable String capitalize(@Nullable String str) { @@ -289,15 +289,15 @@ public static String[] splitByCharacterType(@Nullable String str) { * Simple method to un escape XML special characters in String. * There are five XML Special characters which needs to be escaped: * - * 
+     * 
{@code
      * & => &
      * < => <
      * > => >
      * " => "
      * ' => '
-     * 

+     * }
* - * @param input the input xml as String to unescape, may be null + * @param str the input xml as String to unescape, may be null * @return the unescaped xml as String, may be null */ public static @Nullable String unEscapeXml(@Nullable String str) { diff --git a/bundles/org.openhab.core/src/test/java/org/openhab/core/util/ColorUtilTest.java b/bundles/org.openhab.core/src/test/java/org/openhab/core/util/ColorUtilTest.java index 21acc54d127..1f02ffa9aa7 100644 --- a/bundles/org.openhab.core/src/test/java/org/openhab/core/util/ColorUtilTest.java +++ b/bundles/org.openhab.core/src/test/java/org/openhab/core/util/ColorUtilTest.java @@ -59,6 +59,72 @@ public void inversionTest(HSBType hsb) { assertThat(deltaBri, is(lessThanOrEqualTo(1.0))); } + @Test + public void hsbToRgbwTest() { + HSBType hsb = HSBType.WHITE; + PercentType[] rgbw = ColorUtil.hsbToRgbwPercent(hsb); + assertEquals(0.0, rgbw[0].doubleValue(), 0.01); + assertEquals(0.0, rgbw[1].doubleValue(), 0.01); + assertEquals(0.0, rgbw[2].doubleValue(), 0.01); + assertEquals(100.0, rgbw[3].doubleValue(), 0.01); + + hsb = HSBType.BLACK; + rgbw = ColorUtil.hsbToRgbwPercent(hsb); + assertEquals(0.0, rgbw[0].doubleValue(), 0.01); + assertEquals(0.0, rgbw[1].doubleValue(), 0.01); + assertEquals(0.0, rgbw[2].doubleValue(), 0.01); + assertEquals(0.0, rgbw[3].doubleValue(), 0.01); + + hsb = HSBType.RED; + rgbw = ColorUtil.hsbToRgbwPercent(hsb); + assertEquals(100.0, rgbw[0].doubleValue(), 0.01); + assertEquals(0.0, rgbw[1].doubleValue(), 0.01); + assertEquals(0.0, rgbw[2].doubleValue(), 0.01); + assertEquals(0.0, rgbw[3].doubleValue(), 0.01); + + hsb = HSBType.GREEN; + rgbw = ColorUtil.hsbToRgbwPercent(hsb); + assertEquals(0.0, rgbw[0].doubleValue(), 0.01); + assertEquals(100.0, rgbw[1].doubleValue(), 0.01); + assertEquals(0.0, rgbw[2].doubleValue(), 0.01); + assertEquals(0.0, rgbw[3].doubleValue(), 0.01); + + hsb = HSBType.BLUE; + rgbw = ColorUtil.hsbToRgbwPercent(hsb); + assertEquals(0.0, rgbw[0].doubleValue(), 0.01); + assertEquals(0.0, rgbw[1].doubleValue(), 0.01); + assertEquals(100.0, rgbw[2].doubleValue(), 0.01); + assertEquals(0.0, rgbw[3].doubleValue(), 0.01); + } + + @Test + public void rgbwToHsbTest() { + // Test Red + HSBType hsb = ColorUtil.rgbToHsb(new int[] { 255, 0, 0, 0 }); + int[] convertedRgb = ColorUtil.hsbToRgb(hsb); + assertRgbEquals(new int[] { 255, 0, 0 }, convertedRgb); + + // Test Green + hsb = ColorUtil.rgbToHsb(new int[] { 0, 255, 0, 0 }); + convertedRgb = ColorUtil.hsbToRgb(hsb); + assertRgbEquals(new int[] { 0, 255, 0 }, convertedRgb); + + // Test Blue + hsb = ColorUtil.rgbToHsb(new int[] { 0, 0, 255, 0 }); + convertedRgb = ColorUtil.hsbToRgb(hsb); + assertRgbEquals(new int[] { 0, 0, 255 }, convertedRgb); + + // Test White + hsb = ColorUtil.rgbToHsb(new int[] { 0, 0, 0, 255 }); + convertedRgb = ColorUtil.hsbToRgb(hsb); + assertRgbEquals(new int[] { 255, 255, 255 }, convertedRgb); + + // Test Black + hsb = ColorUtil.rgbToHsb(new int[] { 0, 0, 0, 0 }); + convertedRgb = ColorUtil.hsbToRgb(hsb); + assertRgbEquals(new int[] { 0, 0, 0 }, convertedRgb); + } + @ParameterizedTest @MethodSource("invalids") public void invalidXyValues(double[] xy) {