Improve YAML model repository (#4024)

Signed-off-by: Jan N. Klug <github@klug.nrw>

bundles/org.openhab.core.model.yaml/src/main/java/org/openhab/core/model/yaml/YamlElement.java

@@ -12,28 +12,54 @@
  */
 package org.openhab.core.model.yaml;
 
-import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.NonNull;
+import org.openhab.core.model.yaml.internal.YamlModelRepositoryImpl;
 
 /**
- * The {@link YamlElement} interface offers an identifier and a check validity method
- * to any element defined in a YAML configuration file.
+ * The {@link YamlElement} interface must be implemented by any classes that need to be handled by the
+ * {@link YamlModelRepositoryImpl}.
+ * <p />
+ * Implementations
+ * <ul>
+ * <li>MUST have a default constructor to allow deserialization with Jackson</li>
+ * <li>MUST provide {@code equals(Object other)} and {@code hashcode()} methods</li>
+ * <li>MUST be annotated with {@link YamlElementName} containing the element name</li>
+ * <li>SHOULD implement a proper {@code toString()} method</li>
+ * </ul>
  *
  * @author Laurent Garnier - Initial contribution
+ * @author Jan N. Klug - Refactoring and improvements to JavaDoc
  */
-@NonNullByDefault
 public interface YamlElement {
 
     /**
-     * Get the identifier of the YAML element
+     * Get the identifier of this element.
+     * <p />
+     * <p />
+     * Identifiers
+     * <ul>
+     * <li>MUST be non-null</li>
+     * <li>MUST be unique within a model</li>
+     * <li>SHOULD be unique across all models</li>
+     * </ul>
      *
      * @return the identifier as a string
      */
+    @NonNull
     String getId();
 
     /**
-     * Check that the YAML element is valid
+     * Check if this element is valid and should be included in the model.
+     * <p />
+     * <p />
+     * Implementations
+     * <ul>
+     * <li>MUST check that at least {link #getId()} returns a non-null value</li>
+     * <li>SHOULD log the reason of failed checks at WARN level</li>
+     * <li>MAY perform additional checks</li>
+     * </ul>
      *
-     * @return true if all the checks are OK
+     * @return {@code true} if all the checks are completed successfully
      */
     boolean isValid();
 }

bundles/org.openhab.core.model.yaml/src/main/java/org/openhab/core/model/yaml/YamlElementName.java

@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) 2010-2024 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.model.yaml;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+/**
+ * The {@link YamlElementName} is a required annotation for the inheritors of {@link YamlElement}. It specifies the root
+ * element name in a YAML model that is described by the respective class. Code review MUST ensure that element names
+ * are unique.
+ *
+ * @author Jan N. Klug - Initial contribution
+ */
+@Retention(RetentionPolicy.RUNTIME)
+public @interface YamlElementName {
+    String value();
+}

bundles/org.openhab.core.model.yaml/src/main/java/org/openhab/core/model/yaml/YamlModelListener.java

@@ -19,55 +19,45 @@
 /**
  * The {@link YamlModelListener} interface is responsible for managing a particular model type
  * with data processed from YAML configuration files.
+ * <p />
+ * Implementors are notified whenever a YAML model changed that contains elements of the given type. They MUST declare
+ * at least {@link YamlModelListener} as service to automatically register them with the repository.
  *
  * @author Laurent Garnier - Initial contribution
  */
 @NonNullByDefault
 public interface YamlModelListener<T extends YamlElement> {
 
     /**
-     * Method called by the model repository when elements from a model are added.
+     * Method called by the model repository when elements from a model are added. Only added elements are contained in
+     * the collection. In case the listener is added after a model was read, this method is also called with all
+     * elements from that model.
      *
      * @param modelName the name of the model
      * @param elements the collection of added elements
      */
-    void addedModel(String modelName, Collection<? extends YamlElement> elements);
+    void addedModel(String modelName, Collection<T> elements);
 
     /**
-     * Method called by the model repository when elements from a model are updated.
+     * Method called by the model repository when elements from a model are updated. Only changed elements are contained
+     * in the collection.
      *
      * @param modelName the name of the model
      * @param elements the collection of updated elements
      */
-    void updatedModel(String modelName, Collection<? extends YamlElement> elements);
+    void updatedModel(String modelName, Collection<T> elements);
 
     /**
      * Method called by the model repository when elements from a model are removed.
      *
      * @param modelName the name of the model
      * @param elements the collection of removed elements
      */
-    void removedModel(String modelName, Collection<? extends YamlElement> elements);
+    void removedModel(String modelName, Collection<T> elements);
 
     /**
-     * Get the root name of this model type which is also the name of the root folder
-     * containing the user files for this model type.
-     *
-     * A path is unexpected. What is expected is for example "items" or "things".
-     *
-     * @return the model root name
-     */
-    String getRootName();
-
-    /**
-     * Get the DTO class to be used for a file providing objects for this model type.
-     *
-     * @return the DTO file class
-     */
-    Class<? extends AbstractYamlFile> getFileClass();
-
-    /**
-     * Get the DTO class to be used for each object of this model type.
+     * Get the DTO class to be used for each object of this model type. The DTO class MUST implement {@link YamlElement}
+     * and fulfill all requirements defined for the interface.
      *
      * @return the DTO element class
      */

bundles/org.openhab.core.model.yaml/src/main/java/org/openhab/core/model/yaml/YamlModelRepository.java

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) 2010-2024 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.model.yaml;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * The {@link YamlModelRepository} defines methods to update elements in a YAML model.
+ *
+ * @author Jan N. Klug - Initial contribution
+ */
+@NonNullByDefault
+public interface YamlModelRepository {
+    void addElementToModel(String modelName, YamlElement element);
+
+    void removeElementFromModel(String modelName, YamlElement element);
+
+    void updateElementInModel(String modelName, YamlElement element);
+}