[REST] New API for conversion between file formats

Related to #4585

This PR only supports management of things.
It supports DSL and YAML file formats.

A first new API (POST /file-format/create) allows to create a file format (DSL or YAML) from a JSON object.
A second new API (POST /file-format/parse) allows to parse a file format (DSL or YAML) to a JSON object.

These 2 APIs should help Main UI displaying DSL and YAML file formats for things.

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/fileformat/FileFormatDTO.java

@@ -0,0 +1,28 @@
+/*
+ * Copyright (c) 2010-2025 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.rest.core.fileformat;
+
+import java.util.List;
+
+import org.openhab.core.thing.dto.ThingDTO;
+
+/**
+ * This is a data transfer object to serialize the different components that can be contained
+ * in a file format (items, things, ...).
+ *
+ * @author Laurent Garnier - Initial contribution
+ */
+public class FileFormatDTO {
+
+    public List<ThingDTO> things;
+}

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

@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) 2010-2025 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.rest.core.fileformat;
+
+import java.util.List;
+
+/**
+ * This is a data transfer object to serialize the different components that can be contained
+ * in a file format (items, things, ...) including an optional list of warnings.
+ *
+ * @author Laurent Garnier - Initial contribution
+ */
+public class extendedFileFormatDTO extends FileFormatDTO {
+
+    public List<String> warnings;
+}

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

@@ -14,6 +14,7 @@
 
 import java.io.InputStream;
 import java.io.OutputStream;
+import java.util.List;
 import java.util.Set;
 
 import org.eclipse.emf.ecore.EObject;
@@ -28,6 +29,7 @@
  *
  * @author Kai Kreuzer - Initial contribution
  * @author Laurent Garnier - Added method generateSyntaxFromModel
+ * @author Laurent Garnier - Added method createTemporaryModel
  */
 @NonNullByDefault
 public interface ModelRepository {
@@ -95,6 +97,21 @@ public interface ModelRepository {
      */
     void removeModelRepositoryChangeListener(ModelRepositoryChangeListener listener);
 
+    /**
+     * Creates a temporary model in the repository
+     *
+     * A temporary model is not attached to a file on disk.
+     * A temporary model will be loaded without impacting any object registry.
+     *
+     * @param modelType the model type
+     * @param inputStream an input stream with the model's content
+     * @param errors the list to be used to fill the errors
+     * @param warnings the list to be used to fill the warnings
+     * @return the created model name if it was successfully processed, null otherwise
+     */
+    @Nullable
+    String createTemporaryModel(String modelType, InputStream inputStream, List<String> errors, List<String> warnings);
+
     /**
      * Generate the syntax from a provided model content.
      *

bundles/org.openhab.core.model.core/src/main/java/org/openhab/core/model/core/ModelRepository.java

@@ -20,7 +20,6 @@
 import java.text.MessageFormat;
 import java.util.ArrayList;
 import java.util.HashSet;
-import java.util.LinkedList;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
@@ -52,11 +51,14 @@
  * @author Oliver Libutzki - Added reloadAllModelsOfType method
  * @author Simon Kaufmann - added validation of models before loading them
  * @author Laurent Garnier - Added method generateSyntaxFromModel
+ * @author Laurent Garnier - Added method createTemporaryModel
  */
 @Component(immediate = true)
 @NonNullByDefault
 public class ModelRepositoryImpl implements ModelRepository {
 
+    private static final String PREFIX_TMP_MODEL = "tmp_";
+
     private final Logger logger = LoggerFactory.getLogger(ModelRepositoryImpl.class);
     private final ResourceSet resourceSet;
     private final Map<String, String> resourceOptions = Map.of(XtextResource.OPTION_ENCODING,
@@ -100,17 +102,37 @@ public ModelRepositoryImpl(final @Reference SafeEMF safeEmf) {
 
     @Override
     public boolean addOrRefreshModel(String name, final InputStream originalInputStream) {
+        return addOrRefreshModel(name, originalInputStream, null, null);
+    }
+
+    public boolean addOrRefreshModel(String name, final InputStream originalInputStream, @Nullable List<String> errors,
+            @Nullable List<String> warnings) {
         logger.info("Loading model '{}'", name);
         Resource resource = null;
         byte[] bytes;
         try (InputStream inputStream = originalInputStream) {
             bytes = inputStream.readAllBytes();
-            String validationResult = validateModel(name, new ByteArrayInputStream(bytes));
-            if (validationResult != null) {
-                logger.warn("Configuration model '{}' has errors, therefore ignoring it: {}", name, validationResult);
+            List<String> newErrors = new ArrayList<>();
+            List<String> newWarnings = new ArrayList<>();
+            boolean valid = validateModel(name, new ByteArrayInputStream(bytes), newErrors, newWarnings);
+            if (errors != null) {
+                errors.addAll(newErrors);
+            }
+            if (warnings != null) {
+                warnings.addAll(newWarnings);
+            }
+            if (!valid) {
+                if (!isTemporaryModel(name)) {
+                    logger.warn("Configuration model '{}' has errors, therefore ignoring it: {}", name,
+                            String.join("\n", newErrors));
+                }
                 removeModel(name);
                 return false;
             }
+            if (!isTemporaryModel(name) && !newWarnings.isEmpty()) {
+                logger.info("Validation issues found in configuration model '{}', using it anyway:\n{}", name,
+                        String.join("\n", newWarnings));
+            }
         } catch (IOException e) {
             logger.warn("Configuration model '{}' cannot be parsed correctly!", name, e);
             return false;
@@ -176,7 +198,7 @@ public Iterable<String> getAllModelNamesOfType(final String modelType) {
             return resourceListCopy.stream()
                     .filter(input -> input.getURI().lastSegment().contains(".") && input.isLoaded()
                             && modelType.equalsIgnoreCase(input.getURI().fileExtension())
-                            && !input.getURI().lastSegment().startsWith("tmp_"))
+                            && !isTemporaryModel(input.getURI().lastSegment()))
                     .map(from -> from.getURI().path()).toList();
         }
     }
@@ -189,7 +211,7 @@ public void reloadAllModelsOfType(final String modelType) {
             for (Resource resource : resourceListCopy) {
                 if (resource.getURI().lastSegment().contains(".") && resource.isLoaded()
                         && modelType.equalsIgnoreCase(resource.getURI().fileExtension())
-                        && !resource.getURI().lastSegment().startsWith("tmp_")) {
+                        && !isTemporaryModel(resource.getURI().lastSegment())) {
                     XtextResource xtextResource = (XtextResource) resource;
                     // It's not sufficient to discard the derived state.
                     // The quick & dirts solution is to reparse the whole resource.
@@ -211,7 +233,7 @@ public Set<String> removeAllModelsOfType(final String modelType) {
             for (Resource resource : resourceListCopy) {
                 if (resource.getURI().lastSegment().contains(".") && resource.isLoaded()
                         && modelType.equalsIgnoreCase(resource.getURI().fileExtension())
-                        && !resource.getURI().lastSegment().startsWith("tmp_")) {
+                        && !isTemporaryModel(resource.getURI().lastSegment())) {
                     logger.debug("Removing resource '{}'", resource.getURI().lastSegment());
                     ret.add(resource.getURI().lastSegment());
                     resourceSet.getResources().remove(resource);
@@ -232,10 +254,21 @@ public void removeModelRepositoryChangeListener(ModelRepositoryChangeListener li
         listeners.remove(listener);
     }
 
+    @Override
+    public @Nullable String createTemporaryModel(String modelType, InputStream inputStream, List<String> errors,
+            List<String> warnings) {
+        String name = "%smodel_%d.%s".formatted(PREFIX_TMP_MODEL, ++counter, modelType);
+        return addOrRefreshModel(name, inputStream, errors, warnings) ? name : null;
+    }
+
+    private boolean isTemporaryModel(String modelName) {
+        return modelName.startsWith(PREFIX_TMP_MODEL);
+    }
+
     @Override
     public void generateSyntaxFromModel(OutputStream out, String modelType, EObject modelContent) {
         synchronized (resourceSet) {
-            String name = "tmp_generated_syntax_%d.%s".formatted(++counter, modelType);
+            String name = "%sgenerated_syntax_%d.%s".formatted(PREFIX_TMP_MODEL, ++counter, modelType);
             Resource resource = resourceSet.createResource(URI.createURI(name));
             try {
                 resource.getContents().add(modelContent);
@@ -268,28 +301,28 @@ public void generateSyntaxFromModel(OutputStream out, String modelType, EObject
      * Validation will be done on a separate resource, in order to keep the original one intact in case its content
      * needs to be removed because of syntactical errors.
      *
-     * @param name
-     * @param inputStream
-     * @return error messages as a String if any syntactical error were found, <code>null</code> otherwise
+     * @param name the model name
+     * @param inputStream an input stream with the model's content
+     * @param errors the list to be used to fill the errors
+     * @param warnings the list to be used to fill the warnings
+     * @return false if any syntactical error were found, false otherwise
      * @throws IOException if there was an error with the given {@link InputStream}, loading the resource from there
      */
-    private @Nullable String validateModel(String name, InputStream inputStream) throws IOException {
+    private boolean validateModel(String name, InputStream inputStream, List<String> errors, List<String> warnings)
+            throws IOException {
         // use another resource for validation in order to keep the original one for emergency-removal in case of errors
-        Resource resource = resourceSet.createResource(URI.createURI("tmp_" + name));
+        Resource resource = resourceSet.createResource(URI.createURI(PREFIX_TMP_MODEL + name));
         try {
             resource.load(inputStream, resourceOptions);
-            StringBuilder criticalErrors = new StringBuilder();
-            List<String> warnings = new LinkedList<>();
 
             if (!resource.getContents().isEmpty()) {
                 // Check for syntactical errors
                 for (Diagnostic diagnostic : resource.getErrors()) {
-                    criticalErrors
-                            .append(MessageFormat.format("[{0},{1}]: {2}\n", Integer.toString(diagnostic.getLine()),
-                                    Integer.toString(diagnostic.getColumn()), diagnostic.getMessage()));
+                    errors.add(MessageFormat.format("[{0},{1}]: {2}", Integer.toString(diagnostic.getLine()),
+                            Integer.toString(diagnostic.getColumn()), diagnostic.getMessage()));
                 }
-                if (!criticalErrors.isEmpty()) {
-                    return criticalErrors.toString();
+                if (!resource.getErrors().isEmpty()) {
+                    return false;
                 }
 
                 // Check for validation errors, but log them only
@@ -299,10 +332,6 @@ public void generateSyntaxFromModel(OutputStream out, String modelType, EObject
                     for (org.eclipse.emf.common.util.Diagnostic d : diagnostic.getChildren()) {
                         warnings.add(d.getMessage());
                     }
-                    if (!warnings.isEmpty()) {
-                        logger.info("Validation issues found in configuration model '{}', using it anyway:\n{}", name,
-                                String.join("\n", warnings));
-                    }
                 } catch (NullPointerException e) {
                     // see https://github.com/eclipse/smarthome/issues/3335
                     logger.debug("Validation of '{}' skipped due to internal errors.", name);
@@ -311,12 +340,14 @@ public void generateSyntaxFromModel(OutputStream out, String modelType, EObject
         } finally {
             resourceSet.getResources().remove(resource);
         }
-        return null;
+        return true;
     }
 
     private void notifyListeners(String name, EventType type) {
-        for (ModelRepositoryChangeListener listener : listeners) {
-            listener.modelChanged(name, type);
+        if (!isTemporaryModel(name)) {
+            for (ModelRepositoryChangeListener listener : listeners) {
+                listener.modelChanged(name, type);
+            }
         }
     }
 }

bundles/org.openhab.core.model.core/src/main/java/org/openhab/core/model/core/internal/ModelRepositoryImpl.java

@@ -71,8 +71,9 @@ import org.slf4j.LoggerFactory
  *         factory cannot load a thing yet (bug 470368), 
  *         added delay until ThingTypes are fully loaded
  * @author Markus Rathgeb - Add locale provider support
+ * @author Laurent Garnier - Add method getThingsFromModel
  */
-@Component(immediate=true, service=ThingProvider)
+@Component(immediate=true, service=#[ ThingProvider, GenericThingProvider ])
 class GenericThingProvider extends AbstractProviderLazyNullness<Thing> implements ThingProvider, ModelRepositoryChangeListener, ReadyService.ReadyTracker {
 
     static final String XML_THING_TYPE = "openhab.xmlThingTypes";
@@ -122,25 +123,7 @@ class GenericThingProvider extends AbstractProviderLazyNullness<Thing> implement
                 return
             }
             flattenModelThings(model.things).map [
-                // Get the ThingHandlerFactories
-                val ThingUID thingUID = constructThingUID
-                if (thingUID === null) {
-                    // ignore the Thing because its definition is broken
-                    return null
-                }
-                val thingTypeUID = constructThingTypeUID(thingUID)
-                if (thingTypeUID === null) {
-                    // ignore the Thing because its definition is broken
-                    return null
-                }
-                val factory = thingHandlerFactories.findFirst [
-                    supportsThingType(thingTypeUID)
-                ]
-                if (factory === null && modelLoaded) {
-                    logger.info("No ThingHandlerFactory found for thing {} (thing-type is {}). Deferring initialization.",
-                        thingUID, thingTypeUID)
-                }
-                return factory
+                return getThingHandlerFactory
             ]?.filter [
                 // Drop it if there is no ThingHandlerFactory yet which can handle it
                 it !== null
@@ -151,6 +134,27 @@ class GenericThingProvider extends AbstractProviderLazyNullness<Thing> implement
         }
     }
 
+    def private ThingHandlerFactory getThingHandlerFactory(ModelThing modelThing) {
+        val ThingUID thingUID = constructThingUID(modelThing)
+        if (thingUID === null) {
+            // ignore the Thing because its definition is broken
+            return null
+        }
+        val thingTypeUID = constructThingTypeUID(modelThing, thingUID)
+        if (thingTypeUID === null) {
+            // ignore the Thing because its definition is broken
+            return null
+        }
+        val factory = thingHandlerFactories.findFirst [
+              supportsThingType(thingTypeUID)
+        ]
+        if (factory == null && modelLoaded) {
+            logger.info("No ThingHandlerFactory found for thing {} (thing-type is {}). Deferring initialization.",
+                thingUID, thingTypeUID)
+        }
+        return factory
+    }
+
     def private ThingUID constructThingUID(ModelThing modelThing) {
         if (modelThing.id !== null) {
             return new ThingUID(modelThing.id)
@@ -487,6 +491,23 @@ class GenericThingProvider extends AbstractProviderLazyNullness<Thing> implement
         }
     }
 
+    def public List<Thing> getThingsFromModel(String modelName) {
+        val things = newArrayList()
+        if (modelRepository !== null && modelName.endsWith("things")) {
+            logger.debug("Read things from model '{}'", modelName);
+            val model = modelRepository.getModel(modelName) as ThingModel
+            if (model !== null) {
+                flattenModelThings(model.things).forEach [
+                    val factory = getThingHandlerFactory
+                    if (factory !== null && loadedXmlThingTypes.contains(factory.bundleName)) {
+                        createThing(things, factory)
+                    }
+                ]
+            }
+        }
+        return things
+    }
+
     def private Set<ThingUID> getAllThingUIDs(ThingModel model) {
         return getAllThingUIDs(model.things, null)
     }