http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/a297b0dd/docs/src/reference/the-graph.asciidoc ---------------------------------------------------------------------- diff --cc docs/src/reference/the-graph.asciidoc index 9bc5c65,339b392..1c8c2dc --- a/docs/src/reference/the-graph.asciidoc +++ b/docs/src/reference/the-graph.asciidoc @@@ -612,9 -706,90 +602,8 @@@ IMPORTANT: When using the extended typ Gremlin Language Variants is dependent on the programming language, the driver and its serializers. These implementations are only required to support the core types and not the extended ones. -Here's the same previous example of GraphSON 1.0, but with GraphSON 2.0: - -[gremlin-groovy] ----- -graph = TinkerFactory.createModern() -g = graph.traversal() -f = new ByteArrayOutputStream() -mapper = graph.io(graphson()).mapper().version(GraphSONVersion.V2_0).create() -graph.io(graphson()).writer().mapper(mapper).create().writeVertex(f, g.V(1).next(), BOTH) -f.close() ----- - -Creating a GraphSON 2.0 mapper is done by calling `.version(GraphSONVersion.V2_0)` on the mapper builder. Here's is the -example output from the code above: - -[source, json] ----- -{ - "@type": "g:Vertex", - "@value": { - "id": { - "@type": "g:Int32", - "@value": 1 - }, - "label": "person", - "properties": { - "name": [{ - "@type": "g:VertexProperty", - "@value": { - "id": { - "@type": "g:Int64", - "@value": 0 - }, - "value": "marko", - "label": "name" - } - }], - "uuid": [{ - "@type": "g:VertexProperty", - "@value": { - "id": { - "@type": "g:Int64", - "@value": 12 - }, - "value": { - "@type": "g:UUID", - "@value": "829c7ddb-3831-4687-a872-e25201230cd3" - }, - "label": "uuid" - } - }], - "age": [{ - "@type": "g:VertexProperty", - "@value": { - "id": { - "@type": "g:Int64", - "@value": 1 - }, - "value": { - "@type": "g:Int32", - "@value": 29 - }, - "label": "age" - } - }] - } - } -} ----- - -Types can be disabled when creating a GraphSON 2.0 `Mapper` with: - -[source,groovy] ----- -graph.io(graphson()).mapper(). - version(GraphSONVersion.V2_0). - typeInfo(GraphSONMapper.TypeInfo.NO_TYPES).create() ----- - -By disabling types, the JSON payload produced will lack the extra information that is written for types. Please note, -disabling types can be unsafe with regards to the written data in that types can be lost. - [[gryo-reader-writer]] - Gryo Reader/Writer - ~~~~~~~~~~~~~~~~~~ + === Gryo Reader/Writer image:gremlin-kryo.png[width=400,float=left] link:https://github.com/EsotericSoftware/kryo[Kryo] is a popular serialization package for the JVM. Gremlin-Kryo is a binary `Graph` serialization format for use on the JVM by JVM
http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/a297b0dd/docs/src/reference/the-graphcomputer.asciidoc ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/a297b0dd/docs/src/reference/the-traversal.asciidoc ---------------------------------------------------------------------- diff --cc docs/src/reference/the-traversal.asciidoc index fcfe83e,167073a..de99b7f --- a/docs/src/reference/the-traversal.asciidoc +++ b/docs/src/reference/the-traversal.asciidoc @@@ -220,12 -211,9 +215,11 @@@ g.addE('knows').from(marko).to(peter) < <4> The newly created edge is a traversable object. <5> Two arbitrary bindings in a traversal can be joined `from()`->`to()`, where `id` can be provided for graphs that supports user provided ids. +<6> Add an edge between marko and peter given the directed (detached) vertex references. +<7> Add an edge between marko and peter given the directed (detached) vertex references. [[addvertex-step]] - AddVertex Step - ~~~~~~~~~~~~~~ + === AddVertex Step The `addV()`-step is used to add vertices to the graph (*map*/*sideEffect*). For every incoming object, a vertex is created. Moreover, `GraphTraversalSource` maintains an `addV()` method. @@@ -1317,10 -1269,9 +1274,9 @@@ g.V().hasLabel('person') An option to a <<branch-step,`branch()`>> or <<choose-step,`choose()`>>. [[optional-step]] - Optional Step - ~~~~~~~~~~~~~ + === Optional Step -The `optional()`-step (*map*) returns the result of the specified traversal if it yields a result else it returns the calling +The `optional()`-step (*branch/flatMap*) returns the result of the specified traversal if it yields a result else it returns the calling element, i.e. the `identity()`. [gremlin-groovy,modern] @@@ -2120,38 -2053,8 +2058,36 @@@ g.V('A').as('a') <3> Traverse all acyclic 3-hop paths starting from vertex `A` and from there again all 3-hop paths. The second path may cross the vertices from the first path. +[[skip-step]] - Skip Step - ~~~~~~~~~ ++=== Skip Step + +The `skip()`-step is analogous to <<range-step,`range()`-step>> save that the higher end range is set to -1. + +[gremlin-groovy,modern] +---- +g.V().values('age').order() +g.V().values('age').order().skip(2) +g.V().values('age').order().range(2, -1) +---- + +The `skip()`-step can also be applied with `Scope.local`, in which case it operates on the incoming collection. + +[gremlin-groovy,modern] +---- +g.V().hasLabel('person').filter(outE('created')).as('p'). <1> + map(out('created').values('name').fold()). + project('person','primary','other'). + by(select('p').by('name')). + by(limit(local, 1)). <2> + by(skip(local, 1)) <3> +---- + +<1> For each person who created something... +<2> ...select the first project (random order) as `primary` and... +<3> ...select all other projects as `other`. + [[store-step]] - Store Step - ~~~~~~~~~~ + === Store Step When link:http://en.wikipedia.org/wiki/Lazy_evaluation[lazy] aggregation is needed, `store()`-step (*sideEffect*) should be used over <<aggregate-step,`aggregate()`>>. The two steps differ in that `store()` does not block and only http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/a297b0dd/docs/src/tutorials/getting-started/index.asciidoc ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/a297b0dd/docs/src/tutorials/gremlin-language-variants/index.asciidoc ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/a297b0dd/docs/src/upgrade/index.asciidoc ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/a297b0dd/docs/src/upgrade/release-3.2.x-incubating.asciidoc ---------------------------------------------------------------------- diff --cc docs/src/upgrade/release-3.2.x-incubating.asciidoc index b331d83,d578c2d..920a699 --- a/docs/src/upgrade/release-3.2.x-incubating.asciidoc +++ b/docs/src/upgrade/release-3.2.x-incubating.asciidoc @@@ -145,11 -132,20 +132,9 @@@ See: link:https://issues.apache.org/jir Please see the link:https://github.com/apache/tinkerpop/blob/3.2.5/CHANGELOG.asciidoc#release-3-2-5[changelog] for a complete list of all the modifications that are part of this release. - Upgrading for Users - ~~~~~~~~~~~~~~~~~~~ + === Upgrading for Users - DSL Support - ^^^^^^^^^^^ -==== GraphSON Path Serialization - -Serialization of `Path` with GraphSON was inconsistent with Gryo in that all the properties on any elements of -the `Path` were being included. With Gryo that, correctly, was not happening as that could be extraordinarily -expensive. GraphSON serialization has now been modified to properly not include properties. That change can cause -breaks in application code if that application code tries to access properties on elements in a `Path` as they -will no longer be there. Applications that require the properties will need to alter their Gremlin to better -restrict the data they want to retrieve. - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-1676[TINKERPOP-1676] - + ==== DSL Support It has always been possible to construct Domain Specific Languages (DSLs) with Gremlin, but the approach has required a somewhat deep understanding of the TinkerPop code base and it is not something that has had a recommeded method @@@ -169,20 -165,7 +154,18 @@@ social.persons().where(createdAtLeast(2 See: link:https://issues.apache.org/jira/browse/TINKERPOP-786[TINKERPOP-786], link:http://tinkerpop.apache.org/docs/3.2.5/reference/#dsl[Reference Documentation] - GraphSON Path Serialization - ^^^^^^^^^^^^^^^^^^^^^^^^^^^ ++==== GraphSON Path Serialization + +Serialization of `Path` with GraphSON was inconsistent with Gryo in that all the properties on any elements of +the `Path` were being included. With Gryo that, correctly, was not happening as that could be extraordinarily +expensive. GraphSON serialization has now been modified to properly not include properties. That change can cause +breaks in application code if that application code tries to access properties on elements in a `Path` as they +will no longer be there. Applications that require the properties will need to alter their Gremlin to better +restrict the data they want to retrieve. + +See: link:https://issues.apache.org/jira/browse/TINKERPOP-1676[TINKERPOP-1676] + - Authentication Configuration - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + ==== Authentication Configuration The server settings previously used `authentication.className` to set an authenticator for the the two provided authentication handler and channelizer classes to use. This has been deprecated in favor of `authentication.authenticator`. @@@ -959,13 -888,7 +888,11 @@@ link:https://issues.apache.org/jira/bro link:http://tinkerpop.apache.org/docs/3.2.2/reference/#console-preferences[Reference Documentation - Console Preferences] - REST API Renamed to HTTP API - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ++==== REST API Renamed to HTTP API +This is only a rename to clarify the design of the API. There is no change to the API itself. + + - Upgrading for Providers - ~~~~~~~~~~~~~~~~~~~~~~~ + === Upgrading for Providers IMPORTANT: It is recommended that providers also review all the upgrade instructions specified for users. Many of the changes there may prove important for the provider's implementation. http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/a297b0dd/docs/src/upgrade/release-3.3.x.asciidoc ---------------------------------------------------------------------- diff --cc docs/src/upgrade/release-3.3.x.asciidoc index 1c404c3,0000000..fa50d47 mode 100644,000000..100644 --- a/docs/src/upgrade/release-3.3.x.asciidoc +++ b/docs/src/upgrade/release-3.3.x.asciidoc @@@ -1,651 -1,0 +1,615 @@@ +//// +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +//// + - TinkerPop 3.3.0 - =============== ++= TinkerPop 3.3.0 + +image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/images/gremlin-mozart.png[width=225] + +*Gremlin Symphony #40 in G Minor* + - TinkerPop 3.3.1 - --------------- ++== TinkerPop 3.3.1 + +*Release Date: NOT OFFICIALLY RELEASED YET* + +Please see the link:https://github.com/apache/tinkerpop/blob/3.3.1/CHANGELOG.asciidoc#release-3-3-1[changelog] for a complete list of all the modifications that are part of this release. + - Upgrading for Users - ~~~~~~~~~~~~~~~~~~~ ++=== Upgrading for Users + - PageRankVertexProgram - ^^^^^^^^^^^^^^^^^^^^^ ++==== PageRankVertexProgram + +There were two major bugs in the way in which PageRank was being calculated in `PageRankVertexProgram`. First, teleportation +energy was not being distributed correctly amongst the vertices at each round. Second, terminal vertices (i.e. vertices +with no outgoing edges) did not have their full gathered energy distributed via teleportation. + +For users upgrading, note that while the relative rank orders will remain "the same," the actual PageRank values will differ +from prior TinkerPop versions. + +``` +VERTEX iGRAPH TINKERPOP +marko 0.1119788 0.11375485828040575 +vadas 0.1370267 0.14598540145985406 +lop 0.2665600 0.30472082661863686 +josh 0.1620746 0.14598540145985406 +ripple 0.2103812 0.1757986539008437 +peter 0.1119788 0.11375485828040575 +``` + +Normalization preserved through computation: + +``` +0.11375485828040575 + +0.14598540145985406 + +0.30472082661863686 + +0.14598540145985406 + +0.1757986539008437 + +0.11375485828040575 +==>1.00000000000000018 +``` + +Two other additions to `PageRankVertexProgram` were provided as well. + +1. It now calculates the vertex count and thus, no longer requires the user to specify the vertex count. +2. It now allows the user to leverage an epsilon-based convergence instead of having to specify the number of iterations to execute. + +See: link:https://issues.apache.org/jira/browse/TINKERPOP-1783[TINKERPOP-1783] + - IO Defaults - ^^^^^^^^^^^ ++==== IO Defaults + +While 3.3.0 released Gryo 3.0 and GraphSON 3.0 and these versions were defaulted in a number of places, it seems that +some key defaults were missed. Specifically, calls to `Graph.io(graphson())` and `Graph.io(gryo())` were still using +the old versions. The defaults have now been changed to ensure 3.0 is properly referenced in those cases. + - Upgrade Neo4j - ^^^^^^^^^^^^^ ++==== Upgrade Neo4j + +See Neo4j's link:https://neo4j.com/guides/upgrade/[3.2 Upgrade FAQ] for a complete guide on how to upgrade from the previous 2.3.3 version. Also note that many of the configuration settings have link:https://neo4j.com/developer/kb/manually-migrating-configuration-settings-from-neo4j-2x-to-neo4j-3x/[changed from neo4j 2x to 3x] + +In particular, these properties referenced in TinkerPop documentation and configuration were renamed: + +[width="100%",cols="2",options="header"] +|========================================================= +|Neo4j 2.3 (TinkerPop \<= 3.3.0) |Neo4j 3.2 (TinkerPop 3.3.1) +|node_auto_indexing |dbms.auto_index.nodes.enabled +|relationship_auto_indexing |dbms.auto_index.relationships.enabled +|ha.cluster_server |ha.host.coordination +|ha.server |ha.host.data +|========================================================= + + - Upgrading for Providers - ~~~~~~~~~~~~~~~~~~~~~~~ ++=== Upgrading for Providers + +IMPORTANT: It is recommended that providers also review all the upgrade instructions specified for users. Many of the +changes there may prove important for the provider's implementation. + - Graph Database Providers - ^^^^^^^^^^^^^^^^^^^^^^^^ ++==== Graph Database Providers + - IO Version Check - ++++++++++++++++ ++===== IO Version Check + +In the `Graph.io()` method, providers are to bootstrap the `Io` instance returned with their own custom serializers +typically provided through a custom `IoRegistry` instance. Prior to this change it was not possible to easily determine +the version of `Io` that was expected (nor was it especially necessary as TinkerPop didn't have breaking format changes +between versions). As of 3.3.0 however, there could be IO test incompatibilities for some providers who need to +register a different `IoRegistry` instance depending on the version the user wants. + +To allow for that check, the `Io` interface now has the following method: + +[source,java] +---- +public <V> boolean requiresVersion(final V version); +---- + +which allows the graph provider to check if a specific `GryoVersion` or `GraphSONVersion` is required. Using that +information, the provider could then assign the right `IoRegistry` to match that. + +See: link:https://issues.apache.org/jira/browse/TINKERPOP-1767[TINKERPOP-1767] + + - TinkerPop 3.3.0 - --------------- ++== TinkerPop 3.3.0 + +*Release Date: August 21, 2017* + +Please see the link:https://github.com/apache/tinkerpop/blob/3.3.0/CHANGELOG.asciidoc#release-3-3-0[changelog] for a complete list of all the modifications that are part of this release. + - Upgrading for Users - ~~~~~~~~~~~~~~~~~~~ ++=== Upgrading for Users + - Packaged Data Files - ^^^^^^^^^^^^^^^^^^^ ++==== Packaged Data Files + +TinkerPop has always packaged sample graphs with its zip distributions. As of 3.3.0, the distributions will only +include Gryo 3.0, GraphSON 3.0 and GraphML (which is unversioned) files. Other versions are not included, but could +obviously be generated using the IO API directly. + - GraphTraversal Has-Methods Re-Organized - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ++==== GraphTraversal Has-Methods Re-Organized + +`GraphTraversal.hasXXX()`, where `XXX` is `Id`, `Label`, `Key`, `Value`, was faulty in that they relied on calling an +intermediate method for flattening `Object[]` arguments and thus, yielding a non 1-to-1 correspondence between `GraphTraversal` +and `Bytecode`. This has been remedied. Most users will not notice this change. Perhaps only some users that may use +Java reflection over `GraphTraversal` might have a simple problem. + +See: link:https://issues.apache.org/jira/browse/TINKERPOP-1520[TINKERPOP-1520] + - Changes to IO - ^^^^^^^^^^^^^ ++==== Changes to IO + - Gryo 3.0 - ++++++++ ++===== Gryo 3.0 + +With Gryo, TinkerPop skips version 2.0 and goes right to 3.0 (to maintain better parity with GraphSON versioning). +Gryo 3.0 fixes a number of inconsistencies with Gryo 1.0 and hopefully marks a point where Gryo is better versioned +over time. Gryo 3.0 is not compatible with Gryo 1.0 and is now the default version of Gryo exposed by TinkerPop in +Gremlin Server and IO. + +It isn't hard to switch back to use of Gryo 1.0 if necessary. Here is the approach for writing an entire graph: + +[source,java] +---- +Graph graph = TinkerFactory.createModern(); +GryoMapper mapper = graph.io(IoCore.gryo()).mapper().version(GryoVersion.V1_0).create() +try (OutputStream os = new FileOutputStream("tinkerpop-modern.json")) { + graph.io(IoCore.gryo()).writer().mapper(mapper).create().writeGraph(os, graph) +} + +final Graph newGraph = TinkerGraph.open(); +try (InputStream stream = new FileInputStream("tinkerpop-modern.json")) { + newGraph.io(IoCore.gryo()).reader().mapper(mapper).create().readGraph(stream, newGraph); +} +---- + +Gremlin Server configurations don't include Gryo 1.0 by default: + +[source,yaml] +---- +serializers: + - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV3d0, config: { ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV3d0] }} # application/vnd.gremlin-v3.0+gryo + - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV3d0, config: { serializeResultToString: true }} # application/vnd.gremlin-v3.0+gryo-stringd + - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV3d0, config: { ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV3d0] }} # application/json +---- + +but adding an entry as follows will add it back: + +[source,yaml] +---- +serializers: + - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV1d0, config: { ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV1d0] }} # application/vnd.gremlin-v1.0+gryo + - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV3d0, config: { ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV3d0] }} # application/vnd.gremlin-v3.0+gryo + - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV3d0, config: { serializeResultToString: true }} # application/vnd.gremlin-v3.0+gryo-stringd + - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV3d0, config: { ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV3d0] }} # application/json +---- + +To use Gryo 1.0 with the Java driver, just specify the 1.0 serializer directly: + +[source,java] +---- +GryoMapper.Builder builder = GryoMapper.build(). + version(GryoVersion.V1_0). + addRegistry(TinkerIoRegistryV1d0.instance()); +Cluster cluster = Cluster.build().serializer(GryoMessageSerializerV1d0(builder)); +---- + +See: link:https://issues.apache.org/jira/browse/TINKERPOP-1698[TINKERPOP-1698] + - GraphSON 3.0 - ++++++++++++ ++===== GraphSON 3.0 + +GraphSON 3.0 finishes what GraphSON 2.0 began by taking the extra step to include the following types: `g:Map`, +`g:List` and `g:Set`. With these types it is now possible to get expected Gremlin results in GLVs just as one would +if using Java. This is especially true of the `g:Map` type, which allows non-string keys values, something not allowed +in regular JSON maps. This allows for common traversals like `g.V().groupCount()` to work, where the traversal groups +on a `Vertex` or some other complex object. + +Note that GraphSON 3.0 does not have an option to be without types. This was a feature of 1.0 and 2.0, but it is no +longer supported. There is little point to such a feature as we see more movement toward GLVs, which require types, +and less usage of scripts with custom parsing of results. + +Both TinkerGraph and Gremlin Server have been defaulted to work with GraphSON 3.0. For TinkerGraph this means that +the following commands: + +[source,java] +---- +Graph graph = TinkerFactory.createModern(); +graph.io(IoCore.graphson()).writeGraph("tinkerpop-modern.json"); + +final Graph newGraph = TinkerGraph.open(); +newGraph.io(IoCore.graphson()).readGraph("tinkerpop-modern.json"); +---- + +will write and read GraphSON 3.0 format rather than 1.0. To use 1.0 (or 2.0 for that matter) format simply set the +`version()` on the appropriate builder methods: + +[source,java] +---- +Graph graph = TinkerFactory.createModern(); +GraphSONMapper mapper = graph.io(IoCore.graphson()).mapper().version(GraphSONVersion.V1_0).create() +try (OutputStream os = new FileOutputStream("tinkerpop-modern.json")) { + graph.io(IoCore.graphson()).writer().mapper(mapper).create().writeGraph(os, graph) +} + +final Graph newGraph = TinkerGraph.open(); +try (InputStream stream = new FileInputStream("tinkerpop-modern.json")) { + newGraph.io(IoCore.graphson()).reader().mapper(mapper).create().readGraph(stream, newGraph); +} +---- + +For Gremlin Server, this change means that the `application/json` mime type no longer returns GraphSON 1.0 without +type embedding. Instead, Gremlin Server will return GraphSON 3.0 with partial types enabled (i.e. which is equivalent +to `application/vnd.gremlin-v3.0+json`). The `serializers` section the sample Gremlin Server YAML files now typically +look like this: + +[source,yaml] +---- +serializers: + - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV3d0, config: { ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV3d0] }} # application/vnd.gremlin-v3.0+gryo + - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV3d0, config: { serializeResultToString: true }} # application/vnd.gremlin-v3.0+gryo-stringd + - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV3d0, config: { ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV1d0] }} # application/json +---- + +It is possible to bring back the original configuration for `application/json` by changing the last entry as follows: + +[source,yaml] +---- + - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV3d0, config: { ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV3d0] }} # application/vnd.gremlin-v3.0+gryo + - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV3d0, config: { serializeResultToString: true }} # application/vnd.gremlin-v3.0+gryo-stringd + - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV1d0, config: { ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV1d0] }} # application/json +---- + +See: link:https://issues.apache.org/jira/browse/TINKERPOP-1414[TINKERPOP-1414], +link:https://issues.apache.org/jira/browse/TINKERPOP-1427[TINKERPOP-1427], +link:https://issues.apache.org/jira/browse/TINKERPOP-1574[TINKERPOP-1574] + - Graphite and Ganglia - ^^^^^^^^^^^^^^^^^^^^ ++==== Graphite and Ganglia + +Graphite and Ganglia are no longer packaged with the Gremlin Server distribution. They are considered optional +dependencies and therefore must be installed manually by the user. + +See: link:https://issues.apache.org/jira/browse/TINKERPOP-1550[TINKERPOP-1550], +link:http://tinkerpop.apache.org/docs/3.3.0/reference/#metrics[Reference Documentation - Metrics] + - SelectStep Defaults to Pop.last - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ++==== SelectStep Defaults to Pop.last + +`SelectStep` and `SelectOneStep` (`select()`) are the only `Scoping` steps that default to `Pop.mixed` as their labeled path +selection criteria. All other steps, like `match()`, `where()` and `dedup()`, use `Pop.last`. In order to better enable optimizations +around total `Pop.last` traversals, the `select()`-steps now default to `Pop.last`. Most users will not notice a difference as +it is rare for repeated labels to be used in practice. However, formal backwards compatibility is possible as outlined below. + +Assuming that `x` is not a `Pop` argument: + +1. Change all `select(x,y,z)` calls to `selectV3d2(x,y,z)` calls. +2. Change all `select(x,y,z)`-step calls to `select(Pop.mixed,x,y,z)`. + +If an explicit `Pop` argument is provided, then no changes are required. + +See: link:https://issues.apache.org/jira/browse/TINKERPOP-1541[TINKERPOP-1541] + - OptionalStep and Side-Effects - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ++==== OptionalStep and Side-Effects + +The `optional()`-step was previously implemented using `ChooseStep`. However, if the optional branch contained side-effects, +then unexpected behaviors can emerge. Thus, a potential backwards compatibility issue arises if side-effects were being +used in `optional()`. However, the behavior would be unpredictable so this backwards incompatibility is desirable. + +See link:https://issues.apache.org/jira/browse/TINKERPOP-1506[TINKERPOP-1506] + - Gremlin Console Initialization - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ++==== Gremlin Console Initialization + +It is no longer possible to intialize the Gremlin Console with a script without use of `-e`. In other words, prior +versions allowed: + +[source,text] +bin/gremlin.sh gremlin.groovy + +Such a command must now be written as: + +[source,text] +bin/gremlin.sh -i gremlin.groovy + +See: link:https://issues.apache.org/jira/browse/TINKERPOP-1283[TINKERPOP-1283], +link:https://issues.apache.org/jira/browse/TINKERPOP-1651[TINKERPOP-1651] + - GraphTraversal valueMap() Signature Updated - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ++==== GraphTraversal valueMap() Signature Updated + +`GraphTraversal.valueMap(includeTokens,propertyKeys...)` now returns a `Map<Object,E>` to account for the presence of `T.id` or `T.label` if you pass `true` to it. + +See: link:https://issues.apache.org/jira/browse/TINKERPOP-1283[TINKERPOP-1483] + - HADOOP_GREMLIN_LIBS and Spark - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ++==== HADOOP_GREMLIN_LIBS and Spark + +The TinkerPop reference documentation has always mentioned that the `gremlin-spark` `/lib` directory needed to be +added to `HADOOP_GREMLIN_LIBS` environment variable. In reality, that was not truly necessary. With Spark 1.x having +`gremlin-spark` in `HADOOP_GREMLIN_LIBS` hasn't been a problem, but Spark 2.0 introduces a check for duplicate jars +on the path which will cause job initialization to fail. As a result, going forward with TinkerPop 3.3.0, the +`gremlin-spark` `lib` directory should not be included in `HADOOP_GREMLIN_LIBS`. + - Deprecation Removal - ^^^^^^^^^^^^^^^^^^^ ++==== Deprecation Removal + +The following deprecated classes, methods or fields have been removed in this version: + +* `giraph-gremlin` +** `org.apache.tinkerpop.gremlin.giraph.groovy.plugin.GiraphGremlinPlugin` +* `gremlin-console` +** `org.apache.tinkerpop.gremlin.console.Console(String)` +** `org.apache.tinkerpop.gremlin.console.ConsoleImportCustomizerProvider` +** `org.apache.tinkerpop.gremlin.console.plugin.*` +** `org.apache.tinkerpop.gremlin.console.groovy.plugin.DriverGremlinPlugin` +** `org.apache.tinkerpop.gremlin.console.groovy.plugin.DriverRemoteAcceptor` +** `org.apache.tinkerpop.gremlin.console.groovy.plugin.GephiGremlinPlugin` +** `org.apache.tinkerpop.gremlin.console.groovy.plugin.UtilitiesGremlinPlugin` +* `gremlin-core` +** `org.apache.tinkerpop.gremlin.jsr223.CoreGremlinModule` +** `org.apache.tinkerpop.gremlin.jsr223.CoreGremlinPlugin#INSTANCE` +** `org.apache.tinkerpop.gremlin.jsr223.GremlinModule` +** `org.apache.tinkerpop.gremlin.jsr223.SingleGremlinScriptEngineManager#getInstance()` +** `org.apache.tinkerpop.gremlin.jsr223.GremlinScriptEngineManager#addModule(GremlinModule)` +** `org.apache.tinkerpop.gremlin.jsr223.console.PluginAcceptor` +** `org.apache.tinkerpop.gremlin.process.traversal.TraversalSource.Builder` +** `org.apache.tinkerpop.gremlin.process.traversal.util.ConnectiveP(P...)` +** `org.apache.tinkerpop.gremlin.process.traversal.util.AndP(P...)` +** `org.apache.tinkerpop.gremlin.process.traversal.util.OrP(P...)` +** `org.apache.tinkerpop.gremlin.process.traversal.util.TraversalScriptFunction` +** `org.apache.tinkerpop.gremlin.process.traversal.util.TraversalScriptHelper` +** `org.apache.tinkerpop.gremlin.process.traversal.Order.keyIncr` +** `org.apache.tinkerpop.gremlin.process.traversal.Order.valueIncr` +** `org.apache.tinkerpop.gremlin.process.traversal.Order.keyDecr` +** `org.apache.tinkerpop.gremlin.process.traversal.Order.valueIncr` +** `org.apache.tinkerpop.gremlin.process.traversal.dsl.GraphTraversal.mapKeys()` +** `org.apache.tinkerpop.gremlin.process.traversal.dsl.GraphTraversal.mapValues()` +** `org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversal#addV(Object...)` +** `org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversal#addE(Direction, String, String, Object...)` +** `org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversal#addOutE(String, String, Object...)` +** `org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversal#addInV(String, String, Object...)` +** `org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversal#selectV3d2()` +** `org.apache.tinkerpop.gremlin.process.traversal.Bindings()` +** `org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversalSource#withBindings(Bindings)` +** `org.apache.tinkerpop.gremlin.structure.Transaction.submit(Function)` +** `org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversal#sack(BiFunction,String)` +** `org.apache.tinkerpop.gremlin.process.traversal.strategy.finalization.LazyBarrierStrategy` +** `org.apache.tinkerpop.gremlin.process.traversal.TraversalSideEffects` (various methods) +** `org.apache.tinkerpop.gremlin.process.computer.traversal.step.VertexComputing#generateComputer(Graph)` +** `org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversal#groupV3d0(String)` +** `org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversal#groupV3d0()` +** `org.apache.tinkerpop.gremlin.structure.Graph.Features.VertexPropertyFeatures#supportsAddProperty()` +** `org.apache.tinkerpop.gremlin.structure.Graph.Features.VertexPropertyFeatures#FEATURE_ADD_PROPERTY` +** `org.apache.tinkerpop.gremlin.structure.Graph.OptIn#SUITE_GROOVY_PROCESS_STANDARD` +** `org.apache.tinkerpop.gremlin.structure.Graph.OptIn#SUITE_GROOVY_PROCESS_COMPUTER` +** `org.apache.tinkerpop.gremlin.structure.Graph.OptIn#SUITE_GROOVY_ENVIRONMENT` +** `org.apache.tinkerpop.gremlin.structure.Graph.OptIn#SUITE_GROOVY_ENVIRONMENT_INTEGRATE` +** `org.apache.tinkerpop.gremlin.structure.io.Io.Builder#registry(IoRegistry)` +** `org.apache.tinkerpop.gremlin.structure.io.graphson.GraphSONMapper.Builder#embedTypes(boolean)` +** `org.apache.tinkerpop.gremlin.structure.Transaction.submit(Function)` +** `org.apache.tinkerpop.gremlin.structure.util.detached.DetachedEdge(Object,String,Map,Pair,Pair)` +** `org.apache.tinkerpop.gremlin.util.CoreImports` +** `org.apache.tinkerpop.gremlin.util.ScriptEngineCache` +** `org.apache.tinkerpop.gremlin.process.computer.util.ConfigurationTraversal` +* `gremlin-driver` +** `org.apache.tinkerpop.gremlin.driver.Cluster$Builder#reconnectIntialDelay(int)` +** `org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV1d0(GryoMapper)` +** `org.apache.tinkerpop.gremlin.driver.ser.AbstractGraphSONMessageSerializerV2d0#TOKEN_USE_MAPPER_FROM_GRAPH` +** `org.apache.tinkerpop.gremlin.driver.ser.AbstractGryoSONMessageSerializerV2d0#TOKEN_USE_MAPPER_FROM_GRAPH` +* `gremlin-groovy` +** `org.apache.tinkerpop.gremlin.groovy.AbstractImportCustomizerProvider` +** `org.apache.tinkerpop.gremlin.groovy.CompilerCustomizerProvider` +** `org.apache.tinkerpop.gremlin.groovy.DefaultImportCustomizerProvider` +** `org.apache.tinkerpop.gremlin.groovy.EmptyImportCustomizerProvider` +** `org.apache.tinkerpop.gremlin.groovy.ImportCustomizerProvider` +** `org.apache.tinkerpop.gremlin.groovy.NoImportCustomizerProvider` +** `org.apache.tinkerpop.gremlin.groovy.engine.ConcurrentBindings` +** `org.apache.tinkerpop.gremlin.groovy.engine.GremlinExecutor#build(String,List,List,List,Map)` +** `org.apache.tinkerpop.gremlin.groovy.engine.GremlinExecutor#getScriptEngines()` +** `org.apache.tinkerpop.gremlin.groovy.engine.GremlinExecutor#getGlobalBindings()` +** `org.apache.tinkerpop.gremlin.groovy.engine.GremlinExecutor.Builder#enabledPlugins(Set)` +** `org.apache.tinkerpop.gremlin.groovy.engine.GremlinExecutor.Builder#addEngineSettings(String,List,List,List,Map)` +** `org.apache.tinkerpop.gremlin.groovy.engine.GremlinExecutor.Builder#engineSettings(Map)` +** `org.apache.tinkerpop.gremlin.groovy.engine.GremlinExecutor.Builder#use(List)` +** `org.apache.tinkerpop.gremlin.groovy.engine.ScriptEngines` +** `org.apache.tinkerpop.gremlin.groovy.function.*` +** `org.apache.tinkerpop.gremlin.groovy.plugin.*` +** `org.apache.tinkerpop.gremlin.groovy.plugin.credential.*` +** `org.apache.tinkerpop.gremlin.groovy.jsr223.DependencyManager` +** `org.apache.tinkerpop.gremlin.groovy.jsr223.GremlinGroovyScriptEngine(ImportCustomizerProvider)` +** `org.apache.tinkerpop.gremlin.groovy.jsr223.GremlinGroovyScriptEngine(CompilerCustomizerProvider)` +** `org.apache.tinkerpop.gremlin.groovy.jsr223.GremlinGroovyScriptEngine#plugins()` +** `org.apache.tinkerpop.gremlin.groovy.jsr223.ScriptExecutor` +** `org.apache.tinkerpop.gremlin.groovy.jsr223.ScriptEnginePluginAcceptor` +** `org.apache.tinkerpop.gremlin.groovy.jsr223.customizer.SandboxExtension` +** `org.apache.tinkerpop.gremlin.groovy.jsr223.customizer.*` +** `org.apache.tinkerpop.gremlin.groovy.util.DependencyGrabber#deleteDependenciesFromPath(org.apache.tinkerpop.gremlin.groovy.plugin.Artifact)` +** `org.apache.tinkerpop.gremlin.groovy.util.DependencyGrabber#copyDependenciesToPath(org.apache.tinkerpop.gremlin.groovy.plugin.Artifact)` +* `gremlin-python` +** `org.apache.tinkerpop.gremlin.python.jsr223.GremlinJythonScriptEngine#()` +* `gremlin-server` +** `org.apache.tinkerpop.gremlin.server.GremlinServer(ServerGremlinExecutor)` +** `org.apache.tinkerpop.gremlin.server.Settings#plugins` +** `org.apache.tinkerpop.gremlin.server.auth.AllowAllAuthenticator.newSaslNegotiator()` +** `org.apache.tinkerpop.gremlin.server.auth.Authenticator.newSaslNegotiator()` +** `org.apache.tinkerpop.gremlin.server.auth.Krb5Authenticator.newSaslNegotiator()` +** `org.apache.tinkerpop.gremlin.server.auth.SimpleAuthenticator.newSaslNegotiator()` +** `org.apache.tinkerpop.gremlin.server.handler.IteratorHandler` +** `org.apache.tinkerpop.gremlin.server.handler.NioGremlinResponseEncoder` +** `org.apache.tinkerpop.gremlin.server.handler.WsGremlinResponseEncoder` +** `org.apache.tinkerpop.gremlin.server.handler.OpSelectorHandler.errorMeter` +** `org.apache.tinkerpop.gremlin.server.op.control.*` +** `org.apache.tinkerpop.gremlin.server.op.AbstractEvalOpProcessor.errorMeter` +** `org.apache.tinkerpop.gremlin.server.op.AbstractEvalOpProcessor.validBindingName` +** `org.apache.tinkerpop.gremlin.server.op.session.Session.kill()` +** `org.apache.tinkerpop.gremlin.server.op.session.Session.manualkill()` +* `hadoop-gremlin` +** `org.apache.tinkerpop.gremlin.hadoop.Constants#GREMLIN_HADOOP_GRAPH_INPUT_FORMAT` +** `org.apache.tinkerpop.gremlin.hadoop.Constants#GREMLIN_HADOOP_GRAPH_OUTPUT_FORMAT` +** `org.apache.tinkerpop.gremlin.hadoop.Constants#GREMLIN_HADOOP_GRAPH_INPUT_FORMAT_HAS_EDGES` +** `org.apache.tinkerpop.gremlin.hadoop.Constants#GREMLIN_HADOOP_GRAPH_OUTPUT_FORMAT_HAS_EDGES` +** `org.apache.tinkerpop.gremlin.hadoop.Constants#GREMLIN_SPARK_GRAPH_INPUT_RDD` +** `org.apache.tinkerpop.gremlin.hadoop.Constants#GREMLIN_SPARK_GRAPH_OUTPUT_RDD` +* `spark-gremlin` +** `org.apache.tinkerpop.gremlin.spark.groovy.plugin.SparkGremlinPlugin` +* `tinkergraph-gremlin` +** `org.apache.tinkerpop.gremlin.tinkergraph.groovy.plugin.TinkerGraphGremlinPlugin` +** `org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerGraph#CONFIG_*` +** `org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistry` +** `org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV1d0#getInstance()` +** `org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV2d0#getInstance()` + +Please see the javadoc deprecation notes or upgrade documentation specific to when the deprecation took place to +understand how to resolve this breaking change. + +See: link:https://issues.apache.org/jira/browse/TINKERPOP-832[TINKERPOP-832], +link:https://issues.apache.org/jira/browse/TINKERPOP-833[TINKERPOP-833], +link:https://issues.apache.org/jira/browse/TINKERPOP-834[TINKERPOP-834], +link:https://issues.apache.org/jira/browse/TINKERPOP-999[TINKERPOP-999], +link:https://issues.apache.org/jira/browse/TINKERPOP-1010[TINKERPOP-1010], +link:https://issues.apache.org/jira/browse/TINKERPOP-1028[TINKERPOP-1028], +link:https://issues.apache.org/jira/browse/TINKERPOP-1040[TINKERPOP-1040], +link:https://issues.apache.org/jira/browse/TINKERPOP-1046[TINKERPOP-1046], +link:https://issues.apache.org/jira/browse/TINKERPOP-1049[TINKERPOP-1049], +link:https://issues.apache.org/jira/browse/TINKERPOP-1142[TINKERPOP-1142], +link:https://issues.apache.org/jira/browse/TINKERPOP-1169[TINKERPOP-1169], +link:https://issues.apache.org/jira/browse/TINKERPOP-1171[TINKERPOP-1171], +link:https://issues.apache.org/jira/browse/TINKERPOP-1275[TINKERPOP-1275], +link:https://issues.apache.org/jira/browse/TINKERPOP-1283[TINKERPOP-1283], +link:https://issues.apache.org/jira/browse/TINKERPOP-1289[TINKERPOP-1289], +link:https://issues.apache.org/jira/browse/TINKERPOP-1291[TINKERPOP-1291], +link:https://issues.apache.org/jira/browse/TINKERPOP-1420[TINKERPOP-1420], +link:https://issues.apache.org/jira/browse/TINKERPOP-1421[TINKERPOP-1421], +link:https://issues.apache.org/jira/browse/TINKERPOP-1465[TINKERPOP-1465], +link:https://issues.apache.org/jira/browse/TINKERPOP-1481[TINKERPOP-1481], +link:https://issues.apache.org/jira/browse/TINKERPOP-1526[TINKERPOP-1526], +link:https://issues.apache.org/jira/browse/TINKERPOP-1603[TINKERPOP-1603], +link:https://issues.apache.org/jira/browse/TINKERPOP-1612[TINKERPOP-1612], +link:https://issues.apache.org/jira/browse/TINKERPOP-1622[TINKERPOP-1622], +link:https://issues.apache.org/jira/browse/TINKERPOP-1651[TINKERPOP-1651], +link:https://issues.apache.org/jira/browse/TINKERPOP-1694[TINKERPOP-1694], +link:https://issues.apache.org/jira/browse/TINKERPOP-1700[TINKERPOP-1700], +link:https://issues.apache.org/jira/browse/TINKERPOP-1706[TINKERPOP-1706], +link:https://issues.apache.org/jira/browse/TINKERPOP-1721[TINKERPOP-1721], +link:https://issues.apache.org/jira/browse/TINKERPOP-1719[TINKERPOP-1719], +link:https://issues.apache.org/jira/browse/TINKERPOP-1720[TINKERPOP-1720], +link:https://issues.apache.org/jira/browse/TINKERPOP-880[TINKERPOP-880], +link:https://issues.apache.org/jira/browse/TINKERPOP-1170[TINKERPOP-1170], +link:https://issues.apache.org/jira/browse/TINKERPOP-1729[TINKERPOP-1729] + - Gremlin-server.sh and Init Scripts - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ++==== Gremlin-server.sh and Init Scripts + +`gremlin-server.sh` is now also an init script and can no longer be started without parameters. To start it in the +foreground with defaults like previous usage, please use the `console` parameter. Also, `gremlin-server.sh` will +continue to start in the foreground when provided a yaml configuration file. + +How to install as a service has been added to the link:http://tinkerpop.apache.org/docs/3.3.0/reference/#_as_a_service[Reference Documentation - As A Service]. + +The switch name has changed for installing dependencies. `-i` has been deprecated and replaced by `install`. + +See: link:https://issues.apache.org/jira/browse/TINKERPOP-980[TINKERPOP-980], link:http://tinkerpop.apache.org/docs/3.3.0/reference/#_configuring_2[Reference Documentation - Server Configuration]. + - Removal of useMapperFromGraph - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ++==== Removal of useMapperFromGraph + +The `userMapperFromGraph` serialization configuration option was used to allow the IO configurations of a specific +graph to be assigned to a specific serializer. This feature has been removed completely now. Please use the +`ioRegistries` configuration option to add one or more specific `Graph` serialization capabilities to a serializer. + +[source,yaml] +---- +serializers: + - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV1d0, config: { ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV1d0] }} # application/vnd.gremlin-v1.0+gryo +---- + +see: link:https://issues.apache.org/jira/browse/TINKERPOP-1699[TINKERPOP-1699] + - Gremlin-server.bat - ^^^^^^^^^^^^^^^^^^ ++==== Gremlin-server.bat + +The switch name has changed for installing dependencies. `-i` has been deprecated and replaced by `install`. + - SparkGraphComputer GryoRegistrator - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ++==== SparkGraphComputer GryoRegistrator + +Historically, `SparkGraphComputer` has used `GryoSerializer` to handle the serialization of objects in Spark. The reason +this exists is because TinkerPop uses a shaded version of Kryo and thus, couldn't use the standard `KryoSerializer`-model +provided by Spark. However, a "shim model" was created which allows for the shaded and unshaded versions of Kryo to +interact with one another. To this end, `KryoSerializer` can now be used with a `GryoRegistrator`. The properties file +for a `SparkGraphComputer` now looks as follows: + +``` +spark.serializer=org.apache.spark.serializer.KryoSerializer +spark.kryo.registrator=org.apache.tinkerpop.gremlin.spark.structure.io.gryo.GryoRegistrator +``` + +If the old `GryoSerializer` model is desired, then the properties file should simply look as before: + +``` +spark.serializer=org.apache.tinkerpop.gremlin.spark.structure.io.gryo.GryoSerializer +``` + +See: link:https://issues.apache.org/jira/browse/TINKERPOP-1389 + - ScriptInputFormat - ^^^^^^^^^^^^^^^^^ ++==== ScriptInputFormat + +The API for the script provided to a `ScriptInputFormat` has changed slightly. The signature for `parse(line, factory)` +is now simply `parse(line)`. The inclusion of `factory` was deprecated in 3.1.2. Instead of using the {{factory}} to +get the {{StarGraph}} there is a {{graph}} variable in the glocal context of the script. Simply use that directly in +the script. + +See: link:https://issues.apache.org/jira/browse/TINKERPOP-1137[TINKERPOP-1137], +link:http://tinkerpop.apache.org/docs/3.3.0-SNAPSHOT/reference/#script-io-format[Reference Documentation - Script I/O Format] + - Upgrading for Providers - ~~~~~~~~~~~~~~~~~~~~~~~ ++=== Upgrading for Providers + +IMPORTANT: It is recommended that providers also review all the upgrade instructions specified for users. Many of the +changes there may prove important for the provider's implementation. + - Graph System Providers - ^^^^^^^^^^^^^^^^^^^^^^ ++==== Graph System Providers + - GremlnPlugin - ++++++++++++ ++===== GremlnPlugin + +The previously deprecated `GremlinPlugin` system has been removed. The old `GremlinPlugin` interface formerly resided +in the `org.apache.tinkerpop.gremlin.groovy.plugin` package of `gremlin-groovy`. This interface was replaced by an +interface of the same name in 3.2.4, which now resides in the `org.apache.tinkerpop.gremlin.jsr223` package in +`gremlin-core`. Obviously, existing plugins will need to be updated to use this new interface. + +The plugin model has changed slightly to be more generic and not specifically bound to Groovy based script engines. +Under the new model, the plugin simply returns `Customizer` instances that can be applied generically to any +`ScriptEngine` or specifically to a particular `ScriptEngine`. More details can be found in the +link:http://tinkerpop.apache.org/docs/x.y.z/dev/provider/#gremlin-plugins[Provider Documentation] + - Graph Database Providers - ^^^^^^^^^^^^^^^^^^^^^^^^ ++==== Graph Database Providers + - Test Suite Removal - ++++++++++++++++++ ++===== Test Suite Removal + +A number of test suites that were previously deprecated have been removed which should reduce the burden on graph +providers who are implementing TinkerPop. Test suites related to perfrmance based on `junit-benchmarks` have been +removed as have the suites in `gremlin-groovy-test` (in fact, this entire module has been removed). Specifically, +providers should be concerned with breaking changes related to the removal of: + +* `StructurePerformanceSuite` +* `ProcessPerformanceSuite` +* `GroovyEnvironmentPerformanceSuite` +* `GroovyProcessStandardSuite` +* `GroovyProcessComputerSuite` +* `GroovyEnvironmentSuite` +* `GroovyEnvironmentIntegrateSuite` + +Those graph providers who relied on these tests should simply remove them from their respective test suites. Beware of +`OptOut` annotations that reference tests in these suites as test failure will occur if those references are not +removed. + +See: link:https://issues.apache.org/jira/browse/TINKERPOP-1235[TINKERPOP-1235], link:https://issues.apache.org/jira/browse/TINKERPOP-1612[TINKERPOP-1612] + - TransactionException - ++++++++++++++++++++ ++===== TransactionException + +The `AbstractTransaction.TransactionException` class is now just `TransactionException` which extends `RuntimeExcetpion` +rather than `Exception`. Providers should consider using this exception to wrap their own on calls to +`Transaction.commit()` or `Transaction.rollback()`. By throwing this exception, the TinkerPop stack can better respond +to transaction problems and it allows for more common, generalized error handling for users. + +See: link:https://issues.apache.org/jira/browse/TINKERPOP-1004[TINKERPOP-1004] + - Driver Providers - ^^^^^^^^^^^^^^^^ ++==== Driver Providers + - SASL Byte Array - +++++++++++++++ ++===== SASL Byte Array + +Gremlin Server no longer supports accepting a byte array for the value passed to the "sasl" parameter in +authentication messages. It only accepts a Base64 encoded string. + +See: link:https://issues.apache.org/jira/browse/TINKERPOP-1603[TINKERPOP-1603]
