TINKERPOP-2053 Support for OptionsStrategy

CHANGELOG.asciidoc

@@ -25,6 +25,7 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima
 
 This release also includes changes from <<release-3-3-3, 3.3.3>>.
 
+* Added `OptionsStrategy` to allow traversals to take arbitrary traversal-wide configurations.
 * Added text predicates.
 * Rewrote `ConnectiveStrategy` to support an arbitrary number of infix notations in a single traversal.
 * GraphSON `MessageSerializer`s will automatically register the GremlinServerModule to a provided GraphSONMapper.

docs/src/upgrade/release-3.4.x.asciidoc

@@ -483,6 +483,27 @@ All of the changes above basically mean, that if the `Mutating` interface was be
 
 See: link:https://issues.apache.org/jira/browse/TINKERPOP-1975[TINKERPOP-1975]
 
+===== OptionsStrategy
+
+`OptionsStrategy` is a `TraversalStrategy` that makes it possible for users to set arbitrary configurations on a
+`Traversal`. These configurations can be used by graph providers to allow for traversal-level configurations to be
+accessible to their custom steps. A user would write something like:
+
+[source,java]
+----
+g.withStrategies(OptionsStrategy.build().with("specialLimit", 10000).create());
+----
+
+The graph provider could then access that value of "specialLimit" in their custom step (or elsewhere) as follows:
+
+[source,java]
+----
+OptionsStrategy strategy = this.getTraversal().asAdmin().getStrategies().getStrategy(OptionsStrategy.class).get();
+int specialLimit = (int) strategy.getOptions().get("specialLimit");
+----
+
+See: link:https://issues.apache.org/jira/browse/TINKERPOP-2053[TINKERPOP-2053]
+
 ===== Removed hadoop-gremlin Test Artifact
 
 The `hadoop-gremlin` module no longer generates a test jar that can be used as a test dependency in other modules.

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/strategy/decoration/OptionsStrategy.java

@@ -0,0 +1,97 @@
+/*
+ * 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.strategy.decoration;
+
+import org.apache.commons.configuration.Configuration;
+import org.apache.commons.configuration.MapConfiguration;
+import org.apache.tinkerpop.gremlin.process.traversal.Traversal;
+import org.apache.tinkerpop.gremlin.process.traversal.TraversalStrategy;
+import org.apache.tinkerpop.gremlin.process.traversal.strategy.AbstractTraversalStrategy;
+
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * This strategy will not alter the traversal. It is only a holder for configuration options associated with the
+ * traversal meant to be accessed by steps or other classes that might have some interaction with it. It is
+ * essentially a way for users to provide traversal level configuration options that can be used in various ways by
+ * different graph providers.
+ *
+ * @author Stephen Mallette (http://stephen.genoprime.com)
+ */
+public class OptionsStrategy extends AbstractTraversalStrategy<TraversalStrategy.DecorationStrategy> implements TraversalStrategy.DecorationStrategy {
+    private final Map<String, Object> options;
+
+    private OptionsStrategy(final Builder builder) {
+        options = builder.options;
+    }
+
+    /**
+     * Gets the options on the strategy as an immutable {@code Map}.
+     */
+    public Map<String,Object> getOptions() {
+        return Collections.unmodifiableMap(options);
+    }
+
+    @Override
+    public Configuration getConfiguration() {
+        return new MapConfiguration(options);
+    }
+
+    @Override
+    public void apply(final Traversal.Admin<?, ?> traversal) {
+        // has not effect on the traversal itself - simply carries a options with it that individual steps
+        // can choose to use or not.
+    }
+
+    public static OptionsStrategy create(final Configuration configuration) {
+        final Builder builder = build();
+        configuration.getKeys().forEachRemaining(k -> builder.with(k, configuration.getProperty(k)));
+        return builder.create();
+    }
+
+    public static Builder build() {
+        return new Builder();
+    }
+
+    public static class Builder {
+
+        private final Map<String, Object> options = new HashMap<>();
+
+        /**
+         * Adds an key to the configuration with the value of {@code true}.
+         */
+        public Builder with(final String key) {
+            return with(key, true);
+        }
+
+        /**
+         * Adds an option to the configuration.
+         */
+        public Builder with(final String key, final Object value) {
+            options.put(key, value);
+            return this;
+        }
+
+        public OptionsStrategy create() {
+            return new OptionsStrategy(this);
+        }
+    }
+}

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/strategy/decoration/SubgraphStrategy.java

@@ -43,7 +43,6 @@
 import org.apache.tinkerpop.gremlin.process.traversal.step.sideEffect.SideEffectStep;
 import org.apache.tinkerpop.gremlin.process.traversal.step.util.EmptyStep;
 import org.apache.tinkerpop.gremlin.process.traversal.strategy.AbstractTraversalStrategy;
-import org.apache.tinkerpop.gremlin.process.traversal.traverser.TraverserRequirement;
 import org.apache.tinkerpop.gremlin.process.traversal.util.DefaultTraversal;
 import org.apache.tinkerpop.gremlin.process.traversal.util.TraversalHelper;
 import org.apache.tinkerpop.gremlin.structure.Direction;

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/graphson/GraphSONModule.java

@@ -38,6 +38,7 @@
 import org.apache.tinkerpop.gremlin.process.traversal.strategy.decoration.ElementIdStrategy;
 import org.apache.tinkerpop.gremlin.process.traversal.strategy.decoration.EventStrategy;
 import org.apache.tinkerpop.gremlin.process.traversal.strategy.decoration.HaltedTraverserStrategy;
+import org.apache.tinkerpop.gremlin.process.traversal.strategy.decoration.OptionsStrategy;
 import org.apache.tinkerpop.gremlin.process.traversal.strategy.decoration.PartitionStrategy;
 import org.apache.tinkerpop.gremlin.process.traversal.strategy.decoration.SubgraphStrategy;
 import org.apache.tinkerpop.gremlin.process.traversal.strategy.finalization.MatchAlgorithmStrategy;
@@ -174,6 +175,7 @@ static final class GraphSONModuleV3d0 extends GraphSONModule {
                             InlineFilterStrategy.class,
                             MatchPredicateStrategy.class,
                             OrderLimitStrategy.class,
+                            OptionsStrategy.class,
                             PathProcessorStrategy.class,
                             PathRetractionStrategy.class,
                             CountStrategy.class,
@@ -291,6 +293,7 @@ protected GraphSONModuleV3d0(final boolean normalize) {
                     InlineFilterStrategy.class,
                     MatchPredicateStrategy.class,
                     OrderLimitStrategy.class,
+                    OptionsStrategy.class,
                     PathProcessorStrategy.class,
                     PathRetractionStrategy.class,
                     CountStrategy.class,
@@ -390,6 +393,7 @@ static final class GraphSONModuleV2d0 extends GraphSONModule {
                             InlineFilterStrategy.class,
                             MatchPredicateStrategy.class,
                             OrderLimitStrategy.class,
+                            OptionsStrategy.class,
                             PathProcessorStrategy.class,
                             PathRetractionStrategy.class,
                             CountStrategy.class,
@@ -499,6 +503,7 @@ protected GraphSONModuleV2d0(final boolean normalize) {
                     InlineFilterStrategy.class,
                     MatchPredicateStrategy.class,
                     OrderLimitStrategy.class,
+                    OptionsStrategy.class,
                     PathProcessorStrategy.class,
                     PathRetractionStrategy.class,
                     CountStrategy.class,

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/gryo/GryoVersion.java

@@ -48,6 +48,7 @@
 import org.apache.tinkerpop.gremlin.process.traversal.step.util.Tree;
 import org.apache.tinkerpop.gremlin.process.traversal.strategy.decoration.ConnectiveStrategy;
 import org.apache.tinkerpop.gremlin.process.traversal.strategy.decoration.HaltedTraverserStrategy;
+import org.apache.tinkerpop.gremlin.process.traversal.strategy.decoration.OptionsStrategy;
 import org.apache.tinkerpop.gremlin.process.traversal.strategy.decoration.PartitionStrategy;
 import org.apache.tinkerpop.gremlin.process.traversal.strategy.decoration.SubgraphStrategy;
 import org.apache.tinkerpop.gremlin.process.traversal.strategy.finalization.MatchAlgorithmStrategy;
@@ -340,6 +341,7 @@ public static List<TypeRegistration<?>> initV3d0Registrations() {
             add(GryoTypeReg.of(LazyBarrierStrategy.class, 150));
             add(GryoTypeReg.of(MatchPredicateStrategy.class, 151));
             add(GryoTypeReg.of(OrderLimitStrategy.class, 152));
+            add(GryoTypeReg.of(OptionsStrategy.class, 187));                            // ***LAST ID***
             add(GryoTypeReg.of(PathProcessorStrategy.class, 153));
             add(GryoTypeReg.of(PathRetractionStrategy.class, 154));
             add(GryoTypeReg.of(CountStrategy.class, 155));
@@ -573,6 +575,7 @@ public static List<TypeRegistration<?>> initV1d0Registrations() {
             add(GryoTypeReg.of(LazyBarrierStrategy.class, 150));
             add(GryoTypeReg.of(MatchPredicateStrategy.class, 151));
             add(GryoTypeReg.of(OrderLimitStrategy.class, 152));
+            add(GryoTypeReg.of(OptionsStrategy.class, 187));                            // ***LAST ID***
             add(GryoTypeReg.of(PathProcessorStrategy.class, 153));
             add(GryoTypeReg.of(PathRetractionStrategy.class, 154));
             add(GryoTypeReg.of(CountStrategy.class, 155));

gremlin-core/src/test/java/org/apache/tinkerpop/gremlin/process/traversal/strategy/decoration/OptionsStrategyTest.java

@@ -0,0 +1,38 @@
+/*
+ * 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.strategy.decoration;
+
+import org.junit.Test;
+
+import static org.hamcrest.core.Is.is;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertThat;
+
+/**
+ * @author Stephen Mallette (http://stephen.genoprime.com)
+ */
+public class OptionsStrategyTest {
+
+    @Test
+    public void shouldCreateOptionsStrategy() {
+        final OptionsStrategy strategy = OptionsStrategy.build().with("a", "test").with("b").create();
+        assertEquals("test", strategy.getOptions().get("a"));
+        assertThat(strategy.getOptions().get("b"), is(true));
+    }
+}

gremlin-dotnet/src/Gremlin.Net/Process/Traversal/Strategy/Decoration/OptionsStrategy.cs

@@ -0,0 +1,53 @@
+#region License
+
+/*
+ * 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.
+ */
+
+#endregion
+
+using System.Collections.Generic;
+
+namespace Gremlin.Net.Process.Traversal.Strategy.Decoration
+{
+    /// <summary>
+    ///     OptionsStrategy makes no changes to the traversal itself - it just carries configuration information
+    ///     at the traversal level.
+    /// </summary>
+    public class OptionsStrategy : AbstractTraversalStrategy
+    {
+        /// <summary>
+        ///     Initializes a new instance of the <see cref="OptionsStrategy" /> class.
+        /// </summary>
+        public OptionsStrategy()
+        {
+        }
+
+        /// <summary>
+        ///     Initializes a new instance of the <see cref="OptionsStrategy" /> class.
+        /// </summary>
+        /// <param name="options">Specifies the options for the traversal.</param>
+        public OptionsStrategy(IDictionary<string,object> options)
+        {
+            foreach(var item in options)
+            {
+                Configuration[item.Key] = item.Value;
+            }
+        }
+    }
+}

gremlin-dotnet/test/Gremlin.Net.IntegrationTest/Process/Traversal/DriverRemoteConnection/GraphTraversalTests.cs

@@ -27,6 +27,7 @@
 using Gremlin.Net.Process.Traversal;
 using Gremlin.Net.Structure;
 using Xunit;
+using Gremlin.Net.Process.Traversal.Strategy.Decoration;
 
 namespace Gremlin.Net.IntegrationTest.Process.Traversal.DriverRemoteConnection
 {
@@ -181,6 +182,26 @@ public void ShouldUseBindingsInTraversal()
             var count = g.V().Has(b.Of("propertyKey", "name"), b.Of("propertyValue", "marko")).OutE().Count().Next();
 
             Assert.Equal(3, count);
+        }  
+
+        [Fact]
+        public void ShouldUseOptionsInTraversal()
+        {
+            // smoke test to validate serialization of OptionsStrategy. no way to really validate this from an integration
+            // test perspective because there's no way to access the internals of the strategy via bytecode
+            var graph = new Graph();
+            var connection = _connectionFactory.CreateRemoteConnection();
+            var options = new Dictionary<string,object>
+            {
+                {"x", "test"},
+                {"y", true}
+            };
+            var g = graph.Traversal().WithRemote(connection);
+
+            var b = new Bindings();
+            var count = g.WithStrategies(new OptionsStrategy(options)).V().Count().Next();
+
+            Assert.Equal(6, count);
         }
 
         [Fact]

gremlin-python/src/main/jython/gremlin_python/process/strategies.py

@@ -45,6 +45,11 @@ def __init__(self, halted_traverser_factory=None):
             self.configuration["haltedTraverserFactory"] = halted_traverser_factory
 
 
+class OptionsStrategy(TraversalStrategy):
+    def __init__(self, options=None):
+        TraversalStrategy.__init__(self, configuration=options)
+
+
 class PartitionStrategy(TraversalStrategy):
     def __init__(self, partition_key=None, write_partition=None, read_partitions=None, include_meta_properties=None):
         TraversalStrategy.__init__(self)

gremlin-python/src/main/jython/tests/driver/test_client.py

@@ -21,6 +21,7 @@
 from gremlin_python.driver.client import Client
 from gremlin_python.driver.protocol import GremlinServerError
 from gremlin_python.driver.request import RequestMessage
+from gremlin_python.process.strategies import OptionsStrategy
 from gremlin_python.process.graph_traversal import __
 from gremlin_python.structure.graph import Graph
 
@@ -70,6 +71,16 @@ def test_client_bytecode(client):
     assert len(result_set.all().result()) == 6
 
 
+def test_client_bytecode_options(client):
+    # smoke test to validate serialization of OptionsStrategy. no way to really validate this from an integration
+    # test perspective because there's no way to access the internals of the strategy via bytecode
+    g = Graph().traversal()
+    t = g.withStrategies(OptionsStrategy(options={"x": "test", "y": True})).V()
+    message = RequestMessage('traversal', 'bytecode', {'gremlin': t.bytecode, 'aliases': {'g': 'gmodern'}})
+    result_set = client.submit(message)
+    assert len(result_set.all().result()) == 6
+
+
 def test_iterate_result_set(client):
     g = Graph().traversal()
     t = g.V()

gremlin-python/src/main/jython/tests/process/test_strategies.py

@@ -90,11 +90,21 @@ def test_configurable(self):
             bytecode.source_instructions[0][1])  # even though different confs, same strategy
         assert 0 == len(g.traversal_strategies.traversal_strategies)  # these strategies are proxies
         ###
-        bytecode = g.withStrategies(SubgraphStrategy(vertices=__.has("name","marko"))).bytecode
+        bytecode = g.withStrategies(SubgraphStrategy(vertices=__.has("name", "marko"))).bytecode
         assert 1 == len(bytecode.source_instructions)
         assert 2 == len(bytecode.source_instructions[0])
         assert "withStrategies" == bytecode.source_instructions[0][0]
         assert SubgraphStrategy() == bytecode.source_instructions[0][1]
         strategy = bytecode.source_instructions[0][1]
         assert 1 == len(strategy.configuration)
         assert __.has("name","marko") == strategy.configuration["vertices"]
+        ###
+        bytecode = g.withStrategies(OptionsStrategy(options={"x": "test", "y": True})).bytecode
+        assert 1 == len(bytecode.source_instructions)
+        assert 2 == len(bytecode.source_instructions[0])
+        assert "withStrategies" == bytecode.source_instructions[0][0]
+        assert OptionsStrategy() == bytecode.source_instructions[0][1]
+        strategy = bytecode.source_instructions[0][1]
+        assert 2 == len(strategy.configuration)
+        assert "test" == strategy.configuration["x"]
+        assert strategy.configuration["y"]