Skip to content

Commit

Permalink
[REST] New REST APIs to generate DSL syntax for items and things
Browse files Browse the repository at this point in the history 
Related to #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]>
  • Loading branch information
@lolodomo
lolodomo committed Jan 26, 2025
1 parent ce37425 commit 6bc963f
Show file tree
Hide file tree
Showing 17 changed files with 1,289 additions and 21 deletions.
92 changes: 91 additions & 1 deletion ...st.core/src/main/java/org/openhab/core/io/rest/core/internal/discovery/InboxResource.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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;
Expand All @@ -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;
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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);
}
}
133 changes: 133 additions & 0 deletions ....io.rest.core/src/main/java/org/openhab/core/io/rest/core/internal/item/ItemResource.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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);
Expand All @@ -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;
Expand All @@ -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);
Expand All @@ -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);
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -1006,4 +1078,65 @@ 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:
* - group items are before non group items
* - group items are sorted to have as much as possible ancestors before their children
* - items not linked to a channel are before items linked to a channel
* - items linked to a channel are grouped by thing UID
* - items linked to the same thing UID are sorted by item name
*/
private List<Item> sortItems(Collection<Item> items) {
List<Item> groups = items.stream().filter(item -> item instanceof GroupItem).sorted((item1, item2) -> {
return item1.getName().compareTo(item2.getName());
}).collect(Collectors.toList());

List<Item> topGroups = groups.stream().filter(group -> group.getGroupNames().isEmpty())
.sorted((group1, group2) -> {
return group1.getName().compareTo(group2.getName());
}).collect(Collectors.toList());

List<Item> groupTree = new ArrayList<>();
for (Item group : topGroups) {
fillGroupTree(groupTree, group);
}

if (groupTree.size() != groups.size()) {
logger.warn("Something want wrong when sorting groups; failback to a sort by name.");
groupTree = groups;
}

List<Item> nonGroups = items.stream().filter(item -> !(item instanceof GroupItem)).sorted((item1, item2) -> {
Set<ItemChannelLink> channelLinks1 = itemChannelLinkRegistry.getLinks(item1.getName());
String thingUID1 = channelLinks1.isEmpty() ? null
: channelLinks1.iterator().next().getLinkedUID().getThingUID().getAsString();
Set<ItemChannelLink> channelLinks2 = itemChannelLinkRegistry.getLinks(item2.getName());
String thingUID2 = channelLinks2.isEmpty() ? null
: channelLinks2.iterator().next().getLinkedUID().getThingUID().getAsString();

if (thingUID1 == null && thingUID2 != null) {
return -1;
} else if (thingUID1 != null && thingUID2 == null) {
return 1;
} else if (thingUID1 != null && thingUID2 != null && !thingUID1.equals(thingUID2)) {
return thingUID1.compareTo(thingUID2);
}
return item1.getName().compareTo(item2.getName());
}).collect(Collectors.toList());

return Stream.of(groupTree, nonGroups).flatMap(List::stream).collect(Collectors.toList());
}

private void fillGroupTree(List<Item> groups, Item item) {
if (item instanceof GroupItem group && !groups.contains(group)) {
groups.add(group);
List<Item> members = group.getMembers().stream().sorted((member1, member2) -> {
return member1.getName().compareTo(member2.getName());
}).collect(Collectors.toList());
for (Item member : members) {
fillGroupTree(groups, member);
}
}
}
}
Loading

0 comments on commit 6bc963f

Please sign in to comment.