You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by rd...@apache.org on 2017/04/24 16:36:54 UTC
[1/2] tinkerpop git commit: WebSocket is a protocol and a proper noun
- CTR
Repository: tinkerpop
Updated Branches:
refs/heads/tp32 db035d578 -> 273ad2c8e
WebSocket is a protocol and a proper noun - CTR
Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo
Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/4d117cbd
Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/4d117cbd
Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/4d117cbd
Branch: refs/heads/tp32
Commit: 4d117cbd6df0ccc9f8ccef47011e855cea392447
Parents: ec4f83c
Author: Robert Dale <ro...@gmail.com>
Authored: Mon Apr 24 12:12:24 2017 -0400
Committer: Robert Dale <ro...@gmail.com>
Committed: Mon Apr 24 12:12:24 2017 -0400
----------------------------------------------------------------------
docs/src/dev/provider/index.asciidoc | 8 ++++----
docs/src/reference/gremlin-applications.asciidoc | 8 ++++----
docs/src/tutorials/getting-started/index.asciidoc | 4 ++--
3 files changed, 10 insertions(+), 10 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/4d117cbd/docs/src/dev/provider/index.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/dev/provider/index.asciidoc b/docs/src/dev/provider/index.asciidoc
index aa89020..69060af 100644
--- a/docs/src/dev/provider/index.asciidoc
+++ b/docs/src/dev/provider/index.asciidoc
@@ -626,7 +626,7 @@ which should provide enough information to develop a driver for a specific langu
image::gremlin-server-flow.png[width=300,float=right]
-Gremlin Server is distributed with a configuration that utilizes link:http://en.wikipedia.org/wiki/WebSocket[WebSockets]
+Gremlin Server is distributed with a configuration that utilizes link:http://en.wikipedia.org/wiki/WebSocket[WebSocket]
with a custom sub-protocol. Under this configuration, Gremlin Server accepts requests containing a Gremlin script,
evaluates that script and then streams back the results. The notion of "streaming" is depicted in the diagram to the
right.
@@ -674,7 +674,7 @@ A `RequestMessage` to evaluate a script with variable bindings looks like this i
----
The above JSON represents the "body" of the request to send to Gremlin Server. When sending this "body" over
-websockets Gremlin Server can accept a packet frame using a "text" (1) or a "binary" (2) opcode. Using "text"
+WebSocket, Gremlin Server can accept a packet frame using a "text" (1) or a "binary" (2) opcode. Using "text"
is a bit more limited in that Gremlin Server will always process the body of that request as JSON. Generally speaking
"text" is just for testing purposes.
@@ -689,7 +689,7 @@ The first byte represents the length of the "mime type" string value that follow
Gremlin Server, this value should be set to `application/json`. The "payload" represents the JSON message above
encoded as bytes.
-NOTE: Gremlin Server will only accept masked packets as it pertains to websocket packet header construction.
+NOTE: Gremlin Server will only accept masked packets as it pertains to a WebSocket packet header construction.
When Gremlin Server receives that request, it will decode it given the "mime type", pass it to the requested
`OpProcessor` which will execute the `op` defined in the message. In this case, it will evaluate the script
@@ -716,7 +716,7 @@ In this case the `ResponseMessage` returned to the client would look something l
"status":{"code":206,"attributes":{},"message":""}}
----
-Gremlin Server is capable of streaming results such that additional responses will arrive over the websocket until
+Gremlin Server is capable of streaming results such that additional responses will arrive over the WebSocket connection until
the iteration of the result on the server is complete. Each successful incremental message will have a `ResultCode`
of `206`. Termination of the stream will be marked by a final `200` status code. Note that all messages without a
`206` represent terminating conditions for a request. The following table details the various status codes that
http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/4d117cbd/docs/src/reference/gremlin-applications.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/reference/gremlin-applications.asciidoc b/docs/src/reference/gremlin-applications.asciidoc
index c4a1493..a5c162e 100644
--- a/docs/src/reference/gremlin-applications.asciidoc
+++ b/docs/src/reference/gremlin-applications.asciidoc
@@ -297,7 +297,7 @@ NOTE: Gremlin Server is the replacement for link:http://rexster.tinkerpop.com[Re
NOTE: Please see the link:http://tinkerpop.apache.org/docs/x.y.z/dev/provider/[Provider Documentation] for information
on how to develop a driver for Gremlin Server.
-By default, communication with Gremlin Server occurs over link:http://en.wikipedia.org/wiki/WebSocket[WebSockets] and
+By default, communication with Gremlin Server occurs over link:http://en.wikipedia.org/wiki/WebSocket[WebSocket] and
exposes a custom sub-protocol for interacting with the server.
[[starting-gremlin-server]]
@@ -691,7 +691,7 @@ Connecting via REST
~~~~~~~~~~~~~~~~~~~
image:gremlin-rexster.png[width=225,float=left] While the default behavior for Gremlin Server is to provide a
-WebSockets-based connection, it can also be configured to support link:http://en.wikipedia.org/wiki/Representational_state_transfer[REST].
+WebSocket-based connection, it can also be configured to support link:http://en.wikipedia.org/wiki/Representational_state_transfer[REST].
The REST endpoint provides for a communication protocol familiar to most developers, with a wide support of
programming languages, tools and libraries for accessing it. As a result, REST provides a fast way to get started
with Gremlin Server. It also may represent an easier upgrade path from link:http://rexster.tinkerpop.com/[Rexster]
@@ -767,7 +767,7 @@ string argument with by setting the `language` key.
WARNING: Consider the size of the result of a submitted script being returned from the REST 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
-WebSockets configuration, which supports streaming, if that type of use case is required.
+WebSocket configuration, which supports streaming, if that type of use case is required.
Configuring
~~~~~~~~~~~
@@ -802,7 +802,7 @@ The following table describes the various configuration options that Gremlin Ser
|Key |Description |Default
|authentication.className |The fully qualified classname of an `Authenticator` implementation to use. If this setting is not present, then authentication is effectively disabled. |`AllowAllAuthenticator`
|authentication.config |A `Map` of configuration settings to be passes to the `Authenticator` when it is constructed. The settings available are dependent on the implementation. |_none_
-|channelizer |The fully qualified classname of the `Channelizer` implementation to use. A `Channelizer` is a "channel initializer" which Gremlin Server uses to define the type of processing pipeline to use. By allowing different `Channelizer` implementations, Gremlin Server can support different communication protocols (e.g. Websockets, Java NIO, etc.). |`WebSocketChannelizer`
+|channelizer |The fully qualified classname of the `Channelizer` implementation to use. A `Channelizer` is a "channel initializer" which Gremlin Server uses to define the type of processing pipeline to use. By allowing different `Channelizer` implementations, Gremlin Server can support different communication protocols (e.g. WebSocket, Java NIO, etc.). |`WebSocketChannelizer`
|graphs |A `Map` of `Graph` configuration files where the key of the `Map` becomes the name to which the `Graph` will be bound and the value is the file name of a `Graph` configuration file. |_none_
|gremlinPool |The number of "Gremlin" threads available to execute actual scripts in a `ScriptEngine`. This pool represents the workers available to handle blocking operations in Gremlin Server. |8
|host |The name of the host to bind the server to. |localhost
http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/4d117cbd/docs/src/tutorials/getting-started/index.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/tutorials/getting-started/index.asciidoc b/docs/src/tutorials/getting-started/index.asciidoc
index 3ac80ce..7af5364 100644
--- a/docs/src/tutorials/getting-started/index.asciidoc
+++ b/docs/src/tutorials/getting-started/index.asciidoc
@@ -527,7 +527,7 @@ Gremlin Server
image:gremlin-server-protocol.png[width=325,float=right] link:http://tinkerpop.apache.org/docs/x.y.z/reference/#gremlin-server[Gremlin Server]
provides a way to remotely execute Gremlin scripts against one or more `Graph` instances hosted within it. It does
this by exposing different endpoints, such as link:http://tinkerpop.apache.org/docs/x.y.z/reference/#_connecting_via_rest[REST]
-and link:http://tinkerpop.apache.org/docs/x.y.z/reference/#_connecting_via_java[websockets], which allow a request
+and link:http://tinkerpop.apache.org/docs/x.y.z/reference/#_connecting_via_java[WebSocket], which allow a request
containing a Gremlin script to be processed with results returned.
[source,text]
@@ -574,7 +574,7 @@ applied to the script on execution and is essentially a way to parameterize your
critical to link:http://tinkerpop.apache.org/docs/x.y.z/reference/#_best_practices[performance]. Whenever
possible, parameterize your queries.
-As mentioned earlier, Gremlin Server can also be configured with a websockets endpoint. This endpoint has an
+As mentioned earlier, Gremlin Server can also be configured with a WebSocket endpoint. This endpoint has an
embedded link:http://tinkerpop.apache.org/docs/x.y.z/reference/#_developing_a_driver[subprotocol] that allow a
compliant driver to communicate with it. TinkerPop supplies a
link:http://tinkerpop.apache.org/docs/x.y.z/reference/#_connecting_via_java[reference driver] written in Java, but
[2/2] tinkerpop git commit: Merge branch 'tp31' into tp32
Posted by rd...@apache.org.
Merge branch 'tp31' into tp32
Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo
Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/273ad2c8
Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/273ad2c8
Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/273ad2c8
Branch: refs/heads/tp32
Commit: 273ad2c8e72344c7f9db8b310577fbad82ae9fa8
Parents: db035d5 4d117cb
Author: Robert Dale <ro...@gmail.com>
Authored: Mon Apr 24 12:21:22 2017 -0400
Committer: Robert Dale <ro...@gmail.com>
Committed: Mon Apr 24 12:21:22 2017 -0400
----------------------------------------------------------------------
docs/src/dev/provider/index.asciidoc | 8 ++++----
docs/src/reference/gremlin-applications.asciidoc | 8 ++++----
docs/src/tutorials/getting-started/index.asciidoc | 4 ++--
3 files changed, 10 insertions(+), 10 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/273ad2c8/docs/src/dev/provider/index.asciidoc
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/273ad2c8/docs/src/reference/gremlin-applications.asciidoc
----------------------------------------------------------------------
diff --cc docs/src/reference/gremlin-applications.asciidoc
index 1ecb616,a5c162e..ce8c1b5
--- a/docs/src/reference/gremlin-applications.asciidoc
+++ b/docs/src/reference/gremlin-applications.asciidoc
@@@ -929,118 -767,8 +929,118 @@@ string argument with by setting the `la
WARNING: Consider the size of the result of a submitted script being returned from the REST 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
- WebSockets configuration, which supports streaming, if that type of use case is required.
+ WebSocket configuration, which supports streaming, if that type of use case is required.
+[[connecting-via-remotegraph]]
+Connecting via withRemote
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.tinkerpop</groupId>
+ <artifactId>gremlin-driver</artifactId>
+ <version>x.y.z</version>
+</dependency>
+----
+
+image:remote-graph.png[width=145,float=left] A `TraversalSource` has several `withRemote()` methods which provide an
+interesting alternative to the other methods for connecting to Gremlin Server. It is interesting in that all other
+methods involve construction of a `String` representation of the `Traversal` which is then submitted as a script
+to Gremlin Server (via driver or REST). This approach is quite akin to SQL, where query strings are embedded into code
+and submitted to a database server. While there are patterns for taking this approach that can lead to maintainable
+application code, using `withRemote()` could be a better method as it brings some good benefits with it:
+
+* Get auto-complete when writing traversals in an IDE.
+* Get compile-time errors in traversal writing.
+* Get the feel of working with an embedded database.
+
+One way to create a `Traversal` instance that is remote-enabled is by configuration file. Here is an example of what
+that file looks like:
+
+[source,properties]
+----
+gremlin.remote.remoteConnectionClass=org.apache.tinkerpop.gremlin.driver.remote.DriverRemoteConnection
+gremlin.remote.driver.clusterFile=conf/remote-objects.yaml
+gremlin.remote.driver.sourceName=g
+----
+
+The `gremlin.remote.remoteConnectionClass` should be an implementation of the `RemoteConnection` interface in
+`gremlin-core`. In this case, it points at the `gremlin-driver` implementation, called `DriverRemoteConnection`. The
+other setting, `gremlin.remote.driver.clusterFile`, is a configuration to `DriverRemoteConnection`, and it
+provides a pointer to the config file to use to construct a `gremlin-driver` `Cluster` object to be utilized when
+connecting to Gremlin Server. Please see the <<connecting-via-java, "Connecting Via Java">> section for more
+information on those classes and their usage. Finally, the `gremlin.remote.driver.sourceName` setting tells the
+`DriverRemoteConnection` the name of the `TraversalSource` in Gremlin Server to connect to.
+
+IMPORTANT: Gremlin Server supports configurable serialization options. The `withRemote()` feature works best with
+Gryo serialization. While it is compatible with GraphSON, unknown incompatibilities may arise
+
+Gremlin Server needs to be running for this example to work. Use the following configuration:
+
+[source,bourne]
+$ bin/gremlin-server.sh conf/gremlin-server-modern.yaml
+
+To configure a "remote" traversal, there first needs to be a `TraversalSource`. A `TraversalSource` can be generated
+from any `Graph` instance with the `traversal()` method. Of course, any traversals generated from this source using the
+`withRemote()` configuration option will not execute against the local graph. That could be confusing and it maybe be
+easier to think of the local graph as being "empty". To that end, it is recommended that when using `withRemote()`,
+the `TraversalSource` be generated with `EmptyGraph` as follows:
+
+[gremlin-groovy]
+----
+graph = EmptyGraph.instance()
+g = graph.traversal().withRemote('conf/remote-graph.properties')
+g.V().valueMap(true)
+g.close()
+----
+
+Note the call to `close()` above. The call to `withRemote()` internally instantiates a `Client` instance that can only
+be released by "closing" the `GraphTraversalSource`. It is important to take that step to release resources created
+in that step.
+
+If working with multiple remote `TraversalSource` instances it is more efficient to construct a `Cluster` object and
+then re-use it.
+
+[gremlin-groovy]
+----
+cluster = Cluster.open('conf/remote-objects.yaml')
+graph = EmptyGraph.instance()
+g = graph.traversal().withRemote(DriverRemoteConnection.using(cluster, "g"))
+g.V().valueMap(true)
+g.close()
+cluster.close()
+----
+
+If the `Cluster` instance is supplied externally, as is shown above, then it is not closed implicitly by the close of
+"g". Closing "g" will only close the `Client` instance associated with that `TraversalSource`. In this case, the
+`Cluster` must also be closed explicitly. Closing "g" and the "cluster" aren't actually both necessary - the close of
+a `Cluster` will close all `Client` instance spawned by the `Cluster`.
+
+IMPORTANT: `RemoteGraph` uses the `TraversalOpProcessor` in Gremlin Server which requires a cache to enable the
+retrieval of side-effects (if the `Traversal` produces any). That cache can be configured (e.g. controlling eviction
+times and sizing) can be done in the Gremlin Server configuration file as described <<traversalopprocessor, here>>.
+
+Finally, Gremlin `Bytecode` supports the encoding of bindings which allow GremlinServer to cache traversals that will
+be reused over and over again save that some parameterization may change. Thus, instead of translating, compiling, and
+then executing each submitted bytecode, it is possible to simply execute. To express bindings in Gremlin-Java and
+Gremlin-Groovy, use `Bindings`.
+
+[gremlin-groovy]
+----
+cluster = Cluster.open('conf/remote-objects.yaml')
+b = Bindings.instance()
+g = EmptyGraph.instance().traversal().withRemote(DriverRemoteConnection.using(cluster, "g"))
+g.V(b.of('id',1)).out('created').values('name')
+g.V(b.of('id',4)).out('created').values('name')
+g.V(b.of('id',4)).out('created').values('name').getBytecode()
+g.V(b.of('id',4)).out('created').values('name').getBytecode().getBindings()
+cluster.close()
+----
+
+Both traversals are abstractly defined as `g.V(id).out('created').values('name')` and thus, the first submission
+can be cached for faster evaluation on the next submission.
+
Configuring
~~~~~~~~~~~
@@@ -1072,13 -800,11 +1072,13 @@@ The following table describes the vario
[width="100%",cols="3,10,^2",options="header"]
|=========================================================
|Key |Description |Default
-|authentication.className |The fully qualified classname of an `Authenticator` implementation to use. If this setting is not present, then authentication is effectively disabled. |`AllowAllAuthenticator`
+|authentication.authenticator |The fully qualified classname of an `Authenticator` implementation to use. If this setting is not present, then authentication is effectively disabled. |`AllowAllAuthenticator`
+|authentication.authenticationHandler | The fully qualified classname of an `AbstractAuthenticationHandler` implementation to use. If this setting is not present, but the `authentication.authenticator` is, it will use that authenticator with the default `AbstractAuthenticationHandler` implementation for the specified `Channelizer` |_none_
|authentication.config |A `Map` of configuration settings to be passes to the `Authenticator` when it is constructed. The settings available are dependent on the implementation. |_none_
- |channelizer |The fully qualified classname of the `Channelizer` implementation to use. A `Channelizer` is a "channel initializer" which Gremlin Server uses to define the type of processing pipeline to use. By allowing different `Channelizer` implementations, Gremlin Server can support different communication protocols (e.g. Websockets, Java NIO, etc.). |`WebSocketChannelizer`
-|channelizer |The fully qualified classname of the `Channelizer` implementation to use. A `Channelizer` is a "channel initializer" which Gremlin Server uses to define the type of processing pipeline to use. By allowing different `Channelizer` implementations, Gremlin Server can support different communication protocols (e.g. WebSocket, Java NIO, etc.). |`WebSocketChannelizer`
++|channelizer |The fully qualified classname of the `Channelizer` implementation to use. A `Channelizer` is a "channel initializer" which Gremlin Server uses to define the type of processing pipeline to use. By allowing different `Channelizer` implementations, Gremlin Server can support different communication protocols (e.g. Websocket, Java NIO, etc.). |`WebSocketChannelizer`
+|graphManager |The fully qualified classname of the `GraphManager` implementation to use. A `GraphManager` is a class that adheres to the TinkerPop `GraphManager` interface, allowing custom implementations for storing and managing graph references, as well as defining custom methods to open and close graphs instantiations. It is important to note that the Tinkerpop Http and WebSocketChannelizers auto-commit and auto-rollback based on the graphs stored in the graphManager upon script execution completion. |`DefaultGraphManager`
|graphs |A `Map` of `Graph` configuration files where the key of the `Map` becomes the name to which the `Graph` will be bound and the value is the file name of a `Graph` configuration file. |_none_
-|gremlinPool |The number of "Gremlin" threads available to execute actual scripts in a `ScriptEngine`. This pool represents the workers available to handle blocking operations in Gremlin Server. |8
+|gremlinPool |The number of "Gremlin" threads available to execute actual scripts in a `ScriptEngine`. This pool represents the workers available to handle blocking operations in Gremlin Server. When set to `0`, Gremlin Server will use the value provided by `Runtime.availableProcessors()`. |0
|host |The name of the host to bind the server to. |localhost
|useEpollEventLoop |try to use epoll event loops (works only on Linux os) instead of netty NIO. |false
|maxAccumulationBufferComponents |Maximum number of request components that can be aggregated for a message. |1024
http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/273ad2c8/docs/src/tutorials/getting-started/index.asciidoc
----------------------------------------------------------------------