delight.nashornsandbox.NashornSandbox Maven / Gradle / Ivy
Show all versions of delight-nashorn-sandbox Show documentation
package delight.nashornsandbox;
import java.io.Writer;
import java.util.concurrent.ExecutorService;
import javax.script.ScriptContext;
import javax.script.ScriptException;
import delight.nashornsandbox.exceptions.ScriptCPUAbuseException;
/**
* The Nashorn sandbox interface.
*
* Created on 2015-08-06
*
* @author mxro
* @author Youness SAHOUANE
* @author Eduardo Velasques
* @author philipborg
* @author Marcin Golebski
* @version $Id$
*/
public interface NashornSandbox {
/**
* Add a new class to the list of allowed classes.
*/
void allow(Class clazz);
/**
* Remove a class from the list of allowed classes.
*/
void disallow(Class clazz);
/**
* Check if a class is in the list of allowed classes.
*/
boolean isAllowed(Class clazz);
/**
* Remove all classes from the list of allowed classes.
*/
void disallowAllClasses();
/**
* Will add a global variable available to all scripts executed with this sandbox.
*
* @param variableName the name of the variable
* @param object the value, can be null
*/
void inject(String variableName, Object object);
/**
* Sets the maximum CPU time in milliseconds allowed for script execution.
*
* Note, {@link ExecutorService} should be also set when time is set greater
* than 0.
*
*
* @param limit time limit in miliseconds
* @see #setExecutor(ExecutorService)
*/
void setMaxCPUTime(long limit);
/**
* Sets the maximum memory in Bytes which JS executor thread can allocate.
*
* Note, thread memory usage is only approximation.
*
*
* Note, {@link ExecutorService} should be also set when memory limit is set
* greater than 0. Nashorn takes some memory at start, be denerous and give
* at least 1MB.
*
*
* Current implementation of this limit works only on Sun/Oracle JVM.
*
*
* @param limit limit in bytes
* @see com.sun.management.ThreadMXBean#getThreadAllocatedBytes(long)
*/
void setMaxMemory(long limit);
/**
* Sets the writer, whem want to have output from writer funcion called in
* JS script
*
* @param writer the writer, eg. {@ling StringWriter}
*/
void setWriter(Writer writer);
/**
* Specifies the executor service which is used to run scripts when a CPU time
* limit is specified.
*
* @param executor the executor service
* @see #setMaxCPUTime(long)
*/
void setExecutor(ExecutorService executor);
/**
* Gets the current executor service.
*
* @return current executor service
*/
ExecutorService getExecutor();
/**
* Evaluates the JavaScript string.
*
* @param js the JavaScript script to be evaluated
* @throws ScriptCPUAbuseException when execution time exided (when greater
* than 0 is set
* @throws ScriptException when script syntax error occures
* @see #setMaxCPUTime(long)
*/
Object eval(String js) throws ScriptCPUAbuseException, ScriptException;
/**
* Evaluates the JavaScript string for a given script context
*
* @param js the JavaScript script to be evaluated
* @param js the JavaScript script to be evaluated
* @param scriptContext the ScriptContext exposing sets of attributes in different scopes.
* @throws ScriptCPUAbuseException when execution time exided (when greater
* than 0 is set
* @throws ScriptException when script syntax error occures
* @see #setMaxCPUTime(long)
*/
Object eval(String js, ScriptContext scriptContext) throws ScriptCPUAbuseException, ScriptException;
/**
* Obtains the value of the specified JavaScript variable.
*/
Object get(String variableName);
/**
* Allow Nashorn print and echo functions.
*
* Only before first {@link #eval(String)} call cause efect.
*
*/
void allowPrintFunctions(boolean v);
/**
* Allow Nashorn readLine and readFully functions.
*
* Only before first {@link #eval(String)} call cause efect.
*
*/
void allowReadFunctions(boolean v);
/**
* Allow Nashorn load and loadWithNewGlobal functions.
*
* Only before first {@link #eval(String)} call cause efect.
*
*/
void allowLoadFunctions(boolean v);
/**
* Allow Nashorn quit and exit functions.
*
* Only before first {@link #eval(String)} call cause efect.
*
*/
void allowExitFunctions(boolean v);
/**
* Allow Nashorn globals object $ARG, $ENV, $EXEC, $OPTIONS, $OUT, $ERR and $EXIT.
*
* Only before first {@link #eval(String)} call cause efect.
*
*/
void allowGlobalsObjects(boolean v);
/**
* Force, to check if all blocks are enclosed with curly braces "{}".
*
* Explantion: all loops (for, do-while, while, and if-else, and functions
* should use braces, becouse poison_pill() function will be insertet afet
* 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 {@link Thread#stop()}
* which make JVM unstable.
*
*
* Properly writen 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 nicelly when interrupted.
*
* For legacy code, this check can be turn off, but with no garantie, the
* JS thread will gracefully finish when interrupted.
*
*
* @param v true when sandbox shoud check if all required braces
* are placed into JS code, false when no check should be
* performed
*/
void allowNoBraces(boolean v);
/**
* The size of prepared statments LRU cache. Default 0 (disabled).
*
* Each statments when {@link #setMaxCPUTime(long)} is set is prepared to
* quit itself when time exided. To execute only once this procedure per
* statment set this value.
*
*
* When {@link #setMaxCPUTime(long)} is set 0, this value is ignored.
*
*
* @param max the maximum number of statments in the LRU cache
*/
void setMaxPerparedStatements(int max);
}