# Scripting Module

Commands to launch additional script engines.

## Method Overview

Method | Description
--- | ---
createScriptEngine() | Create a new script engine instance.
executeSync() | Run a code fragment in a synchronized block.
fork() | Fork a new script engine and execute provided resource.
getSharedObject() | Get an object from the shared object store.
join() | Wait for a script engine to shut down.
listScriptEngines() | Retrieve a list of available script engines.
notify() | Wakes up a single thread that is waiting on the monitor.
notifyAll() | Wakes up all threads that are waiting on the monitor.
setSharedObject() | Add an object to the shared object store.
wait() | Causes the current thread to wait until either another thread invokes the Object.notify() method or the Object.notifyAll() method for this object, or a specified amount of time has elapsed.

## Methods

### createScriptEngine

IScriptEngine createScriptEngine(String identifier)

Create a new script engine instance.

identifier
  engine ID, literal engine name or accepted file extension

script engine instance (not started) or `null`

### executeSync

Object executeSync(Object monitor, Object code) throws ExecutionException

Run a code fragment in a synchronized block. Executes code within a synchronized block on the monitor object. The code object might be a String, File, IFile or any other object that can be adapted to IScriptable.

monitor
  monitor to synchronize on
code
  code to run.

execution result of executed code

ExecutionException
  when execution of code fails

### fork

ScriptResult fork(Object resource, [String arguments], [String engineIdOrExtension])

Fork a new script engine and execute provided resource.

resource
  resource to execute (path, URI or file instance)
arguments
  optional script arguments delimited by commas ','. When the string arguments contains commas ',', or for arguments that are not string, the caller may set a shared object with setSharedObject() and pass the key here. The callee can then retrieve it with the getSharedObject() method.Optional: defaults to <null>.
engineIdOrExtension
  engine ID to be used or a file extension to look for engines (eg: js)Optional: defaults to <null>.

execution result

### getSharedObject

Object getSharedObject(String key)

Get an object from the shared object store.

key
  key to retrieve object for

shared object or `null`

### join

boolean join(IScriptEngine engine, [long timeout])

Wait for a script engine to shut down. If timeout is set to 0 this method will wait endlessly.

engine
  script engine to wait for
timeout
  time to wait for shutdown [ms]Optional: defaults to <0>.

`true` when engine is shut down

### listScriptEngines

String[] listScriptEngines()

Retrieve a list of available script engines.

array of engine IDs

### notify

void notify(Object monitor)

Wakes up a single thread that is waiting on the monitor. Calls the java method monitor.notify().

monitor
  monitor to notify

### notifyAll

void notifyAll(Object monitor)

Wakes up all threads that are waiting on the monitor. Calls the java method monitor.notifyAll().

monitor
  monitor to notify

### setSharedObject

void setSharedObject(String key, Object object, [boolean permanent], [boolean writable]) throws IllegalAccessException

Add an object to the shared object store. The shared object store allows to share java instances between several script engines. By default objects are stored until the script engine providing it is terminated. This helps to avoid polluting the java heap. When permanent is set to `true` , this object will be stored forever.

key
  key to store the object
object
  instance to store
permanent
  flag indicating permanent storageOptional: defaults to <als>.
writable
  flag indicating that any engine may write this valueOptional: defaults to <als>.

IllegalAccessException
  when scriptEngine is not the owner of the shared object

### wait

void wait(Object monitor, [long timeout]) throws InterruptedException

Causes the current thread to wait until either another thread invokes the Object.notify() method or the Object.notifyAll() method for this object, or a specified amount of time has elapsed. Calls the java method monitor.wait(timeout).

monitor
  monitor to wait for
timeout
  max timeout (0 does not time out)Optional: defaults to <0>.

InterruptedException
  when wait gets interrupted