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/incubator-tinkerpop/master/docs/static/images/gremlin-gangster.png[width=225]

*A 187 On The Undercover Gremlinz*

TinkerPop 3.1.2
---------------

*Release Date: April 8, 2016*

Please see the link:https://github.com/apache/incubator-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:http://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:http://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:http://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:http://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:http://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:http://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:http://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/incubator-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:http://tinkerpop.apache.org/docs/3.1.1-incubating/#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:http://tinkerpop.apache.org/docs/3.1.1-incubating/#_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:http://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/incubator-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:http://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:http://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]