io.apigee.trireme.core

Class NodeScript

java.lang.Object

io.apigee.trireme.core.NodeScript

public class NodeScript
extends Object

This class represents an instance of a single Node script. It will execute the script in one or more ScriptRunner instances. Scripts are run in a separate thread, so that the caller can decide whether to wait for the script to complete or give up.

Method Summary

Methods

Modifier and Type	Method and Description
org.mozilla.javascript.Scriptable	_getProcessObject() An internal method to retrieve the "process" argument for sending events.
ScriptRunner	_getRuntime() An internal method to get the runtime for this script.
boolean	_isChildProcess()
void	_setChildProcess(boolean child) An internal method to denote that this script was spawned by another Trireme script.
void	_setParentProcess(TriremeProcess parent) An internal method to identify the child process argument of the parent who forked this script.
void	addEnvironment(String name, String value) Add an environment variable to the script without removing anything that already exists.
void	close() Callers should close the script when done to clean up resources.
ScriptFuture	execute() Run the script and return a Future denoting its status.
ScriptFuture	executeModule() Run the script, but treat it as a module rather than as a true script.
Object	getAttachment() Callers can use this method to attach objects to the script.
String	getDisplayName()
Map<String,String>	getEnvironment() Get the current set of environment variables that will be passed to the script.
String	getNodeVersion()
Sandbox	getSandbox()
String	getWorkingDirectory()
boolean	isPinned()
boolean	isPrintEval()
void	setAttachment(Object attachment) Retrieve whatever was set by getAttachment.
void	setDisplayName(String dn) Set a name that is used in diagnostics information from the script.
void	setEnvironment(Map<String,String> env) Replace the current set of environment variables for the script with the specified set.
void	setNodeVersion(String v) Specify which version of the Node.js runtime to select for this script.
void	setPinned(boolean p) Pin the script before running it -- this ensures that the script will never exit unless process.exit is called or the future is explicitly cancelled.
void	setPrintEval(boolean print) If the script was passed as a string when the script was created, print the result at the end.
void	setSandbox(Sandbox box) Set up a restricted environment.
void	setWorkingDirectory(String wd) Specify the working directory for this script.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

execute

public ScriptFuture execute()
                     throws NodeException

Run the script and return a Future denoting its status. The script is treated exactly as any other Node.js program -- that is, it runs in a separate thread, and the returned future may be used to track its status or completion.

When the script has run to completion -- which means that has left no timers or "nextTick" jobs in its queue, and the "http" and "net" modules are no longer listening for incoming network connections, then it will exit with a status code. Cancelling the future will make the script exit more quickly and throw CancellationException. It is also OK to interrupt the script.

Throws:

NodeException

executeModule

public ScriptFuture executeModule()
                           throws NodeException

Run the script, but treat it as a module rather than as a true script. That means that after the script has run to completion, the value of "module.exports" will be returned to the caller via the ScriptFuture, and the script will remain running until it is explicitly cancelled by the ScriptFuture.

This method may be used to invoke a module that may, in turn, be driven externally entirely by Java code. Since the script keeps running until the future is cancelled, it is very important that the caller eventually cancel the script, or the thread will leak.

Throws:

NodeException

close

public void close()

Callers should close the script when done to clean up resources.

setSandbox

public void setSandbox(Sandbox box)

Set up a restricted environment. The specified Sandbox object can specify restrictions on which files are opened, how standard input and output are handled, and what network I/O operations are allowed. The sandbox is checked when the script is executed, so please set all parameters on the Sandbox object before calling "execute". A Sandbox here overrides one set at the Environment level. By default, the sandbox for a script is the one that is set on the Environment that was used to create the script, or null if none was set.

getSandbox

public Sandbox getSandbox()

getAttachment

public Object getAttachment()

Callers can use this method to attach objects to the script. They are accessible to built-in modules and other built-in code.

setAttachment

public void setAttachment(Object attachment)

Retrieve whatever was set by getAttachment.

setPinned

public void setPinned(boolean p)

Pin the script before running it -- this ensures that the script will never exit unless process.exit is called or the future is explicitly cancelled. Used to run the "repl".

isPinned

public boolean isPinned()

setPrintEval

public void setPrintEval(boolean print)

If the script was passed as a string when the script was created, print the result at the end.

isPrintEval

public boolean isPrintEval()

getEnvironment

public Map<String,String> getEnvironment()

Get the current set of environment variables that will be passed to the script. If the environment has not been set then we simply return what is in the current process environment.

setEnvironment

public void setEnvironment(Map<String,String> env)

Replace the current set of environment variables for the script with the specified set.

setWorkingDirectory

public void setWorkingDirectory(String wd)

Specify the working directory for this script. It may be relative to the sandboxes root.

getWorkingDirectory

public String getWorkingDirectory()

setNodeVersion

public void setNodeVersion(String v)

Specify which version of the Node.js runtime to select for this script. Versions are in the format "major.minor.revision", "x" may be used as a wildcard, and trailing digits may be left off. So, "1.2.3", "1.2", "1", "1.2.x", "1.x", and "x" are all valid version strings.

getNodeVersion

public String getNodeVersion()

setDisplayName

public void setDisplayName(String dn)

Set a name that is used in diagnostics information from the script. The main thing that this name will be used for is naming the main script thread. If unset, it is named "Trireme Script Thread." Otherwise, it will be renamed to include this display name.

getDisplayName

public String getDisplayName()

addEnvironment

public void addEnvironment(String name,
                  String value)

Add an environment variable to the script without removing anything that already exists.

_setParentProcess

public void _setParentProcess(TriremeProcess parent)

An internal method to identify the child process argument of the parent who forked this script.

_getProcessObject

public org.mozilla.javascript.Scriptable _getProcessObject()

An internal method to retrieve the "process" argument for sending events.

_setChildProcess

public void _setChildProcess(boolean child)

An internal method to denote that this script was spawned by another Trireme script.

_isChildProcess

public boolean _isChildProcess()

_getRuntime

public ScriptRunner _getRuntime()

An internal method to get the runtime for this script.