Allow selective topology updates via the web API

The endpoint `POST /plantModel/topologyUpdateRequest` now also accepts an optional list of path names allowing the routing topology to be updated selectively. This allows to increase the performance when updating the routing graph by providing only the (usually significantly reduced) set of paths that have actually changed. Merged-by: Martin Grzenia <martin.grzenia@iml.fraunhofer.de>
openTCS · Jun 27, 2024 · be4c5ad · be4c5ad
1 parent 63120de
commit be4c5ad
Show file tree

Hide file tree

Showing 6 changed files with 138 additions and 7 deletions.
diff --git a/openTCS-Documentation/src/docs/release-notes/changelog.adoc b/openTCS-Documentation/src/docs/release-notes/changelog.adoc
@@ -14,7 +14,9 @@ This change log lists the most relevant changes for past releases in reverse chr
 
 == Unreleased
 
-...
+* New features and enhancements:
+** Update web API specification and implementation to version 1.8.0:
+*** The endpoint `POST /plantModel/topologyUpdateRequest` now also accepts an optional list of path names allowing the routing topology to be updated selectively.
 
 == Version 6.0 (2024-06-19)
 

diff --git a/openTCS-Documentation/src/docs/service-web-api-v1/openapi.yaml b/openTCS-Documentation/src/docs/service-web-api-v1/openapi.yaml
@@ -18,7 +18,7 @@ info:
     Optionally, an access key can be set in the kernel configuration.
     The configured value is then expected to be sent by the client in an HTTP header named `X-Api-Access-Key`.
   # IMPORTANT: When updating this version number, remember to mention that in the changelog, too!
-  version: 1.7.0
+  version: 1.8.0
   title: openTCS web API specification
 servers:
   - url: http://localhost:55200/v1
@@ -1192,9 +1192,25 @@ paths:
         - Plant models
       summary: Triggers an update of the routing topology.
       description: ""
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/TopologyUpdateRequest"
       responses:
         "200":
           description: Successful response.
+        "404":
+          description: Referencing object that could not be found.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+                  description: Details on the actual error.
+                  example: Could not find path 'Path-BA'.
   /paths/{NAME}/locked:
     put:
       tags:
@@ -1778,6 +1794,21 @@ components:
         type: string
         description: Name of the resource
       example: [ Point-0042, Path-0041--0042 ]
+    TopologyUpdateRequest:
+      title: TopologyUpdateRequest
+      type: object
+      additionalProperties: false
+      properties:
+        paths:
+         type: array
+         items:
+          type: string
+         description: >-
+           The names of the paths to update in the routing topology.
+           An empty list of paths causes the entire routing topology to be updated.
+         example: [ Path-0042--0043, Path-0041--0042 ]
+      required:
+        - paths
     StatusMessageList:
       title: Status Message List
       type: object

diff --git a/...vices/src/main/java/org/opentcs/kernel/extensions/servicewebapi/v1/PlantModelHandler.java b/...vices/src/main/java/org/opentcs/kernel/extensions/servicewebapi/v1/PlantModelHandler.java
@@ -10,14 +10,19 @@
 import static java.util.Objects.requireNonNull;
 
 import jakarta.inject.Inject;
+import java.util.HashSet;
+import java.util.List;
 import java.util.Set;
 import org.opentcs.access.to.model.PlantModelCreationTO;
 import org.opentcs.components.kernel.services.PlantModelService;
 import org.opentcs.components.kernel.services.RouterService;
 import org.opentcs.data.ObjectUnknownException;
+import org.opentcs.data.TCSObjectReference;
+import org.opentcs.data.model.Path;
 import org.opentcs.data.model.PlantModel;
 import org.opentcs.kernel.extensions.servicewebapi.KernelExecutorWrapper;
 import org.opentcs.kernel.extensions.servicewebapi.v1.binding.PlantModelTO;
+import org.opentcs.kernel.extensions.servicewebapi.v1.binding.PostTopologyUpdateRequestTO;
 import org.opentcs.kernel.extensions.servicewebapi.v1.converter.BlockConverter;
 import org.opentcs.kernel.extensions.servicewebapi.v1.converter.LocationConverter;
 import org.opentcs.kernel.extensions.servicewebapi.v1.converter.LocationTypeConverter;
@@ -128,7 +133,24 @@ public PlantModelTO getPlantModel() {
         .setProperties(propertyConverter.toPropertyTOs(plantModel.getProperties()));
   }
 
-  public void requestTopologyUpdate() {
-    executorWrapper.callAndWait(() -> routerService.updateRoutingTopology(Set.of()));
+  public void requestTopologyUpdate(PostTopologyUpdateRequestTO request)
+      throws ObjectUnknownException {
+    executorWrapper.callAndWait(
+        () -> routerService.updateRoutingTopology(toResourceReferences(request.getPaths()))
+    );
+  }
+
+  private Set<TCSObjectReference<Path>> toResourceReferences(List<String> paths) {
+    Set<TCSObjectReference<Path>> pathsToUpdate = new HashSet<>();
+
+    for (String name : paths) {
+      Path path = plantModelService.fetchObject(Path.class, name);
+      if (path == null) {
+        throw new ObjectUnknownException("Unknown path: " + name);
+      }
+      pathsToUpdate.add(path.getReference());
+    }
+
+    return pathsToUpdate;
   }
 }
diff --git a/...rvices/src/main/java/org/opentcs/kernel/extensions/servicewebapi/v1/V1RequestHandler.java b/...rvices/src/main/java/org/opentcs/kernel/extensions/servicewebapi/v1/V1RequestHandler.java
@@ -10,6 +10,7 @@
 import static java.util.Objects.requireNonNull;
 
 import jakarta.inject.Inject;
+import java.util.List;
 import java.util.concurrent.ExecutionException;
 import org.opentcs.access.KernelRuntimeException;
 import org.opentcs.data.ObjectExistsException;
@@ -25,6 +26,7 @@
 import org.opentcs.kernel.extensions.servicewebapi.v1.binding.PlantModelTO;
 import org.opentcs.kernel.extensions.servicewebapi.v1.binding.PostOrderSequenceRequestTO;
 import org.opentcs.kernel.extensions.servicewebapi.v1.binding.PostPeripheralJobRequestTO;
+import org.opentcs.kernel.extensions.servicewebapi.v1.binding.PostTopologyUpdateRequestTO;
 import org.opentcs.kernel.extensions.servicewebapi.v1.binding.PostTransportOrderRequestTO;
 import org.opentcs.kernel.extensions.servicewebapi.v1.binding.PostVehicleRoutesRequestTO;
 import org.opentcs.kernel.extensions.servicewebapi.v1.binding.PostVehicleRoutesResponseTO;
@@ -482,9 +484,18 @@ private Object handleGetPlantModel(Request request, Response response) {
   }
 
   private Object handlePostUpdateTopology(Request request, Response response)
-      throws KernelRuntimeException {
+      throws ObjectUnknownException,
+        KernelRuntimeException {
     response.type(HttpConstants.CONTENT_TYPE_TEXT_PLAIN_UTF8);
-    plantModelHandler.requestTopologyUpdate();
+    if (request.body().isBlank()) {
+      plantModelHandler.requestTopologyUpdate(new PostTopologyUpdateRequestTO(List.of()));
+    }
+    else {
+      plantModelHandler
+          .requestTopologyUpdate(
+              jsonBinder.fromJson(request.body(), PostTopologyUpdateRequestTO.class)
+          );
+    }
     return "";
   }
 

diff --git a/...a/org/opentcs/kernel/extensions/servicewebapi/v1/binding/PostTopologyUpdateRequestTO.java b/...a/org/opentcs/kernel/extensions/servicewebapi/v1/binding/PostTopologyUpdateRequestTO.java
@@ -0,0 +1,46 @@
+/**
+ * Copyright (c) The openTCS Authors.
+ *
+ * This program is free software and subject to the MIT license. (For details,
+ * see the licensing information (LICENSE.txt) you should have received with
+ * this copy of the software.)
+ */
+package org.opentcs.kernel.extensions.servicewebapi.v1.binding;
+
+import static java.util.Objects.requireNonNull;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import jakarta.annotation.Nonnull;
+import java.util.List;
+
+/**
+ * A list of paths that are to be updated when the routing topology gets updated.
+ */
+public class PostTopologyUpdateRequestTO {
+
+  @Nonnull
+  private List<String> paths;
+
+  @JsonCreator
+  public PostTopologyUpdateRequestTO(
+      @Nonnull
+      @JsonProperty(value = "paths", required = true)
+      List<String> paths
+  ) {
+    this.paths = requireNonNull(paths, "paths");
+  }
+
+  @Nonnull
+  public List<String> getPaths() {
+    return paths;
+  }
+
+  public PostTopologyUpdateRequestTO setPaths(
+      @Nonnull
+      List<String> paths
+  ) {
+    this.paths = requireNonNull(paths, "paths");
+    return this;
+  }
+}
diff --git a/...s/src/test/java/org/opentcs/kernel/extensions/servicewebapi/v1/PlantModelHandlerTest.java b/...s/src/test/java/org/opentcs/kernel/extensions/servicewebapi/v1/PlantModelHandlerTest.java
@@ -32,6 +32,7 @@
 import org.opentcs.data.model.visualization.VisualLayout;
 import org.opentcs.kernel.extensions.servicewebapi.KernelExecutorWrapper;
 import org.opentcs.kernel.extensions.servicewebapi.v1.binding.PlantModelTO;
+import org.opentcs.kernel.extensions.servicewebapi.v1.binding.PostTopologyUpdateRequestTO;
 import org.opentcs.kernel.extensions.servicewebapi.v1.binding.plantmodel.BlockTO;
 import org.opentcs.kernel.extensions.servicewebapi.v1.binding.plantmodel.LocationTO;
 import org.opentcs.kernel.extensions.servicewebapi.v1.binding.plantmodel.LocationTypeTO;
@@ -233,7 +234,25 @@ void getPlantModel() {
 
   @Test
   void requestTopologyUpdate() {
-    handler.requestTopologyUpdate();
+    handler.requestTopologyUpdate(
+        new PostTopologyUpdateRequestTO(List.of())
+    );
     then(routerService).should().updateRoutingTopology(Set.of());
   }
+
+  @Test
+  void requestTopologyUpdateWithPath() {
+    Path path1 = new Path(
+        "path1",
+        new Point("source").getReference(),
+        new Point("dest").getReference()
+    );
+
+    given(orderService.fetchObject(Path.class, "path1")).willReturn(path1);
+
+    handler.requestTopologyUpdate(
+        new PostTopologyUpdateRequestTO(List.of("path1"))
+    );
+    then(routerService).should().updateRoutingTopology(Set.of(path1.getReference()));
+  }
 }