<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.2.0
===============

image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/images/nine-inch-gremlins.png[width=225]

*Nine Inch Gremlins*

TinkerPop 3.2.4
---------------

*Release Date: NOT OFFICIALLY RELEASED YET*

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

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

If/Then-Semantics with Choose Step
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Gremlin's `choose()`-step supports if/then/else-semantics. Thus, to effect if/then-semantics, `identity()` was required.
Thus, the following two traversals below are equivalent with the later being possible in this release.

[source,groovy]
----
g.V().choose(hasLabel('person'),out('created'),identity())
g.V().choose(hasLabel('person'),out('created'))
----

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

FastNoSuchElementException converted to regular NoSuchElementException
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Previously, a call to `Traversal.next()` that did not have a result would throw a `FastNoSuchElementException`.
This has been changed to a regular `NoSuchElementException` that includes the stack trace. Code that explicitly catches
`FastNoSuchElementException` should be converted to check for the more general class of `NoSuchElementException`.

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

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

Graph Database Providers
^^^^^^^^^^^^^^^^^^^^^^^^

HasContainer AndP Splitting
+++++++++++++++++++++++++++<commit_msg>TINKERPOP-1562 Update upgrade docs with ScriptEngine changes.<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.2.0
===============

image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/images/nine-inch-gremlins.png[width=225]

*Nine Inch Gremlins*

TinkerPop 3.2.4
---------------

*Release Date: NOT OFFICIALLY RELEASED YET*

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

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

If/Then-Semantics with Choose Step
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Gremlin's `choose()`-step supports if/then/else-semantics. Thus, to effect if/then-semantics, `identity()` was required.
Thus, the following two traversals below are equivalent with the later being possible in this release.

[source,groovy]
----
g.V().choose(hasLabel('person'),out('created'),identity())
g.V().choose(hasLabel('person'),out('created'))
----

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

FastNoSuchElementException converted to regular NoSuchElementException
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Previously, a call to `Traversal.next()` that did not have a result would throw a `FastNoSuchElementException`.
This has been changed to a regular `NoSuchElementException` that includes the stack trace. Code that explicitly catches
`FastNoSuchElementException` should be converted to check for the more general class of `NoSuchElementException`.

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

ScriptEngine support in gremlin-core
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

`ScriptEngine` and `GremlinPlugin` infrastructure has been moved from gremlin-groovy to gremlin-core to allow for
better re-use across different Gremlin Language Variants. At this point, this change is non-breaking as it was
implemented through deprecation.

The basic concept of a `ScriptEngine` has been replaced by the notion of a `GremlinScriptEngine` (i.e. a
"ScriptEngine" that is specifically tuned for executing Gremlin-related scripts). "ScriptEngine" infrastructure has
been developed to help support this new interface, specifically `GremlinScriptEngineFactory` and
`GremlinScriptEngineManager`. Prefer use of this infrastructure when instantiating a `GremlinScriptEngine` rather
than trying to instantiate directly.

For example, rather than instantiate a `GremlinGroovyScriptEngine` with the constructor:

[source,java]
----
GremlinScriptEngine engine = new GremlinGroovyScriptEngine();
----

prefer to instantiate it as follows:

[source,java]
----
GremlinScriptEngineManager manager = new CachedGremlinScriptEngineManager();
GremlinScriptEngine engine = manager.getEngineByName("gremlin-groovy");
----

Related to the addition of `GremlinScriptEngine`, `org.apache.tinkerpop.gremlin.groovy.plugin.GremlinPlugin` in
gremlin-groovy has been deprecated and then replaced by `org.apache.tinkerpop.gremlin.jsr223.GremlinPlugin`. The new
version of `GremlinPlugin` is similar but does carry some new methods to implement that involves the new `Customizer`
interface. The `Customizer` interface is the way in which `GremlinScriptEngine` instance can be configured with
imports, initialization scripts, compiler options, etc.

Note that a `GremlinPlugin` can be applied to a `GremlinScriptEngine` by adding it to the `GremlinScriptEngineManager`
that creates it.

[source,java]
----
GremlinScriptEngineManager manager = new CachedGremlinScriptEngineManager();
manager.addPlugin(ImportGremlinPlugin.build().classImports(java.awt.Color.class).create());
GremlinScriptEngine engine = manager.getEngineByName("gremlin-groovy");
----

All of this new infrastructure is currently optional on the 3.2.x line of code. More detailed documentation will for
these changes will be supplied as part of 3.3.0 when these features become mandatory and the deprecated code is
removed.

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

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

Graph Database Providers
^^^^^^^^^^^^^^^^^^^^^^^^

HasContainer AndP Splitting
+++++++++++++++++++++++++++
{'fraction_non_alphanumeric': 0.14266648872280796, 'fraction_numerical': 0.012011210463098892, 'mean_word_length': 5.52787456445993, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 9, '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': '2007013', 'n_tokens_mistral': 2207, 'n_tokens_neox': 2040, 'n_words': 746}