Added PopContaining interface, and its implementation in Scoping.java

and TraversalParent.java, and classes that use these interfaces.

Author: Vaibhav Malhotra

CHANGELOG.asciidoc

@@ -30,7 +30,7 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima
 [[release-4-0-0-beta-1]]
 === TinkerPop 4.0.0-beta.1 (January 17, 2025)
 
-* Added a utility function `getScopingInfo()` in all classes implementing `Scoping` and a method `getScopingInfoForTraversal` to get the labels needed by a traversal. 
+* Added an interface `PopContaining` which is implemented by `Scoping` and `TraversalParent`. Used to get label, and Pop info for a step/traversal. The information is wrapped in a `PopInstruction` object
 * Added support for deserialization of `Set` for `gremlin-javascript`.
 * Added grammar-based `Translator` for all languages including explicit ones for Java and anonymization.
 * Removed old `Translator` infrastructure.

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

@@ -0,0 +1,107 @@
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License.
+ */
+package org.apache.tinkerpop.gremlin.process.traversal.step;
+
+import java.util.HashSet;
+import java.util.Objects;
+
+import org.apache.tinkerpop.gremlin.process.traversal.Pop;
+
+/**
+ * The {@code PopContaining} interface is implemented by traversal steps that maintain Pop instructions
+ * for label access. It provides a mechanism to track and manage how labeled elements should
+ * be accessed using {@link Pop} semantics (first, last, all, or mixed).
+ *
+ * In Gremlin traversals, various elements can be labeled and later accessed via these labels.
+ * The {@link Pop} enum determines how to access these labeled elements when there are multiple
+ * values associated with the same label.
+ *
+ * <pre>
+ * {@code
+ * // Simple example with default Pop.last behavior
+ * gremlin> g.V().as("a").out().as("a").select("a")
+ * ==>[v[2]]  // returns the last element labeled "a"
+ *
+ * // Using Pop.first to get the first labeled element
+ * gremlin> g.V().as("a").out().as("a").select(first, "a")
+ * ==>[v[1]]  // returns the first element labeled "a"
+ *
+ * // Using Pop.all to get all labeled elements
+ * gremlin> g.V().as("a").out().as("a").select(all, "a")
+ * ==>[v[1], v[2]]  // returns all elements labeled "a"
+ * }
+ * </pre>
+ *
+ * Steps implementing this interface maintain a collection of {@link PopInstruction} objects, each containing
+ * a label and a {@link Pop} value that specifies how to access elements with that label.
+ *
+ * @author Vaibhav Malhotra
+ */
+public interface PopContaining {
+    public default HashSet<PopInstruction> getPopInstructions() {
+        return new HashSet<PopInstruction>();
+    }
+
+        /**
+         * A class for storing the Scope Context. It has two elements:
+         * - label: String
+         * - pop: Pop value
+         */
+        class PopInstruction {
+            public Pop pop;
+            public String label;
+
+            public PopInstruction(String label, Pop pop) {
+                this.pop = pop;
+                this.label = label;
+            }
+
+            public PopInstruction(Pop pop, String label) {
+                this.pop = pop;
+                this.label = label;
+            }
+
+            public PopInstruction() {
+               this.pop = null;
+               this.label = "";
+            }
+
+        public String getLabel() {
+                return label;
+            }
+
+            public Pop getPop() {
+                return pop;
+            }
+
+            @Override
+            public boolean equals(Object o) {
+                if (o == null || getClass() != o.getClass()) {
+                    return false;
+                }
+                final PopInstruction that = (PopInstruction) o;
+                return getPop() == that.getPop() && Objects.equals(getLabel(), that.getLabel());
+            }
+
+            @Override
+            public int hashCode() {
+                return Objects.hash(getPop(), getLabel());
+            }
+        }
+}

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

@@ -23,8 +23,8 @@
 import org.apache.tinkerpop.gremlin.process.traversal.Step;
 import org.apache.tinkerpop.gremlin.process.traversal.Traverser;
 
+import java.util.HashSet;
 import java.util.Map;
-import java.util.Objects;
 import java.util.Set;
 
 /**
@@ -106,7 +106,7 @@
  * @author Marko A. Rodriguez (http://markorodriguez.com)
  * @author Stephen Mallette (http://stephen.genoprime.com)
  */
-public interface Scoping {
+public interface Scoping extends PopContaining {
 
     public enum Variable {START, END}
 
@@ -168,11 +168,21 @@ public default <S> S getNullableScopeValue(final Pop pop, final String key, fina
     public Set<String> getScopeKeys();
 
     /**
-     * Used to get ScopingInfo of a Step that implements Scoping. Scoping info includes the labels it needs, and the pop type for each label.
+     * Used to get PopInstruction of a Step that implements Scoping. PopInstruction includes the labels it needs, and the
+     * pop type for each label.
      *
-     * @return A Set of {@link ScopingInfo} values which contain the label and Pop value
+     * @return A Set of {@link org.apache.tinkerpop.gremlin.process.traversal.step.PopContaining.PopInstruction} values which contain the label and Pop value
      */
-    public default Set<ScopingInfo> getScopingInfo() {return null; }
+    @Override
+    public default HashSet<PopInstruction> getPopInstructions() {
+        final Set<String> labels = this.getScopeKeys();
+        final HashSet<PopInstruction> scopingInfoSet = new HashSet<>();
+        for (String label : labels) {
+            final PopInstruction scopingInfo = new PopInstruction(Pop.last, label);
+            scopingInfoSet.add(scopingInfo);
+        }
+        return scopingInfoSet;
+    }
 
     public static class KeyNotFoundException extends Exception {
 
@@ -193,39 +203,4 @@ public Scoping getStep() {
             return step;
         }
     }
-
-
-    /**
-     * A class for storing the Scoping information. It has two elements:
-     * - label: String
-     * - pop: Pop value
-     */
-    public static class ScopingInfo {
-        public String label;
-        public Pop pop;
-
-        public ScopingInfo() {
-            this.label = "";
-            this.pop = null;
-        }
-
-        public ScopingInfo(String label, Pop pop) {
-            this.label = label;
-            this.pop = pop;
-        }
-
-        @Override
-        public boolean equals(Object o) {
-            if (o == null || getClass() != o.getClass()) {
-                return false;
-            }
-            ScopingInfo that = (ScopingInfo) o;
-            return Objects.equals(label, that.label) && pop == that.pop;
-        }
-
-        @Override
-        public int hashCode() {
-            return Objects.hash(label, pop);
-        }
-    }
 }

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

@@ -21,16 +21,18 @@
 import org.apache.tinkerpop.gremlin.process.traversal.Step;
 import org.apache.tinkerpop.gremlin.process.traversal.Traversal;
 import org.apache.tinkerpop.gremlin.process.traversal.traverser.TraverserRequirement;
+import org.apache.tinkerpop.gremlin.process.traversal.util.TraversalHelper;
 
 import java.util.Collections;
 import java.util.EnumSet;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
 
 /**
  * @author Marko A. Rodriguez (http://markorodriguez.com)
  */
-public interface TraversalParent extends AutoCloseable {
+public interface TraversalParent extends PopContaining, AutoCloseable {
 
     public default <S, E> List<Traversal.Admin<S, E>> getGlobalChildren() {
         return Collections.emptyList();
@@ -95,4 +97,16 @@ default void close() throws Exception {
             traversal.close();
         }
     }
+
+    @Override
+    public default HashSet<PopInstruction> getPopInstructions() {
+        final HashSet<PopInstruction> scopingInfos = new HashSet<>();
+        for (final Traversal.Admin local: this.getLocalChildren()) {
+            scopingInfos.addAll(TraversalHelper.getPopInstructions(local));
+        }
+        for (final Traversal.Admin global: this.getGlobalChildren()) {
+            scopingInfos.addAll(TraversalHelper.getPopInstructions(global));
+        }
+        return scopingInfos;
+    }
 }

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/filter/DedupGlobalStep.java

@@ -190,16 +190,11 @@ public Set<String> getScopeKeys() {
     }
 
     @Override
-    public Set<ScopingInfo> getScopingInfo() {
-        final Set<String> labels = this.getScopeKeys();
-        final Set<ScopingInfo> scopingInfoSet = new HashSet<>();
-        for (String label : labels) {
-            ScopingInfo scopingInfo = new ScopingInfo();
-            scopingInfo.label = label;
-            scopingInfo.pop = Pop.last;
-            scopingInfoSet.add(scopingInfo);
-        }
-        return scopingInfoSet;
+    public HashSet<PopInstruction> getPopInstructions() {
+        final HashSet<PopInstruction> popInstructions = new HashSet<>();
+        popInstructions.addAll(Scoping.super.getPopInstructions());
+        popInstructions.addAll(TraversalParent.super.getPopInstructions());
+        return popInstructions;
     }
 
     @Override

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/filter/WherePredicateStep.java

@@ -133,16 +133,11 @@ public Set<String> getScopeKeys() {
     }
 
     @Override
-    public Set<ScopingInfo> getScopingInfo() {
-        final Set<String> labels = this.getScopeKeys();
-        final Set<ScopingInfo> scopingInfoSet = new HashSet<>();
-        for (String label : labels) {
-            final ScopingInfo scopingInfo = new ScopingInfo();
-            scopingInfo.label = label;
-            scopingInfo.pop = Pop.last;
-            scopingInfoSet.add(scopingInfo);
-        }
-        return scopingInfoSet;
+    public HashSet<PopInstruction> getPopInstructions() {
+        final HashSet<PopInstruction> popInstructions = new HashSet<>();
+        popInstructions.addAll(Scoping.super.getPopInstructions());
+        popInstructions.addAll(TraversalParent.super.getPopInstructions());
+        return popInstructions;
     }
 
     @Override

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/filter/WhereTraversalStep.java

@@ -148,16 +148,11 @@ public Set<String> getKeepLabels() {
     }
 
     @Override
-    public Set<ScopingInfo> getScopingInfo() {
-        final Set<String> labels = this.getScopeKeys();
-        final Set<ScopingInfo> scopingInfoSet = new HashSet<>();
-        for (String label : labels) {
-            final ScopingInfo scopingInfo = new ScopingInfo();
-            scopingInfo.label = label;
-            scopingInfo.pop = Pop.last;
-            scopingInfoSet.add(scopingInfo);
-        }
-        return scopingInfoSet;
+    public HashSet<PopInstruction> getPopInstructions() {
+        final HashSet<PopInstruction> popInstructions = new HashSet<>();
+        popInstructions.addAll(Scoping.super.getPopInstructions());
+        popInstructions.addAll(TraversalParent.super.getPopInstructions());
+        return popInstructions;
     }
 
     //////////////////////////////

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

@@ -43,6 +43,7 @@
 import org.apache.tinkerpop.gremlin.structure.util.StringFactory;
 import org.apache.tinkerpop.gremlin.structure.util.empty.EmptyGraph;
 
+import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
 
@@ -89,6 +90,14 @@ public Set<String> getScopeKeys() {
         return this.parameters.getReferencedLabels();
     }
 
+    @Override
+    public HashSet<PopInstruction> getPopInstructions() {
+        final HashSet<PopInstruction> popInstructions = new HashSet<>();
+        popInstructions.addAll(Scoping.super.getPopInstructions());
+        popInstructions.addAll(TraversalParent.super.getPopInstructions());
+        return popInstructions;
+    }
+
     @Override
     public void configure(final Object... keyValues) {
         this.parameters.set(this, keyValues);

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

@@ -40,6 +40,7 @@
 import org.apache.tinkerpop.gremlin.structure.util.StringFactory;
 import org.apache.tinkerpop.gremlin.structure.util.empty.EmptyGraph;
 
+import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
 
@@ -86,6 +87,14 @@ public Set<String> getScopeKeys() {
         return this.parameters.getReferencedLabels();
     }
 
+    @Override
+    public HashSet<PopInstruction> getPopInstructions() {
+        final HashSet<PopInstruction> popInstructions = new HashSet<>();
+        popInstructions.addAll(Scoping.super.getPopInstructions());
+        popInstructions.addAll(TraversalParent.super.getPopInstructions());
+        return popInstructions;
+    }
+
     @Override
     public void configure(final Object... keyValues) {
         this.parameters.set(this, keyValues);

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

@@ -38,6 +38,7 @@
 import org.apache.tinkerpop.gremlin.structure.Vertex;
 import org.apache.tinkerpop.gremlin.structure.util.StringFactory;
 
+import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
 
@@ -85,6 +86,14 @@ public Set<String> getScopeKeys() {
         return this.parameters.getReferencedLabels();
     }
 
+    @Override
+    public HashSet<PopInstruction> getPopInstructions() {
+        final HashSet<PopInstruction> popInstructions = new HashSet<>();
+        popInstructions.addAll(Scoping.super.getPopInstructions());
+        popInstructions.addAll(TraversalParent.super.getPopInstructions());
+        return popInstructions;
+    }
+
     @Override
     public <S, E> List<Traversal.Admin<S, E>> getLocalChildren() {
         return this.parameters.getTraversals();