Unify multi-label representation in addV step hierarchy

Collapse the separate Set<Object>/List<Traversal.Admin<?,?>> label
representations into a single Collection<Object>-typed label field
across AbstractAddElementStepPlaceholder, AbstractAddVertexStepPlaceholder,
AddVertexStepPlaceholder, and AddVertexStartStepPlaceholder, with a
private canonical constructor and setLabel() as the single source of
truth for label normalization (constructor and post-construction calls
now behave identically).

Fix AddVertexStep/AddVertexStartStep: introduce a single 'label' field
replacing the disconnected internalParameters T.label entry and the
separate labelTraversals field, so getLabel()/setLabel() are no longer
blind to multi-traversal labels.

getLabel() resolves ConstantTraversal/GValueConstantTraversal elements
to their String value where possible, and otherwise returns the
unresolved Traversal itself (consistent with existing AddEdgeStep
behavior), rather than silently dropping or throwing on unresolvable
elements.

Add/update javadoc on AddElementStepContract.getLabel()/setLabel() to
document actual return/accepted types and drop the previously-implied
'set once' contract, which is not honored uniformly by all
implementations (e.g. AddEdgeStep permits overwriting).

Assisted-by: Kiro:claude-sonnet-5

Author: Cole-Greer

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.java

@@ -1476,7 +1476,7 @@ public default GraphTraversal<S, Vertex> addV(final Traversal<?, ?> first, final
             return this.asAdmin().addStep(new AddVertexStepPlaceholder<>(this.asAdmin(), first.asAdmin()));
         } else {
             this.asAdmin().getGremlinLang().addStep(Symbols.addV, first, more);
-            final List<Traversal.Admin<?, ?>> allTraversals = new ArrayList<>(more.length + 1);
+            final Collection<Object> allTraversals = new LinkedHashSet<>(more.length + 1);
             allTraversals.add(first.asAdmin());
             for (final Traversal<?, ?> t : more) {
                 allTraversals.add(t.asAdmin());
@@ -1515,7 +1515,7 @@ public default GraphTraversal<S, Vertex> addV(final GValue<String> label, final
             return this.asAdmin().addStep(new AddVertexStepPlaceholder<>(this.asAdmin(), label));
         } else {
             this.asAdmin().getGremlinLang().addStep(Symbols.addV, label, additionalLabels);
-            final LinkedHashSet<Object> allLabels = new LinkedHashSet<>();
+            final Collection<Object> allLabels = new LinkedHashSet<>();
             allLabels.add(label);
             Collections.addAll(allLabels, additionalLabels);
             return this.asAdmin().addStep(new AddVertexStepPlaceholder<>(this.asAdmin(), allLabels));

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversalSource.java

@@ -376,7 +376,7 @@ public GraphTraversal<Vertex, Vertex> addV(final Traversal<?, ?> label, final Tr
         } else {
             clone.gremlinLang.addStep(GraphTraversal.Symbols.addV, label, additionalLabels);
             final GraphTraversal.Admin<Vertex, Vertex> traversal = new DefaultGraphTraversal<>(clone);
-            final List<Traversal.Admin<?, ?>> allTraversals = new ArrayList<>(additionalLabels.length + 1);
+            final Collection<Object> allTraversals = new LinkedHashSet<>(additionalLabels.length + 1);
             allTraversals.add(label.asAdmin());
             for (final Traversal<?, ?> t : additionalLabels) {
                 allTraversals.add(t.asAdmin());

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AbstractAddElementStepPlaceholder.java

@@ -20,6 +20,7 @@
 
 import org.apache.tinkerpop.gremlin.process.traversal.Traversal;
 import org.apache.tinkerpop.gremlin.process.traversal.Traverser;
+import org.apache.tinkerpop.gremlin.process.traversal.lambda.ConstantTraversal;
 import org.apache.tinkerpop.gremlin.process.traversal.lambda.GValueConstantTraversal;
 import org.apache.tinkerpop.gremlin.process.traversal.step.GValue;
 import org.apache.tinkerpop.gremlin.process.traversal.step.GValueHolder;
@@ -55,58 +56,32 @@ public abstract class AbstractAddElementStepPlaceholder<S, E extends Element, X
     protected Parameters withConfiguration = new Parameters();
 
     protected AbstractAddElementStepPlaceholder(final Traversal.Admin traversal, final String label) {
-        super(traversal);
-        this.label = label == null ? this.getDefaultLabel() : label;
+        this(traversal, (Object) label);
     }
 
     protected AbstractAddElementStepPlaceholder(final Traversal.Admin traversal, final GValue<String> label) {
-        super(traversal);
-        this.label = label == null ? this.getDefaultLabel() : label;
-        if (label != null && label.isVariable()) {
-            traversal.getGValueManager().register(label);
-        }
+        this(traversal, (Object) label);
     }
 
     protected AbstractAddElementStepPlaceholder(final Traversal.Admin traversal, final Traversal.Admin<S,?> labelTraversal) {
-        super(traversal);
-        this.label = labelTraversal == null ? this.getDefaultLabel() : labelTraversal;
-        if (labelTraversal instanceof GValueConstantTraversal) {
-            traversal.getGValueManager().register(((GValueConstantTraversal<S, String>) labelTraversal).getGValue());
-        }
-        addTraversal(labelTraversal);
-    }
-
-    protected AbstractAddElementStepPlaceholder(final Traversal.Admin traversal, final Set<Object> labels) {
-        super(traversal);
-        if (labels == null || labels.isEmpty()) {
-            this.label = this.getDefaultLabel();
-        } else {
-            this.label = labels;
-            for (final Object l : labels) {
-                if (l instanceof GValue && ((GValue<?>) l).isVariable()) {
-                    traversal.getGValueManager().register((GValue<?>) l);
-                }
-            }
-        }
+        this(traversal, (Object) labelTraversal);
     }
 
     /**
-     * Constructor for multiple label traversals. Each traversal resolves to a single String label
-     * at execution time.
+     * Constructor for multiple labels, each of which may be a {@code String}, a {@link GValue}, or a
+     * {@link Traversal.Admin} that resolves to a single {@code String} label at execution time.
      *
      * @param traversal the parent traversal
-     * @param labelTraversals the list of label-producing traversals (must have 2+ elements)
+     * @param labels the labels to add (must have 2+ elements; {@code null} or empty results in the default label)
      */
-    protected AbstractAddElementStepPlaceholder(final Traversal.Admin traversal, final List<Traversal.Admin<?, ?>> labelTraversals) {
+    protected AbstractAddElementStepPlaceholder(final Traversal.Admin traversal, final Collection<Object> labels) {
+        this(traversal, (Object) labels);
+    }
+
+    private AbstractAddElementStepPlaceholder(final Traversal.Admin traversal, final Object label) {
         super(traversal);
-        if (labelTraversals == null || labelTraversals.isEmpty()) {
-            this.label = this.getDefaultLabel();
-        } else {
-            this.label = labelTraversals;
-            for (final Traversal.Admin<?, ?> t : labelTraversals) {
-                addTraversal(t);
-            }
-        }
+        this.label = this.getDefaultLabel();
+        if (label != null) setLabel(label);
     }
 
     protected abstract String getDefaultLabel();
@@ -136,8 +111,8 @@ protected void addTraversal(final Traversal.Admin<?, ?> traversal) {
         }
         if (label != null && label instanceof Traversal) {
             childTraversals.add(((Traversal<?, ?>) label).asAdmin());
-        } else if (label instanceof List) {
-            for (final Object item : (List<?>) label) {
+        } else if (label instanceof Collection) {
+            for (final Object item : (Collection<?>) label) {
                 if (item instanceof Traversal) {
                     childTraversals.add(((Traversal<?, ?>) item).asAdmin());
                 }
@@ -206,8 +181,8 @@ public boolean isParameterized() {
                 (elementId instanceof GValue && ((GValue<?>) elementId).isVariable())) {
             return true;
         }
-        if (label instanceof Set) {
-            for (final Object l : (Set<?>) label) {
+        if (label instanceof Collection) {
+            for (final Object l : (Collection<?>) label) {
                 if (l instanceof GValue && ((GValue<?>) l).isVariable()) {
                     return true;
                 }
@@ -227,41 +202,76 @@ public Object getLabel() {
             traversal.getGValueManager().pinVariable(((GValue<?>) label).getName());
             return ((GValue<?>) label).get();
         }
-        if (label instanceof Set) {
-            final Set<String> resolved = new LinkedHashSet<>();
-            for (final Object l : (Set<?>) label) {
-                if (l instanceof GValue) {
-                    traversal.getGValueManager().pinVariable(((GValue<?>) l).getName());
-                    resolved.add((String) ((GValue<?>) l).get());
-                } else {
-                    resolved.add((String) l);
-                }
+        if (label instanceof Collection) {
+            final Set<Object> resolved = new LinkedHashSet<>();
+            for (final Object l : (Collection<?>) label) {
+                resolved.add(resolveLabelElement(l));
             }
             return resolved;
         }
+        if (label instanceof Traversal) {
+            return resolveLabelElement(label);
+        }
         return label;
     }
 
+    /**
+     * Resolves a single label element. Handles {@code GValue}, {@code ConstantTraversal}, and
+     * {@code GValueConstantTraversal}, which can be resolved to a {@code String} without a live
+     * {@code Traverser}. Any other {@code Traversal} cannot be resolved statically and is returned as-is.
+     */
+    private Object resolveLabelElement(final Object l) {
+        if (l instanceof GValue) {
+            traversal.getGValueManager().pinVariable(((GValue<?>) l).getName());
+            return ((GValue<?>) l).get();
+        }
+        if (l instanceof GValueConstantTraversal) {
+            traversal.getGValueManager().pinVariable(((GValueConstantTraversal<?, ?>) l).getGValue().getName());
+            return ((GValueConstantTraversal<?, ?>) l).next();
+        }
+        if (l instanceof ConstantTraversal) {
+            return ((ConstantTraversal<?, ?>) l).next();
+        }
+        return l;
+    }
+
     @Override
     public Object getLabelWithGValue() {
         return label;
     }
 
     @Override
     public void setLabel(Object label) {
-        if (this.label.equals(this.getDefaultLabel())) {
-            if (label instanceof Traversal) {
-                this.label = ((Traversal<S, String>) label).asAdmin();
-                this.integrateChild((Traversal.Admin<?, ?>) this.label);
-            } else if (label instanceof GValue) {
-                this.label = label;
+        if (!this.label.equals(this.getDefaultLabel())) {
+            throw new IllegalArgumentException(String.format("Element T.label has already been set to [%s] and cannot be overridden with [%s]",
+                    this.label, label));
+        }
+        if (label instanceof Traversal) {
+            this.label = ((Traversal<S, String>) label).asAdmin();
+            if (label instanceof GValueConstantTraversal) {
+                traversal.getGValueManager().register(((GValueConstantTraversal<S, String>) label).getGValue());
+            }
+            addTraversal((Traversal.Admin<?, ?>) this.label);
+        } else if (label instanceof GValue) {
+            this.label = label;
+            if (((GValue<?>) label).isVariable()) {
                 traversal.getGValueManager().register((GValue<?>) label);
-            } else {
-                this.label = label;
+            }
+        } else if (label instanceof Collection) {
+            final Collection<?> labels = (Collection<?>) label;
+            if (labels.isEmpty()) {
+                return;
+            }
+            this.label = new LinkedHashSet<>(labels);
+            for (final Object l : labels) {
+                if (l instanceof Traversal) {
+                    addTraversal(((Traversal<?, ?>) l).asAdmin());
+                } else if (l instanceof GValue && ((GValue<?>) l).isVariable()) {
+                    traversal.getGValueManager().register((GValue<?>) l);
+                }
             }
         } else {
-            throw new IllegalArgumentException(String.format("Element T.label has already been set to [%s] and cannot be overridden with [%s]",
-                    this.label, label));
+            this.label = label;
         }
     }
 
@@ -364,10 +374,10 @@ public void setElementId(Object elementId) {
     public void updateVariable(String name, Object value) {
         if (label instanceof GValue && name.equals(((GValue<?>) label).getName())) {
             label = GValue.of(name, value);
-        } else if (label instanceof Set) {
+        } else if (label instanceof Collection) {
             final LinkedHashSet<Object> updated = new LinkedHashSet<>();
             boolean changed = false;
-            for (final Object l : (Set<?>) label) {
+            for (final Object l : (Collection<?>) label) {
                 if (l instanceof GValue && name.equals(((GValue<?>) l).getName())) {
                     updated.add(GValue.of(name, value));
                     changed = true;
@@ -396,8 +406,8 @@ public Collection<GValue<?>> getGValues() {
         Set<GValue<?>> gValues = GValueHelper.getGValuesFromProperties(properties);
         if (label instanceof GValue && ((GValue<?>) label).isVariable()) {
             gValues.add((GValue<?>) label);
-        } else if (label instanceof Set) {
-            for (final Object l : (Set<?>) label) {
+        } else if (label instanceof Collection) {
+            for (final Object l : (Collection<?>) label) {
                 if (l instanceof GValue && ((GValue<?>) l).isVariable()) {
                     gValues.add((GValue<?>) l);
                 }
@@ -423,11 +433,13 @@ public AbstractAddElementStepPlaceholder<S, E, X> clone() {
                 clone.label = ((Traversal<?, ?>) this.label).asAdmin().clone();
             } else if (this.label instanceof GValue) {
                 clone.label = ((GValue<?>) this.label).clone();
-            } else if (this.label instanceof Set) {
+            } else if (this.label instanceof Collection) {
                 final LinkedHashSet<Object> clonedSet = new LinkedHashSet<>();
-                for (final Object l : (Set<?>) this.label) {
+                for (final Object l : (Collection<?>) this.label) {
                     if (l instanceof GValue) {
                         clonedSet.add(((GValue<?>) l).clone());
+                    } else if (l instanceof Traversal) {
+                        clonedSet.add(((Traversal<?, ?>) l).asAdmin().clone());
                     } else {
                         clonedSet.add(l);
                     }

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AbstractAddVertexStepPlaceholder.java

@@ -24,9 +24,8 @@
 import org.apache.tinkerpop.gremlin.process.traversal.step.util.event.Event;
 import org.apache.tinkerpop.gremlin.structure.Vertex;
 
-import java.util.List;
+import java.util.Collection;
 import java.util.Objects;
-import java.util.Set;
 
 public abstract class AbstractAddVertexStepPlaceholder<S> extends AbstractAddElementStepPlaceholder<S, Vertex, Event.VertexAddedEvent>
         implements AddVertexStepContract<S>, GValueHolder<S, Vertex> {
@@ -35,27 +34,18 @@ public abstract class AbstractAddVertexStepPlaceholder<S> extends AbstractAddEle
 
     protected AbstractAddVertexStepPlaceholder(final Traversal.Admin traversal, final String label) {
         super(traversal, label);
-        userProvidedLabel = label != null;
     }
 
     protected AbstractAddVertexStepPlaceholder(final Traversal.Admin traversal, final GValue<String> label) {
         super(traversal, label);
-        userProvidedLabel = label != null;
     }
 
     protected AbstractAddVertexStepPlaceholder(final Traversal.Admin traversal, final Traversal.Admin<S,?> vertexLabelTraversal) {
         super(traversal, vertexLabelTraversal);
-        userProvidedLabel = vertexLabelTraversal != null;
     }
 
-    protected AbstractAddVertexStepPlaceholder(final Traversal.Admin traversal, final Set<Object> labels) {
+    protected AbstractAddVertexStepPlaceholder(final Traversal.Admin traversal, final Collection<Object> labels) {
         super(traversal, labels);
-        userProvidedLabel = labels != null && !labels.isEmpty();
-    }
-
-    protected AbstractAddVertexStepPlaceholder(final Traversal.Admin traversal, final List<Traversal.Admin<?, ?>> labelTraversals) {
-        super(traversal, labelTraversals);
-        userProvidedLabel = labelTraversals != null && !labelTraversals.isEmpty();
     }
 
     @Override

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AddElementStepContract.java

@@ -19,6 +19,7 @@
 package org.apache.tinkerpop.gremlin.process.traversal.step.map;
 
 import org.apache.tinkerpop.gremlin.process.traversal.Step;
+import org.apache.tinkerpop.gremlin.process.traversal.Traversal;
 import org.apache.tinkerpop.gremlin.process.traversal.step.Configuring;
 import org.apache.tinkerpop.gremlin.process.traversal.step.PropertiesHolder;
 import org.apache.tinkerpop.gremlin.process.traversal.step.Scoping;
@@ -37,12 +38,28 @@ public interface AddElementStepContract<S, E> extends Step<S, E>, PropertiesHold
     List<Class<? extends Step>> CONCRETE_STEPS = Stream.of(AddVertexStepContract.CONCRETE_STEPS, AddEdgeStepContract.CONCRETE_STEPS)
             .flatMap(List::stream).collect(Collectors.toList());
 
+    /**
+     * Gets the label(s) assigned to the element produced by this step. Returns a single value, or a
+     * {@code Set} when multiple labels were specified (e.g. {@code addV("a", "b")}). Each individual label
+     * value will either be a {@code String} or {@link Traversal} depending on how it was initially set. Callers
+     * should not assume the type is {@code String} and should check with {@code instanceof} before casting.
+     *
+     * @return a {@code String}, {@code Traversal}, or a {@code Set} containing either
+     */
     Object getLabel();
 
     default Object getLabelWithGValue() {
         return getLabel();
     }
 
+    /**
+     * Sets the label(s) to assign to the element produced by this step. Accepts a single {@code String},
+     * {@code GValue<String>}, or {@code Traversal} resolving to a {@code String}, or a {@code Collection<Object>}
+     * of two or more such values. Should behave identically to specifying the same value at construction time.
+     * Implementations may restrict calling this method more than once at their own discretion.
+     *
+     * @param label a {@code String}, {@code GValue<String>}, {@code Traversal}, or {@code Collection<Object>}
+     */
     void setLabel(Object label);
 
     Object getElementId();