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

image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/images/gremlin-sleeping-beauty.png[width=225]

*The Sleeping Gremlin: No. 18 Entr'acte Symphonique*

== TinkerPop 3.5.2

*Release Date: NOT OFFICIALLY RELEASED YET*

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

=== Upgrading for Users

==== datetime()

Gremlin in native programming languages can all construct a native date and time object. In Java, that would probably
be a `java.util.Date` object while in Javascript it would likely be the Node.js `Date`. In any of these cases, these
native objects would be serialized to millisecond-precision offset from the unix epoch to be sent over the wire to the
server (in embedded mode for Java, it would be up to the graph database to determine how the date is handled).

The gap is in Gremlin scripts which do not have a way to natively construct dates and times other than by using Groovy
variants. As TinkerPop moves toward a more secure method of processing Gremlin scripts by way of the `gremlin-language`
model, it was clear that this gap needed to be filled. The new `datetime()` function can take a ISO-8601 formatted
datetime and internally produce a `Date` with a default time zone offset of UTC (+00:00).

This functionality, while syntax of `gremlin-language`, is also exposed as a component of `gremlin-groovy` so that it
can be used in the Gremlin Console and through the `GremlinScriptEngine` in Gremlin Server.

[source,text]
----
gremlin> datetime('2022-10-02').toGMTString()
==>2 Oct 2022 00:00:00 GMT
gremlin> datetime('2022-10-02T00:00:00Z').toGMTString()
==>2 Oct 2022 00:00:00 GMT
gremlin> datetime('2022-10-02T00:00:00-0400').toGMTString()
==>2 Oct 2022 04:00:00 GMT
----

The above examples use the Java `Date` method `toGMTString()` to properly format the date for demonstration purposes.
From a Gremlin language perspective there are no functions that can be called on the return value of `datetime()`.

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

==== Refinements to null

Release 3.5.0 introduce the ability for there to be traversers that contained a `null` value. Since that time it has
been noted that supplying a `null` value as an argument to certain Gremlin steps might cause exception behaviors that
were either not clear or perhaps even unexpected. The following changes were made to help make these behaviors more
consistent and to further solidify the semantics of `null` usage in the Gremlin language:

* `hasKey(null)`, `hasLabel(null)` and `has(T.label,null)` - These methods used to throw general `NullPointerException`
failures, but now filter results. As these structural elements of the graph can't be `null`, it will effectively
filter all elements.
* `hasValue(null)` - Formerly this method would throw a general `NullPointerException`, but now it will filter as
expected.
* `withSideEffect()` - This configuration step can now take a `null` for its value.
* `sum()`, `mean()`, `max()` and `min()` - These methods used to throw general `NullPointerException` failures, but
now ignore `null` values when other numbers are present. If all of the values in the stream are `null` then `hasNext()`
return `false`.

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

== TinkerPop 3.5.1

*Release Date: July 19, 2021*

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

=== Upgrading for Users

==== tx() in Javascript

Javascript is now the first non-JVM variant of Gremlin to get support for
link:https://tinkerpop.apache.org/docs/3.5.1/reference/#transactions[remote transactions]. An example of the `tx()`
syntax can be found in the Javascript link:https://tinkerpop.apache.org/docs/3.5.1/reference/#gremlin-javascript-transactions[Transaction Section].

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

==== Gremlint Library

The link:https://gremlint.com[Gremlint website] became an official part of the TinkerPop project for 3.5.0. In 3.5.1,
the javascript library that contains the logic for the site has been made available as a code library that can be used
independently and has been published to link:https://www.npmjs.com/package/gremlint[npm].

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

== TinkerPop 3.5.0

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

=== Upgrading for Users

==== Host Language Runtimes

TinkerPop implements Gremlin in a variety of different programming languages. For 3.5.0, there are a number of major
upgrades to those programming language environments:

* *Java* - TinkerPop now builds and is compatible with Java 11.
* *Python* - Support for Python 2.x has been dropped completely. Users must use Python 3 going forward. For the most
part, from a user’s perspective, there are no specific API changes to consider as a result of this change.
* *Javascript* - Upgraded to support Node version 10.
* *Jython* - Support for Jython has been removed and gremlin-python no longer produces a JVM-based artifact. This change
means that the `GremlinJythonScriptEngine` no longer exists and there is no way to write native Python lambdas that can
execute in Gremlin Server. All lambdas should be written using gremlin-groovy if they are needed.
* *.NET* - Gremlin.NET no longer targets .NET Standard 1.3, but only .NET Standard 2.0. Since .NET Core 2.0 and .NET
Framework 4.6.1 already support this .NET Standard version, most users should not be impacted by this.

See: link:https://issues.apache.org/jira/browse/TINKERPOP-2076[TINKERPOP-2076],
link:https://issues.apache.org/jira/browse/TINKERPOP-2317[TINKERPOP-2317],
link:https://issues.apache.org/jira/browse/TINKERPOP-2335[TINKERPOP-2335]

==== Gremlint

Gremlint, the JavaScript library powering link:https://www.gremlint.com[gremlint.com], is now part of the TinkerPop<commit_msg>TINKERPOP-2616 Added upgrade docs for ssl exception changes 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.5.0

image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/images/gremlin-sleeping-beauty.png[width=225]

*The Sleeping Gremlin: No. 18 Entr'acte Symphonique*

== TinkerPop 3.5.2

*Release Date: NOT OFFICIALLY RELEASED YET*

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

=== Upgrading for Users

==== datetime()

Gremlin in native programming languages can all construct a native date and time object. In Java, that would probably
be a `java.util.Date` object while in Javascript it would likely be the Node.js `Date`. In any of these cases, these
native objects would be serialized to millisecond-precision offset from the unix epoch to be sent over the wire to the
server (in embedded mode for Java, it would be up to the graph database to determine how the date is handled).

The gap is in Gremlin scripts which do not have a way to natively construct dates and times other than by using Groovy
variants. As TinkerPop moves toward a more secure method of processing Gremlin scripts by way of the `gremlin-language`
model, it was clear that this gap needed to be filled. The new `datetime()` function can take a ISO-8601 formatted
datetime and internally produce a `Date` with a default time zone offset of UTC (+00:00).

This functionality, while syntax of `gremlin-language`, is also exposed as a component of `gremlin-groovy` so that it
can be used in the Gremlin Console and through the `GremlinScriptEngine` in Gremlin Server.

[source,text]
----
gremlin> datetime('2022-10-02').toGMTString()
==>2 Oct 2022 00:00:00 GMT
gremlin> datetime('2022-10-02T00:00:00Z').toGMTString()
==>2 Oct 2022 00:00:00 GMT
gremlin> datetime('2022-10-02T00:00:00-0400').toGMTString()
==>2 Oct 2022 04:00:00 GMT
----

The above examples use the Java `Date` method `toGMTString()` to properly format the date for demonstration purposes.
From a Gremlin language perspective there are no functions that can be called on the return value of `datetime()`.

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

==== Refinements to null

Release 3.5.0 introduce the ability for there to be traversers that contained a `null` value. Since that time it has
been noted that supplying a `null` value as an argument to certain Gremlin steps might cause exception behaviors that
were either not clear or perhaps even unexpected. The following changes were made to help make these behaviors more
consistent and to further solidify the semantics of `null` usage in the Gremlin language:

* `hasKey(null)`, `hasLabel(null)` and `has(T.label,null)` - These methods used to throw general `NullPointerException`
failures, but now filter results. As these structural elements of the graph can't be `null`, it will effectively
filter all elements.
* `hasValue(null)` - Formerly this method would throw a general `NullPointerException`, but now it will filter as
expected.
* `withSideEffect()` - This configuration step can now take a `null` for its value.
* `sum()`, `mean()`, `max()` and `min()` - These methods used to throw general `NullPointerException` failures, but
now ignore `null` values when other numbers are present. If all of the values in the stream are `null` then `hasNext()`
return `false`.

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

== TinkerPop 3.5.1

*Release Date: July 19, 2021*

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

=== Upgrading for Users

==== tx() in Javascript

Javascript is now the first non-JVM variant of Gremlin to get support for
link:https://tinkerpop.apache.org/docs/3.5.1/reference/#transactions[remote transactions]. An example of the `tx()`
syntax can be found in the Javascript link:https://tinkerpop.apache.org/docs/3.5.1/reference/#gremlin-javascript-transactions[Transaction Section].

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

==== Gremlint Library

The link:https://gremlint.com[Gremlint website] became an official part of the TinkerPop project for 3.5.0. In 3.5.1,
the javascript library that contains the logic for the site has been made available as a code library that can be used
independently and has been published to link:https://www.npmjs.com/package/gremlint[npm].

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

==== SSL Exceptions

When connecting to an SSL enabled server using Java, errors with that connectivity would result in a `RuntimeException`
that wrapped an underlying `NoHostAvailableException` which did not surface information about the SSL problem. For
this sort of failure in 3.5.2, the `RuntimeException` has been replaced with the `NoHostAvailableException` which in
turn wraps a more specific `SSLException`. While this change represents a small break in exception handling, it seemed
a worthwhile change to take, so as to help make this error more clear when it arises.

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

== TinkerPop 3.5.0

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

=== Upgrading for Users

==== Host Language Runtimes

TinkerPop implements Gremlin in a variety of different programming languages. For 3.5.0, there are a number of major
upgrades to those programming language environments:

* *Java* - TinkerPop now builds and is compatible with Java 11.
* *Python* - Support for Python 2.x has been dropped completely. Users must use Python 3 going forward. For the most
part, from a user’s perspective, there are no specific API changes to consider as a result of this change.
* *Javascript* - Upgraded to support Node version 10.
* *Jython* - Support for Jython has been removed and gremlin-python no longer produces a JVM-based artifact. This change
means that the `GremlinJythonScriptEngine` no longer exists and there is no way to write native Python lambdas that can
execute in Gremlin Server. All lambdas should be written using gremlin-groovy if they are needed.
* *.NET* - Gremlin.NET no longer targets .NET Standard 1.3, but only .NET Standard 2.0. Since .NET Core 2.0 and .NET
Framework 4.6.1 already support this .NET Standard version, most users should not be impacted by this.

See: link:https://issues.apache.org/jira/browse/TINKERPOP-2076[TINKERPOP-2076],
link:https://issues.apache.org/jira/browse/TINKERPOP-2317[TINKERPOP-2317],
link:https://issues.apache.org/jira/browse/TINKERPOP-2335[TINKERPOP-2335]

==== Gremlint

Gremlint, the JavaScript library powering link:https://www.gremlint.com[gremlint.com], is now part of the TinkerPop
{'fraction_non_alphanumeric': 0.08638007231820008, 'fraction_numerical': 0.03046738984866747, 'mean_word_length': 4.685192234488009, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 15, 'https://': 33, 'lorem ipsum': 0, 'www.': 6, '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': '6705380', 'n_tokens_mistral': 4721, 'n_tokens_neox': 4313, 'n_words': 1888}