[REST] New API to create and parse DSL file formats

Related to #4585

POST /file-format/items/parse to parse items from file format
POST /file-format/items/create to create items in file format
POST /file-format/things/parse to parse things from file format
POST /file-format/things/create to create things in file format

Signed-off-by: Laurent Garnier <[email protected]>

Author: lolodomo

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

@@ -28,6 +28,7 @@
  *
  * @author Kai Kreuzer - Initial contribution
  * @author Laurent Garnier - Added method generateSyntaxFromModel
+ * @author Laurent Garnier - Added methods addStandaloneModel and removeStandaloneModel
  */
 @NonNullByDefault
 public interface ModelRepository {
@@ -95,13 +96,33 @@ public interface ModelRepository {
      */
     void removeModelRepositoryChangeListener(ModelRepositoryChangeListener listener);
 
+    /**
+     * Adds a standalone model to the repository
+     * A standalone model will be loaded without triggering any listener.
+     *
+     * @param modelType the model type
+     * @param inputStream an input stream with the model's content
+     * @param errors the string builder used to fill the errors
+     * @param warnings the string builder used to fill the warnings
+     * @return the created model name if it was successfully processed, null otherwise
+     */
+    @Nullable
+    String addStandaloneModel(String modelType, InputStream inputStream, StringBuilder errors, StringBuilder warnings);
+
+    /**
+     * Removes a standalone model from the repository
+     *
+     * @param name the name of the model to remove
+     * @return true, if model was removed, false, if it did not exist
+     */
+    boolean removeStandaloneModel(String name);
+
     /**
      * Generate the syntax from a provided model content.
      *
      * @param out the output stream to write the generated syntax to
      * @param modelType the model type
      * @param modelContent the content of the model
-     * @return the corresponding syntax
      */
     void generateSyntaxFromModel(OutputStream out, String modelType, EObject modelContent);
 }

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,6 +51,7 @@
  * @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 methods addStandaloneModel and removeStandaloneModel
  */
 @Component(immediate = true)
 @NonNullByDefault
@@ -100,17 +100,37 @@ public ModelRepositoryImpl(final @Reference SafeEMF safeEmf) {
 
     @Override
     public boolean addOrRefreshModel(String name, final InputStream originalInputStream) {
+        return addOrRefreshModel(name, originalInputStream, null, null, false);
+    }
+
+    public boolean addOrRefreshModel(String name, final InputStream originalInputStream, @Nullable StringBuilder errors,
+            @Nullable StringBuilder warnings, boolean standalone) {
         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);
+            StringBuilder newErrors = new StringBuilder();
+            StringBuilder newWarnings = new StringBuilder();
+            boolean valid = validateModel(name, new ByteArrayInputStream(bytes), newErrors, newWarnings);
+            if (errors != null) {
+                errors.append(newErrors);
+            }
+            if (warnings != null) {
+                warnings.append(newWarnings);
+            }
+            if (!valid) {
+                if (!standalone) {
+                    logger.warn("Configuration model '{}' has errors, therefore ignoring it: {}", name,
+                            newErrors.toString());
+                }
                 removeModel(name);
                 return false;
             }
+            String message = newWarnings.toString();
+            if (!standalone && !message.isEmpty()) {
+                logger.info("Validation issues found in configuration model '{}', using it anyway:\n{}", name, message);
+            }
         } catch (IOException e) {
             logger.warn("Configuration model '{}' cannot be parsed correctly!", name, e);
             return false;
@@ -128,7 +148,9 @@ public boolean addOrRefreshModel(String name, final InputStream originalInputStr
                         resource = resourceSet.createResource(URI.createURI(name));
                         if (resource != null) {
                             resource.load(inputStream, resourceOptions);
-                            notifyListeners(name, EventType.ADDED);
+                            if (!standalone) {
+                                notifyListeners(name, EventType.ADDED);
+                            }
                             return true;
                         } else {
                             logger.warn("Ignoring file '{}' as we do not have a parser for it.", name);
@@ -139,7 +161,9 @@ public boolean addOrRefreshModel(String name, final InputStream originalInputStr
                 synchronized (resourceSet) {
                     resource.unload();
                     resource.load(inputStream, resourceOptions);
-                    notifyListeners(name, EventType.MODIFIED);
+                    if (!standalone) {
+                        notifyListeners(name, EventType.MODIFIED);
+                    }
                     return true;
                 }
             }
@@ -154,11 +178,17 @@ public boolean addOrRefreshModel(String name, final InputStream originalInputStr
 
     @Override
     public boolean removeModel(String name) {
+        return removeModel(name, false);
+    }
+
+    private boolean removeModel(String name, boolean standalone) {
         Resource resource = getResource(name);
         if (resource != null) {
             synchronized (resourceSet) {
                 // do not physically delete it, but remove it from the resource set
-                notifyListeners(name, EventType.REMOVED);
+                if (!standalone) {
+                    notifyListeners(name, EventType.REMOVED);
+                }
                 resourceSet.getResources().remove(resource);
                 return true;
             }
@@ -232,6 +262,18 @@ public void removeModelRepositoryChangeListener(ModelRepositoryChangeListener li
         listeners.remove(listener);
     }
 
+    @Override
+    public @Nullable String addStandaloneModel(String modelType, InputStream inputStream, StringBuilder errors,
+            StringBuilder warnings) {
+        String name = "tmp_syntax_%d.%s".formatted(++counter, modelType);
+        return addOrRefreshModel(name, inputStream, errors, warnings, true) ? name : null;
+    }
+
+    @Override
+    public boolean removeStandaloneModel(String name) {
+        return removeModel(name, true);
+    }
+
     @Override
     public void generateSyntaxFromModel(OutputStream out, String modelType, EObject modelContent) {
         String result = "";
@@ -269,40 +311,36 @@ 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 string builder used to fill the errors
+     * @param warnings the string builder 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, StringBuilder errors, StringBuilder 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));
         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.append(MessageFormat.format("[{0},{1}]: {2}\n", 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
                 try {
                     final org.eclipse.emf.common.util.Diagnostic diagnostic = safeEmf
                             .call(() -> Diagnostician.INSTANCE.validate(resource.getContents().getFirst()));
                     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));
+                        warnings.append(d.getMessage() + "\n");
                     }
                 } catch (NullPointerException e) {
                     // see https://github.com/eclipse/smarthome/issues/3335
@@ -312,7 +350,7 @@ public void generateSyntaxFromModel(OutputStream out, String modelType, EObject
         } finally {
             resourceSet.getResources().remove(resource);
         }
-        return null;
+        return true;
     }
 
     private void notifyListeners(String name, EventType type) {

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

@@ -15,6 +15,7 @@
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collection;
+import java.util.Collections;
 import java.util.HashMap;
 import java.util.LinkedHashMap;
 import java.util.List;
@@ -67,11 +68,13 @@
  *
  * @author Kai Kreuzer - Initial contribution
  * @author Thomas Eichstaedt-Engelen - Initial contribution
+ * @author Laurent Garnier - Add interface StandaloneItemProvider
  */
 @NonNullByDefault
-@Component(service = { ItemProvider.class, StateDescriptionFragmentProvider.class }, immediate = true)
-public class GenericItemProvider extends AbstractProvider<Item>
-        implements ModelRepositoryChangeListener, ItemProvider, StateDescriptionFragmentProvider {
+@Component(service = { ItemProvider.class, StandaloneItemProvider.class,
+        StateDescriptionFragmentProvider.class }, immediate = true)
+public class GenericItemProvider extends AbstractProvider<Item> implements ModelRepositoryChangeListener, ItemProvider,
+        StandaloneItemProvider, StateDescriptionFragmentProvider {
 
     private final Logger logger = LoggerFactory.getLogger(GenericItemProvider.class);
 
@@ -521,6 +524,14 @@ private Map<String, Item> toItemMap(@Nullable Collection<Item> items) {
         return null;
     }
 
+    @Override
+    public Collection<Item> getItemsFromStandaloneModel(String modelName) {
+        if (modelName.endsWith("items")) {
+            return getItemsFromModel(modelName);
+        }
+        return Collections.emptyList();
+    }
+
     @Override
     public @Nullable StateDescriptionFragment getStateDescriptionFragment(String itemName, @Nullable Locale locale) {
         return stateDescriptionFragments.get(itemName);

bundles/org.openhab.core.model.item/src/org/openhab/core/model/item/internal/GenericItemProvider.java

@@ -0,0 +1,37 @@
+/*
+ * 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.model.item.internal;
+
+import java.util.Collection;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.core.items.Item;
+
+/**
+ * {@link StandaloneItemProvider} is the interface to implement by an {@link Item} provider that is able
+ * to create a list of items from a model without impacting the item registry.
+ *
+ * @author Laurent Garnier - Initial contribution
+ */
+@NonNullByDefault
+public interface StandaloneItemProvider {
+
+    /**
+     * Parse the provided syntax and return the corresponding {@link Item} objects without impacting
+     * the item registry.
+     *
+     * @param modelName the model name
+     * @return the collection of corresponding {@link Item}
+     */
+    Collection<Item> getItemsFromStandaloneModel(String modelName);
+}

bundles/org.openhab.core.model.item/src/org/openhab/core/model/item/internal/StandaloneItemProvider.java

@@ -12,6 +12,7 @@
  */
 package org.openhab.core.model.item.internal.fileconverter;
 
+import java.io.ByteArrayInputStream;
 import java.io.OutputStream;
 import java.net.URI;
 import java.net.URISyntaxException;
@@ -35,7 +36,9 @@
 import org.openhab.core.items.Metadata;
 import org.openhab.core.items.fileconverter.AbstractItemFileGenerator;
 import org.openhab.core.items.fileconverter.ItemFileGenerator;
+import org.openhab.core.items.fileconverter.ItemFileParser;
 import org.openhab.core.model.core.ModelRepository;
+import org.openhab.core.model.item.internal.StandaloneItemProvider;
 import org.openhab.core.model.items.ItemModel;
 import org.openhab.core.model.items.ItemsFactory;
 import org.openhab.core.model.items.ModelBinding;
@@ -58,18 +61,21 @@
  * @author Laurent Garnier - Initial contribution
  */
 @NonNullByDefault
-@Component(immediate = true, service = ItemFileGenerator.class)
-public class DslItemFileConverter extends AbstractItemFileGenerator {
+@Component(immediate = true, service = { ItemFileGenerator.class, ItemFileParser.class })
+public class DslItemFileConverter extends AbstractItemFileGenerator implements ItemFileParser {
 
     private final Logger logger = LoggerFactory.getLogger(DslItemFileConverter.class);
 
     private final ModelRepository modelRepository;
+    private final StandaloneItemProvider standaloneItemProvider;
     private final ConfigDescriptionRegistry configDescriptionRegistry;
 
     @Activate
     public DslItemFileConverter(final @Reference ModelRepository modelRepository,
+            final @Reference StandaloneItemProvider standaloneItemProvider,
             final @Reference ConfigDescriptionRegistry configDescriptionRegistry) {
         this.modelRepository = modelRepository;
+        this.standaloneItemProvider = standaloneItemProvider;
         this.configDescriptionRegistry = configDescriptionRegistry;
     }
 
@@ -247,4 +253,24 @@ private List<ConfigParameter> getConfigurationParameters(Metadata metadata, bool
         }
         return parameters;
     }
+
+    @Override
+    public String getFileFormatParser() {
+        return "DSL";
+    }
+
+    @Override
+    public boolean parseFileFormat(String syntax, Collection<Item> items, Collection<Metadata> metadata,
+            StringBuilder errors, StringBuilder warnings) {
+        ByteArrayInputStream inputStream = new ByteArrayInputStream(syntax.getBytes());
+        String modelName = modelRepository.addStandaloneModel("items", inputStream, errors, warnings);
+        if (modelName != null) {
+            Collection<Item> newItems = standaloneItemProvider.getItemsFromStandaloneModel(modelName);
+            items.addAll(newItems);
+            // TODO retrieve metadata
+            modelRepository.removeStandaloneModel(modelName);
+            return true;
+        }
+        return false;
+    }
 }