org.eclipse.ease

## Interface IScriptEngine

All Known Subinterfaces:
  IDebugEngine, IPythonDebugEngine, IReplEngine

All Known Implementing Classes:
  AbstractReplScriptEngine, AbstractScriptEngine, ArchiveEngine, JVMCompiledScriptEngine, JythonDebuggerEngine, JythonScriptEngine, NashornScriptEngine, Py4jDebuggerEngine, Py4jScriptEngine, RhinoDebuggerEngine, RhinoScriptEngine, TestSuiteScriptEngine

    public interface IScriptEngine

Interface for a script engine. A script engine is capable of interpreting script code at runtime. Script engines shall be derived from `Thread` and therefore run separately from other code. An engine shall be started by calling `schedule()`.

### Field Summary

Fields
`static boolean` `TRACE_SCRIPT_ENGINE` Trace enablement for script engines.

### Method Summary

All Methods Instance Methods Abstract Methods
`void` `addExecutionListener(IExecutionListener listener)`
`void` `addSecurityCheck(ISecurityCheck.ActionType type, ISecurityCheck check)` Add a dedicated security check for a certain script action.
`ScriptResult` `executeAsync(java.lang.Object content)` Execute script code asynchronously.
`ScriptResult` `executeSync(java.lang.Object content)` Execute script code synchronously.
`EngineDescription` `getDescription()` Get engine description for current engine.
`java.io.PrintStream` `getErrorStream()`
`java.lang.Object` `getExecutedFile()` Get the currently executed file instance.
`java.io.InputStream` `getInputStream()`
`ILaunch` `getLaunch()` Get the launch that was used to create this engine.
`IProgressMonitor` `getMonitor()` Get the monitor of the current running engine.
`java.lang.String` `getName()` Get the engine name.
`java.io.PrintStream` `getOutputStream()`
`java.lang.Object` `getVariable(java.lang.String name)` Get a script variable.
`java.util.Map<java.lang.String,java.lang.Object>` `getVariables()` Get all variables from the scope.
`boolean` `hasVariable(java.lang.String name)` Check if a variable exists within the scope of the engine.
`java.lang.Object` `inject(java.lang.Object content)` Inject script code and execute synchronously.
`java.lang.Object` `injectUI(java.lang.Object content)` Inject script code and execute synchronously within the UI thread.
`boolean` `isFinished()` Verify that engine was started and terminated.
`void` `join(long timeout)` Join engine execution thread.
`void` `registerJar(java.net.URL url)` Register a jar file and add it to the classpath.
`void` `removeExecutionListener(IExecutionListener listener)`
`void` `removeSecurityCheck(ISecurityCheck check)` Remove registered security check for all actions.
`void` `schedule()` Schedule script execution.
`void` `setCloseStreamsOnTerminate(boolean closeStreams)` Set marker to automatically close I/O streams when engine is terminated.
`void` `setErrorStream(java.io.OutputStream errorStream)` Set the default error stream for the interpreter.
`void` `setInputStream(java.io.InputStream inputStream)` Set the default input stream for the interpreter.
`void` `setOutputStream(java.io.OutputStream outputStream)` Set the default output stream for the interpreter.
`void` `setVariable(java.lang.String name, java.lang.Object content)` Set a variable in the script engine.
`void` `terminate()` Terminate this interpreter.
`void` `terminateCurrent()` Stops the currently executed piece of code.

### Field Detail

#### TRACE_SCRIPT_ENGINE

    static final boolean TRACE_SCRIPT_ENGINE

Trace enablement for script engines.

### Method Detail

#### executeAsync

    ScriptResult executeAsync(java.lang.Object content)

Execute script code asynchronously. The code provided will be scheduled and executed as soon as all previously scheduled code is executed. If content is a `Reader` object, or a `File` special treatment is done, otherwise the toString() method is used to extract script code.

Parameters:
  `content` - content to be executed.
Returns:
  execution result

#### executeSync

    ScriptResult executeSync(java.lang.Object content)
                      throws java.lang.InterruptedException

Execute script code synchronously. The code provided will be scheduled and executed as soon as all previously scheduled code is executed.If content is a `Reader` object, or a `File` special treatment is done, otherwise the toString() method is used to extract script code. In case the engine was not started yet, it will be automatically started by this call. This is a blocking call.

Parameters:
  `content` - content to be executed.
Returns:
  execution result
Throws:
  `java.lang.InterruptedException` - when execution is interrupted

#### inject

    java.lang.Object inject(java.lang.Object content)

Inject script code and execute synchronously. Code passed to this method will be invoked immediately. It might interrupt a currently running execution requested asynchronously.

Parameters:
  `content` - content to be executed.
Returns:
  execution result

#### injectUI

    java.lang.Object injectUI(java.lang.Object content)

Inject script code and execute synchronously within the UI thread. Code passed to this method will be invoked immediately. It might interrupt a currently running execution requested asynchronously.

Parameters:
  `content` - content to be executed.
Returns:
  execution result

#### getExecutedFile

    java.lang.Object getExecutedFile()

Get the currently executed file instance.

Returns:
  currently executed file

#### setOutputStream

    void setOutputStream(java.io.OutputStream outputStream)

Set the default output stream for the interpreter.

Parameters:
  `outputStream` - default output stream

#### setErrorStream

    void setErrorStream(java.io.OutputStream errorStream)

Set the default error stream for the interpreter.

Parameters:
  `errorStream` - default error stream

#### setInputStream

    void setInputStream(java.io.InputStream inputStream)

Set the default input stream for the interpreter.

Parameters:
  `inputStream` - default input stream

#### getOutputStream

    java.io.PrintStream getOutputStream()

#### getErrorStream

    java.io.PrintStream getErrorStream()

#### getInputStream

    java.io.InputStream getInputStream()

#### setCloseStreamsOnTerminate

    void setCloseStreamsOnTerminate(boolean closeStreams)

Set marker to automatically close I/O streams when engine is terminated.

Parameters:
  `closeStreams` - `true` to close streams

#### schedule

    void schedule()

Schedule script execution. This will start the script engine that either waits for input or immediate starts execution of previously scheduled input.

#### terminate

    void terminate()

Terminate this interpreter. Addresses a request to terminate current script execution. When the request will be handled is implementation specific.

#### terminateCurrent

    void terminateCurrent()

Stops the currently executed piece of code. Will continue to execute the next scheduled piece of code.

#### addExecutionListener

    void addExecutionListener(IExecutionListener listener)

#### removeExecutionListener

    void removeExecutionListener(IExecutionListener listener)

#### getName

    java.lang.String getName()

Get the engine name.

Returns:
  engine name

#### setVariable

    void setVariable(java.lang.String name,
                     java.lang.Object content)

Set a variable in the script engine. This variable will be stored in the global script scope

Parameters:
  `name` - variable name
  `content` - variable content

#### getVariable

    java.lang.Object getVariable(java.lang.String name)

Get a script variable. Retrieve a variable from the global script scope.

Parameters:
  `name` - variable name
Returns:
  variable content or `null`

#### hasVariable

    boolean hasVariable(java.lang.String name)

Check if a variable exists within the scope of the engine. As a variable content may be `null`, `getVariable(String)` might not be sufficient to query.

Parameters:
  `name` - variable name
Returns:
  `true` when variable exists

#### getDescription

    EngineDescription getDescription()

Get engine description for current engine.

Returns:
  engine description

#### getVariables

    java.util.Map<java.lang.String,java.lang.Object> getVariables()

Get all variables from the scope.

Returns:
  map of variables

#### registerJar

    void registerJar(java.net.URL url)

Register a jar file and add it to the classpath. After registering, classes within the jar file shall be usable within the script.

Parameters:
  `url` - url to load jar file from

#### join

    void join(long timeout)
       throws java.lang.InterruptedException

Join engine execution thread. Waits for engine execution up to timeout

Parameters:
  `timeout` - command timeout in milliseconds
Throws:
  `java.lang.InterruptedException` - when join command got interrupted

#### isFinished

    boolean isFinished()

Verify that engine was started and terminated.

Returns:
  `true` when engine ran and terminated

#### addSecurityCheck

    void addSecurityCheck(ISecurityCheck.ActionType type,
                          ISecurityCheck check)

Add a dedicated security check for a certain script action. If the check was already registered for this action, no further check will be added.

Parameters:
  `type` - action type to add check for
  `check` - check to register

#### removeSecurityCheck

    void removeSecurityCheck(ISecurityCheck check)

Remove registered security check for all actions. If the check was not registered at all nothing will happen.

Parameters:
  `check` - check to be removed

#### getLaunch

    ILaunch getLaunch()

Get the launch that was used to create this engine.

Returns:
  launch or `null` in case this engine was created without launch configuration

#### getMonitor

    IProgressMonitor getMonitor()

Get the monitor of the current running engine. The monitor is only valid while the script engine is running.

Returns:
  current monitor or `null`