delight.nashornsandbox.NashornSandbox Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of delight-nashorn-sandbox Show documentation
A safe sandbox to execute JavaScript code from Nashorn.
The newest version!
package delight.nashornsandbox;

import delight.nashornsandbox.exceptions.ScriptCPUAbuseException;

import javax.script.Bindings;
import javax.script.CompiledScript;
import javax.script.Invocable;
import javax.script.ScriptContext;
import javax.script.ScriptException;
import java.io.StringWriter;
import java.io.Writer;
import java.util.concurrent.ExecutorService;

/**
 * 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 milliseconds
   * @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 generous and give
   *   at least 1MB. If bindings are used, Nashorn allocates additional memory 
   *   for the bindings which might be a multiple of the memory theoretically
   *   required by the data types used. For details, see issue 86.
   * 
   * 
   *   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, when want to have output from writer function called in
   * JS script
   * 
   * @param writer the writer, eg. {@link 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 exceeded (when greater
   *      than 0 is set
   * @throws ScriptException when script syntax error occurs
   * @see #setMaxCPUTime(long)
   */
  Object eval(String js) throws ScriptCPUAbuseException, ScriptException;

  /**
   * Evaluates the JavaScript string.
   *
   * @param js the JavaScript script to be evaluated
   * @param bindings the Bindings to use for evaluation
   * @throws ScriptCPUAbuseException when execution time exceeded (when greater
   *      than 0 is set
   * @throws ScriptException when script syntax error occurs
   * @see #setMaxCPUTime(long)
   */
  Object eval(String js, Bindings bindings) throws ScriptCPUAbuseException, ScriptException;

  /**
   * Evaluates the JavaScript string for a given script context
   *
   * @param js the JavaScript script to be evaluated
   * @param scriptContext the ScriptContext exposing sets of attributes in different scopes.
   * @throws ScriptCPUAbuseException when execution time exceeded (when greater
   *      than 0 is set
   * @throws ScriptException when script syntax error occurs
   * @see #setMaxCPUTime(long)
   */
  Object eval(String js, SandboxScriptContext scriptContext) throws ScriptCPUAbuseException, ScriptException;


  /**
   * Evaluates the JavaScript string for a given script context
   * 
   * @param js the JavaScript script to be evaluated
   * @param bindings the Bindings to use for evaluation
   * @param scriptContext the ScriptContext exposing sets of attributes in different scopes. 
   * @throws ScriptCPUAbuseException when execution time exceeded (when greater
   *      than 0 is set
   * @throws ScriptException when script syntax error occurs
   * @see #setMaxCPUTime(long)
   */
  Object eval(String js, SandboxScriptContext scriptContext,Bindings bindings) 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 effect.
   * 
   */
  void allowPrintFunctions(boolean v);
  
  /**
   * Allow Nashorn readLine and readFully functions.
   * 
   *   Only before first {@link #eval(String)} call cause effect.
   * 
   */
  void allowReadFunctions(boolean v);
  
  /**
   * Allow Nashorn load and loadWithNewGlobal functions.
   * 
   *   Only before first {@link #eval(String)} call cause effect.
   * 
   */
  void allowLoadFunctions(boolean v);
  
  /**
   * Allow Nashorn quit and exit functions.
   * 
   *   Only before first {@link #eval(String)} call cause effect.
   * 
   */
  void allowExitFunctions(boolean v);
  
  /**
   * Allow Nashorn globals object $ARG, $ENV, $EXEC, $OPTIONS, $OUT, $ERR and $EXIT.
   * 
   *   Only before first {@link #eval(String)} call cause effect.
   * 
   */
  void allowGlobalsObjects(boolean v);
  
  /**
   * The size of prepared statements LRU cache. Default 0 (disabled).
   * 
   *   Each statements when {@link #setMaxCPUTime(long)} is set is prepared to
   *   quit itself when time exceeded. To execute only once this procedure per
   *   statement set this value.
   * 
   * 
   *   When {@link #setMaxCPUTime(long)} is set 0, this value is ignored.
   * 
   * 
   * @param max the maximum number of statements in the LRU cache
   */
  void setMaxPreparedStatements(int max);
  
  /**
   * Create new bindings used to replace the state of the current script engine
   * 
   * 	This can be typically used to override ECMAScript "global" properties
   * 
   * 
   * @return
   */
  Bindings createBindings();

  /**
   * Returns an {@link Invocable} instance, so that method invocations are also sandboxed.
   * @return
   */
  Invocable getSandboxedInvocable();

  /**
   * Overwrites the cache for pre-processed javascript. Must be called before the first invocation of {@link #eval(String)}
   * and its overloads.
   * @param cache the new cache to use
   */
  void setScriptCache(SecuredJsCache cache);

  /**
   * Compile the JavaScript string
   *
   * @param js the JavaScript script to be compiled
   * @return a CompiledScript object
   * @throws ScriptException
   */
  CompiledScript compile(final String js) throws ScriptException;

  /**
   * Run a pre-compiled JavaScript
   */
  Object eval(CompiledScript compiledScript) throws ScriptCPUAbuseException, ScriptException;
  Object eval(CompiledScript compiledScript, Bindings bindings) throws ScriptCPUAbuseException, ScriptException;
  Object eval(CompiledScript compiledScript, ScriptContext scriptContext) throws ScriptCPUAbuseException, ScriptException;
  Object eval(CompiledScript compiledScript, ScriptContext scriptContext, Bindings bindings) throws ScriptCPUAbuseException, ScriptException;

  /**
 * Create a new secured script context
 */
SandboxScriptContext createScriptContext();

}