Platform Module

Provides global platform functions like preferences, event bus or the command framework.

Method Overview

Method Description
adapt() Adapt object to target type.
createScriptEngine() Create a new script engine instance.
executeCommand() Execute a command from the command framework.
executeSync() Run a code fragment in a synchronized block.
fork() Fork a new script engine and execute provided resource.
getService() Get a platform service.
getSharedObject() Get an object from the shared object store.
getSystemProperty() Get a system property or environment value.
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.
postEvent() Post an event on the event broker.
readPreferences() Read a preferences value.
runProcess() Run an external process.
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.
waitForEvent() Wait for a given event on the event bus.
writePreferences() Set a preferences value.

Methods

adapt

Object adapt(Object source, Class<?> target)

Adapt object to target type. Try to get an adapter for an object.

source
object to adapt
target
target class to adapt to

adapted object or null

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

executeCommand

void executeCommand(String commandId, [Map<String, String> parameters]) throws ExecutionException, NotDefinedException, NotEnabledException, NotHandledException

Execute a command from the command framework. As we have no UI available, we do not pass a control to the command. Hence HandlerUtil.getActive... commands will very likely fail.

commandId
full id of the command to execute
parameters
command parametersOptional: defaults to <null>.
ExecutionException
If the handler has problems executing this command.
NotDefinedException
If the command you are trying to execute is not defined.
NotEnabledException
If the command you are trying to execute is not enabled.
NotHandledException
If there is no handler.

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

getService

Object getService(Class<?> type)

Get a platform service.

type
service type

service instance or null

getSharedObject

Object getSharedObject(String key)

Get an object from the shared object store.

key
key to retrieve object for

shared object or null

getSystemProperty

String getSystemProperty(String key)

Get a system property or environment value. First we try to look up a system property. If not found we query the environment for the key.

key
key to query

system property/environment variable for key

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

postEvent

void postEvent(String topic, [Object data], [long delay])

Post an event on the event broker. If delay is set, the event will be posted after the given amount of time asynchronously. In any case this method returns immediately.

topic
topic to post
data
topic dataOptional: defaults to <null>.
delay
delay to post this even in [ms]Optional: defaults to <0>.

readPreferences

Object readPreferences(String node, String key, [Object defaultValue])

Read a preferences value. The defaultValue is optional, but contains type information if used. Provide instances of Boolean, Integer, Double, Float, Long, byte[], or String to get the appropriate return value of same type.

node
node to read from
key
key name to read from
defaultValue
default value to use, if value is not setOptional: defaults to <>.

preference value or null

runProcess

Process runProcess(String name, [String[] args], [String output], [String error]) throws IOException

Run an external process. The process is started in the background and a Process object is returned. Query the result for finished state, output and error streams of the executed process. Output and error streams need to be consumed, otherwise the running process may stall (or even die) in case that the buffers are full. Setting parameters output and error to null will automatically discard the produced data.

name
program to run (with full path if necessary)
args
program argumentsOptional: defaults to <null>.
output
output file location to redirect output to.
  • "system.out": use the default output of the application
  • null: discard output
  • "keep": do nothing, let the script deal with it
  • any other: file location to redirect to. Accepts absolute file paths and workspace urls (see ResourcesModule)
Optional: defaults to <system.out>.
error
error stream to redirect output to.
  • "system.err": use the default output of the application
  • null: discard output
  • "keep": do nothing, let the script deal with it
  • any other: file location to redirect to. Accepts absolute file paths and workspace urls (see ResourcesModule)
Optional: defaults to <system.err>.

process object to track process execution

IOException
if an I/O error occurs

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 <false>.
writable
flag indicating that any engine may write this valueOptional: defaults to <false>.
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

waitForEvent

org.osgi.service.event.Event waitForEvent(String topic, [long timeout]) throws InterruptedException

Wait for a given event on the event bus.

topic
topic to subscribe for
timeout
maximum time to wait for event in [ms]. Use 0 to wait without timeout.Optional: defaults to <0>.

posted event or null in case of a timeout

InterruptedException
when the script thread gets interrupted

writePreferences

void writePreferences(String node, String key, Object value) throws org.osgi.service.prefs.BackingStoreException

Set a preferences value. Valid types for value are: Boolean, Integer, Double, Float, Long, byte[], and String.

node
node to write to
key
key to store to
value
value to store
org.osgi.service.prefs.BackingStoreException
when preferences cannot be persisted