[ZEE-6771] Add LabelIdentifier to Inventory

src/main/java/zeenea/connector/common/ItemIdentifier.java

@@ -7,6 +7,8 @@
 /**
  * Represents an identifier for an item, consisting of a list of identification properties.
  *
+ * <p>This ItemIdentifier must be unique for each item in the data source.
+ *
  * <pre>Example : <br>
  * {
  *  "identificationProperties": [
@@ -154,7 +156,6 @@ public String toString() {
   /** Builder class for creating instances of ItemIdentifier. */
   public static class Builder {
 
-    /** The list of identification properties. */
     private List<IdentificationProperty> identificationProperties = new ArrayList<>();
 
     /**

src/main/java/zeenea/connector/common/ItemInventory.java

@@ -1,37 +1,34 @@
 package zeenea.connector.common;
 
-import java.util.ArrayList;
 import java.util.List;
 import java.util.Objects;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
 import org.jetbrains.annotations.NotNull;
-import zeenea.connector.exception.ExceptionUtils;
 
-/**
- * Represents an inventory of items identified by an ItemIdentifier and associated with a label
- * path.
- */
+/** Represents an inventory item, identified by an item identifier and eventually with a label. */
 public final class ItemInventory {
-  /** The identifier for the item. */
+  /** The unique identifier for the item. */
   @NotNull private final ItemIdentifier itemIdentifier;
 
   /**
-   * The list of labels associated with the item.
+   * Ordered list of labels associated with the inventory item.
    *
-   * <p>This label list will generate import hierarchy in Zeenea Studio import modal view.
+   * <p>This human-readable label list will be displayed in Zeenea Studio import modal view.
    *
-   * <p>It must be not empty to display importable items in the Studio.
+   * <p>If empty, item identifier will be used in Zeenea Studio import modal view.
    */
-  @NotNull private final List<String> labels;
+  @NotNull private final LabelIdentifier labelIdentifier;
 
   /**
    * Constructs an ItemInventory instance using the provided builder.
    *
    * @param builder the builder used to create the ItemInventory instance
    */
   private ItemInventory(Builder builder) {
-    ExceptionUtils.requireNonNullOrEmpty("labels", builder.labels);
     this.itemIdentifier = Objects.requireNonNull(builder.itemIdentifier, "itemIdentifier");
-    this.labels = List.copyOf(builder.labels);
+    this.labelIdentifier = Objects.requireNonNull(builder.labelIdentifier, "labelIdentifier");
   }
 
   /**
@@ -59,9 +56,29 @@ public static ItemInventory of(
    * Gets the list of labels associated with the item.
    *
    * @return the list of labels associated with the item
+   * @deprecated since 2.3.0, use getLabelIdentifier() instead
    */
+  @Deprecated(
+      since =
+          "Deprecated since version 2.3.0, use getLabelIdentifier() instead. Scheduled for removal in version 3.0.0.",
+      forRemoval = true)
   public @NotNull List<String> getLabels() {
-    return labels;
+    return labelIdentifier.getIdentificationProperties().stream()
+        .map(IdentificationProperty::getValue)
+        .collect(Collectors.toUnmodifiableList());
+  }
+
+  /**
+   * Ordered list of labels associated with the inventory item.
+   *
+   * <p>This human-readable label list will be displayed in Zeenea Studio import modal view.
+   *
+   * <p>If empty, item identifier will be used in Zeenea Studio import modal view.
+   *
+   * @return the label identifier associated with the item
+   */
+  public @NotNull LabelIdentifier getLabelIdentifier() {
+    return labelIdentifier;
   }
 
   /**
@@ -76,7 +93,7 @@ public boolean equals(Object o) {
     if (o == null || getClass() != o.getClass()) return false;
     ItemInventory that = (ItemInventory) o;
     return Objects.equals(itemIdentifier, that.itemIdentifier)
-        && Objects.equals(labels, that.labels);
+        && Objects.equals(labelIdentifier, that.labelIdentifier);
   }
 
   /**
@@ -86,7 +103,7 @@ public boolean equals(Object o) {
    */
   @Override
   public int hashCode() {
-    return Objects.hash(itemIdentifier, labels);
+    return Objects.hash(itemIdentifier, labelIdentifier);
   }
 
   /**
@@ -96,7 +113,12 @@ public int hashCode() {
    */
   @Override
   public String toString() {
-    return "ItemInventory{" + "itemIdentifier=" + itemIdentifier + ", labels=" + labels + "}";
+    return "ItemInventory{"
+        + "itemIdentifier="
+        + itemIdentifier
+        + ", labelIdentifier="
+        + labelIdentifier
+        + "}";
   }
 
   /**
@@ -111,11 +133,9 @@ public static Builder builder() {
   /** Builder class for creating instances of ItemInventory. */
   public static class Builder {
 
-    /** The identifier for the item. */
     private ItemIdentifier itemIdentifier;
 
-    /** The path of labels associated with the item. */
-    private List<String> labels = new ArrayList<>();
+    private LabelIdentifier labelIdentifier;
 
     /**
      * Sets the item identifier for the builder.
@@ -131,33 +151,87 @@ public Builder itemIdentifier(@NotNull ItemIdentifier itemIdentifier) {
     /**
      * Sets the item identifier for the builder.
      *
-     * @param itemIdentifier the identifier for the item
+     * @param identificationProperty the identifier for the item
      * @return the builder instance
      */
-    public Builder itemIdentifier(IdentificationProperty itemIdentifier) {
-      this.itemIdentifier = ItemIdentifier.of(itemIdentifier);
+    public Builder itemIdentifier(IdentificationProperty identificationProperty) {
+      this.itemIdentifier = ItemIdentifier.of(identificationProperty);
       return this;
     }
 
     /**
      * Set a list of labels for the builder.
      *
+     * <p>Retro-compatibility is ensured by generating label keys automatically with "label_" and
+     * incremented by the index of list.
+     *
+     * <p>Examples : label_1, label_2, label_3...
+     *
      * @param labels the list of labels to add
      * @return the builder instance
+     * @deprecated since 2.3.0, use labelIdentifier() instead
      */
+    @Deprecated(
+        since =
+            "Deprecated since version 2.3.0, use labelIdentifier() instead. Scheduled for removal in version 3.0.0.",
+        forRemoval = true)
     public Builder labels(@NotNull List<String> labels) {
-      this.labels = List.copyOf(labels);
+      AtomicInteger index = new AtomicInteger(1);
+      this.labelIdentifier =
+          LabelIdentifier.of(
+              labels.stream()
+                  .map(
+                      label -> IdentificationProperty.of("label_" + index.getAndIncrement(), label))
+                  .collect(Collectors.toUnmodifiableList()));
       return this;
     }
 
     /**
      * Set a list of labels for the builder.
      *
+     * <p>Retro-compatibility is ensured by generating label keys automatically with "label_" and
+     * incremented by the index of list.
+     *
+     * <p>Examples : label_1, label_2, label_3...
+     *
      * @param labels the list of labels to add
      * @return the builder instance
+     * @deprecated since 2.3.0, use labelIdentifier() instead
      */
+    @Deprecated(
+        since =
+            "Deprecated since version 2.3.0, use labelIdentifier() instead. Scheduled for removal in version 3.0.0.",
+        forRemoval = true)
     public Builder labels(String... labels) {
-      this.labels = List.of(labels);
+      AtomicInteger index = new AtomicInteger(1);
+      this.labelIdentifier =
+          LabelIdentifier.of(
+              Stream.of(labels)
+                  .map(
+                      label -> IdentificationProperty.of("label_" + index.getAndIncrement(), label))
+                  .collect(Collectors.toUnmodifiableList()));
+      return this;
+    }
+
+    /**
+     * Sets the label identifier for the builder.
+     *
+     * @param labelIdentifier the labels for the item
+     * @return the builder instance
+     */
+    public Builder labelIdentifier(@NotNull LabelIdentifier labelIdentifier) {
+      this.labelIdentifier = labelIdentifier;
+      return this;
+    }
+
+    /**
+     * Sets the label identifier for the builder.
+     *
+     * @param identificationProperty the labels for the item
+     * @return the builder instance
+     */
+    public Builder labelIdentifier(IdentificationProperty identificationProperty) {
+      this.labelIdentifier = LabelIdentifier.of(identificationProperty);
       return this;
     }