YAML configuration: add support for things (openhab#4691)

Related to openhab#3666

Signed-off-by: Laurent Garnier <lg.hc@free.fr>

Author: lolodomo

bundles/org.openhab.core.io.rest.core/src/main/java/org/openhab/core/io/rest/core/internal/fileformat/FileFormatResource.java

@@ -94,6 +94,7 @@
  * This resource is registered with the Jersey servlet.
  *
  * @author Laurent Garnier - Initial contribution
+ * @author Laurent Garnier - Add YAML output for things
  */
 @Component
 @JaxrsResource
@@ -108,6 +109,15 @@ public class FileFormatResource implements RESTResource {
     /** The URI path to this resource */
     public static final String PATH_FILE_FORMAT = "file-format";
 
+    private static final String DSL_THINGS_EXAMPLE = "Bridge binding:typeBridge:idBridge \"Label brigde\" @ \"Location bridge\" [stringParam=\"my value\"] {" //
+            + "\n    Thing type id \"Label thing\" @ \"Location thing\" [booleanParam=true, decimalParam=2.5]\n}";
+    private static final String DSL_THING_EXAMPLE = "Thing binding:type:idBridge:id \"Label thing\" @ \"Location thing\" (binding:typeBridge:idBridge) [stringParam=\"my value\", booleanParam=true, decimalParam=2.5]";
+    private static final String YAML_THINGS_EXAMPLE = "version: 2\nthings:\n" //
+            + "  binding:typeBridge:idBridge:\n    isBridge: true\n    label: Label bridge\n    location: Location bridge\n    config:\n      stringParam: my value\n"
+            + "  binding:type:idBridge:id:\n    bridge: binding:typeBridge:idBridge\n    label: Label thing\n    location: Location thing\n    config:\n      booleanParam: true\n      decimalParam: 2.5";
+    private static final String YAML_THING_EXAMPLE = "version: 2\nthings:\n" //
+            + "  binding:type:idBridge:id:\n    bridge: binding:typeBridge:idBridge\n    label: Label thing\n    location: Location thing\n    config:\n      stringParam: my value\n      booleanParam: true\n      decimalParam: 2.5";
+
     private final Logger logger = LoggerFactory.getLogger(FileFormatResource.class);
 
     private final ItemRegistry itemRegistry;
@@ -216,16 +226,28 @@ public Response createFileFormatForItem(final @Context HttpHeaders httpHeaders,
     @GET
     @RolesAllowed({ Role.ADMIN })
     @Path("/things")
-    @Produces("text/vnd.openhab.dsl.thing")
+    @Produces({ "text/vnd.openhab.dsl.thing", "application/yaml" })
     @Operation(operationId = "createFileFormatForAllThings", summary = "Create file format for all existing things in registry.", security = {
             @SecurityRequirement(name = "oauth2", scopes = { "admin" }) }, responses = {
-                    @ApiResponse(responseCode = "200", description = "OK", content = @Content(mediaType = "text/vnd.openhab.dsl.thing", schema = @Schema(example = "Bridge binding:typeBridge:idBridge \"Label\" @ \"Location\" [stringParam=\"my value\"] {\n    Thing type id \"Label\" @ \"Location\" [booleanParam=true, decimalParam=2.5]\n}"))),
+                    @ApiResponse(responseCode = "200", description = "OK", content = {
+                            @Content(mediaType = "text/vnd.openhab.dsl.thing", schema = @Schema(example = DSL_THINGS_EXAMPLE)),
+                            @Content(mediaType = "application/yaml", schema = @Schema(example = YAML_THINGS_EXAMPLE)) }),
                     @ApiResponse(responseCode = "415", description = "Unsupported media type.") })
     public Response createFileFormatForAllThings(final @Context HttpHeaders httpHeaders,
             @DefaultValue("true") @QueryParam("hideDefaultParameters") @Parameter(description = "hide the configuration parameters having the default value") boolean hideDefaultParameters) {
         String acceptHeader = httpHeaders.getHeaderString(HttpHeaders.ACCEPT);
-        String format = "text/vnd.openhab.dsl.thing".equals(acceptHeader) ? "DSL" : null;
-        ThingFileGenerator generator = format == null ? null : thingFileGenerators.get(format);
+        ThingFileGenerator generator;
+        switch (acceptHeader) {
+            case "text/vnd.openhab.dsl.thing":
+                generator = thingFileGenerators.get("DSL");
+                break;
+            case "application/yaml":
+                generator = thingFileGenerators.get("YAML");
+                break;
+            default:
+                generator = null;
+                break;
+        }
         if (generator == null) {
             return Response.status(Response.Status.UNSUPPORTED_MEDIA_TYPE)
                     .entity("Unsupported media type '" + acceptHeader + "'!").build();
@@ -238,18 +260,30 @@ public Response createFileFormatForAllThings(final @Context HttpHeaders httpHead
     @GET
     @RolesAllowed({ Role.ADMIN })
     @Path("/things/{thingUID}")
-    @Produces("text/vnd.openhab.dsl.thing")
+    @Produces({ "text/vnd.openhab.dsl.thing", "application/yaml" })
     @Operation(operationId = "createFileFormatForThing", summary = "Create file format for an existing thing in things or discovery registry.", security = {
             @SecurityRequirement(name = "oauth2", scopes = { "admin" }) }, responses = {
-                    @ApiResponse(responseCode = "200", description = "OK", content = @Content(mediaType = "text/vnd.openhab.dsl.thing", schema = @Schema(example = "Thing binding:type:idBridge:id \"Label\" @ \"Location\" (binding:typeBridge:idBridge) [stringParam=\"my value\", booleanParam=true, decimalParam=2.5]"))),
+                    @ApiResponse(responseCode = "200", description = "OK", content = {
+                            @Content(mediaType = "text/vnd.openhab.dsl.thing", schema = @Schema(example = DSL_THING_EXAMPLE)),
+                            @Content(mediaType = "application/yaml", schema = @Schema(example = YAML_THING_EXAMPLE)) }),
                     @ApiResponse(responseCode = "404", description = "Thing not found in things or discovery registry or thing type not found."),
                     @ApiResponse(responseCode = "415", description = "Unsupported media type.") })
     public Response createFileFormatForThing(final @Context HttpHeaders httpHeaders,
             @DefaultValue("true") @QueryParam("hideDefaultParameters") @Parameter(description = "hide the configuration parameters having the default value") boolean hideDefaultParameters,
             @PathParam("thingUID") @Parameter(description = "thingUID") String thingUID) {
         String acceptHeader = httpHeaders.getHeaderString(HttpHeaders.ACCEPT);
-        String format = "text/vnd.openhab.dsl.thing".equals(acceptHeader) ? "DSL" : null;
-        ThingFileGenerator generator = format == null ? null : thingFileGenerators.get(format);
+        ThingFileGenerator generator;
+        switch (acceptHeader) {
+            case "text/vnd.openhab.dsl.thing":
+                generator = thingFileGenerators.get("DSL");
+                break;
+            case "application/yaml":
+                generator = thingFileGenerators.get("YAML");
+                break;
+            default:
+                generator = null;
+                break;
+        }
         if (generator == null) {
             return Response.status(Response.Status.UNSUPPORTED_MEDIA_TYPE)
                     .entity("Unsupported media type '" + acceptHeader + "'!").build();

bundles/org.openhab.core.model.yaml/pom.xml

@@ -25,5 +25,10 @@
       <artifactId>org.openhab.core.semantics</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.core.bundles</groupId>
+      <artifactId>org.openhab.core.thing</artifactId>
+      <version>${project.version}</version>
+    </dependency>
   </dependencies>
 </project>

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

@@ -12,7 +12,10 @@
  */
 package org.openhab.core.model.yaml;
 
+import java.util.List;
+
 import org.eclipse.jdt.annotation.NonNull;
+import org.eclipse.jdt.annotation.Nullable;
 import org.openhab.core.model.yaml.internal.YamlModelRepositoryImpl;
 
 /**
@@ -30,6 +33,7 @@
  * @author Laurent Garnier - Initial contribution
  * @author Jan N. Klug - Refactoring and improvements to JavaDoc
  * @author Laurent Garnier - Added methods setId and cloneWithoutId
+ * @author Laurent Garnier - Added parameters to method isValid
  */
 public interface YamlElement {
 
@@ -74,7 +78,10 @@ public interface YamlElement {
      * <li>MAY perform additional checks</li>
      * </ul>
      *
+     * @param errors a list of error messages to fill with fatal invalid controls; can be null to ignore messages
+     * @param warnings a list of warning messages to fill with non-fatal invalid controls; can be null to ignore
+     *            messages
      * @return {@code true} if all the checks are completed successfully
      */
-    boolean isValid();
+    boolean isValid(@Nullable List<@NonNull String> errors, @Nullable List<@NonNull String> warnings);
 }

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

@@ -12,12 +12,16 @@
  */
 package org.openhab.core.model.yaml;
 
+import java.io.OutputStream;
+import java.util.List;
+
 import org.eclipse.jdt.annotation.NonNullByDefault;
 
 /**
  * The {@link YamlModelRepository} defines methods to update elements in a YAML model.
  *
  * @author Jan N. Klug - Initial contribution
+ * @author Laurent Garnier - Added methods refreshModelElements and generateSyntaxFromElements
  */
 @NonNullByDefault
 public interface YamlModelRepository {
@@ -26,4 +30,20 @@ public interface YamlModelRepository {
     void removeElementFromModel(String modelName, YamlElement element);
 
     void updateElementInModel(String modelName, YamlElement element);
+
+    /**
+     * Triggers the refresh of a certain type of elements in a given model.
+     *
+     * @param modelName the model name
+     * @param elementName the type of elements to refresh
+     */
+    void refreshModelElements(String modelName, String elementName);
+
+    /**
+     * Generate the YAML syntax from a provided list of elements.
+     *
+     * @param out the output stream to write the generated syntax to
+     * @param elements the list of elements to includ
+     */
+    void generateSyntaxFromElements(OutputStream out, List<YamlElement> elements);
 }