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

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static GremlinExecutor.Builder` | `build()` Create a `Builder` with the gremlin-groovy ScriptEngine configured.
    `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, 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()`
    `ScheduledExecutorService` | `getScheduledExecutorService()`
    `GremlinScriptEngineManager` | `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

          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`.
      Throws:
        `ScriptException`

    - #### getScriptEngineManager

          public GremlinScriptEngineManager getScriptEngineManager()

    - #### getExecutorService

          public ExecutorService getExecutorService()

    - #### getScheduledExecutorService

          public ScheduledExecutorService getScheduledExecutorService()

    - #### 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.

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