docs/src/upgrade/release-3.1.x-incubating.asciidoc

////
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.1.0

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

*A 187 On The Undercover Gremlinz*

== TinkerPop 3.1.8

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

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

=== Upgrading for Users

==== GraphML XSLT

There were some inconsistencies in the GraphML format supported in TinkerPop 2.x. These issues were corrected on the
initial release of TinkerPop 3.0.0, but as a result, attempting to read GraphML from 2.x will end with an error. A
newly added XSLT file in `gremlin-core`, called `tp2-to-tp3-graphml.xslt`, transforms 2.x GraphML into 3.x GraphML,
making it possible easily read in legacy GraphML through a 3.x `GraphMLReader`.

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

== TinkerPop 3.1.6

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

=== Upgrading for Providers

==== Driver Providers

===== Session Close Confirmation

When a session is closed, it now returns a confirmation in the form of a single `NO CONTENT` message. When the message
arrives, it means that the server has already destroyed the session. Prior to this change, the request was somewhat
one-way, in that the client could send the request and the server would silently honor it. The confirmation makes it
a bit easier to ensure from the client perspective that the close did what it was supposed to do, allowing the client
to proceed only when the server was fully complete with its work.

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

== TinkerPop 3.1.5

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

=== Upgrading for Users

==== Java Driver and close()

There were a few problems noted around the `close()` of `Cluster` and `Client` instances, including issues that
presented as system hangs. These issues have been resolved, however, it is worth noting that an unchecked exception
that was thrown under a certain situation has changed as part of the bug fixes. When submitting an in-session request
on a `Client` that was closed (or closing) an `IllegalStateException` is thrown. This replaces older functionality
that threw a `ConnectionException` and relied logic far deeper in the driver to produce that error and had the
potential to open additional resources despite the intention of the user to "close".

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

== TinkerPop 3.1.4

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

=== Upgrading for Users

==== Gremlin Server Workers

In release 3.1.3, a link:https://tinkerpop.apache.org/docs/3.1.3/upgrade/#_tinkerpop_3_1_3[recommendation] was made to
ensure that the `threadPoolWorker` setting for Gremlin Server was no less than `2` in cases where Gremlin Server was
being used with sessions that accept parallel requests. In 3.1.4, that is no longer the case and a size of `1` remains
acceptable even in that specific case.

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

== TinkerPop 3.1.3

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

=== Upgrading for Users

==== Reserved Gremlin Server Keys

Gremlin Server has always considered certain binding keys (request parameters) as reserved, but that list has now
expanded to be more inclusive all the static enums that are imported to the script engine. It is possible that those
using Gremlin Server may have to rename their keys if they somehow successfully were using some of the now reserved
terms in previous versions.

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

==== Remote Timeout

Disabling the timeout for a `:remote` to Gremlin Server was previously accomplished by setting the timeout to `max` as
in:

[source,text]
:remote config timeout max

where `max` would set the timeout to be `Integer.MAX_VALUE`. While this feature is still supported, it has been
deprecated in favor of the new configuration option of `none`, as in:

[source,text]
:remote config timeout none

The use of `none` completely disables the timeout rather than just setting an arbitrarily high one. Note that it is
still possible to get a timeout on a request if the server timeout limits are reached. The console timeout value only
refers to how long the console will wait for a response from the server before giving up. By default, the timeout is
set to `none`.

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

==== Gremlin Server Workers

Past configuration recommendations for the `threadPoolWorker` setting on Gremlin Server stated this value could be
safely set to `1` at the low end. A size of `1` is still valid for most cases, however, if Gremlin Server is being used
with sessions that accept parallel requests, then this value should be no less than `2` or else certain scripts (i.e.
those that block for an extended period of time) may cause Gremlin Server to lock up the session.

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

=== Upgrading for Providers

IMPORTANT: It is recommended that providers also review all the upgrade instructions specified for users. Many of the
changes there may prove important for the provider's implementation.

==== Graph Database Providers

===== Property Keys and Hyphens

Graph providers should no longer rely on the test suite to validate that hyphens work for labels and property keys.

===== Vertex and Edge Counts

A large number of asserts for vertex and edge counts in the test suite were not being applied. This problem has been
rectified, but could manifest as test errors for different implementations. The chances of the new assertions
identifying previously unrecognized bugs seems slim however, as there are many other tests that validate these counts
in other ways. If those were passing previously, then these new asserts should likely not pose a problem.

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

===== Test Feature Annotations

A large number of `gremlin-test` feature annotations were incorrect which caused test cases to run against graphs that
did not support those features. The annotations have been fixed, but this opened the possibility that more test cases
will run against the graph implementation. Providers should ensure that their graph `features()` are consistent with
the capabilities of the graph implementation.

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

==== Graph Language Providers

===== AndTest Renaming

The `get_g_V_andXhasXage_gt_27X__outE_count_gt_2X_name` test in `AndTest` was improperly named and did not match the
nature of the traversal it was providing. It has been renamed to: `get_g_V_andXhasXage_gt_27X__outE_count_gte_2X_name`.

==== Driver Providers

===== SASL Mechanism

Note that the Gremlin Driver for Java now passes a new parameter for SASL authentication called `saslMechanism`. This
is an optional argument and does not represent a breaking change, but it does make the overall implementation more
complete. While the default authentication implementations packaged with Gremlin Server don't utilize this argument
other implementations might, so the drivers should be able to pass it as per the SASL specification.

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

== TinkerPop 3.1.2

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

=== Upgrading for Users

==== Aliasing Sessions

Calls to `SessionedClient.alias()` used to throw `UnsupportedOperationException` and it was therefore not possible to
use that capability with a session. That method is now properly implemented and aliasing is allowed.

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

==== Remote Console

The `:remote console` command provides a way to avoid having to prefix the `:>` command to scripts when remoting. This
mode of console usage can be convenient when working exclusively with a remote like Gremlin Server and there is only a
desire to view the returned data and not to actually work with it locally in any way.

See: link:https://tinkerpop.apache.org/docs/3.1.2-incubating/reference/#console-remote-console[Reference Documentation - Remote Console]

==== Console Remote Sessions

The `:remote tinkerpop.server` command now allows for a "session" argument to be passed to `connect`. This argument,
tells the remote to configure it with a Gremlin Server session. In this way, the console can act as a window to script
exception on the server and behave more like a standard "local" console when it comes to script execution.

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

==== TinkerPop Archetypes

TinkerPop now offers link:https://maven.apache.org/guides/introduction/introduction-to-archetypes.html[Maven archetypes],
which provide example project templates to quickly get started with TinkerPop. The available archetypes are as follows:

* `gremlin-archetype-server` - An example project that demonstrates the basic structure of a Gremlin Server project,
how to connect with the Gremlin Driver, and how to embed Gremlin Server in a testing framework.
* `gremlin-archetype-tinkergraph` - A basic example of how to structure a TinkerPop project with Maven.

See: link:https://issues.apache.org/jira/browse/TINKERPOP-1085[TINKERPOP-1085],
link:https://tinkerpop.apache.org/docs/3.1.2-incubating/reference/#gremlin-archetypes[Reference Documentation - Archetypes]

==== Session Transaction Management

When connecting to a session with `gremlin-driver`, it is now possible to configure the `Client` instance so as to
request that the server manage the transaction for each requests.

[source,java]
----
Cluster cluster = Cluster.open();
Client client = cluster.connect("sessionName", true);
----

Specifying `true` to the `connect()` method signifies that the `client` should make each request as one encapsulated
in a transaction. With this configuration of `client` there is no need to close a transaction manually.

See: link:https://issues.apache.org/jira/browse/TINKERPOP-1039[TINKERPOP-1039],
link:https://tinkerpop.apache.org/docs/3.1.2-incubating/reference/#sessions[Reference Documentation - Considering Sessions]

==== Session Timeout Setting

The `gremlin-driver` now has a setting called `maxWaitForSessionClose` that allows control of how long it will wait for
an in-session connection to respond to a close request before it simply times-out and moves on.  When that happens,
the server will either eventually close the connection via at session expiration or at the time of shutdown.

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

=== Upgrading for Providers

IMPORTANT: It is recommended that providers also review all the upgrade instructions specified for users. Many of the
changes there may prove important for the provider's implementation.

==== All Providers

===== Provider Documentation

Documentation related to the lower-level APIs used by a provider, that was formerly in the reference documentation,
has been moved to its own documentation set that is now referred to as the
link:https://tinkerpop.apache.org/docs/x.y.z/dev/provider/[Provider Documentation].

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

==== Graph System Providers

===== GraphProvider.clear() Semantics

The semantics of the various `clear()` methods on `GraphProvider` didn't really change, but it would be worth reviewing
their implementations to ensure that implementations can be called successfully in an idempotent fashion. Multiple
calls to `clear()` may occur for a single test on the same `Graph` instance, as `3.1.1-incubating` introduced an
automated method for clearing graphs at the end of a test and some tests call `clear()` manually.

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

==== Driver Providers

===== Session Transaction Management

Up until now transaction management has been a feature of sessionless requests only, but the new `manageTransaction`
request argument for the link:https://tinkerpop.apache.org/docs/3.1.2-incubating/reference/#_session_opprocessor[Session OpProcessor]
changes that.  Session-based requests can now pass this boolean value on each request to signal to
Gremlin Server that it should attempt to commit (or rollback) the transaction at the end of the request. By default,
this value as `false`, so there is no change to the protocol for this feature.

See: link:https://issues.apache.org/jira/browse/TINKERPOP-1039[TINKERPOP-1039],
link:https://tinkerpop.apache.org/docs/3.1.2-incubating/reference/#sessions[Reference Documentation - Considering Sessions]

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

==== Plugin Providers

===== RemoteAcceptor allowRemoteConsole

The `RemoteAcceptor` now has a new method called `allowRemoteConsole()`.  It has a default implementation that
returns `false` and should thus be a non-breaking change for current implementations.  This value should only be set
to `true` if the implementation expects the user to always use `:>` to interact with it.  For example, the
`tinkerpop.server` plugin expects all user interaction through `:>`, where the line is sent to Gremlin Server.  In
that case, that `RemoteAcceptor` implementation can return `true`.  On the other hand, the `tinkerpop.gephi` plugin,
expects that the user sometimes call `:>` and sometimes work with local evaluation as well. It interacts with the
local variable bindings in the console itself. For `tinkerpop.gephi`, this method returns `false`.

See: link:https://tinkerpop.apache.org/docs/3.1.2-incubating/reference/#console-remote-console[Reference Documentation - Remote Console]

== TinkerPop 3.1.1

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

=== Upgrading for Users

==== Storage I/O

The `gremlin-core` io-package now has a `Storage` interface. The methods that were available via `hdfs`
(e.g. `rm()`, `ls()`, `head()`, etc.) are now part of `Storage`. Both HDFS and Spark implement `Storage` via
`FileSystemStorage` and `SparkContextStorage`, respectively.  `SparkContextStorage` adds support for interacting with
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.

* `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.
** For graph locations, use `hdfs.head(location,writableClass,lines)`.
** For memory locations, use `hdfs.head(location,memoryKey,writableClass,lines)`.
* `hdfs.head(...,ObjectWritable)` no longer exists. Use `SequenceFileInputFormat` as an input format is the parsing class.

Given that HDFS (and now Spark) interactions are possible via `Storage` and no longer via Groovy meta-programming,
developers can use these `Storage` implementations in their Java code. In fact, `Storage` has greatly simplified
complex file/RDD operations in both `GiraphGraphComputer` and `SparkGraphComputer`.

Finally, note that the following low-level/internal classes have been removed: `HadoopLoader` and `HDFSTools`.

See: link:https://issues.apache.org/jira/browse/TINKERPOP-1033[TINKERPOP-1033],
link:https://issues.apache.org/jira/browse/TINKERPOP-1023[TINKERPOP-1023]

==== Gremlin Server Transaction Management

Gremlin Server now has a setting called `strictTransactionManagement`, which forces the user to pass
`aliases` for all requests. The aliases are then used to determine which graphs will have their transactions closed
for that request. The alternative is to continue with default operations where the transactions of all configured
graphs will be closed. It is likely that `strictTransactionManagement` (which is `false` by default so as to be
backward compatible with previous versions) will become the future standard mode of operation for Gremlin Server as
it provides a more efficient method for transaction management.

See: link:https://issues.apache.org/jira/browse/TINKERPOP-930[TINKERPOP-930],
link:https://tinkerpop.apache.org/docs/3.1.1-incubating/reference/#considering-transactions[Reference Documentation - Considering Transactions]

==== Deprecated credentialsDbLocation

The `credentialsDbLocation` setting was a TinkerGraph only configuration option to the `SimpleAuthenticator` for
Gremlin Server.  It provided the file system location to a "credentials graph" that TinkerGraph would read from a
Gryo file at that spot.  This setting was only required because TinkerGraph did not support file persistence at the
time that `SimpleAuthenticator` was created.

As of 3.1.0-incubating, TinkerGraph received a limited persistence feature that allowed the "credentials graph"
location to be specified in the TinkerGraph properties file via `gremlin.tinkergraph.graphLocation` and as such the
need for `credentialsDbLocation` was eliminated.

This deprecation is not a breaking change, however users should be encouraged to convert their configurations to use
the `gremlin.tinkergraph.graphLocation` as soon as possible, as the deprecated setting will be removed in a future
release.

See: link:https://issues.apache.org/jira/browse/TINKERPOP-981[TINKERPOP-981],
link:https://tinkerpop.apache.org/docs/3.1.1-incubating/reference/#_security[Reference Documentation - Gremlin Server Security]

==== TinkerGraph Supports Any I/O

TinkerGraph's 'gremlin.tinkergraph.graphLocation' configuration setting can now take a fully qualified class name
of a `Io.Builder` implementation, which means that custom IO implementations can be used to read and write
TinkerGraph instances.

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

==== Authenticator Method Deprecation

For users who have a custom `Authenticator` implementation for Gremlin Server, there will be a new method present:

[source,java]
public default SaslNegotiator newSaslNegotiator(final InetAddress remoteAddress)

Implementation of this method is now preferred over the old method with the same name that has no arguments. The old
method has been deprecated.  This is a non-breaking change as the new method has a default implementation that simply
calls the old deprecated method.  In this way, existing `Authenticator` implementations will still work.

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

==== Spark Persistence Updates

Spark RDD persistence is now much safer with a "job server" system that ensures that persisted RDDs are not garbage
collected by Spark. With this, the user is provider a `spark` object that enables them to manage persisted RDDs
much like the `hdfs` object is used for managing files in HDFS.

Finally, `InputRDD` instance no longer need a `reduceByKey()` postfix as view merges happen prior to writing the
`graphRDD`. Note that a `reduceByKey()` postfix will not cause problems if continued, it is simply inefficient
and no longer required.

See: link:https://issues.apache.org/jira/browse/TINKERPOP-1023[TINKERPOP-1023],
link:https://issues.apache.org/jira/browse/TINKERPOP-1027[TINKERPOP-1027]

==== Logging

Logging to Gremlin Server and Gremlin Console can now be consistently controlled by the `log4j-server.properties`
and `log4j-console.properties` which are in the respective `conf/` directories of the packaged distributions.

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

==== Gremlin Server Sandboxing

A number of improvements were made to the sandboxing feature of Gremlin Server (more specifically the
`GremlinGroovyScriptEngine`).  A new base class for sandboxing was introduce with the `AbstractSandboxExtension`,
which makes it a bit easier to build white list style sandboxes. A usable implementation of this was also supplied
with the `FileSandboxExtension`, which takes a configuration file containing a white list of accessible methods and
variables that can be used in scripts. Note that the original `SandboxExtension` has been deprecated in favor of
the `AbsstractSandboxExtension` or extending directly from Groovy's `TypeCheckingDSL`.

See: link:https://issues.apache.org/jira/browse/TINKERPOP-891[TINKERPOP-891],
link:https://tinkerpop.apache.org/docs/3.1.0-incubating/#script-execution[Reference Documentation - Script Execution]

==== Deprecated supportsAddProperty()

It was realized that `VertexPropertyFeatures.supportsAddProperty()` was effectively a duplicate of
`VertexFeatures.supportsMetaProperties()`.  As a result, `supportsAddProperty()` was deprecated in favor of the other.
If using `supportsAddProperty()`, simply modify that code to instead utilize `supportsMetaProperties()`.

=== Upgrading for Providers

IMPORTANT: It is recommended that providers also review all the upgrade instructions specified for users. Many of the
changes there may prove important for the provider's implementation.

==== Graph System Providers

===== Data Types in Tests

There were a number of fixes related to usage of appropriate types in the test suite. There were cases where tests
were mixing types, such that a single property key might have two different values.  This mixed typing caused problems
for some graphs and wasn't really something TinkerPop was looking to explicitly enforce as a rule of implementing the
interfaces.

While the changes should not have been breaking, providers should be aware that improved consistencies in the tests
may present opportunities for test failures.

See: link:https://issues.apache.org/jira/browse/TINKERPOP-984[TINKERPOP-984],
link:https://issues.apache.org/jira/browse/TINKERPOP-990[TINKERPOP-990],
link:https://issues.apache.org/jira/browse/TINKERPOP-1000[TINKERPOP-1000]

==== Graph Database Providers

===== Custom ClassResolver

For providers who have built custom serializers in Gryo, there is a new feature open that can be considered.  A
`GryoMapper` can now take a custom Kryo `ClassResolver`, which means that custom types can be coerced to other types
during serialization (e.g. a custom identifier could be serialized as a `HashMap`).  The advantage to taking this
approach is that users will not need to have the provider's serializers on the client side.  They will only need to
exist on the server (presuming that the a type is coerced to a type available on the client, of course).  The downside
is that serialization is then no longer a two way street. For example, a custom `ClassResolver` that coerced a
custom identifier to `HashMap` would let the client work with the identifier as a `HashMap`, but the client would then
have to send that identifier back to the server as a `HashMap` where it would be recognized as a `HashMap` (not an
identifier).

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

===== Feature Consistency

There were a number of corrections made around the consistency of `Features` and how they were applied in tests.
Corrections fell into two groups of changes:

. Bugs in the how `Features` were applied to certain tests.
. Refactoring around the realization that `VertexFeatures.supportsMetaProperties()` is really just a duplicate of
features already exposed as `VertexPropertyFeatures.supportsAddProperty()`.
`VertexPropertyFeatures.supportsAddProperty()` has been deprecated.

These changes related to "Feature Consistency" open up a number of previously non-executing tests for graphs that did
not support meta-properties, so providers should be wary of potential test failure on previously non-executing tests.

See: link:https://issues.apache.org/jira/browse/TINKERPOP-985[TINKERPOP-985],
link:https://issues.apache.org/jira/browse/TINKERPOP-997[TINKERPOP-997],
link:https://issues.apache.org/jira/browse/TINKERPOP-998[TINKERPOP-998]

==== Graph Processor Providers

===== InputRDD and OutputRDD Updates

There are two new methods on the Spark-Gremlin RDD interfaces.

* `InputRDD.readMemoryRDD()`: get a `ComputerResult.memory()` from an RDD.
* `OutputRDD.writeMemoryRDD()`: write a `ComputerResult.memory()` to an RDD.

Note that both these methods have default implementations which simply work with empty RDDs. Most providers will never
need to implement these methods as they are specific to file/RDD management for `GraphComputer`. The four classes that
implement these methods are `PersistedOutputRDD`, `PersistedInputRDD`, `InputFormatRDD`, and `OutputFormatRDD`. For the
interested provider, study the implementations therein to see the purpose of these two new methods.

== TinkerPop 3.1.0

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

Additional upgrade information can be found here:

* <<_tinkerpop_3_0_2,TinkerPop 3.0.2>>
* <<_tinkerpop_3_0_1,TinkerPop 3.0.1>>

=== Upgrading for Users

==== Shading Jackson

The Jackson library is now shaded to `gremlin-shaded`, which will allow Jackson to version independently without
breaking compatibility with dependent libraries or with those who depend on TinkerPop.  The downside is that if a
library depends on TinkerPop and uses the Jackson classes, those classes will no longer exist with the standard
Jackson package naming.  They will have to shifted as follows:

* `org.objenesis` becomes `org.apache.tinkerpop.shaded.objenesis`
* `com.esotericsoftware.minlog` becomes `org.apache.tinkerpop.shaded.minlog`
* `com.fasterxml.jackson` becomes `org.apache.tinkerpop.shaded.jackson`

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

==== PartitionStrategy and VertexProperty

`PartitionStrategy` now supports partitioning within `VertexProperty`.  The `Graph` needs to be able to support
meta-properties for this feature to work.

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

==== Gremlin Server and Epoll

Gremlin Server provides a configuration option to turn on support for Netty
link:http://netty.io/wiki/native-transports.html[native transport] on Linux, which has been shown to help improve
performance.

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

==== Rebindings Deprecated

The notion of "rebindings" has been deprecated in favor of the term "aliases".  Alias is a better and more intuitive
term than rebindings which should make it easier for newcomers to understand what they are for.

See: link:https://issues.apache.org/jira/browse/TINKERPOP-913[TINKERPOP-913],
link:https://tinkerpop.apache.org/docs/3.1.0-incubating/#_aliases[Reference Documentation - Aliases]

==== Configurable Driver Channelizer

The Gremlin Driver now allows the `Channerlizer` to be supplied as a configuration, which means that custom
implementations may be supplied.

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

==== GraphSON and Strict Option

The `GraphMLReader` now has a `strict` option on the `Builder` so that if a data type for a value is invalid in some
way, GraphMLReader will simply skip that problem value. In that way, it is a bit more forgiving than before especially
with empty data.

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

==== Transaction.close() Default Behavior

The default behavior of `Transaction.close()` is to rollback the transaction.  This is in contrast to previous versions
where the default behavior was commit.  Using rollback as the default should be thought of as a like a safer approach
to closing where a user must now explicitly call `commit()` to persist their mutations.

See link:https://issues.apache.org/jira/browse/TINKERPOP-805[TINKERPOP-805] for more information.

==== ThreadLocal Transaction Settings

The `Transaction.onReadWrite()` and `Transaction.onClose()` settings now need to be set for each thread (if another
behavior than the default is desired). For gremlin-server users that may be changing these settings via scripts.
If the settings are changed for a sessionless request they will now only apply to that one request. If the settings are
changed for an in-session request they will now only apply to all future requests made in the scope of that session.

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

==== Hadoop-Gremlin

* Hadoop1 is no longer supported. Hadoop2 is now the only supported Hadoop version in TinkerPop.
* Spark and Giraph have been split out of Hadoop-Gremlin into their own respective packages (Spark-Gremlin and Giraph-Gremlin).
* The directory where application jars are stored in HDFS is now `hadoop-gremlin-x.y.z-libs`.
** This versioning is important so that cross-version TinkerPop use does not cause jar conflicts.

See link:https://issues.apache.org/jira/browse/TINKERPOP-616

==== Spark-Gremlin

* Providers that wish to reuse a graphRDD can leverage the new `PersistedInputRDD` and `PersistedOutputRDD`.
** This allows the graphRDD to avoid serialization into HDFS for reuse. Be sure to enabled persisted `SparkContext` (see documentation).

See link:https://issues.apache.org/jira/browse/TINKERPOP-868,
link:https://issues.apache.org/jira/browse/TINKERPOP-925

==== TinkerGraph Serialization

TinkerGraph is serializable over Gryo, which means that it can shipped over the wire from Gremlin Server.  This
feature can be useful when working with remote subgraphs.

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

==== Deprecation in TinkerGraph

The `public static String` configurations have been renamed. The old `public static` variables have been deprecated.
If the deprecated variables were being used, then convert to the replacements as soon as possible.

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

==== Deprecation in Gremlin-Groovy

The closure wrappers classes `GFunction`, `GSupplier`, `GConsumer` have been deprecated. In Groovy, a closure can be
specified using `as Function` and thus, these wrappers are not needed. Also, the `GremlinExecutor.promoteBindings()`
method which was previously deprecated has been removed.

See: link:https://issues.apache.org/jira/browse/TINKERPOP-879[TINKERPOP-879],
link:https://issues.apache.org/jira/browse/TINKERPOP-897[TINKERPOP-897]

==== Gephi Traversal Visualization

The process for visualizing a traversal has been simplified.  There is no longer a need to "name" steps that will
represent visualization points for Gephi.  It is possible to just "configure" a `visualTraversal` in the console:

[source,text]
gremlin> :remote config visualTraversal graph vg

which creates a special `TraversalSource` from `graph` called `vg`.  The traversals created from `vg` can be used
to `:submit` to Gephi.

See: link:https://tinkerpop.apache.org/docs/3.1.0-SNAPSHOT/#gephi-plugin[Reference Documentation - Gephi]

==== Alterations to GraphTraversal

There were a number of changes to `GraphTraversal`.  Many of the changes came by way of deprecation, but some semantics
have changed as well:

* `ConjunctionStrategy` has been renamed to `ConnectiveStrategy` (no other behaviors changed).
* `ConjunctionP` has been renamed to `ConnectiveP` (no other behaviors changed).
* `DedupBijectionStrategy` has been renamed (and made more effective) as `FilterRankingStrategy`.
* The `GraphTraversal` mutation API has change significantly with all previous methods being supported but deprecated.
** The general pattern used now is `addE('knows').from(select('a')).to(select('b')).property('weight',1.0)`.
* The `GraphTraversal` sack API has changed with all previous methods being supported but deprecated.
** The old `sack(mult,'weight')` is now `sack(mult).by('weight')`.
* `GroupStep` has been redesigned such that there is now only a key- and value-traversal. No more reduce-traversal.
** The previous `group()`-methods have been renamed to `groupV3d0()`. To immediately upgrade, rename all your `group()`-calls to `groupV3d0()`.
** To migrate to the new `group()`-methods, what was `group().by('age').by(outE()).by(sum(local))` is now `group().by('age').by(outE().sum())`.
* There was a bug in `fold()`, where if a bulked traverser was provided, the traverser was only represented once.
** This bug fix might cause a breaking change to a user query if the non-bulk behavior was being counted on. If so, used `dedup()` prior to `fold()`.
* Both `GraphTraversal().mapKeys()` and `GraphTraversal.mapValues()` has been deprecated.
** Use `select(keys)` and `select(columns)`. However, note that `select()` will not unroll the keys/values. Thus, `mapKeys()` => `select(keys).unfold()`.
* The data type of `Operator` enums will now always be the highest common data type of the two given numbers, rather than the data type of the first number, as it's been before.

==== Aliasing Remotes in the Console

The `:remote` command in Gremlin Console has a new `alias` configuration option.  This `alias` option allows
specification of a set of key/value alias/binding pairs to apply to the remote.  In this way, it becomes possible
to refer to a variable on the server as something other than what it is referred to for purpose of the submitted
script.  For example once a `:remote` is created, this command:

[source,text]
:remote alias x g

would allow "g" on the server to be referred to as "x".

[source,text]
:> x.E().label().groupCount()

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

=== Upgrading for Providers

IMPORTANT: It is recommended that providers also review all the upgrade instructions specified for users. Many of the
changes there may prove important for the provider's implementation.

All providers should be aware that Jackson is now shaded to `gremlin-shaded` and could represent breaking change if
there was usage of the dependency by way of TinkerPop, a direct dependency to Jackson may be required on the
provider's side.

==== Graph System Providers

===== GraphStep Alterations

* `GraphStep` is no longer in `sideEffect`-package, but now in `map`-package as traversals support mid-traversal `V()`.
* Traversals now support mid-traversal `V()`-steps. Graph system providers should ensure that a mid-traversal `V()` can leverage any suitable index.

See link:https://issues.apache.org/jira/browse/TINKERPOP-762

===== Decomposition of AbstractTransaction

The `AbstractTransaction` class has been abstracted into two different classes supporting two different modes of
operation: `AbstractThreadLocalTransaction` and `AbstractThreadedTransaction`, where the former should be used when
supporting `ThreadLocal` transactions and the latter for threaded transactions.  Of course, providers may still
choose to build their own implementation on `AbstractTransaction` itself or simply implement the `Transaction`
interface.

The `AbstractTransaction` gains the following methods to potentially implement (though default implementations
are supplied in `AbstractThreadLocalTransaction` and `AbstractThreadedTransaction`):

* `doReadWrite` that should execute the read-write consumer.
* `doClose` that should execute the close consumer.

See: link:https://issues.apache.org/jira/browse/TINKERPOP-765[TINKERPOP-765],
link:https://issues.apache.org/jira/browse/TINKERPOP-885[TINKERPOP-885]

===== Transaction.close() Default Behavior

The default behavior for `Transaction.close()` is to rollback the transaction and is enforced by tests, which
previously asserted the opposite (i.e. commit on close).  These tests have been renamed to suite the new semantics:

* `shouldCommitOnCloseByDefault` became `shouldCommitOnCloseWhenConfigured`
* `shouldRollbackOnCloseWhenConfigured` became `shouldRollbackOnCloseByDefault`

If these tests were referenced in an `OptOut`, then their names should be updated.

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

===== Graph Traversal Updates

There were numerous changes to the `GraphTraversal` API. Nearly all changes are backwards compatible with respective
"deprecated" annotations. Please review the respective updates specified in the "Graph System Users" section.

* `GraphStep` is no longer in `sideEffect` package. Now in `map` package.
* Make sure mid-traversal `GraphStep` calls are folding `HasContainers` in for index-lookups.
* Think about copying `TinkerGraphStepStrategyTest` for your implementation so you know folding is happening correctly.

===== Element Removal

`Element.Exceptions.elementAlreadyRemoved` has been deprecated and test enforcement for consistency have been removed.
 Providers are free to deal with deleted elements as they see fit.

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

===== VendorOptimizationStrategy Rename

The `VendorOptimizationStrategy` has been renamed to `ProviderOptimizationStrategy`.  This renaming is consistent
with revised terminology for what were formerly referred to as "vendors".

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`
methods), then the provider's `GraphComputer` implementation should simply return and do nothing.

==== Driver Providers

===== Aliases Parameter

The "rebindings" argument to the "standard" `OpProcessor` has been renamed to "aliases". While "rebindings" is still
supported it is recommended that the upgrade to "aliases" be made as soon as possible as support will be removed in
the future.  Gremlin Server will not accept both parameters at the same time - a request must contain either one
parameter or the other if either is supplied.

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

===== ThreadLocal Transaction Settings

If a driver configures the `Transaction.onReadWrite()` or `Transaction.onClose()` settings, note that these settings no
longer apply to all future requests. If the settings are changed for a sessionless request they will only apply to
that one request. If the settings are changed from an in-session request they will only apply to all future requests
made in the scope of that session.

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