ptolemy.actor.lib.jjs

Class RestrictedJavaScriptInterface

java.lang.Object

ptolemy.actor.lib.jjs.RestrictedJavaScriptInterface

public class RestrictedJavaScriptInterface
extends java.lang.Object

Restricted interface to the JavaScript actor. An instance of this class provides limited access to the JavaScript actor specified in the constructor, given access only to methods that an untrusted script can safely execute.

Since:

Ptolemy II 11.0

Version:

$Id$

Author:

Edward A. Lee

Pt.AcceptedRating:

Red (bilung)

Pt.ProposedRating:

Yellow (eal)

Constructor Summary

Constructors

Constructor and Description
RestrictedJavaScriptInterface(JavaScript actor) Construct a restricted interface to the specified JavaScript actor.

Method Summary

Modifier and Type	Method and Description
protected JavaScript	_getActor() Return the actor that this wraps.
void	author(java.lang.String author) Specify author information to appear in the documentation for this actor.
void	clearInterval(java.lang.Integer handle) Clear the interval with the specified handle, if it has not already executed.
void	clearTimeout(java.lang.Integer handle) Clear the timeout with the specified handle, if it has not already executed.
double	currentTime() Return the current time.
void	description(java.lang.String description) Specify a description to appear in the documentation for this actor.
void	description(java.lang.String description, java.lang.String type) Specify a description to appear in the documentation for this actor.
void	error(java.lang.String message) Delegate to the associated JavaScript actor to report an error.
JavaScript.PortOrParameterProxy	getPortOrParameterProxy(java.lang.String name) Get the proxy for a port or parameter with the specified name.
java.lang.Object	getResource(java.lang.String uri, java.lang.Object... arguments) Get a resource, which may be a file name or a URL, and return the value of the resource as a string.
Token	input(java.lang.String name) Create a new input port if it does not already exist.
Token	input(java.lang.String name, java.util.Map options) Create a new input port if it does not already exist.
boolean	isRestricted() Return true.
void	log(java.lang.String message) Delegate to the associated JavaScript actor to log a message.
void	output(java.lang.String name) Create a new output port if it does not already exist.
void	output(java.lang.String name, java.util.Map<java.lang.String,java.lang.Object> options) Create a new output port if it does not already exist.
Token	parameter(java.lang.String name) Create a new parameter if it does not already exist.
Token	parameter(java.lang.String name, java.util.Map options) Create a new parameter if it does not already exist.
java.lang.Object	setInterval(java.lang.Runnable function, java.lang.Double millisecond) Invoke the specified function after the specified interval and periodically after that.
java.lang.Object	setTimeout(java.lang.Runnable function, java.lang.Double millisecond) Invoke the specified function after the specified amount of time.
void	stopEnclosingModel() Stop execution of the enclosing model.
void	version(java.lang.String version) Specify version information to appear in the documentation for this actor.

Methods inherited from class java.lang.Object

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

Constructor Detail

RestrictedJavaScriptInterface

public RestrictedJavaScriptInterface(JavaScript actor)

Construct a restricted interface to the specified JavaScript actor.

Parameters:

actor - The actor.

Method Detail

author

public void author(java.lang.String author)

Specify author information to appear in the documentation for this actor.

Parameters:

author - Author information to appear in documentation.

clearInterval

public void clearInterval(java.lang.Integer handle)

Clear the interval with the specified handle, if it has not already executed.

Parameters:

handle - The interval handle.

clearTimeout

public void clearTimeout(java.lang.Integer handle)

Clear the timeout with the specified handle, if it has not already executed.

Parameters:

handle - The timeout handle.

currentTime

public double currentTime()

Return the current time.

Returns:

The current time in seconds.

description

public void description(java.lang.String description)

Specify a description to appear in the documentation for this actor. The recommended format for documentation is HTML or Markdown.

Parameters:

description - A description to appear in documentation.

description

public void description(java.lang.String description,
                        java.lang.String type)

Specify a description to appear in the documentation for this actor. The recommended format for documentation is HTML or Markdown.

Parameters:

description - A description to appear in documentation.

type - The type, which should be one of "text/html" (the default if null is given), "text/markdown", or "text/plain".

error

public void error(java.lang.String message)
           throws IllegalActionException

Delegate to the associated JavaScript actor to report an error.

Parameters:

message - The message

Throws:

IllegalActionException - If the error cannot be handled.

getPortOrParameterProxy

public JavaScript.PortOrParameterProxy getPortOrParameterProxy(java.lang.String name)

Get the proxy for a port or parameter with the specified name. This is an object on which JavaScript can directly invoke methods.

Parameters:

name - The name of the port or parameter.

Returns:

The proxy for the specified name, or null if there is none.

getResource

public java.lang.Object getResource(java.lang.String uri,
                                    java.lang.Object... arguments)
                             throws IllegalActionException

Get a resource, which may be a file name or a URL, and return the value of the resource as a string. If this instance of JavaScript is restricted (e.g., it is an accessor), then restrict relative file names to be in the same directory where the model is located or in a subdirectory, or if the resource begins with "$CLASSPATH/", to the

Parameters:

uri - A specification for the resource.

arguments - A variable number of arguments, where the first optional argument is an Object that can be a String (the encoding), an integer (the timeout) or a JSON object with encoding and timeout fields, see JavaScript.getResource(String, Object...). The second optional argument is a callback, the first argument to the callback is the error, if any, the second element is the data, if any.

Returns:

The resource

Throws:

IllegalActionException - If the uri specifies any protocol other than "http" or "https", or if the uri contains any "../", or if the uri begins with "/".

input

public Token input(java.lang.String name)
            throws IllegalActionException,
                   NameDuplicationException

Create a new input port if it does not already exist. Leave the type unspecified so that it will be inferred.

Parameters:

name - The name of the port.

Returns:

The previous value of this input, if it has one, and null otherwise.

Throws:

IllegalActionException - If no name is given.

NameDuplicationException - If the name is a reserved word.

input

public Token input(java.lang.String name,
                   java.util.Map options)
            throws IllegalActionException,
                   NameDuplicationException

Create a new input port if it does not already exist. The options argument can specify a "type", a "description", and/or a "value". If a type is given, set the type as specified. Otherwise, leave the type unspecified so that it will be inferred. If a description is given, then create, append to, or modify the DocAttribute named "documentation" contained by this actor to include documentation of this output. If a value is given, then create a PortParameter instead of an ordinary port and set its default value.

Parameters:

name - The name of the port.

options - The options, or null to accept the defaults.

Returns:

The previous value of this input, if it has one, and null otherwise.

Throws:

IllegalActionException - If no name is given.

NameDuplicationException - If the name is a reserved word.

isRestricted

public boolean isRestricted()

Return true. A restricted JavaScript actor limits the capabilities available to the script it executes so that it can execute untrusted code. This class is an interface to a restricted JavaScript actor, so it returns true.

Returns:

True.

log

public void log(java.lang.String message)

Delegate to the associated JavaScript actor to log a message.

Parameters:

message - The message

output

public void output(java.lang.String name)
            throws IllegalActionException,
                   NameDuplicationException

Create a new output port if it does not already exist. Set the type to general.

Parameters:

name - The name of the port.

Throws:

IllegalActionException - If no name is given.

NameDuplicationException - If the name is a reserved word.

output

public void output(java.lang.String name,
                   java.util.Map<java.lang.String,java.lang.Object> options)
            throws IllegalActionException,
                   NameDuplicationException

Create a new output port if it does not already exist. The options argument can specify a "type" and/or a "description". If a type is given, set the type as specified. Otherwise, set the type to general. If a description is given, then create, append to, or modify the DocAttribute named "documentation" contained by this actor to include documentation of this output.

Parameters:

name - The name of the port.

options - The options, or null to accept the defaults.

Throws:

IllegalActionException - If no name is given.

NameDuplicationException - If the name is a reserved word.

parameter

public Token parameter(java.lang.String name)
                throws IllegalActionException,
                       NameDuplicationException

Create a new parameter if it does not already exist. This parameter will have an undeclared type and no description.

Parameters:

name - The name of the parameter.

Returns:

The previous value of this parameter, if it has one, and null otherwise.

Throws:

IllegalActionException - If no name is given, or if the model is executing.

NameDuplicationException - If the name is a reserved word, or if an attribute already exists with the name and is not a parameter.

parameter

public Token parameter(java.lang.String name,
                       java.util.Map options)
                throws IllegalActionException,
                       NameDuplicationException

Create a new parameter if it does not already exist. The options argument can specify a "type", a "description", and/or a "value". If a type is given, set the type as specified. Otherwise, leave the type unspecified so that it will be inferred from the value. If a description is given, then create, append to, or modify the DocAttribute named "documentation" contained by this actor to include documentation of this output. If a value is given, then set the default value of the parameter if it does not already have a value.

Parameters:

name - The name of the parameter.

options - The options, or null to accept the defaults.

Returns:

The previous value of this parameter, if it has one, and null otherwise.

Throws:

IllegalActionException - If no name is given.

NameDuplicationException - If the name is a reserved word, or if an attribute already exists with the name and is not a parameter.

setInterval

public java.lang.Object setInterval(java.lang.Runnable function,
                                    java.lang.Double millisecond)
                             throws IllegalActionException

Invoke the specified function after the specified interval and periodically after that. The time will be added to the current time of the director, and fireAt() request will be made of the director. If the director cannot fulfill the request, this method will throw an exception. Note that if you want real-time behavior, then the director's synchronizeToRealTime parameter needs to be set to true.

Parameters:

function - The function to invoke.

millisecond - The number of milliseconds in the future to invoke it and the period thereafter.

Returns:

A unique ID for this callback

Throws:

IllegalActionException - If the director cannot respect the request.

setTimeout

public java.lang.Object setTimeout(java.lang.Runnable function,
                                   java.lang.Double millisecond)
                            throws IllegalActionException

Invoke the specified function after the specified amount of time. The time will be added to the current time of the director, and fireAt() request will be made of the director. If the director cannot fulfill the request, this method will throw an exception. Note that if you want real-time behavior, then the director's synchronizeToRealTime parameter needs to be set to true.

Parameters:

function - The function to invoke.

millisecond - The number of milliseconds in the future to invoke it.

Returns:

A unique ID for this callback

Throws:

IllegalActionException - If the director cannot respect the request.

stopEnclosingModel

public void stopEnclosingModel()

Stop execution of the enclosing model.

version

public void version(java.lang.String version)

Specify version information to appear in the documentation for this actor.

Parameters:

version - Version information to appear in documentation.

_getActor

protected JavaScript _getActor()

Return the actor that this wraps. This is protected so that instances of HelperBase can retrieve it (for the purposes of synchronization), but not public so that JavaScript cannot gain access to it.

Returns:

the actor that this wraps.