This is an automated email from the ASF dual-hosted git repository. spmallette pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit 9509d87ffa2d0297ad4c5d79908284c9977f3dfe Author: Stephen Mallette <[email protected]> AuthorDate: Tue Sep 16 13:06:38 2025 -0400 Fixed formatting in upgrade docs CTR --- docs/src/upgrade/release-3.0.x-incubating.asciidoc | 20 +++- docs/src/upgrade/release-3.1.x-incubating.asciidoc | 42 +++++--- docs/src/upgrade/release-3.2.x-incubating.asciidoc | 115 +++++++++++---------- docs/src/upgrade/release-3.3.x.asciidoc | 33 +++--- docs/src/upgrade/release-3.4.x.asciidoc | 31 +++--- docs/src/upgrade/release-3.5.x.asciidoc | 39 +++---- docs/src/upgrade/release-3.6.x.asciidoc | 29 ++++-- docs/src/upgrade/release-3.7.x.asciidoc | 112 +++++++++++--------- 8 files changed, 244 insertions(+), 177 deletions(-) diff --git a/docs/src/upgrade/release-3.0.x-incubating.asciidoc b/docs/src/upgrade/release-3.0.x-incubating.asciidoc index 03062f57ff..0be8c0990f 100644 --- a/docs/src/upgrade/release-3.0.x-incubating.asciidoc +++ b/docs/src/upgrade/release-3.0.x-incubating.asciidoc @@ -25,7 +25,8 @@ image::gremlin-hindu.png[width=225] *Release Date: October 19, 2015* -Please see the link:https://github.com/apache/tinkerpop/blob/3.0.2-incubating/CHANGELOG.asciidoc#tinkerpop-302-release-date-october-19-2015[changelog] for a complete list of all the modifications that are part of this release. +Please see the link:https://github.com/apache/tinkerpop/blob/3.0.2-incubating/CHANGELOG.asciidoc#tinkerpop-302-release-date-october-19-2015[changelog] +for a complete list of all the modifications that are part of this release. === Upgrading for Users @@ -80,7 +81,8 @@ link:https://tinkerpop.apache.org/docs/3.0.2-incubating/#_opprocessors_arguments *Release Date: September 2, 2015* -Please see the link:https://github.com/apache/tinkerpop/blob/3.0.1-incubating/CHANGELOG.asciidoc#tinkerpop-301-release-date-september-2-2015[changelog] for a complete list of all the modifications that are part of this release. +Please see the link:https://github.com/apache/tinkerpop/blob/3.0.1-incubating/CHANGELOG.asciidoc#tinkerpop-301-release-date-september-2-2015[changelog] +for a complete list of all the modifications that are part of this release. === Upgrading for Users @@ -112,7 +114,10 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-804[TINKERPOP-804] ===== GraphFactoryClass Annotation -Providers can consider the use of the new `GraphFactoryClass` annotation to specify the factory class that `GraphFactory` will use to open a new `Graph` instance. This is an optional feature and will generally help implementations that have an interface extending `Graph`. If that is the case, then this annotation can be used in the following fashion: +Providers can consider the use of the new `GraphFactoryClass` annotation to specify the factory class that +`GraphFactory` will use to open a new `Graph` instance. This is an optional feature and will generally help +implementations that have an interface extending `Graph`. If that is the case, then this annotation can be used in the +following fashion: [source,java] ---- @@ -127,7 +132,9 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-778[TINKERPOP-778] ===== GraphProvider.Descriptor Annotation -There was a change that affected providers who implemented `GraphComputer` related tests such as the `ProcessComputerSuite`. If the provider runs those tests, then edit the `GraphProvider` implementation for those suites to include the `GraphProvider.Descriptor` annotation as follows: +There was a change that affected providers who implemented `GraphComputer` related tests such as the +`ProcessComputerSuite`. If the provider runs those tests, then edit the `GraphProvider` implementation for those suites +to include the `GraphProvider.Descriptor` annotation as follows: [source,java] ---- @@ -144,7 +151,10 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-690[TINKERPOP-690] for ===== Semantics of Transaction.close() -There were some adjustments to the test suite with respect to how `Transaction.close()` was being validated. For most providers, this will generally mean checking `OptOut` annotations for test renaming problems. The error that occurs when running the test suite should make it apparent that a test name is incorrect in an `OptOut` if there are issues there. +There were some adjustments to the test suite with respect to how `Transaction.close()` was being validated. For most +providers, this will generally mean checking `OptOut` annotations for test renaming problems. The error that occurs +when running the test suite should make it apparent that a test name is incorrect in an `OptOut` if there are issues +there. See: link:https://issues.apache.org/jira/browse/TINKERPOP-764[TINKERPOP-764] for more information. diff --git a/docs/src/upgrade/release-3.1.x-incubating.asciidoc b/docs/src/upgrade/release-3.1.x-incubating.asciidoc index 66d6042643..0bc4419926 100644 --- a/docs/src/upgrade/release-3.1.x-incubating.asciidoc +++ b/docs/src/upgrade/release-3.1.x-incubating.asciidoc @@ -25,13 +25,15 @@ image::gremlin-gangster.png[width=225] *Release Date: August 21, 2017* -Please see the link:https://github.com/apache/tinkerpop/blob/3.1.8/CHANGELOG.asciidoc#tinkerpop-318-release-date-august-21-2017[changelog] for a complete list of all the modifications that are part of this release. +Please see the link:https://github.com/apache/tinkerpop/blob/3.1.8/CHANGELOG.asciidoc#tinkerpop-318-release-date-august-21-2017[changelog] +for a complete list of all the modifications that are part of this release. == TinkerPop 3.1.7 *Release Date: June 12, 2017* -Please see the link:https://github.com/apache/tinkerpop/blob/3.1.7/CHANGELOG.asciidoc#tinkerpop-317-release-date-june-12-2017[changelog] for a complete list of all the modifications that are part of this release. +Please see the link:https://github.com/apache/tinkerpop/blob/3.1.7/CHANGELOG.asciidoc#tinkerpop-317-release-date-june-12-2017[changelog] +for a complete list of all the modifications that are part of this release. === Upgrading for Users @@ -48,7 +50,8 @@ See: https://issues.apache.org/jira/browse/TINKERPOP-1608[TINKERPOP-1608] *Release Date: February 3, 2017* -Please see the link:https://github.com/apache/tinkerpop/blob/3.1.6/CHANGELOG.asciidoc#tinkerpop-316-release-date-february-3-2017[changelog] for a complete list of all the modifications that are part of this release. +Please see the link:https://github.com/apache/tinkerpop/blob/3.1.6/CHANGELOG.asciidoc#tinkerpop-316-release-date-february-3-2017[changelog] +for a complete list of all the modifications that are part of this release. === Upgrading for Providers @@ -68,7 +71,8 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-1544[TINKERPOP-1544] *Release Date: October 17, 2016* -Please see the link:https://github.com/apache/tinkerpop/blob/3.1.5/CHANGELOG.asciidoc#tinkerpop-315-release-date-october-17-2016[changelog] for a complete list of all the modifications that are part of this release. +Please see the link:https://github.com/apache/tinkerpop/blob/3.1.5/CHANGELOG.asciidoc#tinkerpop-315-release-date-october-17-2016[changelog] +for a complete list of all the modifications that are part of this release. === Upgrading for Users @@ -87,7 +91,8 @@ See: https://issues.apache.org/jira/browse/TINKERPOP-1467[TINKERPOP-1467] *Release Date: September 6, 2016* -Please see the link:https://github.com/apache/tinkerpop/blob/3.1.4/CHANGELOG.asciidoc#tinkerpop-314-release-date-september-6-2016[changelog] for a complete list of all the modifications that are part of this release. +Please see the link:https://github.com/apache/tinkerpop/blob/3.1.4/CHANGELOG.asciidoc#tinkerpop-314-release-date-september-6-2016[changelog] +for a complete list of all the modifications that are part of this release. === Upgrading for Users @@ -104,7 +109,8 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-1350[TINKERPOP-1350] *Release Date: July 18, 2016* -Please see the link:https://github.com/apache/tinkerpop/blob/3.1.3/CHANGELOG.asciidoc#tinkerpop-313-release-date-july-18-2016[changelog] for a complete list of all the modifications that are part of this release. +Please see the link:https://github.com/apache/tinkerpop/blob/3.1.3/CHANGELOG.asciidoc#tinkerpop-313-release-date-july-18-2016[changelog] +for a complete list of all the modifications that are part of this release. === Upgrading for Users @@ -198,7 +204,8 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-1263[TINKERPOP-1263] *Release Date: April 8, 2016* -Please see the link:https://github.com/apache/tinkerpop/blob/3.1.2-incubating/CHANGELOG.asciidoc#tinkerpop-312-release-date-april-8-2016[changelog] for a complete list of all the modifications that are part of this release. +Please see the link:https://github.com/apache/tinkerpop/blob/3.1.2-incubating/CHANGELOG.asciidoc#tinkerpop-312-release-date-april-8-2016[changelog] +for a complete list of all the modifications that are part of this release. === Upgrading for Users @@ -303,9 +310,9 @@ link:https://tinkerpop.apache.org/docs/3.1.2-incubating/reference/#sessions[Refe ===== scriptEvalTimeout Override -The Gremlin Server protocol now allows the passing of `scriptEvaluationTimeout` as an argument to the `SessionOpProcessor` -and the `StandardOpProcessor`. This value will override the setting of the same name provided in the Gremlin Server -configuration file on a per request basis. +The Gremlin Server protocol now allows the passing of `scriptEvaluationTimeout` as an argument to the +`SessionOpProcessor` and the `StandardOpProcessor`. This value will override the setting of the same name provided in +the Gremlin Server configuration file on a per request basis. ==== Plugin Providers @@ -325,7 +332,8 @@ See: link:https://tinkerpop.apache.org/docs/3.1.2-incubating/reference/#console- *Release Date: February 8, 2016* -Please see the link:https://github.com/apache/tinkerpop/blob/3.1.1-incubating/CHANGELOG.asciidoc#tinkerpop-311-release-date-february-8-2016[changelog] for a complete list of all the modifications that are part of this release. +Please see the link:https://github.com/apache/tinkerpop/blob/3.1.1-incubating/CHANGELOG.asciidoc#tinkerpop-311-release-date-february-8-2016[changelog] +for a complete list of all the modifications that are part of this release. === Upgrading for Users @@ -337,7 +345,8 @@ The `gremlin-core` io-package now has a `Storage` interface. The methods that we persisted RDDs in the Spark cache. This update changed a few of the file handling methods. As it stands, these changes only effect manual Gremlin Console -usage as HDFS support was previously provided via Groovy meta-programing. Thus, these are not "code-based" breaking changes. +usage as HDFS support was previously provided via Groovy meta-programing. Thus, these are not "code-based" breaking +changes. * `hdfs.rmr()` no longer exists. `hdfs.rm()` is now recursive. Simply change all references to `rmr()` to `rm()` for identical behavior. * `hdfs.head(location,lines,writableClass)` no longer exists. @@ -515,7 +524,8 @@ interested provider, study the implementations therein to see the purpose of the *Release Date: November 16, 2015* -Please see the link:https://github.com/apache/tinkerpop/blob/3.1.0-incubating/CHANGELOG.asciidoc#tinkerpop-310-release-date-november-16-2015[changelog] for a complete list of all the modifications that are part of this release. +Please see the link:https://github.com/apache/tinkerpop/blob/3.1.0-incubating/CHANGELOG.asciidoc#tinkerpop-310-release-date-november-16-2015[changelog] +for a complete list of all the modifications that are part of this release. Additional upgrade information can be found here: @@ -755,9 +765,9 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-876[TINKERPOP-876] ===== GraphComputer Updates -`GraphComputer.configure(String key, Object value)` is now a method (with default implementation). -This allows the user to specify engine-specific parameters to the underlying OLAP system. These parameters are not intended -to be cross engine supported. Moreover, if there are not parameters that can be altered (beyond the standard `GraphComputer` +`GraphComputer.configure(String key, Object value)` is now a method (with default implementation). This allows the user +to specify engine-specific parameters to the underlying OLAP system. These parameters are not intended to be +cross-engine supported. Moreover, if there are not parameters that can be altered (beyond the standard `GraphComputer` methods), then the provider's `GraphComputer` implementation should simply return and do nothing. ==== Driver Providers diff --git a/docs/src/upgrade/release-3.2.x-incubating.asciidoc b/docs/src/upgrade/release-3.2.x-incubating.asciidoc index c94f0098d2..e637e96d9a 100644 --- a/docs/src/upgrade/release-3.2.x-incubating.asciidoc +++ b/docs/src/upgrade/release-3.2.x-incubating.asciidoc @@ -1685,28 +1685,28 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-1219[TINKERPOP-1219] ===== Step API Update -The `Step` interface is fundamental to Gremlin. `Step.processNextStart()` and `Step.next()` both returned `Traverser<E>`. -We had so many `Traverser.asAdmin()` and direct typecast calls throughout (especially in `TraversalVertexProgram`) that -it was deemed prudent to have `Step.processNextStart()` and `Step.next()` return `Traverser.Admin<E>`. Moreover it makes -sense as this is internal logic where `Admins` are always needed. Providers with their own step definitions will simply -need to change the method signatures of `Step.processNextStart()` and `Step.next()`. No logic update is required -- save -that `asAdmin()` can be safely removed if used. Also, `Step.addStart()` and `Step.addStarts()` take `Traverser.Admin<S>` -and `Iterator<Traverser.Admin<S>>`, respectively. +The `Step` interface is fundamental to Gremlin. `Step.processNextStart()` and `Step.next()` both returned +`Traverser<E>`. There were so many `Traverser.asAdmin()` and direct typecast calls throughout (especially in +`TraversalVertexProgram`) that it was deemed prudent to have `Step.processNextStart()` and `Step.next()` return +`Traverser.Admin<E>`. Moreover it makes sense as this is internal logic where `Admins` are always needed. Providers with +their own step definitions will simply need to change the method signatures of `Step.processNextStart()` and +`Step.next()`. No logic update is required -- save that `asAdmin()` can be safely removed if used. Also, +`Step.addStart()` and `Step.addStarts()` take `Traverser.Admin<S>` and `Iterator<Traverser.Admin<S>>`, respectively. ===== Traversal API Update The way in which `TraverserRequirements` are calculated has been changed (for the better). The ramification is that post compilation requirement additions no longer make sense and should not be allowed. To enforce this, -`Traversal.addTraverserRequirement()` method has been removed from the interface. Moreover, providers/users should never be able -to add requirements manually (this should all be inferred from the end compilation). However, if need be, there is always -`RequirementStrategy` which will allow the provider to add a requirement at strategy application time -(though again, there should not be a reason to do so). +`Traversal.addTraverserRequirement()` method has been removed from the interface. Moreover, providers/users should never +be able to add requirements manually (this should all be inferred from the end compilation). However, if need be, there +is always `RequirementStrategy` which will allow the provider to add a requirement at strategy application time (though +again, there should not be a reason to do so). ===== ComparatorHolder API Change -Providers that either have their own `ComparatorHolder` implementation or reason on `OrderXXXStep` will need to update their code. -`ComparatorHolder` now returns `List<Pair<Traversal,Comparator>>`. This has greatly reduced the complexity of comparison-based -steps like `OrderXXXStep`. However, its a breaking API change that is trivial to update to, just some awareness is required. +Providers that either have their own `ComparatorHolder` implementation or reason on `OrderXXXStep` will need to update +their code. `ComparatorHolder` now returns `List<Pair<Traversal,Comparator>>`. This has greatly reduced the complexity +of comparison-based steps like `OrderXXXStep`. See: link:https://issues.apache.org/jira/browse/TINKERPOP-1209[TINKERPOP-1209] @@ -1737,60 +1737,68 @@ Operational semantic test cases have been added to `GraphComputerTest` to ensure The `Barrier` interface use to simply be a marker interface. Now it has methods and it is the primary means by which distributed steps across an OLAP job are aggregated and distributed. It is unlikely that `Barrier` was ever used -directly by a provider's custom step. Instead, a provider most likely extended `SupplyingBarrierStep`, `CollectingBarrierStep`, -and/or `ReducingBarrierStep`. +directly by a provider's custom step. Instead, a provider most likely extended `SupplyingBarrierStep`, +`CollectingBarrierStep`, and/or `ReducingBarrierStep`. -Providers that have custom extensions to these steps or that use `Barrier` directly will need to adjust their implementation slightly to -accommodate a new API that reflects the `Memory` updates above. This should be a simple change. Note that `FinalGet` -no longer exists and such post-reduction processing is handled by the reducing step (via the new `Generating` interface). +Providers that have custom extensions to these steps or that use `Barrier` directly will need to adjust their +implementation slightly to accommodate a new API that reflects the `Memory` updates above. This should be a simple +change. Note that `FinalGet` no longer exists and such post-reduction processing is handled by the reducing step (via +the new `Generating` interface). See: link:https://issues.apache.org/jira/browse/TINKERPOP-1164[TINKERPOP-1164] ===== Performance Tests -The `ProcessPerformanceSuite` and `TraversalPerformanceTest` have been deprecated. They are still available, but going forward, -providers should implement their own performance tests and not rely on the built-in JUnit benchmark-based performance test suite. +The `ProcessPerformanceSuite` and `TraversalPerformanceTest` have been deprecated. They are still available, but going +forward, providers should implement their own performance tests and not rely on the built-in JUnit benchmark-based +performance test suite. ==== Graph Processor Providers ===== GraphFilter and GraphComputer -The `GraphComputer` API has changed with the addition of `GraphComputer.vertices(Traversal)` and `GraphComputer.edges(Traversal)`. -These methods construct a `GraphFilter` object which is also new to TinkerPop 3.2.0. `GraphFilter` is a "push-down predicate" -used to selectively retrieve subgraphs of the underlying graph to be OLAP processed. +The `GraphComputer` API has changed with the addition of `GraphComputer.vertices(Traversal)` and +`GraphComputer.edges(Traversal)`. These methods construct a `GraphFilter` object which is also new to TinkerPop 3.2.0. +`GraphFilter` is a "push-down predicate" used to selectively retrieve subgraphs of the underlying graph to be OLAP +processed. -* If the graph system provider relies on an existing `GraphComputer` implementations such as `SparkGraphComputer` and/or `GiraphGraphComputer`, -then there is no immediate action required on their part to remain TinkerPop-compliant. However, they may wish to update -their `InputFormat` or `InputRDD` implementation to be `GraphFilterAware` and handle the `GraphFilter` filtering at the disk/database -level. It is advisable to do so in order to reduce OLAP load times and memory/GC usage. +* If the graph system provider relies on an existing `GraphComputer` implementations such as `SparkGraphComputer` and/or +`GiraphGraphComputer`, then there is no immediate action required on their part to remain TinkerPop-compliant. However, +they may wish to update their `InputFormat` or `InputRDD` implementation to be `GraphFilterAware` and handle the +`GraphFilter` filtering at the disk/database level. It is advisable to do so in order to reduce OLAP load times and +memory/GC usage. -* If the graph system provider has their own `GraphComputer` implementation, then they should implement the two new methods -and ensure that `GraphFilter` is processed correctly. There is a new test case called `GraphComputerTest.shouldSupportGraphFilter()` -which ensures the semantics of `GraphFilter` are handled correctly. For a "quick and easy" way to move forward, look to -`GraphFilterInputFormat` as a way of wrapping an existing `InputFormat` to do filtering prior to `VertexProgram` or `MapReduce` -execution. +* If the graph system provider has their own `GraphComputer` implementation, then they should implement the two new +methods and ensure that `GraphFilter` is processed correctly. There is a new test case called +`GraphComputerTest.shouldSupportGraphFilter()` which ensures the semantics of `GraphFilter` are handled correctly. For a +"quick and easy" way to move forward, look to `GraphFilterInputFormat` as a way of wrapping an existing `InputFormat` to +do filtering prior to `VertexProgram` or `MapReduce` execution. -NOTE: To quickly move forward, the `GraphComputer` implementation can simply set `GraphComputer.Features.supportsGraphFilter()` -to `false` and ensure that `GraphComputer.vertices()` and `GraphComputer.edges()` throws `GraphComputer.Exceptions.graphFilterNotSupported()`. -This is not recommended as its best to support `GraphFilter`. +NOTE: To quickly move forward, the `GraphComputer` implementation can simply set +`GraphComputer.Features.supportsGraphFilter()` to `false` and ensure that `GraphComputer.vertices()` and +`GraphComputer.edges()` throws `GraphComputer.Exceptions.graphFilterNotSupported()`. This is not recommended as its best +to support `GraphFilter`. See: link:https://issues.apache.org/jira/browse/TINKERPOP-962[TINKERPOP-962] ===== Job Chaining and GraphComputer -TinkerPop 3.2.0 has integrated `VertexPrograms` into `GraphTraversal`. This means, that a single traversal can compile to multiple -`GraphComputer` OLAP jobs. This requires that `ComputeResults` be chainable. There was never any explicit tests to verify if a -provider's `GraphComputer` could be chained, but now there are. Given a reasonable implementation, it is likely that no changes -are required of the provider. However, to ensure the implementation is "reasonable" `GraphComputerTests` have been added. +TinkerPop 3.2.0 has integrated `VertexPrograms` into `GraphTraversal`. This means, that a single traversal can compile +to multiple `GraphComputer` OLAP jobs. This requires that `ComputeResults` be chainable. There was never any explicit +tests to verify if a provider's `GraphComputer` could be chained, but now there are. Given a reasonable implementation, +it is likely that no changes are required of the provider. However, to ensure the implementation is "reasonable" +`GraphComputerTests` have been added. -* For providers that support their own `GraphComputer` implementation, note that there is a new `GraphComputerTest.shouldSupportJobChaining()`. -This tests verifies that the `ComputerResult` output of one job can be fed into the input of a subsequent job. Only linear chains are tested/required -currently. In the future, branching DAGs may be required. +* For providers that support their own `GraphComputer` implementation, note that there is a new +`GraphComputerTest.shouldSupportJobChaining()`. This tests verifies that the `ComputerResult` output of one job can be +fed into the input of a subsequent job. Only linear chains are tested/required currently. In the future, branching DAGs +may be required. -* For providers that support their own `GraphComputer` implementation, note that there is a new `GraphComputerTest.shouldSupportPreExistingComputeKeys()`. -When chaining OLAP jobs together, if an OLAP job requires the compute keys of a previous OLAP job, then the existing compute keys must be accessible. -A simple 2 line change to `SparkGraphComputer` and `TinkerGraphComputer` solved this for TinkerPop. `GiraphGraphComputer` did not need an update as -this feature was already naturally supported. +* For providers that support their own `GraphComputer` implementation, note that there is a new +`GraphComputerTest.shouldSupportPreExistingComputeKeys()`. When chaining OLAP jobs together, if an OLAP job requires the +compute keys of a previous OLAP job, then the existing compute keys must be accessible. A simple 2 line change to +`SparkGraphComputer` and `TinkerGraphComputer` solved this for TinkerPop. `GiraphGraphComputer` did not need an update +as this feature was already naturally supported. See: link:https://issues.apache.org/jira/browse/TINKERPOP-570[TINKERPOP-570] @@ -1798,10 +1806,11 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-570[TINKERPOP-570] ===== ScriptTraversal -Providers that have custom Gremlin language implementations (e.g. Gremlin-Scala), there is a new class called `ScriptTraversal` -which will handle script-based processing of traversals. The entire `GroovyXXXTest`-suite was updated to use this new class. -The previous `TraversalScriptHelper` class has been deprecated so immediate upgrading is not required, but do look into -`ScriptTraversal` as TinkerPop will be using it as a way to serialize "String-based traversals" over the network moving forward. +Providers that have custom Gremlin language implementations (e.g. Gremlin-Scala), there is a new class called +`ScriptTraversal` which will handle script-based processing of traversals. The entire `GroovyXXXTest`-suite was updated +to use this new class. The previous `TraversalScriptHelper` class has been deprecated so immediate upgrading is not +required, but do look into `ScriptTraversal` as TinkerPop will be using it as a way to serialize +"String-based traversals" over the network moving forward. See: link:https://issues.apache.org/jira/browse/TINKERPOP-1154[TINKERPOP-1154] @@ -1818,8 +1827,8 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-1153[TINKERPOP-1153] ===== TraversalEngine Deprecation and GraphProvider -The `TraversalSource` infrastructure has been completely rewritten. Fortunately for users, their code is backwards compatible. -Unfortunately for graph system providers, a few tweaks to their implementation are in order. +The `TraversalSource` infrastructure has been completely rewritten. Fortunately for users, their code is backwards +compatible. Unfortunately for graph system providers, a few tweaks to their implementation are in order. * If the graph system supports more than `Graph.compute()`, then implement `GraphProvider.getGraphComputer()`. * For custom `TraversalStrategy` implementations, change `traverser.getEngine().isGraphComputer()` to `TraversalHelper.onGraphComputer(Traversal)`. diff --git a/docs/src/upgrade/release-3.3.x.asciidoc b/docs/src/upgrade/release-3.3.x.asciidoc index d361cf4ce7..9dda34d243 100644 --- a/docs/src/upgrade/release-3.3.x.asciidoc +++ b/docs/src/upgrade/release-3.3.x.asciidoc @@ -483,7 +483,7 @@ produce a valid range (an empty result), then the `EarlyLimitStrategy` will remo insert a `NoneStep` instead. This strategy is particularly useful when a provider implementation generates the queries to the underlying database. By -making sure that the ranges are applied as early as possible, we can ensure that the underlying database is only asked +making sure that the ranges are applied as early as possible, it is assured that the underlying database is only asked for the least amount of data necessary to continue the traversal evaluation. === Upgrading for Providers @@ -844,7 +844,7 @@ in regular JSON maps. This allows for common traversals like `g.V().groupCount() 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, +longer supported. There is little point to such a feature as there is greater adoption of 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 @@ -912,10 +912,11 @@ link:https://tinkerpop.apache.org/docs/3.3.0/reference/#metrics[Reference Docume ==== 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. +`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: @@ -928,9 +929,10 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-1541[TINKERPOP-1541] ==== 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. +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] @@ -952,7 +954,8 @@ link:https://issues.apache.org/jira/browse/TINKERPOP-1651[TINKERPOP-1651] ==== 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. +`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] @@ -1162,11 +1165,11 @@ The switch name has changed for installing dependencies. `-i` has been deprecate ==== 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: +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 diff --git a/docs/src/upgrade/release-3.4.x.asciidoc b/docs/src/upgrade/release-3.4.x.asciidoc index ab50adb5d1..93c8a1f85c 100644 --- a/docs/src/upgrade/release-3.4.x.asciidoc +++ b/docs/src/upgrade/release-3.4.x.asciidoc @@ -303,8 +303,8 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-2445[TINKERPOP-2445] With Java it has been possible to pass per-request settings for both scripts and bytecode. While Javascript, Python, and .NET allowed this in various ways, it wasn't quite as convenient as Java, nor was it well documented. In this -release, the approach for making this sort of per-request configurations is now much more consistent across languages. -We see this most evident in bytecode based requests: +release, the approach for making this sort of per-request configurations is now much more consistent across languages, +as is most evidently demonstrated in bytecode-based requests: *Java* @@ -677,7 +677,7 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-2318[TINKERPOP-2318] ===== GraphBinary API Change In GraphBinary serialization, Java `GraphBinaryReader` and `GraphBinaryWriter`, along with `TypeSerializer<T>` -interface now take a `Buffer` instance instead of Netty's `ByteBuf`, that way we avoid exposing Netty's API in our own +interface now take a `Buffer` instance instead of Netty's `ByteBuf`, thereby avoiding exposure of Netty's API in our own public API. Using our own `Buffer` interface, wrapping Netty's buffer API, allowed us to move `TypeSerializer<T>` implementations, @@ -692,7 +692,8 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-2305[TINKERPOP-2305] *Release Date: October 14, 2019* -Please see the link:https://github.com/apache/tinkerpop/blob/3.4.4/CHANGELOG.asciidoc#release-3-4-4[changelog] for a complete list of all the modifications that are part of this release. +Please see the link:https://github.com/apache/tinkerpop/blob/3.4.4/CHANGELOG.asciidoc#release-3-4-4[changelog] for a +complete list of all the modifications that are part of this release. === Upgrading for Users @@ -890,7 +891,7 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-2216[TINKERPOP-2216] In GraphBinary serialization, Java `write()` and `writeValue()` from `TypeSerializer<T>` interface now take a Netty's `ByteBuf` instance instead of an `ByteBufAllocator`, that way the same buffer instance gets reused during the write -of a message. Additionally, we took the opportunity to remove the unused parameter from `ResponseMessageSerializer`. +of a message. Additionally, the unused parameter was removed from `ResponseMessageSerializer`. See: link:https://issues.apache.org/jira/browse/TINKERPOP-2161[TINKERPOP-2161] @@ -948,7 +949,7 @@ link:https://tinkerpop.apache.org/docs/3.4.1/reference/#sparql-with-gremlin[Refe In GraphBinary serialization, Java `write()` and `writeValue()` from `TypeSerializer<T>` interface now take a Netty's `ByteBuf` instance instead of an `ByteBufAllocator`, that way the same buffer instance gets reused during the write -of a message. Additionally, we took the opportunity to remove the unused parameter from `ResponseMessageSerializer`. +of a message. Additionally, the unused parameter was removed from `ResponseMessageSerializer`. See: link:https://issues.apache.org/jira/browse/TINKERPOP-2161[TINKERPOP-2161] @@ -956,7 +957,8 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-2161[TINKERPOP-2161] *Release Date: January 2, 2019* -Please see the link:https://github.com/apache/tinkerpop/blob/3.4.0/CHANGELOG.asciidoc#release-3-4-0[changelog] for a complete list of all the modifications that are part of this release. +Please see the link:https://github.com/apache/tinkerpop/blob/3.4.0/CHANGELOG.asciidoc#release-3-4-0[changelog] for a +complete list of all the modifications that are part of this release. === Upgrading for Users @@ -985,7 +987,8 @@ whereas it could previously create an unlimited number of connections. Each `Con `MaxInProcessPerConnection` requests in parallel. If this limit is reached for all connections, then a `NoConnectionAvailableException` is thrown which makes this a breaking change. -These settings can be set as properties on the `ConnectionPoolSettings` instance that can be passed to the `GremlinClient`. +These settings can be set as properties on the `ConnectionPoolSettings` instance that can be passed to the +GremlinClient`. See: link:https://issues.apache.org/jira/browse/TINKERPOP-1774[TINKERPOP-1774], link:https://issues.apache.org/jira/browse/TINKERPOP-1775[TINKERPOP-1775], @@ -993,7 +996,8 @@ link:https://tinkerpop.apache.org/docs/3.4.0/reference/#_connection_pool[Referen ==== Indexing of Collections -TinkerPop 3.4.0 adds a new `index()`-step, which allows users to transform simple collections into index collections or maps. +TinkerPop 3.4.0 adds a new `index()`-step, which allows users to transform simple collections into index collections or +maps. ``` gremlin> g.V().hasLabel("software").values("name").fold(). @@ -1010,11 +1014,13 @@ gremlin> g.V().hasLabel("person").values("name").fold(). ==== Modulation of valueMap() -The `valueMap()` step now supports `by` and `with` modulation, which also led to the deprecation of `valueMap(true)` overloads. +The `valueMap()` step now supports `by` and `with` modulation, which also led to the deprecation of `valueMap(true)` +overloads. ===== by() Modulation -With the help of the `by()` modulator `valueMap()` result values can now be adjusted, which is particularly useful to turn multi-/list-values into single values. +With the help of the `by()` modulator `valueMap()` result values can now be adjusted, which is particularly useful to +turn multi-/list-values into single values. ``` gremlin> g.V().hasLabel("person").valueMap() @@ -1642,7 +1648,8 @@ Server: bin/gremlin-server.sh install org.codehaus.groovy groovy-sql 2.5.2 ``` -If your project depended on groovy-sql transitively, simply include it in your project's build file (e.g. maven: pom.xml). +If your project depended on groovy-sql transitively, simply include it in your project's build file (e.g. maven: +pom.xml). See: link:https://issues.apache.org/jira/browse/TINKERPOP-2037[TINKERPOP-2037] diff --git a/docs/src/upgrade/release-3.5.x.asciidoc b/docs/src/upgrade/release-3.5.x.asciidoc index fc8b088727..be668796b9 100644 --- a/docs/src/upgrade/release-3.5.x.asciidoc +++ b/docs/src/upgrade/release-3.5.x.asciidoc @@ -44,8 +44,8 @@ complete list of all the modifications that are part of this release. Introduced max number length (10000 chars), string length (20 000 000 chars), and nesting depth (1000) constraints for GraphSON deserialization due to security vulnerabilities with earlier versions of Jackson Databind. -New constraints are not expected to impact most users but can be overriden via GraphSONMapper.Builder or through serializer configuration. -Example: +New constraints are not expected to impact most users but can be overriden via GraphSONMapper.Builder or through +serializer configuration. [source,yaml] ---- @@ -94,14 +94,15 @@ There are various performance improvements included in this release: * Gremlin Console now uses `ImportCustomizer` to add imports, reducing the time spent resolving imports. This especially reduces the overhead for executing many simple lines of code. Processing for documentation (which runs thousands of -simple lines) was reduced from 90 minutes to 25 minutes. Users should notice performance improvements when using the Gremlin Console. -* In some instances, a graph may contain elements whose Ids are sequentially increasing integers. When using the `path()` -step with a `CollectingBarrierStep` in these graphs, one may observe a huge increase in processing time because of an -inefficient hash algorithm. This hash algorithm has been updated and tests have shown a 40x improvement in these +simple lines) was reduced from 90 minutes to 25 minutes. Users should notice performance improvements when using the +Gremlin Console. +* In some instances, a graph may contain elements whose Ids are sequentially increasing integers. When using the +`path()` step with a `CollectingBarrierStep` in these graphs, one may observe a huge increase in processing time because +of an inefficient hash algorithm. This hash algorithm has been updated and tests have shown a 40x improvement in these `CollectingBarrierStep` queries involving `path()`. -* There is an important performance improvement to `TraversalStrategy` application which removes some unnecessary recursion -when evaluating the Gremlin syntax tree and should improve traversal compilation times, particularly on traversals with -many children. Tests have shown a 10x improvement in compilation time. +* There is an important performance improvement to `TraversalStrategy` application which removes some unnecessary +recursion when evaluating the Gremlin syntax tree and should improve traversal compilation times, particularly on +traversals with many children. Tests have shown a 10x improvement in compilation time. * `FilterRankingStrategy` saw a fairly specific performance improvement that should be particularly noticeable for traversal that have many children and some depth to their syntax tree. A particularly complex traversal that was used in testing this behavior improved its compilation time from 1 minute 48 seconds to just a few milliseconds. @@ -219,9 +220,9 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-2813[TINKERPOP-2813] ==== Added User Agent to Gremlin drivers -Previously, a server does not distinguish amongst the different types of clients connecting to it. We have now added -user agent to web socket handshake in all the drivers, each with their own configuration to enable or disable user agent. -User agent is enabled by default for all drivers. +Previously, a server does not distinguish amongst the different types of clients connecting to it. This release adds a +user agent to web socket handshake in all the drivers, each with their own configuration to enable or disable user +agent. User agent is enabled by default for all drivers. * Java driver can be controlled by the `enableUserAgentOnConnect` configuration. * .Net driver can be controlled by the `EnableUserAgentOnConnect` in `ConnectionPoolSettings`. @@ -233,8 +234,9 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-2480[TINKERPOP-2480] ==== Update to SSL Handshake Timeout Configuration -Previously, the java driver relies on the default 10 second SSL handshake timeout defined by Netty. We have removed -the default SSL handshake timeout. The SSL handshake timeout will instead be capped by setting `connectionSetupTimeoutMillis`. +Previously, the java driver relies on the default 10 second SSL handshake timeout defined by Netty. The default SSL +handshake timeout has been removed. The SSL handshake timeout will instead be capped by setting +`connectionSetupTimeoutMillis`. See: link:https://issues.apache.org/jira/browse/TINKERPOP-2814[TINKERPOP-2814] @@ -265,7 +267,7 @@ In the root directory of your project, containing the `go.mod` file, run the fol `go get github.com/apache/tinkerpop/gremlin-go/[email protected]` -Afterwards, we can quickly get started with writing Gremlin in Go: +Writing Gremlin in Go looks like this: [source,go] ---- @@ -587,7 +589,8 @@ See: link: https://issues.apache.org/jira/browse/TINKERPOP-2616[TINKERPOP-2616] *Release Date: May 3, 2021* -Please see the link:https://github.com/apache/tinkerpop/blob/3.5.0/CHANGELOG.asciidoc#release-3-5-0[changelog] for a complete list of all the modifications that are part of this release. +Please see the link:https://github.com/apache/tinkerpop/blob/3.5.0/CHANGELOG.asciidoc#release-3-5-0[changelog] for a +complete list of all the modifications that are part of this release. === Upgrading for Users @@ -1122,8 +1125,8 @@ confusing approach as the behavior of the step changes simply because another st execution of the traversal, relies on the execution of traversal strategies when the same traversal should produce the same results irrespective of the strategies applied to it. -In 3.5.0, we look to better adhere to that guiding design principle and ensure a more consistent output for these types -of traversals. While the preferred method is to specify the labels to preserve from `match()` with a following +In 3.5.0, there is better adherence to that guiding design principle and ensuring a more consistent output for these +types of traversals. While the preferred method is to specify the labels to preserve from `match()` with a following `select()` step as shown above, `match()` will now consistently return all labels when they are not specified explicitly. diff --git a/docs/src/upgrade/release-3.6.x.asciidoc b/docs/src/upgrade/release-3.6.x.asciidoc index ff6c79a04b..448c082114 100644 --- a/docs/src/upgrade/release-3.6.x.asciidoc +++ b/docs/src/upgrade/release-3.6.x.asciidoc @@ -72,14 +72,15 @@ complete list of all the modifications that are part of this release. === Upgrading for Providers -The `HttpGremlinRequestEncoder` constructor has been deprecated in favor of one with an additional parameter `boolean userAgentEnabled`. -User agent HTTP headers can now be encoded if this flag is enabled. +The `HttpGremlinRequestEncoder` constructor has been deprecated in favor of one with an additional parameter +`boolean userAgentEnabled`. User agent HTTP headers can now be encoded if this flag is enabled. == TinkerPop 3.6.5 *Release Date: July 31, 2023* -Please see the link:https://github.com/apache/tinkerpop/blob/3.6.5/CHANGELOG.asciidoc#release-3.6.5[changelog] for a complete list of all the modifications that are part of this release. +Please see the link:https://github.com/apache/tinkerpop/blob/3.6.5/CHANGELOG.asciidoc#release-3.6.5[changelog] for a +complete list of all the modifications that are part of this release. === Upgrading for Users @@ -124,20 +125,22 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-2965[TINKERPOP-2965] *Release Date: May 12, 2023* -Please see the link:https://github.com/apache/tinkerpop/blob/3.6.4/CHANGELOG.asciidoc#release-3-6-4[changelog] for a complete list of all the modifications that are part of this release. +Please see the link:https://github.com/apache/tinkerpop/blob/3.6.4/CHANGELOG.asciidoc#release-3-6-4[changelog] for a +complete list of all the modifications that are part of this release. == TinkerPop 3.6.3 *Release Date: May 1, 2023* -Please see the link:https://github.com/apache/tinkerpop/blob/3.6.3/CHANGELOG.asciidoc#release-3-6-3[changelog] for a complete list of all the modifications that are part of this release. +Please see the link:https://github.com/apache/tinkerpop/blob/3.6.3/CHANGELOG.asciidoc#release-3-6-3[changelog] for a +complete list of all the modifications that are part of this release. === Upgrading for Users ==== Deprecation Warning for Go 1.17 -Release 3.6.3 will be one of the last versions of 3.6.x to use Go 1.17 for `gremlin-go` as this runtime is no longer supported. -Upcoming releases of `gremlin-go` will attempt to use the latest available version of Go. +Release 3.6.3 will be one of the last versions of 3.6.x to use Go 1.17 for `gremlin-go` as this runtime is no longer +supported. Upcoming releases of `gremlin-go` will attempt to use the latest available version of Go. === Upgrading for Providers @@ -159,7 +162,8 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-2929[TINKERPOP-2929] *Release Date: January 16, 2023* -Please see the link:https://github.com/apache/tinkerpop/blob/3.6.2/CHANGELOG.asciidoc#release-3-6-2[changelog] for a complete list of all the modifications that are part of this release. +Please see the link:https://github.com/apache/tinkerpop/blob/3.6.2/CHANGELOG.asciidoc#release-3-6-2[changelog] for a +complete list of all the modifications that are part of this release. === Upgrading for Users @@ -218,7 +222,8 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-2850[TINKERPOP-2850] *Release Date: July 18, 2022* -Please see the link:https://github.com/apache/tinkerpop/blob/3.6.1/CHANGELOG.asciidoc#release-3-6-1[changelog] for a complete list of all the modifications that are part of this release. +Please see the link:https://github.com/apache/tinkerpop/blob/3.6.1/CHANGELOG.asciidoc#release-3-6-1[changelog] for a +complete list of all the modifications that are part of this release. === Upgrading for Users @@ -236,7 +241,8 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-2723[TINKERPOP-2723] *Release Date: April 4, 2022* -Please see the link:https://github.com/apache/tinkerpop/blob/3.6.0/CHANGELOG.asciidoc#release-3-6-0[changelog] for a complete list of all the modifications that are part of this release. +Please see the link:https://github.com/apache/tinkerpop/blob/3.6.0/CHANGELOG.asciidoc#release-3-6-0[changelog] for a +complete list of all the modifications that are part of this release. === Upgrading for Users @@ -902,7 +908,8 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-2650[TINKERPOP-2650] ==== `property()` with Map -The `property()` step has been extended to take a `Map` of property key/value pairs as an argument with two new signatures: +The `property()` step has been extended to take a `Map` of property key/value pairs as an argument with two new +signatures: ```text property(Map) diff --git a/docs/src/upgrade/release-3.7.x.asciidoc b/docs/src/upgrade/release-3.7.x.asciidoc index c38af84179..09d40562ac 100644 --- a/docs/src/upgrade/release-3.7.x.asciidoc +++ b/docs/src/upgrade/release-3.7.x.asciidoc @@ -136,9 +136,9 @@ gremlin> g.V(1).outE().as("a").V(1).values("name").concat(select("a").label(), s ==>markoknowsjosh ---- -A notable breaking change from 3.7.0 is that we have output order of `inject()` as a child of `concat()` to be -consistent with other parent steps. Any 3.7.0 uses of `concat(inject(X))` should change to `concat(constant(X))` to -retain the old semantics. +A notable breaking change from 3.7.0 is that the output order of `inject()` as a child of `concat()` has been adjusted +to be consistent with other parent steps. Any 3.7.0 uses of `concat(inject(X))` should change to `concat(constant(X))` +to retain the previous semantics. [source,text] ---- @@ -160,6 +160,7 @@ link:https://tinkerpop.apache.org/docs/3.7.1/reference/#concat-step[concat()-ste ===== New String Steps asString(), length(), toLower(), toUpper(): The following example demonstrates the use of a closure to perform the above functions: + [source,text] ---- gremlin> g.V().hasLabel("person").values("age").map{it.get().toString()} @@ -188,6 +189,7 @@ gremlin> g.V().values("name").map{it.get().toUpperCase()} ---- With these additional steps this operation can be performed with standard Gremlin syntax: + [source,text] ---- gremlin> g.V().hasLabel("person").values("age").asString() @@ -215,8 +217,9 @@ gremlin> g.V().values("name").toUpper() ==>PETER ---- -Scopes are also enabled on these string functions. The global scope functions synonymous to parameterless function call, and will only accept string traversers. -The local scope will also operate inside of lists of strings. +Scopes are also enabled on these string functions. The global scope functions synonymous to parameterless function call, +and will only accept string traversers. The local scope will also operate inside of lists of strings. + [source,text] ---- gremlin> g.V().values("name").fold().toUpper(local) @@ -231,7 +234,8 @@ link:https://tinkerpop.apache.org/docs/3.7.1/reference/#toUpper-step[toUpper()-s ===== New String Steps trim(), lTrim(), rTrim(), reverse(): -The following example demonstrates the use of a closure to reverse and trim strings (concatenated with a string for demonstration): +The following example shows the use of a closure to reverse and trim strings (concatenated with a string for +demonstration): [source,text] ---- @@ -251,6 +255,7 @@ gremlin> g.inject(" hi ").map{it.get().replaceAll(/\s+$/, '') + "right_trim"} ---- With these additional steps this operation can be performed with standard Gremlin syntax: + [source,text] ---- gremlin> g.V().values("name").reverse() @@ -268,9 +273,11 @@ gremlin> g.inject(" hi ").rTrim().concat("right_trim") ==> hiright_trim ---- -Scopes are enabled on trim(), lTrim(), and rTrim(). The global scope functions synonymous to parameterless function call, and will only accept string traversers. -The local scope will also operate inside of lists of strings. -Due to reverse() overloading as a list function, scope is not applied, as reversing lists inside of lists is not a practical use case. +`Scope` arguments are allowed on `trim()`, `lTrim()`, and `rTrim()`. The global scope functions synonymous to +parameterless function call, and will only accept string traversers. Using `Scope.local` will configure the step to +operate inside of lists of strings. Due to `reverse()` overloading as a list function, `Scope` is not applied, as +reversing lists inside of lists is not a practical use case. + [source,text] ---- gremlin> g.inject([" hello ", " world "]).trim(Scope.local) @@ -286,6 +293,7 @@ link:https://issues.apache.org/jira/browse/TINKERPOP-2672[TINKERPOP-2672] ===== New String Steps replace(), split(), substring() The following example demonstrates the use of a closure to perform `replace()` and `split()` functions: + [source,text] ---- gremlin> g.V().hasLabel("software").values("name").map{it.get().replace("p", "g")} @@ -297,7 +305,9 @@ gremlin> g.V().hasLabel("person").values("name").map{it.get().split("a")} ==>[josh] ==>[peter] ---- + With these additional steps this operation can be performed with standard Gremlin syntax: + [source,text] ---- gremlin> g.V().hasLabel("software").values("name").replace("p", "g") @@ -310,8 +320,9 @@ gremlin> g.V().hasLabel("person").values("name").split("a") ==>[peter] ---- -For `substring()`, the new Gremlin step follows the Python standard, taking parameters start index and optionally an -end index. This will enable certain operations that would be complex to achieve with closure: +For `substring()`, the new Gremlin step follows the Python standard, taking a start index and optionally an end index. +This will enable certain operations that would be complex to achieve with closure: + [source,text] ---- gremlin> g.V().hasLabel("person").values("name").map{it.get().substring(1,4)} @@ -332,6 +343,7 @@ Type ':help' or ':h' for help. The `substring()`-step will return a substring with indices specified by the start and end indices, or from the start index to the remainder of the string if an end index is not specified. Negative indices are allowed and will count from the end of the string: + [source,text] ---- gremlin> g.V().hasLabel("person").values("name").substring(1,4) @@ -357,8 +369,10 @@ link:https://tinkerpop.apache.org/docs/3.7.1/reference/#substring-step[substring link:https://issues.apache.org/jira/browse/TINKERPOP-2672[TINKERPOP-2672] ===== New String Step format() -This step is designed to simplify some string operations. In general, it is similar to the string formatting function -available in many programming languages. Variable values can be picked up from Element properties, maps and scope variables. + +The `format()` step is designed to simplify some string operations. In general, it is similar to the string formatting +function available in many programming languages. Variable values can be picked up from `Element` properties, `Map` and +step labels. [source,text] ---- @@ -378,6 +392,7 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-2334[TINKERPOP-2334], link:https://tinkerpop.apache.org/docs/3.7.1/reference/#format-step[format()-step] ==== List Manipulation Steps + Additional List manipulation/filter steps have been added to replace the use of closures: `any()`, `all()`, `product()`, `merge()`, `intersect()`, `combine()`, `conjoin()`, `difference()`,`disjunct()` and `reverse()`. @@ -421,7 +436,7 @@ link:https://tinkerpop.apache.org/docs/3.7.1/reference/#disjunct-step[disjunct() ==== Date Manipulation Steps Date manipulations in Gremlin queries were only possible using closures, which may or may not be supported by -different providers. In 3.7.1, we introduce the `asDate()`, `dateAdd` and `dateDiff` steps aimed to replace the usage of closure. +different providers. In 3.7.1, the `asDate()`, `dateAdd` and `dateDiff` steps were introduced. The following example demonstrates usage of newly introduced steps: @@ -461,20 +476,23 @@ removed. ===== InsertionOrderingRequired Test Tag -Added a new `@InsertionOrderingRequired` tag which signifies Gherkin feature tests which are reliant on the graph system predictably returning results (vertices, edges, properties) in the same order in which they were inserted into the graph. These tests should be skipped by any graph which does not guarantee such ordering. +Added a new `@InsertionOrderingRequired` tag which signifies Gherkin feature tests which are reliant on the graph system +predictably returning results (vertices, edges, properties) in the same order in which they were inserted into the +graph. These tests should be skipped by any graph which does not guarantee such ordering. == TinkerPop 3.7.0 *Release Date: July 31, 2023* -Please see the link:https://github.com/apache/tinkerpop/blob/3.7.0/CHANGELOG.asciidoc#release-3-7-0[changelog] for a complete list of all the modifications that are part of this release. +Please see the link:https://github.com/apache/tinkerpop/blob/3.7.0/CHANGELOG.asciidoc#release-3-7-0[changelog] for a +complete list of all the modifications that are part of this release. === Upgrading for Users ==== String concat() Step String manipulations in Gremlin queries were only possible using closures, which may or may not be supported by -different providers. In 3.7.0, we introduce the `concat()`-step as the beginning of a series of string manipulation steps +different providers. In 3.7.0, the `concat()`-step is introduced as the first in a series of string manipulation steps aimed to replace the usage of closure. The following example demonstrates the use of a closure to add a new vertex with a label like an existing vertex but @@ -538,9 +556,9 @@ to vertices, a `Map` can be given to `mergeV()` and `property()` steps. The limi with this syntax was not possible without reverting back to `property()` steps that took a `Cardinality` as an argument in some way. The following paragraphs show how changes for in 3.6.5 make this syntax much better for multi-properties. -The `mergeV()` step makes it much easier to write upsert-like traversals. Of course, if you had a graph that required -the use of multi-properties, some of the ease of `mergeV()` was lost. It typically meant falling back to traversals -using `sideEffect()` or similar direct uses of `property()` to allow it to work properly: +The `mergeV()` step makes it much easier to write upsert-like traversals. Of course, if a graph required the use of +multi-properties, some of the ease of `mergeV()` was lost. It typically meant falling back to traversals using +`sideEffect()` or similar direct uses of `property()` to allow it to work properly: [source,groovy] ---- @@ -605,16 +623,16 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-2957[TINKERPOP-2957] ==== TinkerGraph Transactions Previously, there was no reference implementation provided for the `Transaction` API as this feature wasn't supported by -TinkerGraph. Users were instead directed towards the Neo4jGraph provided in `neo4j-gremlin` if they wanted to get access -to a `Graph` implementation that supported transactions. Unfortunately, the maintenance around this plugin has largely -been abandoned and is only compatible with Neo4j version 3.4, which reached end of life in March 2020. +TinkerGraph. Users were instead directed towards the Neo4jGraph provided in `neo4j-gremlin` to gain access +to a `Graph` implementation that supported transactions. Unfortunately, maintenance around this plugin has largely +been abandoned and it is only compatible with Neo4j version 3.4, which reached end of life in March 2020. -As of this version, we are introducing the transactional TinkerGraph, `TinkerTransactionGraph`, which is TinkerGraph with +As of this version, the transactional TinkerGraph, `TinkerTransactionGraph`, is introduced, which is TinkerGraph with transaction capabilities. The `TinkerTransactionGraph` has `read committed` isolation level, which is the same as the Neo4jGraph provided in `neo4j-gremlin`. Only `ThreadLocal` transactions are implemented, therefore embedded graph -transactions may not be fully supported. These transaction semantics may not fit the use case for some production -scenarios that require strict ACID-like transactions. Therefore, it is recommended that TinkerTransactionGraph be used -as a Graph for test environments where you still require support for transactions. +transactions may not be fully supported. These transaction semantics may not fit certain production +scenarios that require strict ACID-like transactions. Therefore, `TinkerTransactionGraph` is recommended for test +environments where transaction support is still required. ===== Usage examples @@ -687,9 +705,9 @@ gremlin> g.V().valueMap() <5> <1> Open remote Console session and spawn remote graph traversal source for the empty TinkerTransactionGraph. <2> Spawn a GraphTraversalSource by opening a transaction. -<3> The vertex is added in the remote graph until we commit the transaction (which automatically closes the transaction). +<3> The vertex is added in the remote graph until the commit of the transaction (which automatically closes the transaction). <4> Spawn another GraphTraversalSource by opening a new transaction. -<5> The second vertex will not bed added to the remote graph since we rolled back the change +<5> The second vertex will not be added to the remote graph since the change was rolled back. To use the embedded TinkerTransactionGraph in Gremlin Console: @@ -734,13 +752,12 @@ link:https://tinkerpop.apache.org/docs/3.7.0/reference/#tinkergraph-gremlin-tx[R ==== Properties on Elements -One of the peculiar aspects of using Gremlin remotely is that if you do something like `v = g.V().next()` you will -find that the `v`, the `Vertex` object, does not have any properties associated with it, even if the database -associates some with it. It will be a "reference" only, in that it will only have an `id` and `label`. The reason and +One of the peculiar aspects of using Gremlin remotely is that a traversal such as `v = g.V().next()` will +return a `Vertex` object without any properties associated with it, even if the database +associates properties. It will be a "reference" only, with just an `id` and `label`. The reason and history for this approach can be found on the link:https://lists.apache.org/thread/xltcon4zxnwq4fyw2r2126syyrqm8spy[dev list]. -While this has been a long-standing way TinkerPop operates, it is a confusing point for new users and often forces -some inconvenience on folks by requiring them to alter queries to transform graph elements to other forms that can -carry the property data (e.g. `elementMap()`). +While this has been a long-standing way TinkerPop operates, it can be confusing and often forces inconvenience by +requiring queries to transform graph elements to other forms that can carry the property data (e.g. `elementMap()`). With this new release, properties are finally available on graph elements for all programming languages and are now returned by default for OLTP requests. Gremlin Server 3.5 and 3.6 can return properties only in some special cases. @@ -785,7 +802,8 @@ drivers connecting to 3.7.x servers should disable this functionality server-sid globals << [g : traversal().withEmbedded(graph).withStrategies(ReferenceElementStrategy)] ---- -For 3.7 drivers, properties on elements can also be disabled per request using the `tokens` option with `materializeProperties`. +For 3.7 drivers, properties on elements can also be disabled per request using the `tokens` option with +`materializeProperties`. [source,csharp] ---- @@ -795,7 +813,7 @@ g.With("materializeProperties", "tokens").V(1).Next() ===== Possible issues `ReferenceElement`-type objects are no longer returned by the server by default. When upgrading existing code to 3.7.0, -it is possible that this change could have some impact if you directly declared use of those classes. For example: +it is possible that this change could have some impact if code directly declared use of those classes. For example: [source,java] ---- @@ -829,7 +847,7 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-2348[TINKERPOP-2348] Removed the `connectOnStartup` option for Gremlin Javascript API to resolve potential `unhandledRejection` and race conditions. New `DriverRemoteConnection` objects no longer initiate connection by default at startup. Call `open()` -explicitly if one wishes to manually connect on startup. +explicitly to manually connect on startup if desired. For example: @@ -875,7 +893,7 @@ the GraphSON `MessageSerializer` implementations. For GraphSON 1.0, untyped Grap `GraphSONMessageSerializerV1d0` and typed as `GraphSONMessageSerializerGremlinV1d0`, but for version 2.0 of GraphSON, the idea of untyped GraphSON was left behind and so typed GraphSON became `GraphSONMessageSerializerV2d0` which followed to version 3.0. With the return of typed and untyped GraphSON for 3.6.5, it seemed important to unify all -of this naming and given the previously mentioned removal of the "d0" we now have: +of this naming and given the previously mentioned removal of the "d0" the following changes apply: * `GraphSONMessageSerializerV1` is now typed GraphSON 1.0 * `GraphSONMessageSerializerGremlinV1d0` is removed. @@ -888,10 +906,10 @@ of this naming and given the previously mentioned removal of the "d0" we now hav ==== Building and Running with JDK 17 -You can now run TinkerPop with Java 17. Be advised that there are some issues with reflection and so you may need to -either --add-opens or --add-exports certain modules to enable it to work with Java 17. This mostly affects the Kryo -serialization library which is used with OLAP. If you use OLTP, then you may not need to add any of these options to -the JVM. The following are only examples used by TinkerPop's automated tests and are placed here for convenience. +TinkerPop can now be run with Java 17. Be advised that there are some issues with reflection and so it may be necessary +to either --add-opens or --add-exports certain modules to enable it to work with Java 17. This mostly affects the Kryo +serialization library which is used with OLAP. For OLTP usage, these options may not be required. +The following are examples used by TinkerPop's automated tests and are placed here for convenience. [source,text] ---- @@ -923,7 +941,7 @@ one method `ReadValueAsync`, there are now methods `WriteNullableValueAsync` and Some `set` property accessors were removed from some pure data classes in the `Structure` and the `Driver.Messages` namespaces to initialize these properties directly from the constructor which ensures that they are really not `null`. -We also used this opportunity to convert some of these pure data classes into a `record`. +This update also converted some of these pure data classes into a `record`. See: link:https://issues.apache.org/jira/browse/TINKERPOP-2348[TINKERPOP-2348] @@ -939,9 +957,9 @@ link:https://tinkerpop.apache.org/docs/3.7.0/dev/developer/#gremlin-socket-serve Traversals now support mid-traversal E()-steps. -Prior to this change you were limited to using E()-step only at the start of traversal, but now you can this step in -the middle. This improvement makes it easier for users to build certain types of queries. For example, get edges with -label knows, if there is none then add new one between josh and vadas. +Prior to this change, the E()-step was limited to use at the start of a traversal, but this step can now appear in +the middle. This improvement makes it easier to build certain types of queries. For example, get edges with +label knows; if there is none then add a new one between josh and vadas. `g.inject(1).coalesce(E().hasLabel("knows"), addE("knows").from(V().has("name","josh")).to(V().has("name","vadas")))`
