[REST] New REST APIs to generate DSL syntax for items and things

Related to openhab#4509

Added REST APIs:
- GET /inbox/{thingUID}/filesyntax to generate file syntax for the thing associated to the discovery result
- GET /items/filesyntax to generate file syntax for all items
- GET /items/{itemname}/filesyntax to generate file syntax for an item
- GET /things/filesyntax to generate file syntax for all things
- GET /things/{thingUID}/filesyntax to generate file syntax for a thing

All these APIs have a parameter named "format" to request a particular output format. Of course, a syntax generator should be available for this format.
Only "DSL" format is provided by this PR as this is currently our unique supported format for items and things in config files.
So this parameter is set to "DSL" by default.
In the future, new formats could be added and they will be automatically supported by these APIs.

The API GET /things/filesyntax has another parameter named "preferPresentationAsTree" allowing to choose between a flat display or a display as a tree.
Its default value is true for a display of things as tree.

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/discovery/InboxResource.java

@@ -12,6 +12,13 @@
  */
 package org.openhab.core.io.rest.core.internal.discovery;
 
+import static org.openhab.core.config.discovery.inbox.InboxPredicates.forThingUID;
+
+import java.net.URI;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
 import java.util.stream.Stream;
 
 import javax.annotation.security.RolesAllowed;
@@ -33,6 +40,11 @@
 import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.eclipse.jdt.annotation.Nullable;
 import org.openhab.core.auth.Role;
+import org.openhab.core.config.core.ConfigDescription;
+import org.openhab.core.config.core.ConfigDescriptionParameter;
+import org.openhab.core.config.core.ConfigDescriptionRegistry;
+import org.openhab.core.config.core.ConfigUtil;
+import org.openhab.core.config.core.Configuration;
 import org.openhab.core.config.discovery.DiscoveryResult;
 import org.openhab.core.config.discovery.DiscoveryResultFlag;
 import org.openhab.core.config.discovery.dto.DiscoveryResultDTO;
@@ -44,9 +56,15 @@
 import org.openhab.core.io.rest.Stream2JSONInputStream;
 import org.openhab.core.thing.Thing;
 import org.openhab.core.thing.ThingUID;
+import org.openhab.core.thing.binding.ThingFactory;
+import org.openhab.core.thing.syntaxgenerator.ThingSyntaxGenerator;
+import org.openhab.core.thing.type.ThingType;
+import org.openhab.core.thing.type.ThingTypeRegistry;
 import org.osgi.service.component.annotations.Activate;
 import org.osgi.service.component.annotations.Component;
 import org.osgi.service.component.annotations.Reference;
+import org.osgi.service.component.annotations.ReferenceCardinality;
+import org.osgi.service.component.annotations.ReferencePolicy;
 import org.osgi.service.jaxrs.whiteboard.JaxrsWhiteboardConstants;
 import org.osgi.service.jaxrs.whiteboard.propertytypes.JSONRequired;
 import org.osgi.service.jaxrs.whiteboard.propertytypes.JaxrsApplicationSelect;
@@ -78,6 +96,7 @@
  * @author Markus Rathgeb - Migrated to JAX-RS Whiteboard Specification
  * @author Wouter Born - Migrated to OpenAPI annotations
  * @author Laurent Garnier - Added optional parameter newThingId to approve API
+ * @author Laurent Garnier - Added API to generate file syntax
  */
 @Component(service = { RESTResource.class, InboxResource.class })
 @JaxrsResource
@@ -96,10 +115,25 @@ public class InboxResource implements RESTResource {
     public static final String PATH_INBOX = "inbox";
 
     private final Inbox inbox;
+    private final ThingTypeRegistry thingTypeRegistry;
+    private final ConfigDescriptionRegistry configDescRegistry;
+    private final Map<String, ThingSyntaxGenerator> thingSyntaxGenerators = new ConcurrentHashMap<>();
 
     @Activate
-    public InboxResource(final @Reference Inbox inbox) {
+    public InboxResource(final @Reference Inbox inbox, final @Reference ThingTypeRegistry thingTypeRegistry,
+            final @Reference ConfigDescriptionRegistry configDescRegistry) {
         this.inbox = inbox;
+        this.thingTypeRegistry = thingTypeRegistry;
+        this.configDescRegistry = configDescRegistry;
+    }
+
+    @Reference(policy = ReferencePolicy.DYNAMIC, cardinality = ReferenceCardinality.MULTIPLE)
+    protected void addThingSyntaxGenerator(ThingSyntaxGenerator thingSyntaxGenerator) {
+        thingSyntaxGenerators.put(thingSyntaxGenerator.getFormat(), thingSyntaxGenerator);
+    }
+
+    protected void removeThingSyntaxGenerator(ThingSyntaxGenerator thingSyntaxGenerator) {
+        thingSyntaxGenerators.remove(thingSyntaxGenerator.getFormat());
     }
 
     @POST
@@ -182,4 +216,60 @@ public Response unignore(@PathParam("thingUID") @Parameter(description = "thingU
         inbox.setFlag(new ThingUID(thingUID), DiscoveryResultFlag.NEW);
         return Response.ok(null, MediaType.TEXT_PLAIN).build();
     }
+
+    @GET
+    @Path("/{thingUID}/filesyntax")
+    @Produces(MediaType.TEXT_PLAIN)
+    @Operation(operationId = "generateSyntaxForDiscoveryResult", summary = "Generate file syntax for the thing associated to the discovery result.", responses = {
+            @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = String.class))),
+            @ApiResponse(responseCode = "400", description = "Unsupported syntax format."),
+            @ApiResponse(responseCode = "404", description = "Discovery result not found in the inbox or thing type not found.") })
+    public Response generateSyntaxForDiscoveryResult(
+            @HeaderParam(HttpHeaders.ACCEPT_LANGUAGE) @Parameter(description = "language") @Nullable String language,
+            @PathParam("thingUID") @Parameter(description = "thingUID") String thingUID,
+            @DefaultValue("DSL") @QueryParam("format") @Parameter(description = "syntax format") String format) {
+        ThingSyntaxGenerator generator = thingSyntaxGenerators.get(format);
+        if (generator == null) {
+            String message = "No syntax available for format " + format + "!";
+            return Response.status(Response.Status.BAD_REQUEST).entity(message).build();
+        }
+
+        List<DiscoveryResult> results = inbox.getAll().stream().filter(forThingUID(new ThingUID(thingUID))).toList();
+        if (results.isEmpty()) {
+            String message = "Discovery result for thing with UID " + thingUID + " not found in the inbox!";
+            return Response.status(Response.Status.NOT_FOUND).entity(message).build();
+        }
+        DiscoveryResult result = results.get(0);
+        ThingType thingType = thingTypeRegistry.getThingType(result.getThingTypeUID());
+        if (thingType == null) {
+            String message = "Thing type with UID " + result.getThingTypeUID() + " does not exist!";
+            return Response.status(Response.Status.NOT_FOUND).entity(message).build();
+        }
+
+        return Response.ok(generator.generateSyntax(List.of(simulateThing(result, thingType)), false)).build();
+    }
+
+    /*
+     * Create a thing from a discovery result without inserting it in the thing registry
+     */
+    private Thing simulateThing(DiscoveryResult result, ThingType thingType) {
+        Map<String, Object> configParams = new HashMap<>();
+        List<ConfigDescriptionParameter> configDescriptionParameters = List.of();
+        URI descURI = thingType.getConfigDescriptionURI();
+        if (descURI != null) {
+            ConfigDescription desc = configDescRegistry.getConfigDescription(descURI);
+            if (desc != null) {
+                configDescriptionParameters = desc.getParameters();
+            }
+        }
+        for (ConfigDescriptionParameter param : configDescriptionParameters) {
+            Object value = result.getProperties().get(param.getName());
+            if (value != null) {
+                configParams.put(param.getName(), ConfigUtil.normalizeType(value, param));
+            }
+        }
+        Configuration config = new Configuration(configParams);
+        return ThingFactory.createThing(thingType, result.getThingUID(), config, result.getBridgeUID(),
+                configDescRegistry);
+    }
 }

bundles/org.openhab.core.io.rest.core/src/main/java/org/openhab/core/io/rest/core/internal/item/ItemResource.java

@@ -27,6 +27,7 @@
 import java.util.Objects;
 import java.util.Optional;
 import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
 import java.util.function.Predicate;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
@@ -89,13 +90,18 @@
 import org.openhab.core.library.types.UpDownType;
 import org.openhab.core.semantics.SemanticTagRegistry;
 import org.openhab.core.semantics.SemanticsPredicates;
+import org.openhab.core.thing.link.ItemChannelLink;
+import org.openhab.core.thing.link.ItemChannelLinkRegistry;
+import org.openhab.core.thing.syntaxgenerator.ItemSyntaxGenerator;
 import org.openhab.core.types.Command;
 import org.openhab.core.types.State;
 import org.openhab.core.types.TypeParser;
 import org.osgi.service.component.annotations.Activate;
 import org.osgi.service.component.annotations.Component;
 import org.osgi.service.component.annotations.Deactivate;
 import org.osgi.service.component.annotations.Reference;
+import org.osgi.service.component.annotations.ReferenceCardinality;
+import org.osgi.service.component.annotations.ReferencePolicy;
 import org.osgi.service.jaxrs.whiteboard.JaxrsWhiteboardConstants;
 import org.osgi.service.jaxrs.whiteboard.propertytypes.JSONRequired;
 import org.osgi.service.jaxrs.whiteboard.propertytypes.JaxrsApplicationSelect;
@@ -137,6 +143,7 @@
  * @author Stefan Triller - Added bulk item add method
  * @author Markus Rathgeb - Migrated to JAX-RS Whiteboard Specification
  * @author Wouter Born - Migrated to OpenAPI annotations
+ * @author Laurent Garnier - Added API to generate file syntax
  */
 @Component
 @JaxrsResource
@@ -182,7 +189,9 @@ private static void respectForwarded(final UriBuilder uriBuilder, final @Context
     private final MetadataRegistry metadataRegistry;
     private final MetadataSelectorMatcher metadataSelectorMatcher;
     private final SemanticTagRegistry semanticTagRegistry;
+    private final ItemChannelLinkRegistry itemChannelLinkRegistry;
     private final TimeZoneProvider timeZoneProvider;
+    private final Map<String, ItemSyntaxGenerator> itemSyntaxGenerators = new ConcurrentHashMap<>();
 
     private final RegistryChangedRunnableListener<Item> resetLastModifiedItemChangeListener = new RegistryChangedRunnableListener<>(
             () -> lastModified = null);
@@ -202,6 +211,7 @@ public ItemResource(//
             final @Reference MetadataRegistry metadataRegistry,
             final @Reference MetadataSelectorMatcher metadataSelectorMatcher,
             final @Reference SemanticTagRegistry semanticTagRegistry,
+            final @Reference ItemChannelLinkRegistry itemChannelLinkRegistry,
             final @Reference TimeZoneProvider timeZoneProvider) {
         this.dtoMapper = dtoMapper;
         this.eventPublisher = eventPublisher;
@@ -212,6 +222,7 @@ public ItemResource(//
         this.metadataRegistry = metadataRegistry;
         this.metadataSelectorMatcher = metadataSelectorMatcher;
         this.semanticTagRegistry = semanticTagRegistry;
+        this.itemChannelLinkRegistry = itemChannelLinkRegistry;
         this.timeZoneProvider = timeZoneProvider;
 
         this.itemRegistry.addRegistryChangeListener(resetLastModifiedItemChangeListener);
@@ -224,6 +235,15 @@ void deactivate() {
         this.metadataRegistry.removeRegistryChangeListener(resetLastModifiedMetadataChangeListener);
     }
 
+    @Reference(policy = ReferencePolicy.DYNAMIC, cardinality = ReferenceCardinality.MULTIPLE)
+    protected void addItemSyntaxGenerator(ItemSyntaxGenerator itemSyntaxGenerator) {
+        itemSyntaxGenerators.put(itemSyntaxGenerator.getFormat(), itemSyntaxGenerator);
+    }
+
+    protected void removeItemSyntaxGenerator(ItemSyntaxGenerator itemSyntaxGenerator) {
+        itemSyntaxGenerators.remove(itemSyntaxGenerator.getFormat());
+    }
+
     private UriBuilder uriBuilder(final UriInfo uriInfo, final HttpHeaders httpHeaders) {
         final UriBuilder uriBuilder = uriInfo.getBaseUriBuilder().path(PATH_ITEMS).path("{itemName}");
         respectForwarded(uriBuilder, httpHeaders);
@@ -901,6 +921,58 @@ public Response getSemanticItem(final @Context UriInfo uriInfo, final @Context H
         return JSONResponse.createResponse(Status.OK, dto, null);
     }
 
+    @GET
+    @RolesAllowed({ Role.ADMIN })
+    @Path("/filesyntax")
+    @Produces(MediaType.TEXT_PLAIN)
+    @Operation(operationId = "generateSyntaxForAllItems", summary = "Generate file syntax for all items.", security = {
+            @SecurityRequirement(name = "oauth2", scopes = { "admin" }) }, responses = {
+                    @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = String.class))),
+                    @ApiResponse(responseCode = "400", description = "Unsupported syntax format.") })
+    public Response generateSyntaxForAllItems(
+            @HeaderParam(HttpHeaders.ACCEPT_LANGUAGE) @Parameter(description = "language") @Nullable String language,
+            @DefaultValue("DSL") @QueryParam("format") @Parameter(description = "syntax format") String format) {
+        ItemSyntaxGenerator generator = itemSyntaxGenerators.get(format);
+        if (generator == null) {
+            String message = "No syntax available for format " + format + "!";
+            return Response.status(Response.Status.BAD_REQUEST).entity(message).build();
+        }
+        return Response.ok(generator.generateSyntax(sortItems(itemRegistry.getAll()), itemChannelLinkRegistry.getAll(),
+                metadataRegistry.getAll())).build();
+    }
+
+    @GET
+    @RolesAllowed({ Role.ADMIN })
+    @Path("/{itemname: [a-zA-Z_0-9]+}/filesyntax")
+    @Produces(MediaType.TEXT_PLAIN)
+    @Operation(operationId = "generateSyntaxForItem", summary = "Generate file syntax for an item.", security = {
+            @SecurityRequirement(name = "oauth2", scopes = { "admin" }) }, responses = {
+                    @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = String.class))),
+                    @ApiResponse(responseCode = "400", description = "Unsupported syntax format."),
+                    @ApiResponse(responseCode = "404", description = "Item not found.") })
+    public Response generateSyntaxForItem(
+            @HeaderParam(HttpHeaders.ACCEPT_LANGUAGE) @Parameter(description = "language") @Nullable String language,
+            @PathParam("itemname") @Parameter(description = "item name") String itemname,
+            @DefaultValue("DSL") @QueryParam("format") @Parameter(description = "syntax format") String format) {
+        ItemSyntaxGenerator generator = itemSyntaxGenerators.get(format);
+        if (generator == null) {
+            String message = "No syntax available for format " + format + "!";
+            return Response.status(Response.Status.BAD_REQUEST).entity(message).build();
+        }
+
+        Item item = getItem(itemname);
+        if (item == null) {
+            String message = "Item " + itemname + " does not exist!";
+            return Response.status(Response.Status.NOT_FOUND).entity(message).build();
+        }
+
+        Set<ItemChannelLink> channelLinks = itemChannelLinkRegistry.getLinks(itemname);
+        Set<Metadata> metadata = metadataRegistry.getAll().stream()
+                .filter(md -> md.getUID().getItemName().equals(itemname)).collect(Collectors.toSet());
+
+        return Response.ok(generator.generateSyntax(List.of(item), channelLinks, metadata)).build();
+    }
+
     private JsonObject buildStatusObject(String itemName, String status, @Nullable String message) {
         JsonObject jo = new JsonObject();
         jo.addProperty("name", itemName);
@@ -1006,4 +1078,66 @@ private void addMetadata(EnrichedItemDTO dto, Set<String> namespaces, @Nullable
     private boolean isEditable(String itemName) {
         return managedItemProvider.get(itemName) != null;
     }
+
+    /*
+     * Sort the items in such a way:
+     * - first the groups, with ancestors before its children and then sorted by names.
+     * - Then all items not linked to a channel, sorted by names.
+     * - Finally all items linked to a channel, sorted first by binding names and then by item names.
+     */
+    private List<Item> sortItems(Collection<Item> items) {
+        return items.stream().sorted((item1, item2) -> {
+            String name1 = item1.getName();
+            String name2 = item2.getName();
+            if (name1.equals(name2)) {
+                return 0;
+            } else if (item1 instanceof GroupItem && !(item2 instanceof GroupItem)) {
+                return -1;
+            } else if (!(item1 instanceof GroupItem) && item2 instanceof GroupItem) {
+                return 1;
+            } else if (item1 instanceof GroupItem group1 && item2 instanceof GroupItem group2
+                    && isAncestorGroupOf(group1, group2)) {
+                return -1;
+            } else if (item1 instanceof GroupItem group1 && item2 instanceof GroupItem group2
+                    && isAncestorGroupOf(group2, group1)) {
+                return 1;
+            } else if (!(item1 instanceof GroupItem) && !(item2 instanceof GroupItem)) {
+                Set<ItemChannelLink> channelLinks1 = itemChannelLinkRegistry.getLinks(name1);
+                String binding1 = channelLinks1.isEmpty() ? null
+                        : channelLinks1.iterator().next().getLinkedUID().getBindingId();
+                Set<ItemChannelLink> channelLinks2 = itemChannelLinkRegistry.getLinks(name2);
+                String binding2 = channelLinks2.isEmpty() ? null
+                        : channelLinks2.iterator().next().getLinkedUID().getBindingId();
+
+                if (binding1 == null && binding2 != null) {
+                    return -1;
+                } else if (binding1 != null && binding2 == null) {
+                    return 1;
+                } else if (binding1 != null && binding2 != null && !binding1.equals(binding2)) {
+                    return binding1.compareTo(binding2);
+                }
+            }
+            return name1.compareTo(name2);
+        }).collect(Collectors.toList());
+    }
+
+    private boolean isAncestorGroupOf(GroupItem group1, GroupItem group2) {
+        if (!group1.getName().equals(group2.getName())) {
+            Set<GroupItem> groups = new HashSet<>();
+            fillGroupTree(groups, group1);
+            return groups.contains(group2);
+        }
+        return false;
+    }
+
+    private void fillGroupTree(Set<GroupItem> groups, GroupItem group) {
+        if (!groups.contains(group)) {
+            groups.add(group);
+            for (Item member : group.getMembers()) {
+                if (member instanceof GroupItem groupMember) {
+                    fillGroupTree(groups, groupMember);
+                }
+            }
+        }
+    }
 }