org.eclipse.ease

## Interface IScriptEngine

All Known Subinterfaces:
  IDebugEngine

All Known Implementing Classes:
  AbstractScriptEngine, JavaEngine, RhinoDebuggerEngine, RhinoScriptEngine

    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()`.

### Method Summary

Methods
`void` `addExecutionListener(IExecutionListener listener)`
`ScriptResult` `executeAsync(Object content)` Execute script code asynchronously.
`ScriptResult` `executeSync(Object content)` Execute script code synchronously.
`EngineDescription` `getDescription()` Get engine description for current engine.
`PrintStream` `getErrorStream()`
`Object` `getExecutedFile()` Get the currently executed file instance.
`InputStream` `getInputStream()`
`String` `getName()` Get the engine name.
`PrintStream` `getOutputStream()`
`String` `getSaveVariableName(String name)` Return a save name to be used for a variable.
`boolean` `getTerminateOnIdle()` Get termination condition when engine is idle.
`Object` `getVariable(String name)` Get a script variable.
`Map<String,Object>` `getVariables()` Get all variables from the scope.
`boolean` `hasVariable(String name)` Check if a variable exists within the scope of the engine.
`Object` `inject(Object content)` Inject script code and execute synchronously.
`Object` `injectUI(Object content)` Inject script code and execute synchronously within the UI thread.
`boolean` `isIdle()` Returns the execution state of the engine.
`void` `registerJar(URL url)` Register a jar file and add it to the classpath.
`void` `removeExecutionListener(IExecutionListener listener)`
`Object` `removeVariable(String name)` Remove a variable from the scope.
`void` `reset()` Resets the script engine to a fresh state (removes all variables and code history).
`void` `schedule()` Schedule script execution.
`void` `setCloseStreamsOnTerminate(boolean closeStreams)` Set marker to automatically close I/O streams when engine is terminated.
`void` `setErrorStream(OutputStream errorStream)` Set the default error stream for the interpreter.
`void` `setInputStream(InputStream inputStream)` Set the default input stream for the interpreter.
`void` `setOutputStream(OutputStream outputStream)` Set the default output stream for the interpreter.
`void` `setTerminateOnIdle(boolean terminate)` Set a marker that the interpreter should terminate instead entering IDLE mode.
`void` `setVariable(String name, Object content)` Set a variable in the script engine.
`void` `terminate()` Terminate this interpreter.
`void` `terminateCurrent()` Stops the currently executed piece of code.

### Method Detail

#### executeAsync

    ScriptResult executeAsync(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(Object content)
                             throws 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. The calling thread is stalled until the script code is processed.

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

#### inject

    Object inject(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

    Object injectUI(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

    Object getExecutedFile()

Get the currently executed file instance.

Returns:
  currently executed file

#### setOutputStream

    void setOutputStream(OutputStream outputStream)

Set the default output stream for the interpreter.

Parameters:
  `outputStream` - default output stream

#### setErrorStream

    void setErrorStream(OutputStream errorStream)

Set the default error stream for the interpreter.

Parameters:
  `errorStream` - default error stream

#### setInputStream

    void setInputStream(InputStream inputStream)

Set the default input stream for the interpreter.

Parameters:
  `inputStream` - default input stream

#### getOutputStream

    PrintStream getOutputStream()

#### getErrorStream

    PrintStream getErrorStream()

#### getInputStream

    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

#### setTerminateOnIdle

    void setTerminateOnIdle(boolean terminate)

Set a marker that the interpreter should terminate instead entering IDLE mode. If set, the interpreter will execute all pending requests and terminate afterwards.

Parameters:
  `terminate` - `true` to request termination

#### getTerminateOnIdle

    boolean getTerminateOnIdle()

Get termination condition when engine is idle.

Returns:
  `true` when engine is terminated when idle

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

#### reset

    void reset()

Resets the script engine to a fresh state (removes all variables and code history).

#### isIdle

    boolean isIdle()

Returns the execution state of the engine. If the engine is processing code or is terminated this will return `false`. If the engine is waiting for further scripts to execute this will return `true`.

Returns:
  execution state.

#### getName

    String getName()

Get the engine name.

Returns:
  engine name

#### setVariable

    void setVariable(String name,
                   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

    Object getVariable(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(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

#### getSaveVariableName

    String getSaveVariableName(String name)

Return a save name to be used for a variable. The returned value denotes a valid name to be used for a variable within this engine. The returned name might already be in use.

Parameters:
  `name` - variable name candidate
Returns:
  converted variable name

#### getDescription

    EngineDescription getDescription()

Get engine description for current engine.

Returns:
  engine description

#### removeVariable

    Object removeVariable(String name)

Remove a variable from the scope.

Parameters:
  `name` - variable to be removed.
Returns:

#### getVariables

    Map<String,Object> getVariables()

Get all variables from the scope.

Returns:
  map of variables

#### registerJar

    void registerJar(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