<commit_before>////
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
===============

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.0
---------------

*Release Date: NOT OFFICIALLY RELEASED YET*

Please see the link:https://github.com/apache/tinkerpop/blob/3.3.3/CHANGELOG.asciidoc#release-3-3-0[changelog] for a complete list of all the modifications that are part of this release.

Upgrading for Users
~~~~~~~~~~~~~~~~~~~

GraphSON 2.0
^^^^^^^^^^^^

Both TinkerGraph and Gremlin Server have been defaulted to work with GraphSON 2.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 2.0 format rather than 1.0. To use 1.0 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).vertexIdKey("name").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 2.0 with partial types enabled (i.e. which is equivalent
to `application/vnd.gremlin-v2.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.GryoMessageSerializerV1d0, config: { useMapperFromGraph: graph }}             # application/vnd.gremlin-v1.0+gryo
  - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoLiteMessageSerializerV1d0, config: { useMapperFromGraph: graph }}         # application/vnd.gremlin-v1.0+gryo-lite
  - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV1d0, config: { serializeResultToString: true }}         # application/vnd.gremlin-v1.0+gryo-stringd
  - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerGremlinV1d0, config: { ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistry] }} # application/vnd.gremlin-v1.0+json
  - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerGremlinV2d0, config: { useMapperFromGraph: graph  }} # application/vnd.gremlin-v2.0+json
  - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV2d0, config: { useMapperFromGraph: graph }}         # application/json
----

It is possible to bring back the original configuration for `application/json` by changing the last entry as follows:

[source,yaml]
----
serializers:
  - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV1d0, config: { useMapperFromGraph: graph }}             # application/vnd.gremlin-v1.0+gryo
  - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoLiteMessageSerializerV1d0, config: { useMapperFromGraph: graph }}         # application/vnd.gremlin-v1.0+gryo-lite
  - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV1d0, config: { serializeResultToString: true }}         # application/vnd.gremlin-v1.0+gryo-stringd
  - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerGremlinV1d0, config: { ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistry] }} # application/vnd.gremlin-v1.0+json
  - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerGremlinV2d0, config: { useMapperFromGraph: graph  }} # application/vnd.gremlin-v2.0+json
  - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV1d0, config: { useMapperFromGraph: graph }}         # application/json
----

See: link:https://issues.apache.org/jira/browse/TINKERPOP-1414[TINKERPOP-1414]

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
^^^^^^^^^^^^^

*WILL NEED TO WRITE SOMETHING MORE COHESIVE HERE - JUST LISTING STUFF FOR RIGHT NOW*

* Gryo incompatibilities with 3.2.x:
** `RequestMessage`
** `ResponseMessage`

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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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 Script Execution
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

It is no longer possible to run a script in execution mode in the Gremlin Console from the terminal 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 -e gremlin.groovy

See: link:https://issues.apache.org/jira/browse/TINKERPOP-1283[TINKERPOP-1283]

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]

Deprecation Removal
^^^^^^^^^^^^^^^^^^^

The following deprecated classes, methods or fields have been removed in this version:

* `gremlin-console`
** `org.apache.tinkerpop.gremlin.console.Console(String)`
* `gremlin-groovy`
** `org.apache.tinkerpop.gremlin.groovy.engine.ConcurrentBindings`
** `org.apache.tinkerpop.gremlin.groovy.jsr223.GremlinGroovyScriptEngine(ImportCustomizerProvider)`
** `org.apache.tinkerpop.gremlin.groovy.jsr223.GremlinGroovyScriptEngine#plugins()`
** `org.apache.tinkerpop.gremlin.groovy.jsr223.ScriptExecutor`
** `org.apache.tinkerpop.gremlin.groovy.jsr223.customizer.SandboxExtension`

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-1283[TINKERPOP-1283], link:https://issues.apache.org/jira/browse/TINKERPOP-1420[TINKERPOP-1420],
link:https://issues.apache.org/jira/browse/TINKERPOP-833[TINKERPOP-833], link:https://issues.apache.org/jira/browse/TINKERPOP-1040[TINKERPOP-1040]

Upgrading for Providers
~~~~~~~~~~~~~~~~~~~~~~~
<commit_msg>Added a note about spark and HADOOP_GREMLIN_LIBS CTR<commit_after>////
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
===============

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.0
---------------

*Release Date: NOT OFFICIALLY RELEASED YET*

Please see the link:https://github.com/apache/tinkerpop/blob/3.3.3/CHANGELOG.asciidoc#release-3-3-0[changelog] for a complete list of all the modifications that are part of this release.

Upgrading for Users
~~~~~~~~~~~~~~~~~~~

GraphSON 2.0
^^^^^^^^^^^^

Both TinkerGraph and Gremlin Server have been defaulted to work with GraphSON 2.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 2.0 format rather than 1.0. To use 1.0 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).vertexIdKey("name").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 2.0 with partial types enabled (i.e. which is equivalent
to `application/vnd.gremlin-v2.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.GryoMessageSerializerV1d0, config: { useMapperFromGraph: graph }}             # application/vnd.gremlin-v1.0+gryo
  - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoLiteMessageSerializerV1d0, config: { useMapperFromGraph: graph }}         # application/vnd.gremlin-v1.0+gryo-lite
  - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV1d0, config: { serializeResultToString: true }}         # application/vnd.gremlin-v1.0+gryo-stringd
  - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerGremlinV1d0, config: { ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistry] }} # application/vnd.gremlin-v1.0+json
  - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerGremlinV2d0, config: { useMapperFromGraph: graph  }} # application/vnd.gremlin-v2.0+json
  - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV2d0, config: { useMapperFromGraph: graph }}         # application/json
----

It is possible to bring back the original configuration for `application/json` by changing the last entry as follows:

[source,yaml]
----
serializers:
  - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV1d0, config: { useMapperFromGraph: graph }}             # application/vnd.gremlin-v1.0+gryo
  - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoLiteMessageSerializerV1d0, config: { useMapperFromGraph: graph }}         # application/vnd.gremlin-v1.0+gryo-lite
  - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV1d0, config: { serializeResultToString: true }}         # application/vnd.gremlin-v1.0+gryo-stringd
  - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerGremlinV1d0, config: { ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistry] }} # application/vnd.gremlin-v1.0+json
  - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerGremlinV2d0, config: { useMapperFromGraph: graph  }} # application/vnd.gremlin-v2.0+json
  - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV1d0, config: { useMapperFromGraph: graph }}         # application/json
----

See: link:https://issues.apache.org/jira/browse/TINKERPOP-1414[TINKERPOP-1414]

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
^^^^^^^^^^^^^

*WILL NEED TO WRITE SOMETHING MORE COHESIVE HERE - JUST LISTING STUFF FOR RIGHT NOW*

* Gryo incompatibilities with 3.2.x:
** `RequestMessage`
** `ResponseMessage`

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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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 Script Execution
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

It is no longer possible to run a script in execution mode in the Gremlin Console from the terminal 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 -e gremlin.groovy

See: link:https://issues.apache.org/jira/browse/TINKERPOP-1283[TINKERPOP-1283]

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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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
^^^^^^^^^^^^^^^^^^^

The following deprecated classes, methods or fields have been removed in this version:

* `gremlin-console`
** `org.apache.tinkerpop.gremlin.console.Console(String)`
* `gremlin-groovy`
** `org.apache.tinkerpop.gremlin.groovy.engine.ConcurrentBindings`
** `org.apache.tinkerpop.gremlin.groovy.jsr223.GremlinGroovyScriptEngine(ImportCustomizerProvider)`
** `org.apache.tinkerpop.gremlin.groovy.jsr223.GremlinGroovyScriptEngine#plugins()`
** `org.apache.tinkerpop.gremlin.groovy.jsr223.ScriptExecutor`
** `org.apache.tinkerpop.gremlin.groovy.jsr223.customizer.SandboxExtension`

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-1283[TINKERPOP-1283], link:https://issues.apache.org/jira/browse/TINKERPOP-1420[TINKERPOP-1420],
link:https://issues.apache.org/jira/browse/TINKERPOP-833[TINKERPOP-833], link:https://issues.apache.org/jira/browse/TINKERPOP-1040[TINKERPOP-1040]

Upgrading for Providers
~~~~~~~~~~~~~~~~~~~~~~~

{'fraction_non_alphanumeric': 0.1371214875603802, 'fraction_numerical': 0.01911390432659845, 'mean_word_length': 5.173132414235332, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 24, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1996504', 'n_tokens_mistral': 6510, 'n_tokens_neox': 5993, 'n_words': 1609}