org.apache.tinkerpop.gremlin.groovy.jsr223

Class GremlinGroovyScriptEngine

java.lang.Object

GroovyScriptEngineImpl

org.apache.tinkerpop.gremlin.groovy.jsr223.GremlinGroovyScriptEngine

All Implemented Interfaces:

AutoCloseable, ScriptEngine, DependencyManager, GremlinScriptEngine

public class GremlinGroovyScriptEngine
extends GroovyScriptEngineImpl
implements DependencyManager, AutoCloseable, GremlinScriptEngine

Provides methods to compile and evaluate Gremlin scripts. Compiled scripts are stored in a managed cache to cut down on compilation times of future evaluations of the same script. This ScriptEngine implementation is heavily adapted from the GroovyScriptEngineImpl to include some additional functionality.

Author:

Marko A. Rodriguez (http://markorodriguez.com), Stephen Mallette (http://stephen.genoprime.com)

See Also:

GremlinExecutor

Field Summary

Fields

Modifier and Type	Field and Description
static String	COLLECTED_BOUND_VARS_MAP_VARNAME Name of variable that holds local variables to be globally bound if "interpreter mode" is enabled with InterpreterModeCustomizerProvider.
static ThreadLocal<Map<String,Object>>	COMPILE_OPTIONS
static String	COMPILE_OPTIONS_VAR_TYPES An "internal" key for sandboxing the script engine - technically not for public use.
static String	KEY_REFERENCE_TYPE The attribute key (passed as a binding on the context) for how to cache scripts.
static String	REFERENCE_TYPE_HARD A value to the KEY_REFERENCE_TYPE that makes the evaluated script available in the cache for the life of the JVM.
static String	REFERENCE_TYPE_PHANTOM A value to the KEY_REFERENCE_TYPE that immediately garbage collects the script after evaluation.
static String	REFERENCE_TYPE_SOFT A value to the KEY_REFERENCE_TYPE that retains the script until memory is "low" and therefore should be reclaimed before an OutOfMemoryError occurs.
static String	REFERENCE_TYPE_WEAK A value to the KEY_REFERENCE_TYPE that marks the script as one that can be garbage collected even when memory is abundant.

Fields inherited from interface org.apache.tinkerpop.gremlin.jsr223.GremlinScriptEngine

HIDDEN_G

Fields inherited from interface javax.script.ScriptEngine

ARGV, ENGINE, ENGINE_VERSION, FILENAME, LANGUAGE, LANGUAGE_VERSION, NAME

Constructor Summary

Constructors

Constructor and Description
GremlinGroovyScriptEngine() Creates a new instance using the DefaultImportCustomizerProvider.
GremlinGroovyScriptEngine(CompilerCustomizerProvider... compilerCustomizerProviders) Deprecated. As of release 3.2.4, replaced by GremlinGroovyScriptEngine(Customizer...).
GremlinGroovyScriptEngine(Customizer... customizers)
GremlinGroovyScriptEngine(ImportCustomizerProvider importCustomizerProvider) Deprecated. As of release 3.0.1, replaced by GremlinGroovyScriptEngine(CompilerCustomizerProvider...)

Method Summary

Modifier and Type	Method and Description
void	addImports(Set<String> importStatements) Perform class imports for the ScriptEngine.
void	close() Deprecated. As of release 3.2.4, not replaced as this class will not implement AutoCloseable in the future.
CompiledScript	compile(Reader reader)
CompiledScript	compile(String scriptSource)
Bindings	createBindings() Create bindings to be used by this ScriptEngine.
Map[]	dependencies() List the dependencies in the ScriptEngine classloader.
Traversal.Admin	eval(Bytecode bytecode, Bindings bindings, String traversalSource) Evaluates Traversal Bytecode with the specified Bindings.
Object	eval(Reader reader, ScriptContext context)
Object	eval(String script, ScriptContext context)
double	getClassCacheAverageLoadPenalty() Gets the average time spent compiling new scripts.
long	getClassCacheEstimatedSize() Gets the estimated size of the class cache for compiled scripts.
long	getClassCacheEvictionCount() Gets the number of times a script compiled to a class has been evicted from the cache.
long	getClassCacheEvictionWeight() Gets the sum of the weights of evicted entries from the class cache.
long	getClassCacheHitCount() Gets the number of times cache look up for a compiled script returned a cached value.
double	getClassCacheHitRate() Gets the hit rate of the class cache.
long	getClassCacheLoadCount() Gets the total number of times the cache lookup method attempted to compile new scripts.
long	getClassCacheLoadFailureCount() Gets the total number of times the cache lookup method failed to compile a new script.
double	getClassCacheLoadFailureRate() Gets the ratio of script compilation attempts that failed.
long	getClassCacheLoadSuccessCount() Gets the total number of times the cache lookup method succeeded to compile a new script.
long	getClassCacheLongRunCompilationCount() Gets the number of compilations that extended beyond the expectedCompilationTime.
long	getClassCacheMissCount() Gets the total number of times the cache lookup method returned a newly compiled script.
double	getClassCacheMissRate() Gets the ratio of script compilation attempts that were misses.
long	getClassCacheRequestCount() Gets the total number of times the cache lookup method returned a cached or uncached value.
long	getClassCacheTotalLoadTime() Gets the total number of nanoseconds that the cache spent compiling scripts.
GremlinScriptEngineFactory	getFactory()
<T> T	getInterface(Class<T> clazz)
<T> T	getInterface(Object thiz, Class<T> clazz)
protected ClassLoader	getParentLoader()
Set	getPlugins() Get the list of loaded plugins.
protected ScriptContext	getScriptContext(Bindings nn) Creates the ScriptContext using a GremlinScriptContext which avoids a significant amount of additional object creation on script evaluation.
Map<String,Set<String>>	imports() List the imports in the ScriptEngine;
Object	invokeFunction(String name, Object... args)
Object	invokeMethod(Object thiz, String name, Object... args)
void	loadPlugins(List<GremlinPlugin> plugins) Load a list of GremlinPlugin instances.
Set	plugins() Deprecated. As of release 3.0.1, replaced by getPlugins()
void	reset() Reset the ScriptEngine.
List<GremlinPlugin>	use(String group, String artifact, String version) Take maven coordinates and load the classes into the classloader used by the ScriptEngine.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.tinkerpop.gremlin.jsr223.GremlinScriptEngine

eval, eval, eval

Methods inherited from interface javax.script.ScriptEngine

eval, eval, eval, eval, get, getBindings, getContext, put, setBindings, setContext

Field Detail

COMPILE_OPTIONS_VAR_TYPES

public static final String COMPILE_OPTIONS_VAR_TYPES

An "internal" key for sandboxing the script engine - technically not for public use.

See Also:

Constant Field Values

KEY_REFERENCE_TYPE

public static final String KEY_REFERENCE_TYPE

The attribute key (passed as a binding on the context) for how to cache scripts. The value must be one of the following:

• REFERENCE_TYPE_HARD
• REFERENCE_TYPE_SOFT
• REFERENCE_TYPE_WEAK
• REFERENCE_TYPE_PHANTOM

See Also:

Constant Field Values

REFERENCE_TYPE_PHANTOM

public static final String REFERENCE_TYPE_PHANTOM

A value to the KEY_REFERENCE_TYPE that immediately garbage collects the script after evaluation.

See Also:

Constant Field Values

REFERENCE_TYPE_WEAK

public static final String REFERENCE_TYPE_WEAK

A value to the KEY_REFERENCE_TYPE that marks the script as one that can be garbage collected even when memory is abundant.

See Also:

Constant Field Values

REFERENCE_TYPE_SOFT

public static final String REFERENCE_TYPE_SOFT

A value to the KEY_REFERENCE_TYPE that retains the script until memory is "low" and therefore should be reclaimed before an OutOfMemoryError occurs.

See Also:

Constant Field Values

REFERENCE_TYPE_HARD

public static final String REFERENCE_TYPE_HARD

A value to the KEY_REFERENCE_TYPE that makes the evaluated script available in the cache for the life of the JVM.

See Also:

Constant Field Values

COLLECTED_BOUND_VARS_MAP_VARNAME

public static final String COLLECTED_BOUND_VARS_MAP_VARNAME

Name of variable that holds local variables to be globally bound if "interpreter mode" is enabled with InterpreterModeCustomizerProvider.

See Also:

Constant Field Values

COMPILE_OPTIONS

public static final ThreadLocal<Map<String,Object>> COMPILE_OPTIONS

Constructor Detail

GremlinGroovyScriptEngine

public GremlinGroovyScriptEngine()

Creates a new instance using the DefaultImportCustomizerProvider.

GremlinGroovyScriptEngine

@Deprecated
public GremlinGroovyScriptEngine(ImportCustomizerProvider importCustomizerProvider)

Deprecated. As of release 3.0.1, replaced by GremlinGroovyScriptEngine(CompilerCustomizerProvider...)

GremlinGroovyScriptEngine

public GremlinGroovyScriptEngine(Customizer... customizers)

GremlinGroovyScriptEngine

@Deprecated
public GremlinGroovyScriptEngine(CompilerCustomizerProvider... compilerCustomizerProviders)

Deprecated. As of release 3.2.4, replaced by GremlinGroovyScriptEngine(Customizer...).

Creates a new instance with the specified CompilerCustomizerProvider objects.

Method Detail

use

public List<GremlinPlugin> use(String group,
                               String artifact,
                               String version)

Take maven coordinates and load the classes into the classloader used by the ScriptEngine. Those ScriptEngines that can support script engine plugins should check if there are any new GremlinPlugin implementations in the classloader. The GremlinGroovyScriptEngine implementation uses ServiceLoader to figure out if there are such classes to return.

It is up to the caller to execute the GremlinPlugin.pluginTo(org.apache.tinkerpop.gremlin.groovy.plugin.PluginAcceptor) method. The reason for this has to do with conflicts that can occur with mapper imports that are added via the ImportCustomizerProvider and scripts executed through the PluginAcceptor. Generally speaking, all calls to this "use" method should be complete prior to calling GremlinPlugin.pluginTo(PluginAcceptor).

This method should be called after "expected" imports have been added to the DependencyManager because adding imports with addImports(java.util.Set) will reset the classloader and flush away dependencies.

Specified by:

use in interface DependencyManager

loadPlugins

public void loadPlugins(List<GremlinPlugin> plugins)
                 throws GremlinPluginException

Load a list of GremlinPlugin instances. These plugins are typically returned from calls to DependencyManager.use(String, String, String).

Specified by:

loadPlugins in interface DependencyManager

Throws:

GremlinPluginException - if there is a problem loading the plugin itself.

dependencies

public Map[] dependencies()

List the dependencies in the ScriptEngine classloader.

Specified by:

dependencies in interface DependencyManager

imports

public Map<String,Set<String>> imports()

List the imports in the ScriptEngine;

Specified by:

imports in interface DependencyManager

addImports

public void addImports(Set<String> importStatements)

Perform class imports for the ScriptEngine.

Specified by:

addImports in interface DependencyManager

plugins

@Deprecated
public Set plugins()

Deprecated. As of release 3.0.1, replaced by getPlugins()

Get the list of loaded plugins.

getPlugins

public Set getPlugins()

Get the list of loaded plugins.

eval

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

Description copied from interface: GremlinScriptEngine

Evaluates Traversal Bytecode with the specified Bindings. These Bindings supplied to this method will be merged with global engine bindings and override them where keys match.

Specified by:

eval in interface GremlinScriptEngine

Throws:

ScriptException

close

@Deprecated
public void close()
                       throws Exception

Deprecated. As of release 3.2.4, not replaced as this class will not implement AutoCloseable in the future.

Specified by:

close in interface AutoCloseable

Throws:

Exception

reset

public void reset()

Reset the ScriptEngine. Clear caches and kill the classloader.

Specified by:

reset in interface DependencyManager

getScriptContext

protected ScriptContext getScriptContext(Bindings nn)

Creates the ScriptContext using a GremlinScriptContext which avoids a significant amount of additional object creation on script evaluation.

eval

public Object eval(Reader reader,
                   ScriptContext context)
            throws ScriptException

Specified by:

eval in interface ScriptEngine

Throws:

ScriptException

eval

public Object eval(String script,
                   ScriptContext context)
            throws ScriptException

Specified by:

eval in interface ScriptEngine

Throws:

ScriptException

createBindings

public Bindings createBindings()

Create bindings to be used by this ScriptEngine. In this case, SimpleBindings are returned.

Specified by:

createBindings in interface ScriptEngine

getFactory

public GremlinScriptEngineFactory getFactory()

Specified by:

getFactory in interface ScriptEngine

Specified by:

getFactory in interface GremlinScriptEngine

compile

public CompiledScript compile(String scriptSource)
                       throws ScriptException

Throws:

ScriptException

compile

public CompiledScript compile(Reader reader)
                       throws ScriptException

Throws:

ScriptException

invokeFunction

public Object invokeFunction(String name,
                             Object... args)
                      throws ScriptException,
                             NoSuchMethodException

Throws:

ScriptException

NoSuchMethodException

invokeMethod

public Object invokeMethod(Object thiz,
                           String name,
                           Object... args)
                    throws ScriptException,
                           NoSuchMethodException

Throws:

ScriptException

NoSuchMethodException

getInterface

public <T> T getInterface(Class<T> clazz)

getInterface

public <T> T getInterface(Object thiz,
                          Class<T> clazz)

getClassCacheLongRunCompilationCount

public long getClassCacheLongRunCompilationCount()

Gets the number of compilations that extended beyond the expectedCompilationTime.

getClassCacheEstimatedSize

public long getClassCacheEstimatedSize()

Gets the estimated size of the class cache for compiled scripts.

getClassCacheAverageLoadPenalty

public double getClassCacheAverageLoadPenalty()

Gets the average time spent compiling new scripts.

getClassCacheEvictionCount

public long getClassCacheEvictionCount()

Gets the number of times a script compiled to a class has been evicted from the cache.

getClassCacheEvictionWeight

public long getClassCacheEvictionWeight()

Gets the sum of the weights of evicted entries from the class cache.

getClassCacheHitCount

public long getClassCacheHitCount()

Gets the number of times cache look up for a compiled script returned a cached value.

getClassCacheHitRate

public double getClassCacheHitRate()

Gets the hit rate of the class cache.

getClassCacheLoadCount

public long getClassCacheLoadCount()

Gets the total number of times the cache lookup method attempted to compile new scripts.

getClassCacheLoadFailureCount

public long getClassCacheLoadFailureCount()

Gets the total number of times the cache lookup method failed to compile a new script.

getClassCacheLoadFailureRate

public double getClassCacheLoadFailureRate()

Gets the ratio of script compilation attempts that failed.

getClassCacheLoadSuccessCount

public long getClassCacheLoadSuccessCount()

Gets the total number of times the cache lookup method succeeded to compile a new script.

getClassCacheMissCount

public long getClassCacheMissCount()

Gets the total number of times the cache lookup method returned a newly compiled script.

getClassCacheMissRate

public double getClassCacheMissRate()

Gets the ratio of script compilation attempts that were misses.

getClassCacheRequestCount

public long getClassCacheRequestCount()

Gets the total number of times the cache lookup method returned a cached or uncached value.

getClassCacheTotalLoadTime

public long getClassCacheTotalLoadTime()

Gets the total number of nanoseconds that the cache spent compiling scripts.

getParentLoader

protected ClassLoader getParentLoader()