[34/47] tinkerpop git commit: TINKERPOP-1562 Update upgrade docs with ScriptEngine changes.

[sp...@apache.org]

TINKERPOP-1562 Update upgrade docs with ScriptEngine changes.


Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo
Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/00ccf0fe
Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/00ccf0fe
Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/00ccf0fe

Branch: refs/heads/master
Commit: 00ccf0fe0b728bd742f9b6f9c1cf6936f4f07b27
Parents: 8368921
Author: Stephen Mallette <sp...@genoprime.com>
Authored: Wed Nov 30 18:42:49 2016 -0500
Committer: Stephen Mallette <sp...@genoprime.com>
Committed: Fri Dec 2 06:31:50 2016 -0500

----------------------------------------------------------------------
 .../upgrade/release-3.2.x-incubating.asciidoc   | 50 ++++++++++++++++++++
 1 file changed, 50 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/00ccf0fe/docs/src/upgrade/release-3.2.x-incubating.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/upgrade/release-3.2.x-incubating.asciidoc b/docs/src/upgrade/release-3.2.x-incubating.asciidoc
index 2b38906..8a184b4 100644
--- a/docs/src/upgrade/release-3.2.x-incubating.asciidoc
+++ b/docs/src/upgrade/release-3.2.x-incubating.asciidoc
@@ -55,6 +55,56 @@ This has been changed to a regular `NoSuchElementException` that includes the st
 
 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
 ~~~~~~~~~~~~~~~~~~~~~~~