You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by ke...@apache.org on 2024/12/06 06:58:47 UTC
(tinkerpop) branch master updated: Update inaccurate information in documentation CTR.
This is an automated email from the ASF dual-hosted git repository.
kenhuuu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
The following commit(s) were added to refs/heads/master by this push:
new 7b1cc8d205 Update inaccurate information in documentation CTR.
7b1cc8d205 is described below
commit 7b1cc8d205d90dd035f6f53566daa4728262fef0
Author: Ken Hu <10...@users.noreply.github.com>
AuthorDate: Thu Dec 5 22:56:55 2024 -0800
Update inaccurate information in documentation CTR.
Mostly relates to references to bytecode (replaced with GremlinLang) and
WebSockets (replaced with HTTP).
---
docs/src/dev/provider/index.asciidoc | 18 +-
docs/src/reference/gremlin-applications.asciidoc | 222 +++--------------------
docs/src/reference/gremlin-variants.asciidoc | 27 +--
docs/src/reference/intro.asciidoc | 21 ++-
docs/src/reference/the-traversal.asciidoc | 9 +-
5 files changed, 62 insertions(+), 235 deletions(-)
diff --git a/docs/src/dev/provider/index.asciidoc b/docs/src/dev/provider/index.asciidoc
index 20f79e8767..c4f73c027d 100644
--- a/docs/src/dev/provider/index.asciidoc
+++ b/docs/src/dev/provider/index.asciidoc
@@ -582,26 +582,26 @@ include::../../../../gremlin-dotnet/test/Gremlin.Net.IntegrationTest/Docs/Dev/Pr
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[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
+step will then send the `GremlinLang` of the `Traversal` over the `RemoteConnection` to get the results that it will
iterate.
There is one method to implement on `RemoteConnection`:
[source,java]
-public <E> CompletableFuture<RemoteTraversal<?, E>> submitAsync(final Bytecode bytecode) throws RemoteConnectionException;
+public <E> CompletableFuture<RemoteTraversal<?, E>> submitAsync(final GremlinLang gremlinLang) throws RemoteConnectionException;
Note that it returns a `RemoteTraversal`. This interface should also be implemented and in most cases implementers can
simply extend the `AbstractRemoteTraversal`.
TinkerPop provides the `DriverRemoteConnection` as a useful and
link:https://github.com/apache/tinkerpop/blob/x.y.z/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/remote[example implementation].
-`DriverRemoteConnection` serializes the `Traversal` as Gremlin bytecode and then submits it for remote processing on
-Gremlin Server. Gremlin Server rebinds the `Traversal` to a configured `Graph` instance and then iterates the results
-back as it would normally do.
+`DriverRemoteConnection` serializes the `Traversal` as GremlinLang and then submits it for remote processing on
+Gremlin Server. Gremlin Server parses the script into a `Traversal` to a configured `Graph` instance and then iterates
+the results back as it would normally do.
Implementing `RemoteConnection` is not something routinely done for those implementing `gremlin-core`. It is only
something required if there is a need to exploit remote traversal submission. If a graph provider has a "graph server"
-similar to Gremlin Server that can accept bytecode-based requests on its own protocol, then that would be one example
+similar to Gremlin Server that can accept traversal-based requests on its own protocol, then that would be one example
of a reason to implement this interface.
[[bulk-import-export]]
@@ -1070,7 +1070,7 @@ user-agent: NotAvailable Gremlin-Java.4.0.0 11.0.25 Windows_11.10.0 amd64
===== Request Header Value Options
-[width="100%",cols="3,10",options="header"]
+[width="100%",cols="2,10",options="header"]
|=========================================================
|Name |Options
|mimetype |A MIME type listed in <<serializers>>.
@@ -1120,7 +1120,7 @@ serialized. In that case, the `Content-Type` of the response should be `applicat
===== Response Message Format
-[width="100%",cols="3,10a",options="header"]
+[width="100%",cols="2,10a",options="header"]
|=========================================================
|Key |Description
|result |A map that contains the result data.
@@ -1163,7 +1163,7 @@ serialized. In that case, the `Content-Type` of the response should be `applicat
The following table details the HTTP status codes that Gremlin Server will send:
-[width="100%",cols="2,2,9",options="header"]
+[width="100%",cols="1,3,9",options="header"]
|=========================================================
|Code |Name |Description
|200 |SUCCESS |The server successfully processed a request to completion - there are no messages remaining in this stream.
diff --git a/docs/src/reference/gremlin-applications.asciidoc b/docs/src/reference/gremlin-applications.asciidoc
index 8cdb7d6c4b..037222e3d3 100644
--- a/docs/src/reference/gremlin-applications.asciidoc
+++ b/docs/src/reference/gremlin-applications.asciidoc
@@ -499,8 +499,8 @@ executing. It is up to the script to properly commit or rollback transactions i
[[connecting-via-drivers]]
=== Connecting via Drivers
-image:rexster-connect.png[width=180,float=right] TinkerPop offers client-side drivers for the Gremlin Server websocket
-sub-protocol in a variety of languages:
+image:rexster-connect.png[width=180,float=right] TinkerPop offers client-side drivers for the Gremlin Server that
+communicates via the TinkerPop HTTP API in a variety of languages:
* <<gremlin-dotnet,C#>>
* <<gremlin-go,Go>>
@@ -509,9 +509,9 @@ sub-protocol in a variety of languages:
* <<gremlin-python,Python>>
These drivers provide methods to send Gremlin based requests and get back traversal results as a response. The requests
-may be script-based or bytecode-based. As discussed earlier in the <<connecting-gremlin-server,introduction>> the
-recommendation is to use bytecode-based requests. The difference between sending scripts and sending bytecode are
-demonstrated below in some basic examples:
+are script-based or traversal-based. Traversals are internally translated into a `gremlin-lang` compatible script.
+Traversals are still the recommended way to send Gremlin as it has better integration with your language of choice. The
+difference between sending scripts and sending traversals are demonstrated below in some basic examples:
[source,java,tab]
----
@@ -576,8 +576,8 @@ g := Traversal_().With(remote)
list, err := g.V().Has("person", "name", "marko").Out("knows").ToList()
----
-The advantage of bytecode over scripts should be apparent from the above examples. Scripts are just strings that are
-embedded in code (in the above examples, the strings are Groovy-based) whereas bytecode based requests are themselves
+The advantage of traversals over scripts should be apparent from the above examples. Scripts are just strings that are
+embedded in code (in the above examples, the strings are Groovy-based) whereas traversal based requests are themselves
code written in the native language of use. Obviously, the advantage of the Gremlin being actual code is that there
are checks (e.g. compile-time, auto-complete and other IDE support, language level checks, etc.) that help validate the
Gremlin during the development process.
@@ -717,11 +717,6 @@ curl -X POST -d "{\"gremlin\":\"100-x\", \"language\":\"gremlin-groovy\", \"bind
By default this value is set to `gremlin-groovy`. If using a `GET` operation, this value can be set as a query
string argument with by setting the `language` key.
-WARNING: Consider the size of the result of a submitted script being returned from the HTTP endpoint. A script
-that iterates thousands of results will serialize each of those in memory into a single JSON result set. It is
-quite possible that such a script will generate `OutOfMemoryError` exceptions on the server. Consider the default
-WebSocket configuration, which supports streaming, if that type of use case is required.
-
=== Configuring
The `gremlin-server.sh` file serves multiple purposes. It can be used to "install" dependencies to the Gremlin
@@ -823,9 +818,6 @@ The following table describes the various YAML configuration options that Gremli
|metrics.slf4jReporter.enabled |Turns on SLF4j reporting of metrics. |false
|metrics.slf4jReporter.interval |Time in milliseconds between reports of metrics to SLF4j. |180000
|port |The port to bind the server to. |8182
-|processors |A `List` of `Map` settings, where each `Map` represents a `OpProcessor` implementation to use along with its configuration. |_none_
-|processors[X].className |The full class name of the `OpProcessor` implementation. |_none_
-|processors[X].config |A `Map` containing `OpProcessor` specific configurations. |_none_
|resultIterationBatchSize |Defines the size in which the result of a request is "batched" back to the client. In other words, if set to `1`, then a result that had ten items in it would get each result sent back individually. If set to `2` the same ten results would come back in five batches of two each. |64
|scriptEngines |A `Map` of `ScriptEngine` implementations to expose through Gremlin Server, where the key is the name given by the `ScriptEngine` implementation. The key must match the name exactly for the `ScriptEngine` to be constructed. The value paired with this key is itself a `Map` of configuration for that `ScriptEngine`. If this value is not set, it will default to "gremlin-groovy". |_gremlin-groovy_
|scriptEngines.<name>.imports |A comma separated list of classes/packages to make available to the `ScriptEngine`. |_none_
@@ -855,53 +847,6 @@ The following table describes the various YAML configuration options that Gremli
See the <<metrics,Metrics>> section for more information on how to configure Ganglia and Graphite.
-[[opprocessor-configurations]]
-==== OpProcessor Configurations
-
-An `OpProcessor` provides a way to plug-in handlers to Gremlin Server's processing flow. Gremlin Server uses this
-plug-in system itself to expose the packaged functionality that it exposes. Configurations can be supplied to an
-`OpProcessor` through the `processors` key in the Gremlin Server configuration file. Each `OpProcessor` can take a
-`Map` of arguments which are specific to a particular implementation:
-
-[source,yaml]
-----
-processors:
- - { className: org.apache.tinkerpop.gremlin.server.op.session.SessionOpProcessor, config: { sessionTimeout: 28800000 }}
-----
-
-The following sub-sections describe those configurations for each `OpProcessor` implementations supplied with Gremlin
-Server.
-
-===== SessionOpProcessor
-
-The `SessionOpProcessor` provides a way to interact with Gremlin Server over a <<sessions,session>>.
-
-[width="100%",cols="3,10,^2",options="header"]
-|=========================================================
-|Name |Description |Default
-|globalFunctionCacheEnabled |Determines if the script engine cache for global functions is enabled and behaves as an override to the plugin specific setting of the same name. |true
-|maxParameters |Maximum number of parameters that can be passed on the request. |16
-|perGraphCloseTimeout |Time in milliseconds to wait for each configured graph to close any open transactions when the session is killed. |10000
-|sessionTimeout |Time in milliseconds before a session will time out. |28800000
-|=========================================================
-
-===== StandardOpProcessor
-
-The `StandardOpProcessor` provides a way to interact with Gremlin Server without use of sessions and is the default
-method for processing script evaluation requests.
-
-[width="100%",cols="3,10,^2",options="header"]
-|=========================================================
-|Name |Description |Default
-|maxParameters |Maximum number of parameters that can be passed on the request. |16
-|=========================================================
-
-[[traversalopprocessor]]
-===== TraversalOpProcessor
-
-The `TraversalOpProcessor` provides a way to accept traversals configured via <<connecting-via-drivers,with()>>.
-It has no special configuration settings.
-
==== Serialization
Gremlin Server can accept requests and return results using different serialization formats. Serializers implement the
@@ -938,12 +883,8 @@ available GraphSON serializers that can be configured:
[width="100%",cols="2,2,4,4",options="header"]
|=========================================================
|Version |Embedded Types |Mime Type |Class
-|1.0 |yes |`application/vnd.gremlin-v1.0+json` |`GraphSONMessageSerializerGremlinV1`
-|1.0 |no |`application/vnd.gremlin-v1.0+json;types=false` |`GraphSONUntypedMessageSerializerV1`
-|2.0 |yes |`application/vnd.gremlin-v2.0+json` |`GraphSONMessageSerializerV2`
-|2.0 |no |`application/vnd.gremlin-v2.0+json;types=false` |`GraphSONUntypedMessageSerializerV2`
-|3.0 |yes |`application/vnd.gremlin-v3.0+json` |`GraphSONMessageSerializerV3`
-|3.0 |no |`application/vnd.gremlin-v3.0+json;types=false` |`GraphSONMessageSerializerV3`
+|4.0 |yes |`application/vnd.gremlin-v4.0+json` |`GraphSONMessageSerializerV4`
+|4.0 |no |`application/vnd.gremlin-v4.0+json;types=false` |`GraphSONMessageSerializerV4`
|=========================================================
The above serializer classes can be found in the `org.apache.tinkerpop.gremlin.util.ser` package of `gremlin-util`.
@@ -959,10 +900,10 @@ Configuring GraphSON in the Gremlin Server configuration looks like this:
[source,yaml]
----
- - { className: org.apache.tinkerpop.gremlin.util.ser.GraphSONMessageSerializerV3 }
+ - { className: org.apache.tinkerpop.gremlin.util.ser.GraphSONMessageSerializerV4 }
----
-Gremlin Server is configured by default with GraphSON 3.0 as shown above. It has the following configuration option:
+Gremlin Server is configured by default with GraphSON 4.0 as shown above. It has the following configuration option:
[width="100%",cols="3,10,^2",options="header"]
|=========================================================
@@ -970,23 +911,11 @@ Gremlin Server is configured by default with GraphSON 3.0 as shown above. It has
|ioRegistries |A list of `IoRegistry` implementations to be applied to the serializer. |_none_
|=========================================================
-It is worth noting that GraphSON 1.0 still has some appeal for some users as it can be configured to produce an untyped
-JSON format which is a bit easier to consume than its successors which embed data types into the output. This version
-of GraphSON tends to be the one that users like to utilize when <<connecting-via-http,connecting via HTTP>> and is still
-used by some <<connecting-rgp, Remote Gremlin Providers>> for this purpose.
+It is possible for two serializers to bind to the same mime type such as `application/json`. When such conflicts arise,
+Gremlin Server will use the order of the serializers to determine priority such that the first serializer to bind to a
+type will be used and the others ignored. The following log message will indicate how the server is ultimately configured:
-To configure Gremlin Server this way, the `GraphSONMessageSerializerV1d0` must be included:
-
-[source,yaml]
-----
- - { className: org.apache.tinkerpop.gremlin.util.ser.GraphSONMessageSerializerV1 }
- - { className: org.apache.tinkerpop.gremlin.util.ser.GraphSONMessageSerializerV3 }
-----
-
-In the above situation, both `GraphSONMessageSerializerV1d0` and `GraphSONMessageSerializerV3d0` each bind to the
-`application/json` mime type. When such conflicts arise, Gremlin Server will use the order of the serializers to
-determine priority such that the first serializer to bind to a type will be used and the others ignored. The following
-log message will indicate how the server is ultimately configured:
+NOTE: The below examples use GraphSON 1.0 and GraphSON 3.0 for example purposes, however, they are no longer available.
[source,text]
----
@@ -1013,20 +942,18 @@ both the client and the server, as well as limiting the size of the payload that
format itself is described in the link:https://tinkerpop.apache.org/docs/x.y.z/dev/io/#graphbinary[IO Documentation].
[source,yaml]
- - { className: org.apache.tinkerpop.gremlin.util.ser.GraphBinaryMessageSerializerV1 }
+ - { className: org.apache.tinkerpop.gremlin.util.ser.GraphBinaryMessageSerializerV4 }
-It has the MIME type of `application/vnd.graphbinary-v1.0` and the following configuration options:
+It has the MIME type of `application/vnd.graphbinary-v4.0` and the following configuration options:
[width="100%",cols="3,10,^2",options="header"]
|=========================================================
|Key |Description |Default
-|custom |A list of classes with custom kryo `Serializer` implementations related to them in the form of `<class>;<serializer-class>`. |_none_
|ioRegistries |A list of `IoRegistry` implementations to be applied to the serializer. |_none_
|builder |Name of the `TypeSerializerRegistry.Builder` instance to be used to construct the `TypeSerializerRegistry`. |_none_
|=========================================================
-As described above, there are multiple ways in which to register serializers for GraphBinary-based serialization. Note
-that the `ioRegistries` setting is applied first, followed by the `custom` setting.
+As described above, there are multiple ways in which to register serializers for GraphBinary-based serialization.
[[metrics]]
==== Metrics
@@ -1353,6 +1280,8 @@ is hardly feasible, because such requests get full access to Gremlin Server's ex
execution of `GraphFactory.open()` or `GraphTraversalSource.getGraph()` methods without resorting to TinkerPop
implementation details (that is, internal API's that can change without notice).
+IMPORTANT: 4.0 Milestone Release - These authorization mechanisms don't currently apply due to the removal of Bytecode.
+
The three mechanisms for authorization each have their merits in terms of simplicity and flexibility. The table below
gives an overview.
@@ -1384,8 +1313,8 @@ such as read only access can be either applied at authorization time as policy i
execution time as a result of an applied `Strategy` (denoted as 'hybrid' bytecode analysis in the table). A code
example pursuing the former option is provided in the <<authz-code-example, next section>>.
-NOTE: Both the passive and active authorization solutions need to analyze the gremlin bytecode of the original request
-for unwanted removal of restricting Strategies.
+IMPORTANT: 4.0 Milestone Release - passive and active authorization mechanisms are not supported in this milestone
+because bytecode has been replaced with GremlinLang.
NOTE: Gremlin Server is not shipped with `Authorizer` implementations, because these would heavily depend on the external
systems to integrate with, e.g. link:https://ldap.com/directory-servers/[LDAP systems] or
@@ -1982,10 +1911,10 @@ It was mentioned above at the start of this "Best Practices" section that serial
by the requesting system. This point begs for further clarification as there are a number of ways to use and configure
Gremlin Server which might influence its interpretation.
-To begin to discuss these nuances, first consider the method of making requests to Gremlin Server: script or bytecode.
+To begin to discuss these nuances, first consider the method of making requests to Gremlin Server: script or traversal.
For scripts, that will mean that users are sending string representation of Gremlin to the server directly through a
-driver over websockets or through the HTTP. For bytecode, users will be utilize a <<gremlin-drivers-variants, Gremlin GLV>>
-which will construct bytecode for them and submit the request to the server upon iteration of their traversal.
+driver or over HTTP. For bytecode, users will be utilize a <<gremlin-drivers-variants, Gremlin GLV>> which will
+construct bytecode for them and submit the request to the server upon iteration of their traversal.
In either case, it is important to also consider the method of "detachment". Detachment refers to the manner in which
a graph element is disconnected from the graph for purpose of serialization. Depending on the case and configuration,
@@ -2089,9 +2018,9 @@ to the TinkerPop dev list which outlines the full history of this issue and rela
If Gremlin Server processes a large number of unique scripts, the global function cache will grow beyond the memory
available to Gremlin Server and an `OutOfMemoryError` will loom. Script parameterization goes a long way to solving
this problem and running out of memory should not be an issue for those cases. If it is a problem or if there is no
-script parameterization due to a given use case (perhaps using with use of <<sessions,sessions>>), it is possible to
-better control the nature of the global function cache from the client side, by issuing scripts with a parameter to
-help define how the garbage collector should treat the references.
+script parameterization due to a given use case, it is possible to better control the nature of the global function
+cache from the client side, by issuing scripts with a parameter to help define how the garbage collector should treat
+the references.
The parameter is called `#jsr223.groovy.engine.keep.globals` and has four options:
@@ -2136,101 +2065,6 @@ By default, the cache is set to `softValues` which means they are garbage collec
manner as memory gets low. For production systems, it is likely that a more predictable strategy be taken as shown
above with the use of the `maximumSize`.
-[[sessions]]
-==== Considering Sessions
-
-The preferred approach for issuing script-based requests to Gremlin Server is to do so in a sessionless manner. The
-concept of "sessionless" refers to a request that is completely encapsulated within a single transaction, such that
-the script in the request starts with a new transaction and ends with a closed transaction. Sessionless requests have
-automatic transaction management handled by Gremlin Server, thus automatically opening and closing transactions as
-previously described. The downside to the sessionless approach is that the entire script to be executed must be known
-at the time of submission so that it can all be executed at once. This requirement makes it difficult for some use
-cases where more control over the transaction is desired.
-
-For such use cases, Gremlin Server supports sessions. With sessions, the user is in complete control of the start
-and end of the transaction. This feature comes with some additional expense to consider:
-
-* Initialization scripts will be executed for each session created so any expense related to them will be established
-each time a session is constructed.
-* There will be one script cache per session, which obviously increases memory requirements. The cache is not shared,
-so as to ensure that a session has isolation from other session environments. As a result, if the same script is
-executed in each session the same compilation cost will be paid for each session it is executed in.
-* Each session will require its own thread pool with a single thread in it - this ensures that transactional
-boundaries are managed properly from one request to the next.
-* If there are multiple Gremlin Server instances, communication from the client to the server must be bound to the
-server that the session was initialized in. Gremlin Server does not share session state as the transactional context
-of a `Graph` is bound to the thread it was initialized in.
-
-To connect to a session with Java via the `gremlin-driver`, it is necessary to create a `SessionedClient` from the
-`Cluster` object:
-
-[source,java]
-----
-Cluster cluster = Cluster.open(); <1>
-Client client = cluster.connect("sessionName"); <2>
-----
-
-<1> Opens a reference to `localhost` as <<gremlin-java,previously shown>>.
-<2> Creates a `SessionedClient` given the configuration options of the Cluster. The `connect()` method is given a
-`String` value that becomes the unique name of the session. It is often best to simply use a `UUID` to represent
-the session.
-
-It is also possible to have Gremlin Server manage the transactions as is done with sessionless requests. The user is
-in control of enabling this feature when creating the `SessionedClient`:
-
-[source,java]
-----
-Cluster cluster = Cluster.open();
-Client client = cluster.connect("sessionName", true);
-----
-
-Specifying `true` to the `connect()` method signifies that the `client` should make each request as one encapsulated
-in a transaction. With this configuration of `client` there is no need to close a transaction manually.
-
-When using this mode of the `SessionedClient` it is important to recognize that global variable state for the session
-is not rolled-back on failure depending on where the failure occurs. For example, sending the following script would
-create a variable "x" in global session scope that would be accessible on the next request:
-
-[source,groovy]
-x = 1
-
-However, sending this script which explicitly throws an exception:
-
-[source,groovy]
-y = 2
-throw new RuntimeException()
-
-will result in an obvious failure during script evaluation and "y" will not be available to the next request. The
-complication arises where the script evaluates successfully, but fails during result iteration or serialization. For
-example, this script:
-
-[source,groovy]
-a = 1
-g.addV()
-
-would successfully evaluate and return a `Traversal`. The variable "a" would be available on the next request. However,
-if there was a failure in transaction management on the call to `commit()`, "a" would still be available to the next
-request.
-
-To avoid unexpected problems with state in relation to errors in sessions, it is best to follow these guidelines:
-
-* Do not re-use session identifiers. Simply use a new UUID for each session.
-* On exception, be sure to call `close()` on the `Client` and create a new session.
-* While you may submit parallel asynchronous requests to a session, it may not make sense to do so because they are
-simply executed serially as they arrive to the session. A failed asynchronous request could leave an invalid state
-in the session which may not allow later requests to succeed. Either use synchronous requests only or carefully
-consider error conditions with asynchronous requests.
-
-[source,java]
-----
-Client.SessionSettings settings =
- Client.SessionSettings.build().maintainStateAfterException(true).create();
-Client session = cluster.connect(Client.Settings.build().useSession(settings).create());
-----
-
-A session is a "heavier" approach to the simple "request/response" approach of sessionless requests, but is sometimes
-necessary for a given use case.
-
[[considering-transactions]]
==== Considering Transactions
diff --git a/docs/src/reference/gremlin-variants.asciidoc b/docs/src/reference/gremlin-variants.asciidoc
index adc349fb50..8f9440a945 100644
--- a/docs/src/reference/gremlin-variants.asciidoc
+++ b/docs/src/reference/gremlin-variants.asciidoc
@@ -33,12 +33,12 @@ as well.
TinkerPop provides an array of drivers in different programming languages as a way to connect to a remote Gremlin
Server or Remote Gremlin Provider. Drivers allow the developer to make requests to that remote system and get back
-results from the TinkerPop-enabled graphs hosted within. A driver can submit Gremlin strings and Gremlin bytecode
-over this sub-protocol. Gremlin strings are written in the scripting language made available by the remote system that
+results from the TinkerPop-enabled graphs hosted within. A driver can submit Gremlin strings and Gremlin traversals
+over this HTTP protocol. Gremlin strings are written in the scripting language made available by the remote system that
the driver is connecting to (typically, Groovy-based). This connection approach is quite similar to what developers
are likely familiar with when using JDBC and SQL.
-The preferred approach is to use bytecode-based requests, which essentially allows the ability to craft Gremlin
+The preferred approach is to use traversal-based requests, which essentially allows the ability to craft Gremlin
directly in the programming language of choice. As Gremlin makes use of two fundamental programming constructs:
link:https://en.wikipedia.org/wiki/Function_composition[function composition] and
link:https://en.wikipedia.org/wiki/Nested_function[function nesting], it is possible to embed the Gremlin language
@@ -798,7 +798,7 @@ The following table describes the various configuration options for the Gremlin
|auth.password |The password to submit on requests that require basic authentication. |_none_
|auth.region |The region setting for sigv4 authentication. |_none_
|auth.serviceName |The service name setting for sigv4 authentication. |_none_
-|connectionPool.connectionSetupTimeoutMillis | Duration of time in milliseconds provided for connection setup to complete which includes WebSocket protocol handshake and SSL handshake. |15000
+|connectionPool.connectionSetupTimeoutMillis | Duration of time in milliseconds provided for connection setup to complete which includes the SSL handshake. |15000
|connectionPool.enableSsl |Determines if SSL should be enabled or not. If enabled on the server then it must be enabled on the client. |false
|connectionPool.idleConnectionTimeout | Duration of time in milliseconds that the driver will allow a channel to not receive read or writes before it automatically closes. |180000
|connectionPool.keyStore |The private key in JKS or PKCS#12 format. |_none_
@@ -1478,15 +1478,6 @@ for (const vertex of result2) {
}
----
-It is also possible to initialize the `Client` to use <<sessions,sessions>>:
-
-[source,javascript]
-----
-const client = new gremlin.driver.Client('ws://localhost:8182/gremlin', { traversalSource: 'g', 'session': 'unique-string-id' });
-----
-
-With this configuration, the state of variables within scripts are preserved between requests.
-
==== Per Request Settings
The `client.submit()` functions accept a `requestOptions` which expects a dictionary. The `requestOptions`
@@ -1915,14 +1906,6 @@ If the remote system has authentication and SSL enabled, then the `GremlinServer
include::../../../gremlin-dotnet/test/Gremlin.Net.IntegrationTest/Docs/Reference/GremlinVariantsTests.cs[tags=submittingScriptsWithAuthentication]
----
-It is also possible to initialize the `Client` to use <<sessions,sessions>>:
-
-[source,csharp]
-----
-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
@@ -2332,7 +2315,7 @@ re-construction machine-side.
[[gremlin-python-transactions]]
=== Transactions
-WARNING: Transaction is currently disabled in this Milestone release.
+IMPORTANT: 4.0 Milestone Release - Transactions are currently disabled in this Milestone release.
To get a full understanding of this section, it would be good to start by reading the <<transactions,Transactions>>
section of this documentation, which discusses transactions in the general context of TinkerPop itself. This section
diff --git a/docs/src/reference/intro.asciidoc b/docs/src/reference/intro.asciidoc
index 86d4bbceda..d6b472d9af 100644
--- a/docs/src/reference/intro.asciidoc
+++ b/docs/src/reference/intro.asciidoc
@@ -422,6 +422,9 @@ has two such formats that it uses with link:https://tinkerpop.apache.org/docs/x.
link:https://tinkerpop.apache.org/docs/x.y.z/dev/io/#graphson[GraphSON]. Users should prefer GraphBinary when available
in the programming language being used.
+IMPORTANT: 4.0 Milestone Release - There is temporary support for GraphSON in the Java driver which will help with
+testing, but it is expected that the drivers will only support GraphBinary when 4.0 is fully released.
+
A good example is the `subgraph()`-step which returns a `Graph` instance as its result. The subgraph returned from
the server can be deserialized into an actual `Graph` instance on the client, which then means it is possible to
spawn a `GraphTraversalSource` from that to do local Gremlin traversals on the client-side. For non-JVM
@@ -429,9 +432,11 @@ spawn a `GraphTraversalSource` from that to do local Gremlin traversals on the c
no GTM to process Gremlin so there isn't much that can be done with such a result.
The second point is related to this issue. As there is no GTM, there is no "structure" API and thus graph elements like
-`Vertex` and `Edge` are "references" only. A "reference" means that they only contain the `id` and `label` of the
+`Vertex` and `Edge` are usually "references". A "reference" means that they only contain the `id` and `label` of the
element and not the properties. To be consistent, even JVM-based languages hold this limitation when talking to a
-remote Gremlin Server.
+remote Gremlin Server. However, you can alternatively get a "detached" element when using the `all` option for
+`materializeProperties`. In this case, the element will contain all of its properties, but will not be connected to any
+other element.
IMPORTANT: Most SQL developers would not write a query as `SELECT * FROM table`. They would instead write the
individual names of the fields they wanted in place of the wildcard. Writing "good" Gremlin is no different with this
@@ -440,15 +445,17 @@ regard. Prefer explicit property key names in Gremlin unless it is completely im
The third and final point involves transactions. Under this model, one traversal is equivalent to a single transaction
and there is no way in TinkerPop to string together multiple traversals into the same transaction.
+IMPORTANT: 4.0 Milestone Release - Remote transactions are not supported in this milestone.
+
[[connecting-rgp]]
=== Remote Gremlin Provider
Remote Gremlin Providers (RGPs) are showing up more and more often in the graph database space. In TinkerPop terms,
this category of graph providers is defined by those 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.
+server-based graphs, often cloud-based, which accept Gremlin scripts 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, 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
@@ -556,7 +563,7 @@ therefore recommended that users avoid usage of methods like `Graph.addVertex()`
prefer 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
+is to avoid <<connecting-embedded,embedded>> mode and stick to the traversal-based approaches explained in the
<<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.
diff --git a/docs/src/reference/the-traversal.asciidoc b/docs/src/reference/the-traversal.asciidoc
index 237e83eb15..36a7d81667 100644
--- a/docs/src/reference/the-traversal.asciidoc
+++ b/docs/src/reference/the-traversal.asciidoc
@@ -54,7 +54,7 @@ traversal strategies may not function properly.
[[transactions]]
== Traversal Transactions
-WARNING: Transaction is currently disabled in this Milestone release.
+IMPORTANT: 4.0 Milestone Release - Transactions are currently disabled in this Milestone release.
image:gremlin-coins.png[width=100,float=right] A link:http://en.wikipedia.org/wiki/Database_transaction[database transaction]
represents a unit of work to execute against the database. A traversals unit of work is affected by usage convention
@@ -277,13 +277,16 @@ Graph API and thus also the transactional model described in the <<tx-embedded,e
script can have the ability to execute multiple transactions per request with complete control provided to the
developer to commit or rollback transactions as needed.
+IMPORTANT: 4.0 Milestone Release - Transactions are currently disabled in this Milestone release.
+
There are two methods for sending scripts to Gremlin Server: sessionless and session-based. With sessionless requests
there will always be an attempt to close the transaction at the end of the request with a commit if there are no errors
or a rollback if there is a failure. It is therefore unnecessary to close transactions manually within scripts
themselves. By default, session-based requests do not have this quality. The transaction will be held open on the
server until the user closes it manually. There is an option to have automatic transaction management for sessions.
-More information on this topic can be found in the <<considering-transactions,Considering Transactions>> Section and
-the <<sessions,Considering Sessions>> Section.
+More information on this topic can be found in the <<considering-transactions,Considering Transactions>> Section.
+
+IMPORTANT: 4.0 Milestone Release - Sessions have been removed. All scripts are now sessionless.
[[tx-rgp]]
=== Remote Gremlin Providers