org.apache.tinkerpop.gremlin.groovy.engine

Class GremlinExecutor

java.lang.Object

org.apache.tinkerpop.gremlin.groovy.engine.GremlinExecutor

All Implemented Interfaces:

AutoCloseable

public class GremlinExecutor
extends Object
implements AutoCloseable

Execute Gremlin scripts against a ScriptEngine instance. It is designed to host any JSR-223 enabled ScriptEngine and assumes such engines are designed to be thread-safe in the evaluation. Script evaluation functions return a CompletableFuture where scripts may timeout if their evaluation takes too long. The default timeout is 8000ms.

By default, the GremlinExecutor initializes itself to use a shared thread pool initialized with four threads. This default thread pool is shared for both the task of executing script evaluations and for scheduling timeouts. It is worth noting that a timeout simply triggers the returned CompletableFuture to abort, but the thread processing the script will continue to evaluate until completion. This offers only marginal protection against run-away scripts.

Author:

Stephen Mallette (http://stephen.genoprime.com)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	GremlinExecutor.Builder
static class	GremlinExecutor.LifeCycle The lifecycle of execution within the eval(String, String, Bindings, LifeCycle) method.

Method Summary

Modifier and Type	Method and Description
static GremlinExecutor.Builder	build() Create a Builder with the gremlin-groovy ScriptEngine configured.
static GremlinExecutor.Builder	build(String engineName, List<String> imports, List<String> staticImports, List<String> scripts, Map<String,Object> config) Deprecated. As of release 3.2.4, replaced by build().
void	close() Executors are only closed if they were not supplied externally in the GremlinExecutor.Builder
CompletableFuture<Void>	closeAsync() Executors are only closed if they were not supplied externally in the GremlinExecutor.Builder
Optional<CompiledScript>	compile(String script) Attempts to compile a script and cache it in the default ScriptEngine.
Optional<CompiledScript>	compile(String script, Optional<String> language) Attempts to compile a script and cache it in the request ScriptEngine.
Traversal.Admin	eval(Bytecode bytecode, Bindings boundVars, String language) Deprecated. As of release 3.2.7, replaced by eval(Bytecode, Bindings, String, String)
Traversal.Admin	eval(Bytecode bytecode, Bindings boundVars, String language, String traversalSource) Evaluates bytecode with bindings for a specific language into a Traversal.
CompletableFuture<Object>	eval(String script) Evaluate a script with empty bindings.
CompletableFuture<Object>	eval(String script, Bindings boundVars) Evaluate a script with specified bindings.
CompletableFuture<Object>	eval(String script, Map<String,Object> boundVars) Evaluate a script with a Map of bindings.
CompletableFuture<Object>	eval(String script, String language, Bindings boundVars) Evaluate a script.
CompletableFuture<Object>	eval(String script, String language, Bindings boundVars, Function<Object,Object> transformResult, Consumer<Object> withResult) Evaluate a script and allow for the submission of both a transform Function and Consumer.
CompletableFuture<Object>	eval(String script, String language, Bindings boundVars, GremlinExecutor.LifeCycle lifeCycle) Evaluate a script and allow for the submission of alteration to the entire evaluation execution lifecycle.
CompletableFuture<Object>	eval(String script, String language, Map<String,Object> boundVars) Evaluate a script.
CompletableFuture<Object>	eval(String script, String language, Map<String,Object> boundVars, Consumer<Object> withResult) Evaluate a script and allow for the submission of a Consumer that will take the result for additional processing after the script evaluates and after the CompletableFuture is completed, but before the transaction is committed.
CompletableFuture<Object>	eval(String script, String language, Map<String,Object> boundVars, Function<Object,Object> transformResult) Evaluate a script and allow for the submission of a transform Function that will transform the result after script evaluates but before transaction commit and before the returned CompletableFuture is completed.
ExecutorService	getExecutorService()
Bindings	getGlobalBindings() Deprecated. As of release 3.2.5, replaced by getScriptEngineManager() to add global scoped bindings directly to that object.
ScheduledExecutorService	getScheduledExecutorService()
GremlinScriptEngineManager	getScriptEngineManager()
ScriptEngines	getScriptEngines() Deprecated. As of release 3.2.4, replaced by getScriptEngineManager().

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

compile

public Optional<CompiledScript> compile(String script)
                                 throws ScriptException

Attempts to compile a script and cache it in the default ScriptEngine. This is only possible if the ScriptEngine implementation implements Compilable. In the event that the default ScriptEngine does not implement it, the method will return empty.

Throws:

ScriptException

compile

public Optional<CompiledScript> compile(String script,
                                        Optional<String> language)
                                 throws ScriptException

Attempts to compile a script and cache it in the request ScriptEngine. This is only possible if the ScriptEngine implementation implements Compilable. In the event that the requested ScriptEngine does not implement it, the method will return empty.

Throws:

ScriptException

eval

public CompletableFuture<Object> eval(String script)

Evaluate a script with empty bindings.

eval

public CompletableFuture<Object> eval(String script,
                                      Bindings boundVars)

Evaluate a script with specified bindings.

eval

public CompletableFuture<Object> eval(String script,
                                      Map<String,Object> boundVars)

Evaluate a script with a Map of bindings.

eval

public CompletableFuture<Object> eval(String script,
                                      String language,
                                      Map<String,Object> boundVars)

Evaluate a script.

Parameters:

script - the script to evaluate

language - the language to evaluate it in

boundVars - the bindings as a Map to evaluate in the context of the script

eval

public CompletableFuture<Object> eval(String script,
                                      String language,
                                      Bindings boundVars)

Evaluate a script.

Parameters:

script - the script to evaluate

language - the language to evaluate it in

boundVars - the bindings to evaluate in the context of the script

eval

public CompletableFuture<Object> eval(String script,
                                      String language,
                                      Map<String,Object> boundVars,
                                      Function<Object,Object> transformResult)

Evaluate a script and allow for the submission of a transform Function that will transform the result after script evaluates but before transaction commit and before the returned CompletableFuture is completed.

Parameters:

script - the script to evaluate

language - the language to evaluate it in

boundVars - the bindings to evaluate in the context of the script

transformResult - a Function that transforms the result - can be null

eval

public CompletableFuture<Object> eval(String script,
                                      String language,
                                      Map<String,Object> boundVars,
                                      Consumer<Object> withResult)

Evaluate a script and allow for the submission of a Consumer that will take the result for additional processing after the script evaluates and after the CompletableFuture is completed, but before the transaction is committed.

Parameters:

script - the script to evaluate

language - the language to evaluate it in

boundVars - the bindings to evaluate in the context of the script

withResult - a Consumer that accepts the result - can be null

eval

public CompletableFuture<Object> eval(String script,
                                      String language,
                                      Bindings boundVars,
                                      Function<Object,Object> transformResult,
                                      Consumer<Object> withResult)

Evaluate a script and allow for the submission of both a transform Function and Consumer. The Function will transform the result after script evaluates but before transaction commit and before the returned CompletableFuture is completed. The Consumer will take the result for additional processing after the script evaluates and after the CompletableFuture is completed, but before the transaction is committed.

Parameters:

script - the script to evaluate

language - the language to evaluate it in

boundVars - the bindings to evaluate in the context of the script

transformResult - a Function that transforms the result - can be null

withResult - a Consumer that accepts the result - can be null

eval

public CompletableFuture<Object> eval(String script,
                                      String language,
                                      Bindings boundVars,
                                      GremlinExecutor.LifeCycle lifeCycle)

Evaluate a script and allow for the submission of alteration to the entire evaluation execution lifecycle.

Parameters:

script - the script to evaluate

language - the language to evaluate it in

boundVars - the bindings to evaluate in the context of the script

lifeCycle - a set of functions that can be applied at various stages of the evaluation process

eval

@Deprecated
public Traversal.Admin eval(Bytecode bytecode,
                                        Bindings boundVars,
                                        String language)
                                 throws ScriptException

Deprecated. As of release 3.2.7, replaced by eval(Bytecode, Bindings, String, String)

Evaluates bytecode with bindings for a specific language into a Traversal.

Throws:

ScriptException

eval

public Traversal.Admin eval(Bytecode bytecode,
                            Bindings boundVars,
                            String language,
                            String traversalSource)
                     throws ScriptException

Evaluates bytecode with bindings for a specific language into a Traversal.

Parameters:

bytecode - to execute as a traversal

boundVars - local bindings

language - the scripting language to use to process the bytecode

traversalSource - the specific traversal source to execute the bytecode against

Throws:

ScriptException

getScriptEngines

@Deprecated
public ScriptEngines getScriptEngines()

Deprecated. As of release 3.2.4, replaced by getScriptEngineManager().

getScriptEngineManager

public GremlinScriptEngineManager getScriptEngineManager()

getExecutorService

public ExecutorService getExecutorService()

getScheduledExecutorService

public ScheduledExecutorService getScheduledExecutorService()

getGlobalBindings

@Deprecated
public Bindings getGlobalBindings()

Deprecated. As of release 3.2.5, replaced by getScriptEngineManager() to add global scoped bindings directly to that object.

close

public void close()
           throws Exception

Executors are only closed if they were not supplied externally in the GremlinExecutor.Builder

Specified by:

close in interface AutoCloseable

Throws:

Exception

closeAsync

public CompletableFuture<Void> closeAsync()
                                   throws Exception

Executors are only closed if they were not supplied externally in the GremlinExecutor.Builder

Throws:

Exception

build

public static GremlinExecutor.Builder build()

Create a Builder with the gremlin-groovy ScriptEngine configured.

build

public static GremlinExecutor.Builder build(String engineName,
                                            List<String> imports,
                                            List<String> staticImports,
                                            List<String> scripts,
                                            Map<String,Object> config)

Deprecated. As of release 3.2.4, replaced by build().

Create a Builder and specify the first ScriptEngine to be included.