tinkerpop-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From spmalle...@apache.org
Subject [tinkerpop] 01/02: TINKERPOP-2413 Added withEmbedded() to replace withGraph()
Date Wed, 02 Sep 2020 14:25:52 GMT
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 <spmva@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.


Mime
View raw message