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/09/02 14:25:52 UTC
[tinkerpop] 01/02: TINKERPOP-2413 Added withEmbedded() to replace
withGraph()
This is an automated email from the ASF dual-hosted git repository.
spmallette pushed a commit to branch TINKERPOP-2413
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit 26e7e8eb451853a04d567a1da3a27f1c367e1f3c
Author: Stephen Mallette <sp...@genoprime.com>
AuthorDate: Wed Sep 2 08:22:37 2020 -0400
TINKERPOP-2413 Added withEmbedded() to replace withGraph()
Deprecated withGraph() where necessary.
---
CHANGELOG.asciidoc | 3 +-
docs/src/upgrade/release-3.4.x.asciidoc | 31 +++++++++++++++++++-
.../traversal/AnonymousTraversalSource.java | 34 ++++++++++++++--------
.../lib/process/anonymous-traversal.js | 15 ++++++----
.../gremlin-javascript/lib/structure/graph.js | 3 ++
5 files changed, 67 insertions(+), 19 deletions(-)
diff --git a/CHANGELOG.asciidoc b/CHANGELOG.asciidoc
index fc23846..262427c 100644
--- a/CHANGELOG.asciidoc
+++ b/CHANGELOG.asciidoc
@@ -26,8 +26,9 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima
* Delegated handling of erroneous response to the worker thread pool instead of event loop thread pool in Java Driver.
* 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`.
* Fixed bug in Javascript `Translator` that wasn't handling child traversals well.
-* Fix an interator leak in HasContainer.
+* Fixed an iterator leak in `HasContainer`.
[[release-3-4-8]]
=== TinkerPop 3.4.8 (Release Date: August 3, 2020)
diff --git a/docs/src/upgrade/release-3.4.x.asciidoc b/docs/src/upgrade/release-3.4.x.asciidoc
index 658659c..7cf4bb2 100644
--- a/docs/src/upgrade/release-3.4.x.asciidoc
+++ b/docs/src/upgrade/release-3.4.x.asciidoc
@@ -21,14 +21,43 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima
*Avant-Gremlin Construction #3 for Theremin and Flowers*
-== TinkerPop 3.4.8
+== TinkerPop 3.4.9
*Release Date: NOT OFFICIALLY RELEASED YET*
Please see the link:https://github.com/apache/tinkerpop/blob/3.4.9/CHANGELOG.asciidoc#release-3-4-9[changelog] for a
complete list of all the modifications that are part of this release.
+=== withEmbedded()
+
+The `AnonymousTraversalSource` was introduced in 3.3.5 and is most typically used for constructing remote
+`TraversalSource` instances, but it also provides a way to construct a `TraversalSource` from an embedded `Graph`
+instance:
+
+[source,text]
+----
+gremlin> g = traversal().withGraph(TinkerFactory.createModern())
+==>graphtraversalsource[tinkergraph[vertices:6 edges:6], standard]
+gremlin> g = traversal().withRemote(DriverRemoteConnection.using('localhost',8182))
+==>graphtraversalsource[emptygraph[empty], standard]
+----
+
+The `withGraph(Graph)` method is now deprecated in favor the new `withEmbedded(Graph)` method that is more explicit
+about its intent:
+[source,text]
+----
+gremlin> g = traversal().withEmbedded(TinkerFactory.createModern())
+==>graphtraversalsource[tinkergraph[vertices:6 edges:6], standard]
+----
+
+This change is mostly applicable to JVM languages where embedded `Graph` instances are available. For Gremlin Language
+Variants not on the JVM, the `withGraph(Graph)` method has simply been deprecated and not replaced (with the preference
+to use `withRemote()` variants).
+
+See: link:https://issues.apache.org/jira/browse/TINKERPOP-2413[TINKERPOP-2413]
+
+== TinkerPop 3.4.8
*Release Date: August 3, 2020*
diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/AnonymousTraversalSource.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/AnonymousTraversalSource.java
index 05fcab7..b0be46f 100644
--- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/AnonymousTraversalSource.java
+++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/AnonymousTraversalSource.java
@@ -24,10 +24,6 @@ import org.apache.tinkerpop.gremlin.process.remote.RemoteConnection;
import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversalSource;
import org.apache.tinkerpop.gremlin.structure.Graph;
-import java.lang.reflect.Constructor;
-
-import static org.apache.tinkerpop.gremlin.process.remote.RemoteConnection.GREMLIN_REMOTE_CONNECTION_CLASS;
-
/**
* Provides a unified way to construct a {@link TraversalSource} from the perspective of the traversal. In this syntax
* the user is creating the source and binding it to a reference which is either an existing {@link Graph} instance
@@ -60,24 +56,28 @@ public class AnonymousTraversalSource<T extends TraversalSource> {
}
/**
- * Creates the specified {@link TraversalSource} binding a {@link RemoteConnection} as its reference such that
- * traversals spawned from it will execute over that reference.
+ * Creates a {@link TraversalSource} binding a {@link RemoteConnection} to a remote {@link Graph} instances as its
+ * reference so that traversals spawned from it will execute over that reference.
+ *
+ * @param configFile a path to a file that would normally be provided to configure a {@link RemoteConnection}
*/
public T withRemote(final String configFile) throws Exception {
return withRemote(new PropertiesConfiguration(configFile));
}
/**
- * Creates the specified {@link TraversalSource} binding a {@link RemoteConnection} as its reference such that
- * traversals spawned from it will execute over that reference.
+ * Creates a {@link TraversalSource} binding a {@link RemoteConnection} to a remote {@link Graph} instances as its
+ * reference so that traversals spawned from it will execute over that reference.
+ *
+ * @param conf a {@code Configuration} object that would normally be provided to configure a {@link RemoteConnection}
*/
public T withRemote(final Configuration conf) {
return withRemote(RemoteConnection.from(conf));
}
/**
- * Creates the specified {@link TraversalSource} binding a {@link RemoteConnection} as its reference such that
- * traversals spawned from it will execute over that reference.
+ * Creates a {@link TraversalSource} binding a {@link RemoteConnection} to a remote {@link Graph} instances as its
+ * reference so that traversals spawned from it will execute over that reference.
*/
public T withRemote(final RemoteConnection remoteConnection) {
try {
@@ -88,10 +88,20 @@ public class AnonymousTraversalSource<T extends TraversalSource> {
}
/**
- * Creates the specified {@link TraversalSource} binding a {@link Graph} as its reference such that traversals
- * spawned from it will execute over that reference.
+ * Creates the specified {@link TraversalSource} binding an embedded {@link Graph} as its reference such that
+ * traversals spawned from it will execute over that reference.
+ *
+ * @deprecated As of release 3.4.9, replaced by {@link #withEmbedded(Graph)}
*/
public T withGraph(final Graph graph) {
+ return withEmbedded(graph);
+ }
+
+ /**
+ * Creates the specified {@link TraversalSource} binding an embedded {@link Graph} as its reference such that
+ * traversals spawned from it will execute over that reference.
+ */
+ public T withEmbedded(final Graph graph) {
try {
return traversalSourceClass.getConstructor(Graph.class).newInstance(graph);
} catch (final Exception e) {
diff --git a/gremlin-javascript/src/main/javascript/gremlin-javascript/lib/process/anonymous-traversal.js b/gremlin-javascript/src/main/javascript/gremlin-javascript/lib/process/anonymous-traversal.js
index ff30a4b..63e1e77 100644
--- a/gremlin-javascript/src/main/javascript/gremlin-javascript/lib/process/anonymous-traversal.js
+++ b/gremlin-javascript/src/main/javascript/gremlin-javascript/lib/process/anonymous-traversal.js
@@ -32,7 +32,7 @@ const Graph = require('../structure/graph').Graph;
class AnonymousTraversalSource {
/**
- * Creates a new instance of {@link AnonymousTraversalSource}.
+ * Creates a new instance of {@code AnonymousTraversalSource}.
* @param {Function} [traversalSourceClass] Optional {@code GraphTraversalSource} constructor.
*/
constructor(traversalSourceClass) {
@@ -50,8 +50,8 @@ class AnonymousTraversalSource {
}
/**
- * Creates the specified {@link GraphTraversalSource{ binding a {@link RemoteConnection} as its reference such that
- * traversals spawned from it will execute over that reference.
+ * Creates a {@link GraphTraversalSource} binding a {@link RemoteConnection} to a remote {@link Graph} instances as its
+ * reference so that traversals spawned from it will execute over that reference.
* @param {GraphTraversalSource} remoteConnection
* @return {GraphTraversalSource}
*/
@@ -60,10 +60,15 @@ class AnonymousTraversalSource {
}
/**
- * Creates the specified {@link GraphTraversalSource} binding a {@link Graph} as its reference such that traversals
- * spawned from it will execute over that reference.
+ * Creates the specified {@link GraphTraversalSource} binding an embedded {@link Graph} as its reference such that
+ * traversals spawned from it will execute over that reference. As there are no "embedded Graph" instances in
+ * gremlin-javascript as there on the JVM, the {@link GraphTraversalSource} can only ever be constructed as "empty"
+ * with a {@link Graph} instance (which is only a reference to a graph and is not capable of holding data). As a
+ * result, the {@link GraphTraversalSource} will do nothing unless a "remote" is then assigned to it later.
* @param {Graph} graph
* @return {GraphTraversalSource}
+ * @deprecated As of release 3.4.9, prefer {@link withRemote} until some form of "embedded graph" becomes available
+ * at which point there will be support for {@code withEmbedded} which is part of the canonical Java API.
*/
withGraph(graph) {
return new this.traversalSourceClass(graph, new TraversalStrategies());
diff --git a/gremlin-javascript/src/main/javascript/gremlin-javascript/lib/structure/graph.js b/gremlin-javascript/src/main/javascript/gremlin-javascript/lib/structure/graph.js
index 359e2f8..78bf435 100644
--- a/gremlin-javascript/src/main/javascript/gremlin-javascript/lib/structure/graph.js
+++ b/gremlin-javascript/src/main/javascript/gremlin-javascript/lib/structure/graph.js
@@ -25,6 +25,9 @@
const gt = require('../process/graph-traversal');
const { TraversalStrategies } = require('../process/traversal-strategy');
+/**
+ * An "empty" graph object to server only as a reference.
+ */
class Graph {
/**
* Returns the graph traversal source.