[tinkerpop] 03/07: Changed from Gremlin Service Provider to Remote Gremlin Provider

[sp...@apache.org]

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

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

commit 3722a088d1511f9a900871596972dfd16bd1e724
Author: Stephen Mallette <sp...@genoprime.com>
AuthorDate: Wed Oct 17 15:35:38 2018 -0400

    Changed from Gremlin Service Provider to Remote Gremlin Provider
    
    Using "remote" in the name is good because it better captures non-cloud based systems that deploy in this fashion.
---
 docs/src/reference/intro.asciidoc         | 18 +++++++++---------
 docs/src/reference/the-graph.asciidoc     | 15 ++++++++-------
 docs/src/reference/the-traversal.asciidoc | 16 ++++++++++------
 3 files changed, 27 insertions(+), 22 deletions(-)

diff --git a/docs/src/reference/intro.asciidoc b/docs/src/reference/intro.asciidoc
index bba00f1..db5eab6 100644
--- a/docs/src/reference/intro.asciidoc
+++ b/docs/src/reference/intro.asciidoc
@@ -317,7 +317,7 @@ of the following places:
 
 * Embedded in a Java application
 * Hosted in Gremlin Server
-* Exposed by a remote Gremlin Service Provider
+* Exposed by a remote Remote Gremlin Provider
 
 The following sections outline each of these models and what they impact they have to using Gremlin.
 
@@ -442,18 +442,18 @@ IMPORTANT: Most SQL developers would not write a query as `SELECT * FROM table`.
 individual names of the fields they wanted in place of the wildcard. Writing "good" Gremlin is no different with this
 regard. Prefer explicit property key names in Gremlin unless it is completely impossible to do so.
 
-[[connecting-gsp]]
-=== Gremlin Service Provider
+[[connecting-rgp]]
+=== Remote Gremlin Provider
 
-Gremlin Service Providers (GSPs) are showing up more and more often in the graph database space. In TinkerPop terms,
+Gremlin Service Providers (RGPs) are showing up more and more often in the graph database space. In TinkerPop terms,
 this category of graph providers are ones who simply support the Gremlin language. Typically, these are server-based
 graphs, often cloud-based, which accept Gremlin scripts or bytecode as a request and return results. They will often
 implement Gremlin Server protocols, which enables TinkerPop drivers to connect to them as they would with Gremlin
 Server. Therefore, the typical connection approach is identical to the method of connection presented in the
 <<connecting-gremlin-server,previous section>> with the exact same caveats pointed out toward the end.
 
-Despite leveraging TinkerPop protocols and drivers as being typical, GSPs are not required to do so to be considered
-TinkerPop-enabled. GSPs may well have their own drivers and protocols that may plug into GLVs and may allow for more
+Despite leveraging TinkerPop protocols and drivers as being typical, RGPs are not required to do so to be considered
+TinkerPop-enabled. RGPs may well have their own drivers and protocols that may plug into GLVs and may allow for more
 advanced options like better security, cluster awareness, batched requests or other features. The details of these
 different systems are outside the scope of this documentation so be sure to consult their documentation for more
 information.
@@ -463,7 +463,7 @@ information.
 
 The `GraphTraversalSource` is basically the connection to a graph instance. That graph instance might be
 <<connecting-embedded,embedded>>, hosted in <<connecting-gremlin-server,Gremlin Server>> or hosted in a
-<<connecting-gsp,GSP>>, but the `GraphTraversalSource` is agnostic to that, because this object allows users to write
+<<connecting-rgp,RGP>>, but the `GraphTraversalSource` is agnostic to that, because this object allows users to write
 Gremlin. Assuming "g" is the `GraphTraversalSource`, getting data into the graph regardless of programming language
 or mode of operation is just some Gremlin:
 
@@ -566,7 +566,7 @@ link:http://tinkerpop.apache.org/docs/x.y.z/tutorials/gremlins-anatomy/#_express
 certain features of that specific graph shine in powerful ways. Using those options is probably recommended, but users
 should be aware that doing so ties them more tightly to that graph.
 * Graph specific semantics - TinkerPop tries to enforce specific semantics through its test suite which is quite
-extensive, but some <<connecting-gsp,Graph Service Providers>> may not completely respect all the semantics
+extensive, but some <<connecting-rgp,Remote Gremlin Providers>> may not completely respect all the semantics
 of the Gremlin language. For the most part, that doesn't disqualify them from being any less TinkerPop-enabled than
 another provider that might meet the semantics perfectly. Take care when considering a new graph and pay attention to
 what it supports and does not support.
@@ -577,7 +577,7 @@ use of Gremlin with `g.addV()` or `g.V(1).properties()`.
 
 Outside of considering these points, the best practice for ensuring the greatest level of compatibility across graphs
 is to avoid <<connecting-embedded,embedded>> mode and stick to the bytecode based approaches explained in the
-<<connecting-gremlin-server,Gremlin Server>> and the <<connecting-gsp,GSP>> sections above. It creates the least
+<<connecting-gremlin-server,Gremlin Server>> and the <<connecting-rgp,RGP>> sections above. It creates the least
 opportunity to stray from the agnostic path as anything that can be done with those two modes also works in embedded
 mode. If using embedded mode, simply write code as though the `Graph` instance is "remote" and not local to the JVM.
 In other words, write code as though the GVM is not available locally. Taking that approach and isolating the points
diff --git a/docs/src/reference/the-graph.asciidoc b/docs/src/reference/the-graph.asciidoc
index ea86b5f..4d58409 100644
--- a/docs/src/reference/the-graph.asciidoc
+++ b/docs/src/reference/the-graph.asciidoc
@@ -46,7 +46,7 @@ possible:
 
 * The application is being developed on the JVM and the developer is using <<connecting-embedded, Embedded>> mode
 * The architecture includes Gremlin Server and the user is sending Gremlin scripts to the server
-* The graph system chosen is a <<connecting-gsp, Gremlin Service Provider>> and they expose the Graph API via scripts
+* The graph system chosen is a <<connecting-rgp, Remote Gremlin Provider>> and they expose the Graph API via scripts
 
 Note that Gremlin Language Variants force developers to use the Graph API by reference. There is no `addVertex()`
 method available to GLVs on their respective `Graph` instances, nor are their graph elements filled with data at the
@@ -214,7 +214,7 @@ image:gremlin-coins.png[width=100,float=right] A link:http://en.wikipedia.org/wi
 represents a unit of work to execute against the database. Transactions in TinkerPop can be considered in several
 contexts: transactions for <<connecting-embedded,embedded graphs>> via the Graph API,
 transactions for <<connecting-gremlin-server,Gremlin Server>> and transactions within
-<<connecting-gsp,Graph Service Providers>>. For those following recommended patterns, the concepts presented in the
+<<connecting-rgp,Remote Gremlin Providers>>. For those following recommended patterns, the concepts presented in the
 embedded section should generally be of little interest and are present mainly for reference. Utilizing those
 transactional features will greatly reduce the portability of an application's Gremlin code.
 
@@ -425,14 +425,15 @@ the <<sessions,Considering Sessions>> Section.
 While those sections provide some additional details, the short advice is to avoid scripts when possible and prefer
 bytecode based requests.
 
-[[tx-gsp]]
-=== Gremlin Service Providers
+[[tx-rgp]]
+=== Remote Gremlin Providers
 
-At this time, transactional patterns for Gremlin Service Providers are largely in line with Gremlin Server. Most
+At this time, transactional patterns for Remote Gremlin Providers are largely in line with Gremlin Server. Most
 offer bytecode or script based sessionless requests, which have automatic transaction management, such that a
-successful traversal will commit on success and a failing traversal will rollback. As most of these GSPs do not
+successful traversal will commit on success and a failing traversal will rollback. As most of these RGPs do not
 expose a `Graph` instances, access to lower level transactional functions even in a sessionless fashion are not
-typically allowed.           
+typically allowed. The nature of what a "transaction" means will be dependent on the RGP as is the case with any
+TinkerPop-enabled graph system, so it is important to consult that systems documentation for more details.
 
 == Namespace Conventions
 
diff --git a/docs/src/reference/the-traversal.asciidoc b/docs/src/reference/the-traversal.asciidoc
index 0fb7006..93a1207 100644
--- a/docs/src/reference/the-traversal.asciidoc
+++ b/docs/src/reference/the-traversal.asciidoc
@@ -162,18 +162,22 @@ g.V().out('created').fill(results) <8>
 g.addV('person').iterate() <9>
 ----
 
-<1> `hasNext()` determines whether there are available results.
+<1> `hasNext()` determines whether there are available results (not supported in `gremlin-javascript`).
 <2> `next()` will return the next result.
-<3> `next(n)` will return the next `n` results in a list.
-<4> `tryNext()` will return an `Optional` and thus, is a composite of `hasNext()`/`next()`.
+<3> `next(n)` will return the next `n` results in a list (not supported in `gremlin-javascript` or Gremlin.NET).
+<4> `tryNext()` will return an `Optional` and thus, is a composite of `hasNext()`/`next()` (only supported for JVM languages).
 <5> `toList()` will return all results in a list.
-<6> `toSet()` will return all results in a set (thus, duplicates removed).
-<7> `toBulkSet()` will return all results in a weighted set (thus, duplicates preserved via weighting).
-<8> `fill(collection)` will put all results in the provided collection and return the collection when complete.
+<6> `toSet()` will return all results in a set and thus, duplicates removed (not supported in `gremlin-javascript`).
+<7> `toBulkSet()` will return all results in a weighted set and thus, duplicates preserved via weighting (only supported for JVM languages).
+<8> `fill(collection)` will put all results in the provided collection and return the collection when complete (only supported for JVM languages).
 <9> `iterate()` does not exactly fit the definition of a terminal step in that it doesn't return a result, but still
 returns a traversal - it does however behave as a terminal step in that it iterates the traversal and generates side
 effects without returning the actual result.
 
+There is also the `promise()` terminator step, which can only be used with remote traversals to
+<<connecting-gremlin-server,Gremlin Server>> or <<connecting-rgp,RGPs>>. It starts a promise to execute a function
+on the current `Traversal` that will be completed in the future.
+
 Finally, <<explain-step,`explain()`>>-step is also a terminal step and is described in its own section.
 
 [[addedge-step]]