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

    All Methods Instance Methods Concrete Methods Deprecated Methods
    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()

Copyright © 2013–2019 Apache Software Foundation. All rights reserved.