Mark vehicle envelope key to become non-null

Mark the envelope key in Vehicle and related APIs to become a non-null value with openTCS 7.0. Additionally, update the user's guide regarding vehicle envelope keys and documented what happens if a vehicle envelope key is not defined at a point or path. Merged-by: Martin Grzenia <[email protected]>
openTCS · Oct 30, 2024 · 27ceb1a · 27ceb1a
1 parent ff95f0a
commit 27ceb1a
Show file tree

Hide file tree

Showing 6 changed files with 14 additions and 0 deletions.
diff --git a/opentcs-api-base/src/main/java/org/opentcs/access/to/model/VehicleCreationTO.java b/opentcs-api-base/src/main/java/org/opentcs/access/to/model/VehicleCreationTO.java
@@ -427,6 +427,7 @@ public VehicleCreationTO withMaxReverseVelocity(int maxReverseVelocity) {
    *
    * @return The key for selecting the envelope to be used for resources the vehicle occupies.
    */
+  @ScheduledApiChange(when = "7.0", details = "Envelope key will become non-null.")
   @Nullable
   public String getEnvelopeKey() {
     return envelopeKey;
@@ -439,6 +440,7 @@ public String getEnvelopeKey() {
    * @param envelopeKey The value to be set in the copy.
    * @return A copy of this object, differing in the given value.
    */
+  @ScheduledApiChange(when = "7.0", details = "Envelope key will become non-null.")
   public VehicleCreationTO withEnvelopeKey(
       @Nullable
       String envelopeKey

diff --git a/opentcs-api-base/src/main/java/org/opentcs/data/model/Vehicle.java b/opentcs-api-base/src/main/java/org/opentcs/data/model/Vehicle.java
@@ -1513,6 +1513,7 @@ public Vehicle withOrientationAngle(double orientationAngle) {
    *
    * @return The key for selecting the envelope to be used for resources the vehicle occupies.
    */
+  @ScheduledApiChange(when = "7.0", details = "Envelope key will become non-null.")
   @Nullable
   public String getEnvelopeKey() {
     return envelopeKey;
@@ -1524,6 +1525,7 @@ public String getEnvelopeKey() {
    * @param envelopeKey The value to be set in the copy.
    * @return A copy of this object, differing in the given value.
    */
+  @ScheduledApiChange(when = "7.0", details = "Envelope key will become non-null.")
   public Vehicle withEnvelopeKey(
       @Nullable
       String envelopeKey

diff --git a/opentcs-common/src/main/java/org/opentcs/util/persistence/v6/VehicleTO.java b/opentcs-common/src/main/java/org/opentcs/util/persistence/v6/VehicleTO.java
@@ -12,6 +12,7 @@
 import javax.xml.bind.annotation.XmlElement;
 import javax.xml.bind.annotation.XmlSchemaType;
 import javax.xml.bind.annotation.XmlType;
+import org.opentcs.util.annotations.ScheduledApiChange;
 
 /**
  */
@@ -131,12 +132,14 @@ public VehicleTO setMaxReverseVelocity(
     return this;
   }
 
+  @ScheduledApiChange(when = "7.0", details = "Envelope key will become non-null.")
   @XmlAttribute
   @Nullable
   public String getEnvelopeKey() {
     return envelopeKey;
   }
 
+  @ScheduledApiChange(when = "7.0", details = "Envelope key will become non-null.")
   public VehicleTO setEnvelopeKey(
       @Nullable
       String envelopeKey

diff --git a/opentcs-documentation/src/docs/users-guide/03_operating-opentcs.adoc b/opentcs-documentation/src/docs/users-guide/03_operating-opentcs.adoc
@@ -79,6 +79,8 @@ By referencing an envelope key, a vehicle indicates which envelopes (that may be
 (For more details on this, see <<Default scheduler>>.)
 With this, it is possible to prevent vehicles from allocating areas intersecting with areas already allocated by other vehicles.
 
+NOTE: If an envelope key is set for a vehicle, but no envelope with the respective key is defined at a specific resource (i.e. point or path), no envelope will be considered for the vehicle when it allocates that resource.
+
 .Defining and editing vehicle envelopes for points and paths
 image::screenshot_envelope_editing.drawio.png[]
 

diff --git a/...ain/java/org/opentcs/kernel/extensions/servicewebapi/v1/binding/GetVehicleResponseTO.java b/...ain/java/org/opentcs/kernel/extensions/servicewebapi/v1/binding/GetVehicleResponseTO.java
@@ -17,6 +17,7 @@
 import org.opentcs.data.model.Vehicle.IntegrationLevel;
 import org.opentcs.data.model.Vehicle.ProcState;
 import org.opentcs.data.model.Vehicle.State;
+import org.opentcs.util.annotations.ScheduledApiChange;
 
 /**
  */
@@ -238,11 +239,13 @@ public GetVehicleResponseTO setAllowedOrderTypes(List<String> allowedOrderTypes)
     return this;
   }
 
+  @ScheduledApiChange(when = "7.0", details = "Envelope key will become non-null.")
   @Nullable
   public String getEnvelopeKey() {
     return envelopeKey;
   }
 
+  @ScheduledApiChange(when = "7.0", details = "Envelope key will become non-null.")
   public GetVehicleResponseTO setEnvelopeKey(
       @Nullable
       String envelopeKey

diff --git a/opentcs-kernel/src/main/java/org/opentcs/kernel/services/StandardVehicleService.java b/opentcs-kernel/src/main/java/org/opentcs/kernel/services/StandardVehicleService.java
@@ -33,6 +33,7 @@
 import org.opentcs.kernel.vehicles.LocalVehicleControllerPool;
 import org.opentcs.kernel.vehicles.VehicleCommAdapterRegistry;
 import org.opentcs.kernel.workingset.PlantModelManager;
+import org.opentcs.util.annotations.ScheduledApiChange;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -451,6 +452,7 @@ public void updateVehicleAllowedOrderTypes(
   }
 
   @Override
+  @ScheduledApiChange(when = "7.0", details = "Envelope key will become non-null.")
   public void updateVehicleEnvelopeKey(TCSObjectReference<Vehicle> ref, String envelopeKey)
       throws ObjectUnknownException,
         IllegalArgumentException,