Add support for transport order types with priorities

For vehicle elements, transport order types (that a vehicle is allowed
to process) can now be assigned a priority.

Also add a new key "BY_ORDER_TYPE_PRIORITY" that can be configured for
the kernel configuration entries
"defaultdispatcher.orderCandidatePriorities" and
"defaultdispatcher.vehicleCandidatePriorities". With this key
configured, a vehicle's acceptable order types are considered when
assigning transport order to it.

Finally, add an endpoint "PUT /vehicles/{NAME}/acceptableOrderTypes",
which allows a vehicle's set of acceptable order types to be modified
during runtime. This endpoint replaces
"PUT /vehicles/{NAME}/allowedOrderTypes", which is now deprecated.

Co-authored-by: Martin Grzenia <[email protected]>
Co-authored-by: Stefan Walter <[email protected]>
Reviewed-by: Finja Averhaus <[email protected]>
Merged-by: Stefan Walter <[email protected]>

Author: 3 people

opentcs-api-base/src/main/java/org/opentcs/access/rmi/services/RemoteVehicleService.java

@@ -8,6 +8,7 @@
 import org.opentcs.access.rmi.ClientID;
 import org.opentcs.components.kernel.services.VehicleService;
 import org.opentcs.data.TCSObjectReference;
+import org.opentcs.data.model.AcceptableOrderType;
 import org.opentcs.data.model.Vehicle;
 import org.opentcs.data.model.Vehicle.EnergyLevelThresholdSet;
 import org.opentcs.drivers.vehicle.AdapterCommand;
@@ -95,13 +96,24 @@ default void updateVehicleEnergyLevelThresholdSet(
     throw new UnsupportedOperationException("Not yet implemented.");
   }
 
+  @Deprecated
+  @ScheduledApiChange(when = "7.0", details = "Will be removed.")
   void updateVehicleAllowedOrderTypes(
       ClientID clientId,
       TCSObjectReference<Vehicle> ref,
       Set<String> allowedOrderTypes
   )
       throws RemoteException;
 
+  default void updateVehicleAcceptableOrderTypes(
+      ClientID clientId,
+      TCSObjectReference<Vehicle> ref,
+      Set<AcceptableOrderType> acceptableOrderTypes
+  )
+      throws RemoteException {
+    throw new UnsupportedOperationException("Not yet implemented.");
+  }
+
   void updateVehicleEnvelopeKey(
       ClientID clientId,
       TCSObjectReference<Vehicle> ref,

opentcs-api-base/src/main/java/org/opentcs/access/rmi/services/RemoteVehicleServiceProxy.java

@@ -8,12 +8,14 @@
 import org.opentcs.components.kernel.services.VehicleService;
 import org.opentcs.data.ObjectUnknownException;
 import org.opentcs.data.TCSObjectReference;
+import org.opentcs.data.model.AcceptableOrderType;
 import org.opentcs.data.model.Vehicle;
 import org.opentcs.data.model.Vehicle.EnergyLevelThresholdSet;
 import org.opentcs.drivers.vehicle.AdapterCommand;
 import org.opentcs.drivers.vehicle.VehicleCommAdapterDescription;
 import org.opentcs.drivers.vehicle.management.VehicleAttachmentInformation;
 import org.opentcs.drivers.vehicle.management.VehicleProcessModelTO;
+import org.opentcs.util.annotations.ScheduledApiChange;
 
 /**
  * The default implementation of the vehicle service.
@@ -185,6 +187,8 @@ public void updateVehicleEnergyLevelThresholdSet(
   }
 
   @Override
+  @Deprecated
+  @ScheduledApiChange(when = "7.0", details = "Will be removed.")
   public void updateVehicleAllowedOrderTypes(
       TCSObjectReference<Vehicle> ref,
       Set<String> allowedOrderTypes
@@ -205,6 +209,27 @@ public void updateVehicleAllowedOrderTypes(
     }
   }
 
+  @Override
+  public void updateVehicleAcceptableOrderTypes(
+      TCSObjectReference<Vehicle> ref,
+      Set<AcceptableOrderType> acceptableOrderTypes
+  )
+      throws ObjectUnknownException,
+        KernelRuntimeException {
+    checkServiceAvailability();
+
+    try {
+      getRemoteService().updateVehicleAcceptableOrderTypes(
+          getClientId(),
+          ref,
+          acceptableOrderTypes
+      );
+    }
+    catch (RemoteException ex) {
+      throw findSuitableExceptionFor(ex);
+    }
+  }
+
   @Override
   public void updateVehicleEnvelopeKey(TCSObjectReference<Vehicle> ref, String envelopeKey)
       throws ObjectUnknownException,

opentcs-api-base/src/main/java/org/opentcs/components/kernel/services/VehicleService.java

@@ -6,6 +6,7 @@
 import org.opentcs.access.KernelRuntimeException;
 import org.opentcs.data.ObjectUnknownException;
 import org.opentcs.data.TCSObjectReference;
+import org.opentcs.data.model.AcceptableOrderType;
 import org.opentcs.data.model.Vehicle;
 import org.opentcs.data.model.Vehicle.EnergyLevelThresholdSet;
 import org.opentcs.drivers.vehicle.AdapterCommand;
@@ -176,14 +177,34 @@ default void updateVehicleEnergyLevelThresholdSet(
    * @param allowedOrderTypes A set of transport order types.
    * @throws ObjectUnknownException If the referenced vehicle does not exist.
    * @throws KernelRuntimeException In case there is an exception executing this method.
+   * @deprecated Use {@link #updateVehicleAcceptableOrderTypes(TCSObjectReference, Set)} instead.
    */
+  @Deprecated
+  @ScheduledApiChange(when = "7.0", details = "Will be removed.")
   void updateVehicleAllowedOrderTypes(
       TCSObjectReference<Vehicle> ref,
       Set<String> allowedOrderTypes
   )
       throws ObjectUnknownException,
         KernelRuntimeException;
 
+  /**
+   * Updates the types of transport orders a vehicle is allowed to process.
+   *
+   * @param ref A reference to the vehicle to be modified.
+   * @param acceptableOrderTypes A set of transport order types and their priorities.
+   * @throws ObjectUnknownException If the referenced vehicle does not exist.
+   * @throws KernelRuntimeException In case there is an exception executing this method.
+   */
+  default void updateVehicleAcceptableOrderTypes(
+      TCSObjectReference<Vehicle> ref,
+      Set<AcceptableOrderType> acceptableOrderTypes
+  )
+      throws ObjectUnknownException,
+        KernelRuntimeException {
+    throw new UnsupportedOperationException("Not yet implemented.");
+  }
+
   /**
    * Updates the vehicle's envelope key.
    *

opentcs-api-base/src/main/java/org/opentcs/data/model/AcceptableOrderType.java

@@ -0,0 +1,74 @@
+// SPDX-FileCopyrightText: The openTCS Authors
+// SPDX-License-Identifier: MIT
+package org.opentcs.data.model;
+
+import static java.util.Objects.requireNonNull;
+
+import java.io.Serializable;
+import java.util.Objects;
+
+/**
+ * Acceptable order type with priority.
+ */
+public class AcceptableOrderType
+    implements
+      Serializable {
+
+  private final String name;
+  private final int priority;
+
+  /**
+   * Creates a new vehicle.
+   *
+   * @param name The name of the order type.
+   * @param priority Priority of the order type, with a lower value indicating a higher priority.
+   */
+  public AcceptableOrderType(String name, int priority) {
+    this.name = requireNonNull(name, "name");
+    this.priority = priority;
+  }
+
+  /**
+   * Returns the name of the order type.
+   *
+   * @return The name of the order type.
+   */
+  public String getName() {
+    return name;
+  }
+
+  /**
+   * Returns the priority of the order type, with a lower value indicating a higher priority.
+   *
+   * @return The priority of the order type.
+   */
+  public int getPriority() {
+    return priority;
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (o == this) {
+      return true;
+    }
+    if (!(o instanceof AcceptableOrderType other)) {
+      return false;
+    }
+
+    return Objects.equals(name, other.getName()) && priority == other.getPriority();
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(name, priority);
+  }
+
+  @Override
+  public String toString() {
+    return "AcceptableOrderType{"
+        + "name=" + name
+        + ", priority=" + priority
+        + '}';
+  }
+
+}