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/TINKERPOP-1562 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 ~~~~~~~~~~~~~~~~~~~~~~~
