openhab · J-N-K · Jan 3, 2024 · Jan 2, 2024
@@ -129,7 +129,7 @@ public void addTemplateAsJSON(String uid, String json) throws ParsingException {
      * This adds a new rule template to the persistent storage from its YAML representation.
      *
      * @param uid the UID to be used for the template
-     * @param json the template content as a YAML string
+     * @param yaml the template content as a YAML string
      *
      * @throws ParsingException if the content cannot be parsed correctly
      */

@@ -22,6 +22,7 @@
 import org.openhab.core.config.core.xml.util.GenericUnmarshaller;
 import org.openhab.core.config.core.xml.util.NodeIterator;
 
+import com.thoughtworks.xstream.converters.Converter;
 import com.thoughtworks.xstream.converters.UnmarshallingContext;
 import com.thoughtworks.xstream.io.HierarchicalStreamReader;
 

@@ -26,7 +26,8 @@
  * objects by a {@link AddonInfoReader} for a certain bundle.
  * <p>
  * This implementation registers each {@link AddonInfo} object at the {@link XmlAddonInfoProvider} which is itself
- * registered as {@link AddonInfoProvider} service at the <i>OSGi</i> service registry.
+ * registered as {@link org.openhab.core.addon.AddonInfoProvider AddonInfoProvider} service at the <i>OSGi</i> service
+ * registry.
  * <p>
  * If there is a {@link ConfigDescription} object within the {@link AddonInfoXmlResult} object, it is added to the
  * {@link AbstractXmlConfigDescriptionProvider} which is itself registered as <i>OSGi</i> service at the service

@@ -20,6 +20,7 @@
 import org.openhab.core.config.core.xml.util.GenericUnmarshaller;
 import org.openhab.core.config.core.xml.util.NodeIterator;
 
+import com.thoughtworks.xstream.converters.Converter;
 import com.thoughtworks.xstream.converters.UnmarshallingContext;
 import com.thoughtworks.xstream.io.HierarchicalStreamReader;
 

@@ -21,6 +21,7 @@
 import org.openhab.core.config.core.xml.util.GenericUnmarshaller;
 import org.openhab.core.config.core.xml.util.NodeIterator;
 
+import com.thoughtworks.xstream.converters.Converter;
 import com.thoughtworks.xstream.converters.UnmarshallingContext;
 import com.thoughtworks.xstream.io.HierarchicalStreamReader;
 

@@ -49,7 +49,7 @@ public class AudioPlayer extends Thread {
     /**
      * Constructs an AudioPlayer to play the passed AudioSource
      *
-     * @param audioSource The AudioSource to play
+     * @param audioStream The AudioStream to play
      */
     public AudioPlayer(AudioStream audioStream) {
         this.audioStream = audioStream;

@@ -16,7 +16,8 @@
 import org.openhab.core.events.AbstractEvent;
 
 /**
- * This is an {@link Event} that is sent when a web client should play an audio stream from a url.
+ * This is an {@link org.openhab.core.events.Event Event} that is sent when a web client should play an audio stream
+ * from a url.
  *
  * @author Kai Kreuzer - Initial contribution and API
  */

@@ -89,7 +89,6 @@ private OAuthClientServiceImpl(String handle, int tokenExpiresInSeconds, HttpCli
     /**
      * It should only be used internally, thus the access is package level
      *
-     * @param bundleContext Bundle Context
      * @param handle The handle produced previously from
      *            {@link org.openhab.core.auth.client.oauth2.OAuthFactory#createOAuthClientService}
      * @param storeHandler Storage handler
@@ -119,12 +118,11 @@ private OAuthClientServiceImpl(String handle, int tokenExpiresInSeconds, HttpCli
     /**
      * It should only be used internally, thus the access is package level
      *
-     * @param bundleContext Bundle Context*
      * @param handle The handle produced previously from
      *            {@link org.openhab.core.auth.client.oauth2.OAuthFactory#createOAuthClientService}*
      * @param storeHandler Storage handler
      * @param httpClientFactory Http client factory
-     * @param persistedParams These parameters are static with respect to the OAuth provider and thus can be persisted.
+     * @param params These parameters are static with respect to the OAuth provider and thus can be persisted.
      * @return OAuthClientServiceImpl an instance
      */
     static OAuthClientServiceImpl createInstance(String handle, OAuthStoreHandler storeHandler,

@@ -356,14 +356,16 @@ private AccessTokenResponse doRequest(final String grantType, HttpClient httpCli
 
     /**
      * This is a special case where the httpClient (jetty) is created due to the need for certificate pinning.
-     * If certificate pinning is needed, please refer to {@code TrustManagerProvider}. The http client is
-     * created, used and then shutdown immediately after use. There is little reason to cache the client/ connections
+     * If certificate pinning is needed, please refer to
+     * {@code org.openhab.core.io.net.http.ExtensibleTrustManager ExtensibleTrustManager}.
+     * The http client is created, used and then shutdown immediately after use. There is little reason to cache the
+     * client/ connections
      * because oauth requests are short; and it may take hours/ days before the next request is needed.
      *
      * @param tokenUrl access token url
      * @return http client. This http client
      * @throws OAuthException If any exception is thrown while starting the http client.
-     * @see TrustManagerProvider
+     * @see org.openhab.core.io.net.http.ExtensibleTrustManager
      */
     private HttpClient createHttpClient(String tokenUrl) throws OAuthException {
         HttpClient httpClient = httpClientFactory.createHttpClient(HTTP_CLIENT_CONSUMER_NAME);

@@ -38,7 +38,7 @@
 
 /**
  * The {@link OAuthStoreHandlerTest} contains tests for
- * {@link org.openhab.core.auth.oauth2client.OAuthStoreHandlerImpl}
+ * {@link org.openhab.core.auth.oauth2client.internal.OAuthStoreHandlerImpl}
  *
  * @author Jacob Laursen - Initial contribution
  */

@@ -99,7 +99,7 @@ private List<ModuleType> getModuleTypesUnconditionally(@Nullable Locale locale)
     }
 
     /**
-     * This method creates the {@link ConfigurationDescriptionParameter}s used by the generated ScriptActionType and
+     * This method creates the {@link ConfigDescriptionParameter}s used by the generated ScriptActionType and
      * ScriptConditionType. {@link AbstractScriptModuleHandler} requires that the names of these be 'type' and 'script'.
      *
      * @return a list of {#link ConfigurationDescriptionParameter}s

@@ -44,9 +44,9 @@ public class RulePredicates {
      * <br/>
      * The name space is part of the UID and the prefix thereof.
      * <br/>
-     * If the UID does not contain a {@link PREFIX_SEPARATOR} {@code null} will be returned.
+     * If the UID does not contain a {@link #PREFIX_SEPARATOR} {@code null} will be returned.
      * <br/>
-     * If the UID does contain a {@link PREFIX_SEPARATOR} the prefix until the first occurrence will be returned.
+     * If the UID does contain a {@link #PREFIX_SEPARATOR} the prefix until the first occurrence will be returned.
      * <br/>
      * If the prefix would have a zero length {@code null} will be returned.
      *

@@ -110,7 +110,7 @@ private List<RuleExecution> simulateExecutionsForRule(Rule rule, ZonedDateTime f
      * @param rule {@link Rule} to be simulated.
      * @param from {@link ZonedDateTime} earliest time to be contained in the rule simulation.
      * @param until {@link ZonedDateTime} latest time to be contained in the rule simulation.
-     * @param cron cron-expression to be evaluated for determining the execution times.
+     * @param temporalAdjuster {@link SchedulerTemporalAdjuster} to be evaluated for determining the execution times.
      * @return a list of expected executions.
      */
     private List<RuleExecution> simulateExecutionsForCronBasedRule(Rule rule, ZonedDateTime from, ZonedDateTime until,

@@ -63,7 +63,7 @@
  * The {@link RuleRegistryImpl} provides basic functionality for managing {@link Rule}s.
  * It can be used to
  * <ul>
- * <li>Add Rules with the {@link #add(Rule)}, {@link #added(Provider, Rule)}, {@link #addProvider(RuleProvider)}
+ * <li>Add Rules with the {@link #add(Rule)}, {@link #added(Provider, Rule)}, {@link #addProvider(Provider)}
  * methods.</li>
  * <li>Get the existing rules with the {@link #get(String)}, {@link #getAll()}, {@link #getByTag(String)},
  * {@link #getByTags(String[])} methods.</li>
@@ -130,7 +130,7 @@ public RuleRegistryImpl() {
     /**
      * Activates this component. Called from DS.
      *
-     * @param componentContext this component context.
+     * @param bundleContext this component context.
      */
     @Override
     @Activate

@@ -18,7 +18,7 @@
 import org.openhab.core.config.core.Configuration;
 
 /**
- * This class is implementation of {@link Trigger} modules used in the {@link RuleEngine}s.
+ * This class is implementation of {@link Trigger} modules used in the rule engines.
  *
  * @author Yordan Mihaylov - Initial contribution
  */

@@ -82,7 +82,7 @@ public abstract class AbstractCommandProvider<@NonNull E> implements ServiceTrac
      * high performance at runtime of the system, when the Rule Engine asks for any particular object, instead of
      * waiting it for parsing every time.
      * <p>
-     * The Map has for keys UIDs of the objects and for values {@link Localizer}s of the objects.
+     * The Map has for keys UIDs of the objects and for values the objects.
      */
     protected final Map<String, E> providedObjectsHolder = new HashMap<>();
 
@@ -101,7 +101,6 @@ public AbstractCommandProvider(BundleContext context) {
     }
 
     /**
-     * This method is inherited from {@link AbstractPersistentProvider}.
      * Extends parent's functionality with closing the {@link Parser} service tracker.
      * Clears the {@link #parsers}, {@link #providedObjectsHolder}, {@link #providerPortfolio}
      */

@@ -71,7 +71,7 @@ public class CommandlineModuleTypeProvider extends AbstractCommandProvider<Modul
      * add any new functionality to the constructors of the providers. Only provides consistency by invoking the
      * parent's constructor.
      *
-     * @param context is the {@code BundleContext}, used for creating a tracker for {@link Parser} services.
+     * @param bundleContext is the {@code BundleContext}, used for creating a tracker for {@link Parser} services.
      * @param moduleTypeRegistry a ModuleTypeRegistry service
      */
     public CommandlineModuleTypeProvider(BundleContext bundleContext, ModuleTypeRegistry moduleTypeRegistry) {
@@ -152,8 +152,6 @@ public Collection<ModuleType> getModuleTypes(@Nullable Locale locale) {
     /**
      * This method is responsible for removing a set of objects loaded from a specified file or URL resource.
      *
-     * @param providerType specifies the provider responsible for removing the objects loaded from a specified file or
-     *            URL resource.
      * @param url is a specified file or URL resource.
      * @return the string <b>SUCCESS</b>.
      */

@@ -146,8 +146,6 @@ public Collection<RuleTemplate> getTemplates(@Nullable Locale locale) {
     /**
      * This method is responsible for removing a set of objects loaded from a specified file or URL resource.
      *
-     * @param providerType specifies the provider responsible for removing the objects loaded from a specified file or
-     *            URL resource.
      * @param url is a specified file or URL resource.
      * @return the string <b>SUCCESS</b>.
      */

@@ -323,7 +323,6 @@ static String printRuleStatus(String ruleUID, RuleStatus status) {
      * This method is responsible for printing the strings, representing the auxiliary automation objects.
      *
      * @param columnWidths represents the column widths of the table.
-     * @param width represents the table width.
      * @param prop is a property name of the property with value the collection of the auxiliary automation objects for
      *            printing.
      * @param list with the auxiliary automation objects for printing.
@@ -530,10 +529,10 @@ private static List<String> getConfigurationDescriptionRecords(
     }
 
     /**
-     * This method is responsible for printing the set of {@link Input}s or {@link Output}s or {@link Inputs}s.
+     * This method is responsible for printing the set of tags.
      *
-     * @param set is the set of {@link Input}s or {@link Output}s or {@link Inputs}s for printing.
-     * @return a formated string, representing the set of {@link Input}s or {@link Output}s or {@link Input}s.
+     * @param tags is the set of tags for printing.
+     * @return a formatted string, representing the set of tags.
      */
     private static String getTagsRecord(Set<String> tags) {
         if (tags == null || tags.isEmpty()) {

@@ -65,8 +65,7 @@ public class CompositeModuleHandlerFactory extends BaseModuleHandlerFactory impl
     /**
      * The constructor of system handler factory for composite module types.
      *
-     * @param context is a bundle context
-     * @param mtManager is a module type manager
+     * @param mtRegistry is a module type registry
      * @param re is a rule engine
      */
     public CompositeModuleHandlerFactory(ModuleTypeRegistry mtRegistry, RuleEngineImpl re) {

@@ -114,10 +114,10 @@ public ScheduledExecutorService getScheduler() {
 
     /**
      * The {@link CompositeTriggerHandler} sets itself as callback to the child triggers and store the callback to the
-     * rule engine. In this way the trigger of composite type will be notified always when some of the child triggers
+     * rule engine. In this way the trigger of composite type will always be notified when some of the child triggers
      * are triggered and has an opportunity to set the outputs of parent trigger to the rule context.
      *
-     * @see org.openhab.core.automation.handler.TriggerHandler#setTriggerHandlerCallback(org.openhab.core.automation.handler.TriggerHandlerCallback)
+     * @see org.openhab.core.automation.handler.TriggerHandler#setCallback(ModuleHandlerCallback)
      */
     @Override
     public void setCallback(@Nullable ModuleHandlerCallback callback) {

@@ -50,9 +50,6 @@ public class ItemCommandActionHandler extends BaseActionModuleHandler {
 
     /**
      * constructs a new ItemCommandActionHandler
-     *
-     * @param module
-     * @param moduleTypes
      */
     public ItemCommandActionHandler(Action module, EventPublisher eventPublisher, ItemRegistry itemRegistry) {
         super(module);

@@ -162,12 +162,6 @@ protected void deactivate() {
         }
     }
 
-    /**
-     * This method is used to initialize field {@link #queue}, when the instance of
-     * {@link AutomationResourceBundlesEventQueue} is created.
-     *
-     * @param queue provides an access to the queue for processing bundles.
-     */
     protected AutomationResourceBundlesEventQueue getQueue() {
         return queue;
     }
@@ -399,7 +393,6 @@ protected List<ConfigDescriptionParameter> getLocalizedConfigurationDescription(
      * This method is called from {@link #processAutomationProvider(Bundle)} to process the loading of the provided
      * objects.
      *
-     * @param vendor is a holder of information about the bundle providing data for import.
      * @param parser the {@link Parser} which is responsible for parsing of a particular format in which the provided
      *            objects are presented
      * @param url the resource which is used for loading the objects.

@@ -43,9 +43,7 @@ static Set<Entry<Bundle, List<Bundle>>> getMapping() {
     /**
      * This method is used to get the host bundles of the parameter which is a fragment bundle.
      *
-     * @param pkgAdmin
-     *
-     * @param bundle an OSGi fragment bundle.
+     * @param fragment an OSGi fragment bundle.
      * @return a list with the hosts of the <code>fragment</code> parameter.
      */
     static List<Bundle> returnHostBundles(Bundle fragment) {

@@ -61,8 +61,6 @@ public class ModuleTypeResourceBundleProvider extends AbstractResourceBundleProv
     /**
      * This constructor is responsible for initializing the path to resources and tracking the
      * {@link ModuleTypeRegistry}.
-     *
-     * @param context is the {@code BundleContext}, used for creating a tracker for {@link Parser} services.
      */
     @Activate
     public ModuleTypeResourceBundleProvider(final @Reference ModuleTypeI18nService moduleTypeI18nService) {
@@ -138,7 +136,7 @@ protected String getUID(ModuleType parsedObject) {
     /**
      * This method is used to localize the {@link ModuleType}s.
      *
-     * @param element is the {@link ModuleType} that must be localized.
+     * @param defModuleType is the {@link ModuleType} that must be localized.
      * @param locale represents a specific geographical, political, or cultural region.
      * @return the localized {@link ModuleType}.
      */

@@ -52,8 +52,6 @@ public class RuleResourceBundleImporter extends AbstractResourceBundleProvider<R
     /**
      * This constructor is responsible for initializing the path to resources and tracking the managing service of the
      * {@link Rule}s.
-     *
-     * @param registry the managing service of the {@link Rule}s.
      */
     public RuleResourceBundleImporter() {
         super(ROOT_DIRECTORY + "/rules/");

@@ -28,7 +28,6 @@
 import org.openhab.core.automation.parser.Parser;
 import org.openhab.core.automation.template.RuleTemplate;
 import org.openhab.core.automation.template.RuleTemplateProvider;
-import org.openhab.core.automation.template.Template;
 import org.openhab.core.automation.template.TemplateProvider;
 import org.openhab.core.automation.type.ModuleType;
 import org.openhab.core.common.registry.Provider;
@@ -46,15 +45,15 @@
 import org.osgi.service.component.annotations.ReferencePolicy;
 
 /**
- * This class is implementation of {@link TemplateProvider}. It serves for providing {@link RuleTemplates}s by loading
+ * This class is implementation of {@link TemplateProvider}. It serves for providing {@link RuleTemplate}s by loading
  * bundle resources. It extends functionality of {@link AbstractResourceBundleProvider} by specifying:
  * <ul>
- * <li>the path to resources, corresponding to the {@link RuleTemplates}s - root directory
+ * <li>the path to resources, corresponding to the {@link RuleTemplate}s - root directory
  * {@link AbstractResourceBundleProvider#ROOT_DIRECTORY} with sub-directory "templates".
- * <li>type of the {@link Parser}s, corresponding to the {@link RuleTemplates}s - {@link Parser#PARSER_TEMPLATE}
- * <li>specific functionality for loading the {@link RuleTemplates}s
+ * <li>type of the {@link Parser}s, corresponding to the {@link RuleTemplate}s - {@link Parser#PARSER_TEMPLATE}
+ * <li>specific functionality for loading the {@link RuleTemplate}s
  * <li>tracking the managing service of the {@link ModuleType}s.
- * <li>tracking the managing of the {@link RuleTemplates}s.
+ * <li>tracking the managing of the {@link RuleTemplate}s.
  * </ul>
  *
  * @author Ana Dimova - Initial contribution
@@ -72,9 +71,7 @@ public class TemplateResourceBundleProvider extends AbstractResourceBundleProvid
 
     /**
      * This constructor is responsible for initializing the path to resources and tracking the managing service of the
-     * {@link ModuleType}s and the managing service of the {@link RuleTemplates}s.
-     *
-     * @param context is the {@code BundleContext}, used for creating a tracker for {@link Parser} services.
+     * {@link ModuleType}s and the managing service of the {@link RuleTemplate}s.
      */
     @Activate
     public TemplateResourceBundleProvider(final @Reference ConfigI18nLocalizationService configI18nService,
@@ -151,11 +148,11 @@ public Collection<RuleTemplate> getTemplates(@Nullable Locale locale) {
     }
 
     /**
-     * This method is used to localize the {@link Template}s.
+     * This method is used to localize the {@link RuleTemplate}s.
      *
-     * @param element is the {@link Template} that must be localized.
+     * @param defTemplate is the {@link RuleTemplate} that must be localized.
      * @param locale represents a specific geographical, political, or cultural region.
-     * @return the localized {@link Template}.
+     * @return the localized {@link RuleTemplate}.
      */
     private @Nullable RuleTemplate getPerLocale(@Nullable RuleTemplate defTemplate, @Nullable Locale locale) {
         if (locale == null || defTemplate == null) {