delight.nashornsandbox

Interface NashornSandbox

All Known Implementing Classes:

NashornSandboxImpl

public interface NashornSandbox

The Nashorn sandbox interface.

Created on 2015-08-06

Version:

$Id$

Author:

mxro, Youness SAHOUANE, Eduardo Velasques, philipborg, Marcin Golebski

Method Summary

Modifier and Type	Method and Description
void	allow(Class<?> clazz) Add a new class to the list of allowed classes.
void	allowExitFunctions(boolean v) Allow Nashorn quit and exit functions.
void	allowGlobalsObjects(boolean v) Allow Nashorn globals object $ARG, $ENV, $EXEC, $OPTIONS, $OUT, $ERR and $EXIT.
void	allowLoadFunctions(boolean v) Allow Nashorn load and loadWithNewGlobal functions.
void	allowNoBraces(boolean v) Force, to check if all blocks are enclosed with curly braces "{}".
void	allowPrintFunctions(boolean v) Allow Nashorn print and echo functions.
void	allowReadFunctions(boolean v) Allow Nashorn readLine and readFully functions.
Bindings	createBindings() Create new bindings used to replace the state of the current script engine
void	disallow(Class<?> clazz) Remove a class from the list of allowed classes.
void	disallowAllClasses() Remove all classes from the list of allowed classes.
Object	eval(String js) Evaluates the JavaScript string.
Object	eval(String js, Bindings bindings) Evaluates the JavaScript string.
Object	eval(String js, ScriptContext scriptContext) Evaluates the JavaScript string for a given script context
Object	eval(String js, ScriptContext scriptContext, Bindings bindings) Evaluates the JavaScript string for a given script context
Object	get(String variableName) Obtains the value of the specified JavaScript variable.
ExecutorService	getExecutor() Gets the current executor service.
Invocable	getSandboxedInvocable() Returns an Invocable instance, so that method invocations are also sandboxed.
void	inject(String variableName, Object object) Will add a global variable available to all scripts executed with this sandbox.
boolean	isAllowed(Class<?> clazz) Check if a class is in the list of allowed classes.
void	setExecutor(ExecutorService executor) Specifies the executor service which is used to run scripts when a CPU time limit is specified.
void	setMaxCPUTime(long limit) Sets the maximum CPU time in milliseconds allowed for script execution.
void	setMaxMemory(long limit) Sets the maximum memory in Bytes which JS executor thread can allocate.
void	setMaxPreparedStatements(int max) The size of prepared statements LRU cache.
void	setScriptCache(SecuredJsCache cache) Overwrites the cache for pre-processed javascript.
void	setWriter(Writer writer) Sets the writer, when want to have output from writer function called in JS script

Method Detail

allow

void allow(Class<?> clazz)

Add a new class to the list of allowed classes.

disallow

void disallow(Class<?> clazz)

Remove a class from the list of allowed classes.

isAllowed

boolean isAllowed(Class<?> clazz)

Check if a class is in the list of allowed classes.

disallowAllClasses

void disallowAllClasses()

Remove all classes from the list of allowed classes.

inject

void inject(String variableName,
            Object object)

Will add a global variable available to all scripts executed with this sandbox.

Parameters:

variableName - the name of the variable

object - the value, can be null

setMaxCPUTime

void setMaxCPUTime(long limit)

Sets the maximum CPU time in milliseconds allowed for script execution.

Note, ExecutorService should be also set when time is set greater than 0.

Parameters:

limit - time limit in milliseconds

See Also:

setExecutor(ExecutorService)

setMaxMemory

void setMaxMemory(long limit)

Sets the maximum memory in Bytes which JS executor thread can allocate.

Note, thread memory usage is only approximation.

Note, ExecutorService should be also set when memory limit is set greater than 0. Nashorn takes some memory at start, be generous and give at least 1MB.

Current implementation of this limit works only on Sun/Oracle JVM.

Parameters:

limit - limit in bytes

See Also:

ThreadMXBean.getThreadAllocatedBytes(long)

setWriter

void setWriter(Writer writer)

Sets the writer, when want to have output from writer function called in JS script

Parameters:

writer - the writer, eg. StringWriter

setExecutor

void setExecutor(ExecutorService executor)

Specifies the executor service which is used to run scripts when a CPU time limit is specified.

Parameters:

executor - the executor service

See Also:

setMaxCPUTime(long)

getExecutor

ExecutorService getExecutor()

Gets the current executor service.

Returns:

current executor service

eval

Object eval(String js)
     throws ScriptCPUAbuseException,
            ScriptException

Evaluates the JavaScript string.

Parameters:

js - the JavaScript script to be evaluated

Throws:

ScriptCPUAbuseException - when execution time exceeded (when greater than 0 is set

ScriptException - when script syntax error occurs

See Also:

setMaxCPUTime(long)

eval

Object eval(String js,
            Bindings bindings)
     throws ScriptCPUAbuseException,
            ScriptException

Evaluates the JavaScript string.

Parameters:

js - the JavaScript script to be evaluated

bindings - the Bindings to use for evaluation

Throws:

ScriptCPUAbuseException - when execution time exceeded (when greater than 0 is set

ScriptException - when script syntax error occurs

See Also:

setMaxCPUTime(long)

eval

Object eval(String js,
            ScriptContext scriptContext)
     throws ScriptCPUAbuseException,
            ScriptException

Evaluates the JavaScript string for a given script context

Parameters:

js - the JavaScript script to be evaluated

scriptContext - the ScriptContext exposing sets of attributes in different scopes.

Throws:

ScriptCPUAbuseException - when execution time exceeded (when greater than 0 is set

ScriptException - when script syntax error occurs

See Also:

setMaxCPUTime(long)

eval

Object eval(String js,
            ScriptContext scriptContext,
            Bindings bindings)
     throws ScriptCPUAbuseException,
            ScriptException

Evaluates the JavaScript string for a given script context

Parameters:

js - the JavaScript script to be evaluated

bindings - the Bindings to use for evaluation

scriptContext - the ScriptContext exposing sets of attributes in different scopes.

Throws:

ScriptCPUAbuseException - when execution time exceeded (when greater than 0 is set

ScriptException - when script syntax error occurs

See Also:

setMaxCPUTime(long)

get

Object get(String variableName)

Obtains the value of the specified JavaScript variable.

allowPrintFunctions

void allowPrintFunctions(boolean v)

Allow Nashorn print and echo functions.

Only before first eval(String) call cause effect.

allowReadFunctions

void allowReadFunctions(boolean v)

Allow Nashorn readLine and readFully functions.

Only before first eval(String) call cause effect.

allowLoadFunctions

void allowLoadFunctions(boolean v)

Allow Nashorn load and loadWithNewGlobal functions.

Only before first eval(String) call cause effect.

allowExitFunctions

void allowExitFunctions(boolean v)

Allow Nashorn quit and exit functions.

Only before first eval(String) call cause effect.

allowGlobalsObjects

void allowGlobalsObjects(boolean v)

Allow Nashorn globals object $ARG, $ENV, $EXEC, $OPTIONS, $OUT, $ERR and $EXIT.

Only before first eval(String) call cause effect.

allowNoBraces

void allowNoBraces(boolean v)

Force, to check if all blocks are enclosed with curly braces "{}".

Explanation: all loops (for, do-while, while, and if-else, and functions should use braces, because poison_pill() function will be inserted after each open brace "{", to ensure interruption checking. Otherwise simple code like:

     while(true) while(true) {
       // do nothing
     }
   

or even:

     while(true)
   

cause unbreakable loop, which force this sandbox to use Thread.stop() which make JVM unstable.

Properly written code (even in bad intention) like:

     while(true) { while(true) {
       // do nothing
     }}
   

will be changed into:

     while(true) {poison_pill(); 
       while(true) {poison_pill();
         // do nothing
       }
     }
   

which finish nicely when interrupted.

For legacy code, this check can be turned off, but with no guarantee, the JS thread will gracefully finish when interrupted.

Parameters:

v - true when sandbox should check if all required braces are placed into JS code, false when no check should be performed

setMaxPreparedStatements

void setMaxPreparedStatements(int max)

The size of prepared statements LRU cache. Default 0 (disabled).

Each statements when setMaxCPUTime(long) is set is prepared to quit itself when time exceeded. To execute only once this procedure per statement set this value.

When setMaxCPUTime(long) is set 0, this value is ignored.

Parameters:

max - the maximum number of statements in the LRU cache

createBindings

Bindings createBindings()

Create new bindings used to replace the state of the current script engine

This can be typically used to override ECMAScript "global" properties

Returns:

getSandboxedInvocable

Invocable getSandboxedInvocable()

Returns an Invocable instance, so that method invocations are also sandboxed.

Returns:

setScriptCache

void setScriptCache(SecuredJsCache cache)

Overwrites the cache for pre-processed javascript. Must be called before the first invocation of eval(String) and its overloads.

Parameters:

cache - the new cache to use