You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by sp...@apache.org on 2020/10/06 10:27:10 UTC

[tinkerpop] 01/01: TINKERPOP-2420 Added docs for request options to all GLVs

This is an automated email from the ASF dual-hosted git repository.

spmallette pushed a commit to branch TINKERPOP-2420
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git

commit 4b85179fbbbedd78260224e394ae493f9fc1bb0f
Author: Stephen Mallette <st...@amazon.com>
AuthorDate: Mon Oct 5 20:09:47 2020 -0400

    TINKERPOP-2420 Added docs for request options to all GLVs
---
 CHANGELOG.asciidoc                                 |  2 +-
 docs/src/reference/gremlin-variants.asciidoc       | 40 ++++++++++++++++++----
 docs/src/upgrade/release-3.4.x.asciidoc            | 32 +++++++++++++++++
 .../Docs/Reference/GremlinVariantsTests.cs         | 18 ++++++++++
 4 files changed, 84 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.asciidoc b/CHANGELOG.asciidoc
index ef6c7a3..fe320c5 100644
--- a/CHANGELOG.asciidoc
+++ b/CHANGELOG.asciidoc
@@ -30,7 +30,7 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima
 * Removed `Connection` from `Connection Pool` when server closes a connection with no pending requests in Java Driver.
 * Improved initialization time of Java Driver if the default serializer is replaced.
 * Deprecated `withGraph()` in favor of `withEmbedded()` on `AnonymousTraversalSource`.
-* Added support for per-request level configurations, like timeouts, in Python and Javascript.
+* Added support for per-request level configurations, like timeouts, in .NET, Python and Javascript.
 * Fixed bug in Javascript `Translator` that wasn't handling child traversals well.
 * Implemented `AutoCloseable` on `MultiIterator`.
 * Fixed an iterator leak in `HasContainer`.
diff --git a/docs/src/reference/gremlin-variants.asciidoc b/docs/src/reference/gremlin-variants.asciidoc
index 70c084e..7f941ad 100644
--- a/docs/src/reference/gremlin-variants.asciidoc
+++ b/docs/src/reference/gremlin-variants.asciidoc
@@ -216,7 +216,7 @@ List<Vertex> vertices = g.with(Tokens.ARGS_EVAL_TIMEOUT, 500L).V().out("knows").
 ----
 
 The following options are allowed on a per-request basis in this fashion: `batchSize`, `requestId`, `userAgent` and
-`evaluationTimeout` (formerly 'scriptEvaluationTimeout' which is also supported but now deprecated). Use of `Tokens`
+`evaluationTimeout` (formerly `scriptEvaluationTimeout` which is also supported but now deprecated). Use of `Tokens`
 to reference these options is preferred.
 
 anchor:java-imports[]
@@ -684,11 +684,11 @@ Some connection options can also be set on individual requests made through the
 
 [source,python]
 ----
-vertices = g.with_('evaluationTimeout', 500L).V().out('knows').toList()
+vertices = g.with_('evaluationTimeout', 500).V().out('knows').toList()
 ----
 
 The following options are allowed on a per-request basis in this fashion: `batchSize`, `requestId`, `userAgent` and
-`evaluationTimeout` (formerly 'scriptEvaluationTimeout' which is also supported but now deprecated).
+`evaluationTimeout` (formerly `scriptEvaluationTimeout` which is also supported but now deprecated).
 
 anchor:python-imports[]
 [[gremlin-python-imports]]
@@ -965,7 +965,7 @@ result_set = client.submit('g.V().repeat(both()).times(100)', result_options={'e
 ----
 
 The following options are allowed on a per-request basis in this fashion: `batchSize`, `requestId`, `userAgent` and
-`evaluationTimeout` (formerly 'scriptEvaluationTimeout' which is also supported but now deprecated).
+`evaluationTimeout` (formerly `scriptEvaluationTimeout` which is also supported but now deprecated).
 
 [[gremlin-python-dsl]]
 === Domain Specific Languages
@@ -1121,6 +1121,18 @@ the remote end.
 include::../../../gremlin-dotnet/test/Gremlin.Net.IntegrationTest/Docs/Reference/GremlinVariantsTests.cs[tags=connecting]
 ----
 
+Some connection options can also be set on individual requests made through the using `With()` step on the
+`TraversalSource`. For instance to set request timeout to 500 milliseconds:
+
+[source,csharp]
+----
+var l = g.With(Tokens.ArgsEvalTimeout, 500).V().Out("knows").Count();
+----
+
+The following options are allowed on a per-request basis in this fashion: `batchSize`, `requestId`, `userAgent` and
+`evaluationTimeout` (formerly `scriptEvaluationTimeout` which is also supported but now deprecated). These options are
+available as constants on the `Gremlin.Net.Driver.Tokens` class.
+
 [[gremlin-dotnet-imports]]
 === Common Imports
 
@@ -1246,6 +1258,20 @@ var gremlinServer = new GremlinServer("localhost", 8182);
 var client = new GremlinClient(gremlinServer, sessionId: Guid.NewGuid().ToString()))
 ----
 
+==== Per Request Settings
+
+The `GremlinClient.submit()` functions accept an option to build a raw `RequestMessage`. A good use-case for this
+feature is to set a per-request override to the `evaluationTimeout` so that it only applies to the current request.
+
+[source,csharp]
+----
+include::../../../gremlin-dotnet/test/Gremlin.Net.IntegrationTest/Docs/Reference/GremlinVariantsTests.cs[tags=submittingScriptsWithTimeout]
+----
+
+The following options are allowed on a per-request basis in this fashion: `batchSize`, `requestId`, `userAgent` and
+`evaluationTimeout` (formerly `scriptEvaluationTimeout` which is also supported but now deprecated). These options are
+available as constants on the `Gremlin.Net.Driver.Tokens` class.
+
 anchor:gremlin-net-dsl[]
 [[gremlin-dotnet-dsl]]
 === Domain Specific Languages
@@ -1418,11 +1444,11 @@ Some connection options can also be set on individual requests made through the
 
 [source,javascript]
 ----
-const vertices = await g.with_('evaluationTimeout', 500L).V().out('knows').toList()
+const vertices = await g.with_('evaluationTimeout', 500).V().out('knows').toList()
 ----
 
 The following options are allowed on a per-request basis in this fashion: `batchSize`, `requestId`, `userAgent` and
-`evaluationTimeout` (formerly 'scriptEvaluationTimeout' which is also supported but now deprecated).
+`evaluationTimeout` (formerly `scriptEvaluationTimeout` which is also supported but now deprecated).
 
 [[gremlin-javascript-imports]]
 === Common Imports
@@ -1504,7 +1530,7 @@ const result = await client.submit("g.V().repeat(both()).times(100)", null, { ev
 ----
 
 The following options are allowed on a per-request basis in this fashion: `batchSize`, `requestId`, `userAgent` and
-`evaluationTimeout` (formerly 'scriptEvaluationTimeout' which is also supported but now deprecated).
+`evaluationTimeout` (formerly `scriptEvaluationTimeout` which is also supported but now deprecated).
 
 [[gremlin-javascript-dsl]]
 === Domain Specific Languages
diff --git a/docs/src/upgrade/release-3.4.x.asciidoc b/docs/src/upgrade/release-3.4.x.asciidoc
index a1bf501..40b2a68 100644
--- a/docs/src/upgrade/release-3.4.x.asciidoc
+++ b/docs/src/upgrade/release-3.4.x.asciidoc
@@ -70,6 +70,38 @@ const sg = g.withStrategies(
 
 See: link:https://issues.apache.org/jira/browse/TINKERPOP-2054[TINKERPOP-2054]
 
+==== Per Request Options
+
+With Java it has been possible to pass per-request settings for both scripts and bytecode. While Javascript, Python,
+and .NET allowed this in various ways, it wasn't quite as convenient as Java, nor was it well documented. In this
+release, the approach for making this sort of per-request configurations is now much more consistent across languages.
+We see this most evident in bytecode based requests:
+
+[source,java,tab]
+----
+g.with(Tokens.ARGS_EVAL_TIMEOUT, 500L).V().out("knows");
+----
+[source,csharp]
+----
+g.With(Tokens.ArgsEvalTimeout, 500).V().Out("knows").Count();
+----
+[source,javascript]
+----
+g.with_('evaluationTimeout', 500).V().out('knows');
+----
+[source,python]
+----
+g.with_('evaluationTimeout', 500).V().out('knows')
+----
+
+Please see the new "Per Request Settings" sections for each language in the
+<<gremlin-drivers-variants, Gremlin Drivers and Variants>> section for information on how to send scripts with specific
+request configurations.
+
+See: link:https://issues.apache.org/jira/browse/TINKERPOP-2296[TINKERPOP-2296],
+link:https://issues.apache.org/jira/browse/TINKERPOP-2420[TINKERPOP-2420],
+link:https://issues.apache.org/jira/browse/TINKERPOP-2421[TINKERPOP-2421]
+
 === Upgrading for Providers
 
 ==== Graph System Providers
diff --git a/gremlin-dotnet/test/Gremlin.Net.IntegrationTest/Docs/Reference/GremlinVariantsTests.cs b/gremlin-dotnet/test/Gremlin.Net.IntegrationTest/Docs/Reference/GremlinVariantsTests.cs
index 723afa6..61264e0 100644
--- a/gremlin-dotnet/test/Gremlin.Net.IntegrationTest/Docs/Reference/GremlinVariantsTests.cs
+++ b/gremlin-dotnet/test/Gremlin.Net.IntegrationTest/Docs/Reference/GremlinVariantsTests.cs
@@ -23,6 +23,7 @@
 
 using System.Threading.Tasks;
 using Gremlin.Net.Driver;
+using Gremlin.Net.Driver.Messages;
 using Gremlin.Net.Driver.Remote;
 using Gremlin.Net.IntegrationTest.Process.Traversal.DriverRemoteConnection;
 using Gremlin.Net.Process.Traversal;
@@ -105,6 +106,23 @@ using (var gremlinClient = new GremlinClient(gremlinServer))
 }
 // end::submittingScripts[]
         }
+        
+        [Fact(Skip="No Server under localhost")]
+        public async Task SubmittingScriptsWithTimeoutTest()
+        {
+// tag::submittingScriptsWithTimeout[]
+var gremlinServer = new GremlinServer("localhost", 8182);
+using (var gremlinClient = new GremlinClient(gremlinServer))
+{
+    var response =
+        await gremlinClient.SubmitWithSingleResultAsync<string>(
+            RequestMessage.Build(Tokens.OpsEval).
+                AddArgument(Tokens.ArgsGremlin, "g.V().count()").
+                AddArgument(Tokens.ArgsEvalTimeout, 500).
+                Create());
+}
+// end::submittingScriptsWithTimeout[]
+        }
 
         [Fact(Skip = "No Server under localhost")]
         public void SubmittingScriptsWithAuthenticationTest()