TINKERPOP-3017 Added AnonymousTraversalSource.with()

Replaces withEmbedded() and withRemote() and removes the long deprecated withGraph(). A single unified with() removes the need to check the object being given to the AnonymousTraversalSource to decide which method to use. Can't remember why that split was used in the first place. This should make it easier to explain how to use the AnonymousTraversalSource in the first place, requires a bit less typing and simply streamlines the API.

CHANGELOG.asciidoc

@@ -25,6 +25,9 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima
 
 * Added support for deserialization of `Set` for `gremlin-javascript`.
 * Added integer overflow checks.
+* Deprecated `withEmbedded()` and `withRemote()` options on `AnonymousTraversalSource`.
+* Added `with()` on `AnonymousTraversalSource` to cover both embedded and remote creation options.
+* Removed the deprecated `withGraph()` option from `AnonymousTraversalSource`.
 
 == TinkerPop 3.7.0 (Gremfir Master of the Pan Flute)
 

docs/src/dev/provider/index.asciidoc

@@ -580,7 +580,7 @@ include::../../../../gremlin-dotnet/test/Gremlin.Net.IntegrationTest/Docs/Dev/Pr
 ==== RemoteConnection Implementations
 
 A `RemoteConnection` is an interface that is important for usage on traversal sources configured using the
-link:https://tinkerpop.apache.org/docs/x.y.z/reference/#connecting-via-drivers[withRemote()] option. A `Traversal`
+link:https://tinkerpop.apache.org/docs/x.y.z/reference/#connecting-via-drivers[with()] option. A `Traversal`
 that is generated from that source will apply a `RemoteStrategy` which will inject a `RemoteStep` to its end. That
 step will then send the `Bytecode` of the `Traversal` over the `RemoteConnection` to get the results that it will
 iterate.
@@ -1251,7 +1251,7 @@ To demonstrate consider this example:
 cluster = Cluster.open()
 client = cluster.connect()
 aliased = client.alias("g")
-g = traversal().withEmbedded(org.apache.tinkerpop.gremlin.structure.util.empty.EmptyGraph.instance())     <1>
+g = traversal().with(org.apache.tinkerpop.gremlin.structure.util.empty.EmptyGraph.instance())     <1>
 rs = aliased.submit(g.V().both().barrier().both().barrier()).all().get()                    <2>
 aliased.submit(g.V().both().barrier().both().barrier().count()).all().get().get(0).getInt() <3>
 rs.collect{[value: it.getObject().get(), bulk: it.getObject().bulk()]}                      <4>

docs/src/recipes/centrality.asciidoc

@@ -184,6 +184,6 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#pagerank-step[pageRank()
 
 [gremlin-groovy,modern]
 ----
-g = traversal().withEmbedded(graph).withComputer()
+g = traversal().with(graph).withComputer()
 g.V().pageRank().with(PageRank.propertyName,'pageRank').values('pageRank')
 ----

docs/src/recipes/olap-spark-yarn.asciidoc

@@ -105,7 +105,7 @@ conf.setProperty('spark.executor.extraLibraryPath', "$hadoop/lib/native:$hadoop/
 conf.setProperty('gremlin.spark.persistContext', 'true')
 hdfs.copyFromLocal('data/tinkerpop-modern.kryo', 'tinkerpop-modern.kryo')
 graph = GraphFactory.open(conf)
-g = traversal().withEmbedded(graph).withComputer(SparkGraphComputer)
+g = traversal().with(graph).withComputer(SparkGraphComputer)
 g.V().group().by(values('name')).by(both().count())
 ----
 

docs/src/reference/compilers.asciidoc

@@ -67,7 +67,7 @@ may be used as follows:
 [gremlin-groovy,modern]
 ----
 graph = TinkerFactory.createModern()
-g = traversal(SparqlTraversalSource).withEmbedded(graph)                                               <1>
+g = traversal(SparqlTraversalSource).with(graph)                                                       <1>
 g.sparql("""SELECT ?name ?age
             WHERE { ?person v:name ?name . ?person v:age ?age }
             ORDER BY ASC(?age)""")                                                                     <2>
@@ -388,7 +388,7 @@ graph.
 
 [gremlin-groovy,theCrew]
 ----
-g = traversal(SparqlTraversalSource).withEmbedded(graph)
+g = traversal(SparqlTraversalSource).with(graph)
 g.sparql("""SELECT ?name ?startTime
 WHERE {
   ?person v:name "daniel" .
@@ -422,7 +422,7 @@ steps as shown below:
 
 [gremlin-groovy,modern]
 ----
-g = traversal(SparqlTraversalSource).withEmbedded(graph)
+g = traversal(SparqlTraversalSource).with(graph)
 g.sparql("SELECT ?name ?age WHERE { ?person v:name ?name . ?person v:age ?age }")
 g.sparql("SELECT ?name ?age WHERE { ?person v:name ?name . ?person v:age ?age }").select("name")
 g.sparql("SELECT * WHERE { }").out("knows").values("name")

docs/src/reference/gremlin-applications.asciidoc

@@ -109,7 +109,7 @@ The "toy" graph provides a way to get started with Gremlin quickly.
 
 [gremlin-groovy]
 ----
-g = traversal().withEmbedded(TinkerFactory.createModern())
+g = traversal().with(TinkerFactory.createModern())
 g.V()
 g.V().values('name')
 g.V().has('name','marko').out('knows').values('name')
@@ -315,7 +315,7 @@ from the command line.  Consider the following file named `gremlin.groovy`:
 [source,groovy]
 ----
 graph = TinkerFactory.createModern()
-g = traversal().withEmbedded(graph)
+g = traversal().with(graph)
 g.V().each { println it }
 ----
 
@@ -341,7 +341,7 @@ to system out:
 [source,groovy]
 ----
 graph = TinkerFactory.createModern()
-g = traversal().withEmbedded(graph)
+g = traversal().with(graph)
 g.V().has('name',args[0]).each { println it }
 ----
 
@@ -381,7 +381,7 @@ graph might create a script called `init.groovy` like:
 [source,groovy]
 ----
 graph = TinkerFactory.createModern()
-g = traversal().withEmbedded(graph)
+g = traversal().with(graph)
 ----
 
 and then start Gremlin Console as follows:
@@ -569,7 +569,7 @@ params.put("name","marko");
 List<Result> list = client.submit("g.V().has('person','name',name).out('knows')", params).all().get();
 
 // bytecode
-GraphTraversalSource g = traversal().withRemote(DriverRemoteConnection.using("localhost",8182,"g"));
+GraphTraversalSource g = traversal().with(DriverRemoteConnection.using("localhost",8182,"g"));
 List<Vertex> list = g.V().has("person","name","marko").out("knows").toList();
 ----
 [source,groovy]
@@ -580,7 +580,7 @@ def client = cluster.connect()
 def list = client.submit("g.V().has('person','name',name).out('knows')", [name: "marko"]).all().get();
 
 // bytecode
-def g = traversal().withRemote(DriverRemoteConnection.using("localhost",8182,"g"))
+def g = traversal().with(DriverRemoteConnection.using("localhost",8182,"g"))
 def list = g.V().has('person','name','marko').out('knows').toList()
 ----
 [source,csharp]
@@ -595,7 +595,7 @@ const conn = client.open();
 const list = conn.submit("g.V().has('person','name',name).out('knows')",{name: 'marko'}).then(function (response) { ... });
 
 // bytecode
-const g = gtraversal().withRemote(new DriverRemoteConnection('ws://localhost:8182/gremlin'));
+const g = gtraversal().with(new DriverRemoteConnection('ws://localhost:8182/gremlin'));
 const list = g.V().has("person","name","marko").out("knows").toList();
 ----
 [source,python]
@@ -605,7 +605,7 @@ client = Client('ws://localhost:8182/gremlin', 'g')
 list = client.submit("g.V().has('person','name',name).out('knows')",{'name': 'marko'}).all()
 
 # bytecode
-g = traversal().withRemote(DriverRemoteConnection('ws://localhost:8182/gremlin','g'))
+g = traversal().with(DriverRemoteConnection('ws://localhost:8182/gremlin','g'))
 list = g.V().has("person","name","marko").out("knows").toList()
 ----
 [source,go]
@@ -618,7 +618,7 @@ result, err := resultSet.All()
 
 // bytecode
 remote, err := NewDriverRemoteConnection("ws://localhost:8182/gremlin")
-g := Traversal_().WithRemote(remote)
+g := Traversal_().With(remote)
 list, err := g.V().Has("person", "name", "marko").Out("knows").ToList()
 ----
 
@@ -1114,7 +1114,7 @@ method for processing script evaluation requests.
 [[traversalopprocessor]]
 ===== TraversalOpProcessor
 
-The `TraversalOpProcessor` provides a way to accept traversals configured via <<connecting-via-drivers,withRemote()>>.
+The `TraversalOpProcessor` provides a way to accept traversals configured via <<connecting-via-drivers,with()>>.
 It has no special configuration settings.
 
 ==== Serialization
@@ -1521,7 +1521,7 @@ Please see the example usage as follows:
 ----
 graph = TinkerGraph.open()
 graph.createIndex("username",Vertex.class)
-credentials = traversal(CredentialTraversalSource.class).withEmbedded(graph)
+credentials = traversal(CredentialTraversalSource.class).with(graph)
 credentials.user("stephen","password")
 credentials.user("daniel","better-password")
 credentials.user("marko","rainbow-dash")
@@ -2313,7 +2313,7 @@ included. The relevant configuration from the Gremlin Server initialization scri
 
 [source,groovy]
 ----
-globals << [g : traversal().withEmbedded(graph).withStrategies(ReferenceElementStrategy)]
+globals << [g : traversal().with(graph).withStrategies(ReferenceElementStrategy)]
 ----
 
 This configuration is global to Gremlin Server and therefore all methods of connection will always return elements
@@ -2330,7 +2330,7 @@ Cluster cluster = Cluster.open();
 Client client = cluster.connect();
 ResultSet results = client.submit("g.V().hasLabel('person').elementMap('name')");
 
-GraphTraversalSource g = traversal().withRemote('conf/remote-graph.properties');
+GraphTraversalSource g = traversal().with('conf/remote-graph.properties');
 List<Vertex> results = g.V().hasLabel("person").elementMap('name').toList();
 ----
 

docs/src/reference/gremlin-variants.asciidoc

@@ -92,7 +92,7 @@ creating a `GraphTraversalSource`. A `GraphTraversalSource` is created from the
 [source,go]
 ----
 remote, err := gremlingo.NewDriverRemoteConnection("ws://localhost:8182/gremlin")
-g := gremlingo.Traversal_().WithRemote(remote)
+g := gremlingo.Traversal_().With(remote)
 ----
 
 If you need to additional parameters to connection setup, you can pass in a configuration function.
@@ -210,7 +210,7 @@ builds on that content by demonstrating the transactional syntax for Go.
 [source,go]
 ----
 remote, err := NewDriverRemoteConnection("ws://localhost:8182/gremlin")
-g := gremlingo.Traversal_().WithRemote(remote)
+g := gremlingo.Traversal_().With(remote)
 
 // Create a Transaction.
 tx := g.Tx()
@@ -442,7 +442,7 @@ driverRemoteConnection, _ := gremlingo.NewDriverRemoteConnection("ws://localhost
 defer driverRemoteConnection.Close()
 
 // Create social traversal source from graph traversal source.
-social := &socialTraversalSource{gremlingo.Traversal_().WithRemote(driverRemoteConnection)}
+social := &socialTraversalSource{gremlingo.Traversal_().With(driverRemoteConnection)}
 
 // We can now use the social traversal source as well as traversal steps
 resBool, _ := social.persons("marko", "stephen").knows("josh").HasNext()
@@ -629,7 +629,7 @@ to creating a `GraphTraversalSource`. For <<connecting-embedded,embedded>> mode,
 [source,java]
 ----
 Graph graph = ...;
-GraphTraversalSource g = traversal().withEmbedded(graph);
+GraphTraversalSource g = traversal().with(graph);
 ----
 
 Using "g" it is then possible to start writing Gremlin. The "g" allows for the setting of many configuration options
@@ -643,14 +643,14 @@ are provided as follows:
 
 [source,java]
 ----
-GraphTraversalSource g = traversal().withRemote(DriverRemoteConnection.using("localhost",8182,"g"));
+GraphTraversalSource g = traversal().with(DriverRemoteConnection.using("localhost",8182,"g"));
 ----
 
 It is also possible to create it from a configuration. The most basic way to do so involves the following line of code:
 
 [source,java]
 ----
-GraphTraversalSource g = traversal().withRemote('conf/remote-graph.properties');
+GraphTraversalSource g = traversal().with('conf/remote-graph.properties');
 ----
 
 The `remote-graph.properties` file simply provides connection information to the `GraphTraversalSource` which is used
@@ -670,7 +670,7 @@ TinkerPop driver. The driver is configured by the specified `gremlin.remote.driv
 bound to the `GraphTraversalSource` on the remote end with `gremlin.remote.driver.sourceName` which in this case is
 also "g".
 
-There are other ways to configure the traversal using `withRemote()` as it has other overloads. It can take an
+There are other ways to configure the traversal using `with()` as it has other overloads. It can take an
 Apache Commons `Configuration` object which would have keys similar to those shown in the properties file and it
 can also take a `RemoteConnection` instance directly. The latter is interesting in that it means it is possible to
 programmatically construct all aspects of the `RemoteConnection`. For TinkerPop usage, that might mean directly
@@ -680,26 +680,26 @@ the command shown above could be re-written using programmatic construction as f
 [source,java]
 ----
 Cluster cluster = Cluster.open();
-GraphTraversalSource g = traversal().withRemote(DriverRemoteConnection.using(cluster, "g"));
+GraphTraversalSource g = traversal().with(DriverRemoteConnection.using(cluster, "g"));
 ----
 
 Please consider the following example:
 
 [gremlin-groovy]
 ----
-g = traversal().withRemote('conf/remote-graph.properties')
+g = traversal().with('conf/remote-graph.properties')
 g.V().elementMap()
 g.close()
 ----
 
 [source,java]
 ----
-GraphTraversalSource g = traversal().withRemote("conf/remote-graph.properties");
+GraphTraversalSource g = traversal().with("conf/remote-graph.properties");
 List<Map> list = g.V().elementMap();
 g.close();
 ----
 
-Note the call to `close()` above. The call to `withRemote()` internally instantiates a connection via the driver that
+Note the call to `close()` above. The call to `with()` internally instantiates a connection via the driver that
 can only be released by "closing" the `GraphTraversalSource`. It is important to take that step to release network
 resources associated with `g`.
 
@@ -710,7 +710,7 @@ objects and then re-use them.
 ----
 cluster = Cluster.open('conf/remote-objects.yaml')
 client = cluster.connect()
-g = traversal().withRemote(DriverRemoteConnection.using(client, "g"))
+g = traversal().with(DriverRemoteConnection.using(client, "g"))
 g.V().elementMap()
 g.close()
 client.close()
@@ -727,7 +727,7 @@ on the `TraversalSource`. For instance to set request timeout to 500 millisecond
 
 [source,java]
 ----
-GraphTraversalSource g = traversal().withRemote(conf);
+GraphTraversalSource g = traversal().with(conf);
 List<Vertex> vertices = g.with(Tokens.ARGS_EVAL_TIMEOUT, 500L).V().out("knows").toList()
 ----
 
@@ -834,7 +834,7 @@ Cluster cluster = Cluster.build().
                           serializer(serializer).
                           create();
 Client client = cluster.connect();
-GraphTraversalSource g = traversal().withRemote(DriverRemoteConnection.using(client, "g"));
+GraphTraversalSource g = traversal().with(DriverRemoteConnection.using(client, "g"));
 ----
 
 The `IoRegistry` tells the serializer what classes from the graph provider to auto-register during serialization.
@@ -1077,7 +1077,7 @@ Using the DSL then just involves telling the `Graph` to use it:
 
 [source,java]
 ----
-SocialTraversalSource social = traversal(SocialTraversalSource.class).withEmbedded(graph);
+SocialTraversalSource social = traversal(SocialTraversalSource.class).with(graph);
 social.V().has("name","marko").knows("josh");
 ----
 
@@ -1133,7 +1133,7 @@ It is then possible to use the `persons()` method to start traversals:
 
 [source,java]
 ----
-SocialTraversalSource social = traversal(SocialTraversalSource.class).withEmbedded(graph);
+SocialTraversalSource social = traversal(SocialTraversalSource.class).with(graph);
 social.persons("marko").knows("josh");
 ----
 
@@ -1245,15 +1245,15 @@ the remote end.
 
 [source,javascript]
 ----
-const g = traversal().withRemote(new DriverRemoteConnection('ws://localhost:8182/gremlin'));
+const g = traversal().with(new DriverRemoteConnection('ws://localhost:8182/gremlin'));
 ----
 
 Gremlin-JavaScript supports plain text SASL authentication, you can set it on the connection options.
 
 [source,javascript]
 ----
 const authenticator = new gremlin.driver.auth.PlainTextSaslAuthenticator('myuser', 'mypassword');
-const g = traversal().withRemote(new DriverRemoteConnection('ws://localhost:8182/gremlin', { authenticator });
+const g = traversal().with(new DriverRemoteConnection('ws://localhost:8182/gremlin', { authenticator });
 ----
 
 Given that I/O operations in Node.js are asynchronous by default, <<terminal-steps,Terminal Steps>> return a `Promise`:
@@ -1369,7 +1369,7 @@ builds on that content by demonstrating the transactional syntax for Javascript.
 
 [source,javascript]
 ----
-const g = traversal().withRemote(new DriverRemoteConnection('ws://localhost:8182/gremlin'));
+const g = traversal().with(new DriverRemoteConnection('ws://localhost:8182/gremlin'));
 const tx = g.tx(); // create a Transaction
 
 // spawn a new GraphTraversalSource binding all traversals established from it to tx
@@ -1567,7 +1567,7 @@ To use the DSL, simply initialize the `g` as follows:
 
 [source,javascript]
 ----
-const g = traversal(SocialTraversalSource).withRemote(connection);
+const g = traversal(SocialTraversalSource).with(connection);
 g.person('marko').aged(29).values('name').toList().
   then(names => console.log(names));
 ----
@@ -2514,7 +2514,7 @@ from asynchronous code using a thread.
 [source,python]
 ----
 def print_vertices():
-    g = traversal().withRemote(DriverRemoteConnection("ws://localhost:8182/gremlin"))
+    g = traversal().with(DriverRemoteConnection("ws://localhost:8182/gremlin"))
     # Do your traversal.
 
 async def run_in_thread():

docs/src/reference/implementations-hadoop-start.asciidoc

@@ -148,7 +148,7 @@ which is the OLAP Gremlin machine.
 hdfs.copyFromLocal('data/tinkerpop-modern.kryo', 'tinkerpop-modern.kryo')
 hdfs.ls()
 graph = GraphFactory.open('conf/hadoop/hadoop-gryo.properties')
-g = traversal().withEmbedded(graph)
+g = traversal().with(graph)
 g.V().count()
 g.V().out().out().values('name')
 g.V().group().by{it.value('name')[1]}.by('name').next()