Interface ScriptEngine

All Known Implementing Classes:
AbstractScriptEngine
public interfaceScriptEngine
ScriptEngine is the fundamental interface whose methods must be fully functional in every implementation of this specification.

These methods provide basic scripting functionality. Applications written to this simple interface are expected to work with minimal modifications in every implementation. It includes methods that execute scripts, and ones that set and get values.

The values are key/value pairs of two types. The first type of pairs consists of those whose keys are reserved and defined in this specification or by individual implementations. The values in the pairs with reserved keys have specified meanings.

The other type of pairs consists of those that create Java language Bindings, the values are usually represented in scripts by the corresponding keys or by decorated forms of them.
Since:
1.6

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static finalString
    Reserved key for a named value that passes an array of positional arguments to a script.
    static finalString
    Reserved key for a named value that is the name of theScriptEngine implementation.
    static finalString
    Reserved key for a named value that identifies the version of theScriptEngine implementation.
    static finalString
    Reserved key for a named value that is the name of the file being executed.
    static finalString
    Reserved key for a named value that is the full name of Scripting Language supported by the implementation.
    static finalString
    Reserved key for the named value that identifies the version of the scripting language supported by the implementation.
    static finalString
    Reserved key for a named value that identifies the short name of the scripting language.

  • Method Summary

    Modifier and Type
    Method
    Description
    Returns an uninitializedBindings.
    eval(Reader reader)
    Same aseval(String) except that the source of the script is provided as aReader
    eval(Reader reader,Bindings n)
    Same aseval(String, Bindings) except that the source of the script is provided as aReader.
    eval(Reader reader,ScriptContext context)
    Same aseval(String, ScriptContext) where the source of the script is read from aReader.
    eval(String script)
    Executes the specified script.
    eval(String script,Bindings n)
    Executes the script using theBindings argument as theENGINE_SCOPEBindings of theScriptEngine during the script execution.
    eval(String script,ScriptContext context)
    Causes the immediate execution of the script whose source is the String passed as the first argument.
    get(String key)
    Retrieves a value set in the state of this engine.
    getBindings(int scope)
    Returns a scope of named values.
    Returns the defaultScriptContext of theScriptEngine whose Bindings, Reader and Writers are used for script executions when noScriptContext is specified.
    Returns aScriptEngineFactory for the class to which thisScriptEngine belongs.
    void
    put(String key,Object value)
    Sets a key/value pair in the state of the ScriptEngine that may either create a Java Language Binding to be used in the execution of scripts or be used in some other way, depending on whether the key is reserved.
    void
    setBindings(Bindings bindings, int scope)
    Sets a scope of named values to be used by scripts.
    void
    Sets the defaultScriptContext of theScriptEngine whose Bindings, Reader and Writers are used for script executions when noScriptContext is specified.

  • Field Details

    • ARGV

      static final String ARGV
      Reserved key for a named value that passes an array of positional arguments to a script.
      See Also:

    • FILENAME

      static final String FILENAME
      Reserved key for a named value that is the name of the file being executed.
      See Also:

    • ENGINE

      static final String ENGINE
      Reserved key for a named value that is the name of theScriptEngine implementation.
      See Also:

    • ENGINE_VERSION

      static final String ENGINE_VERSION
      Reserved key for a named value that identifies the version of theScriptEngine implementation.
      See Also:

    • NAME

      static final String NAME
      Reserved key for a named value that identifies the short name of the scripting language. The name is used by theScriptEngineManager to locate aScriptEngine with a given name in thegetEngineByName method.
      See Also:

    • LANGUAGE

      static final String LANGUAGE
      Reserved key for a named value that is the full name of Scripting Language supported by the implementation.
      See Also:

    • LANGUAGE_VERSION

      static final String LANGUAGE_VERSION
      Reserved key for the named value that identifies the version of the scripting language supported by the implementation.
      See Also:

  • Method Details

    • eval

      Object eval(String script,ScriptContext context) throwsScriptException
      Causes the immediate execution of the script whose source is the String passed as the first argument. The script may be reparsed or recompiled before execution. State left in the engine from previous executions, including variable values and compiled procedures may be visible during this execution.
      Parameters:
      script - The script to be executed by the script engine.
      context - AScriptContext exposing sets of attributes in different scopes. The meanings of the scopesScriptContext.GLOBAL_SCOPE, andScriptContext.ENGINE_SCOPE are defined in the specification.

      TheENGINE_SCOPEBindings of theScriptContext contains the bindings of scripting variables to application objects to be used during this script execution.
      Returns:
      The value returned from the execution of the script.
      Throws:
      ScriptException - if an error occurs in script. ScriptEngines should create and throwScriptException wrappers for checked Exceptions thrown by underlying scripting implementations.
      NullPointerException - if either argument is null.

    • eval

      Object eval(Reader reader,ScriptContext context) throwsScriptException
      Same aseval(String, ScriptContext) where the source of the script is read from aReader.
      Parameters:
      reader - The source of the script to be executed by the script engine.
      context - TheScriptContext passed to the script engine.
      Returns:
      The value returned from the execution of the script.
      Throws:
      ScriptException - if an error occurs in script. ScriptEngines should create and throwScriptException wrappers for checked Exceptions thrown by underlying scripting implementations.
      NullPointerException - if either argument is null.

    • eval

      Object eval(String script) throwsScriptException
      Executes the specified script. The defaultScriptContext for theScriptEngine is used.
      Parameters:
      script - The script language source to be executed.
      Returns:
      The value returned from the execution of the script.
      Throws:
      ScriptException - if an error occurs in script. ScriptEngines should create and throwScriptException wrappers for checked Exceptions thrown by underlying scripting implementations.
      NullPointerException - if the argument is null.

    • eval

      Object eval(Reader reader) throwsScriptException
      Same aseval(String) except that the source of the script is provided as aReader
      Parameters:
      reader - The source of the script.
      Returns:
      The value returned by the script.
      Throws:
      ScriptException - if an error occurs in script. ScriptEngines should create and throwScriptException wrappers for checked Exceptions thrown by underlying scripting implementations.
      NullPointerException - if the argument is null.

    • eval

      Object eval(String script,Bindings n) throwsScriptException
      Executes the script using theBindings argument as theENGINE_SCOPEBindings of theScriptEngine during the script execution. TheReader,Writer and non-ENGINE_SCOPEBindings of the defaultScriptContext are used. TheENGINE_SCOPEBindings of theScriptEngine is not changed, and its mappings are unaltered by the script execution.
      Parameters:
      script - The source for the script.
      n - TheBindings of attributes to be used for script execution.
      Returns:
      The value returned by the script.
      Throws:
      ScriptException - if an error occurs in script. ScriptEngines should create and throwScriptException wrappers for checked Exceptions thrown by underlying scripting implementations.
      NullPointerException - if either argument is null.

    • eval

      Object eval(Reader reader,Bindings n) throwsScriptException
      Same aseval(String, Bindings) except that the source of the script is provided as aReader.
      Parameters:
      reader - The source of the script.
      n - TheBindings of attributes.
      Returns:
      The value returned by the script.
      Throws:
      ScriptException - if an error occurs in script. ScriptEngines should create and throwScriptException wrappers for checked Exceptions thrown by underlying scripting implementations.
      NullPointerException - if either argument is null.

    • put

      void put(String key,Object value)
      Sets a key/value pair in the state of the ScriptEngine that may either create a Java Language Binding to be used in the execution of scripts or be used in some other way, depending on whether the key is reserved. Must have the same effect asgetBindings(ScriptContext.ENGINE_SCOPE).put.
      Parameters:
      key - The name of named value to add
      value - The value of named value to add.
      Throws:
      NullPointerException - if key is null.
      IllegalArgumentException - if key is empty.

    • get

      Object get(String key)
      Retrieves a value set in the state of this engine. The value might be one which was set usingsetValue or some other value in the state of theScriptEngine, depending on the implementation. Must have the same effect asgetBindings(ScriptContext.ENGINE_SCOPE).get
      Parameters:
      key - The key whose value is to be returned
      Returns:
      the value for the given key
      Throws:
      NullPointerException - if key is null.
      IllegalArgumentException - if key is empty.

    • getBindings

      Bindings getBindings(int scope)
      Returns a scope of named values. The possible scopes are:

      • ScriptContext.GLOBAL_SCOPE - The set of named values representing global scope. If thisScriptEngine is created by aScriptEngineManager, then the manager sets global scope bindings. This may benull if no global scope is associated with thisScriptEngine
      • ScriptContext.ENGINE_SCOPE - The set of named values representing the state of thisScriptEngine. The values are generally visible in scripts using the associated keys as variable names.
      • Any other value of scope defined in the defaultScriptContext of theScriptEngine.


      TheBindings instances that are returned must be identical to those returned by thegetBindings method ofScriptContext called with corresponding arguments on the defaultScriptContext of theScriptEngine.
      Parameters:
      scope - EitherScriptContext.ENGINE_SCOPE orScriptContext.GLOBAL_SCOPE which specifies theBindings to return. Implementations ofScriptContext may define additional scopes. If the defaultScriptContext of theScriptEngine defines additional scopes, any of them can be passed to get the correspondingBindings.
      Returns:
      TheBindings with the specified scope.
      Throws:
      IllegalArgumentException - if specified scope is invalid

    • setBindings

      void setBindings(Bindings bindings, int scope)
      Sets a scope of named values to be used by scripts. The possible scopes are:

      • ScriptContext.ENGINE_SCOPE - The specifiedBindings replaces the engine scope of theScriptEngine.
      • ScriptContext.GLOBAL_SCOPE - The specifiedBindings must be visible as theGLOBAL_SCOPE.
      • Any other value of scope defined in the defaultScriptContext of theScriptEngine.


      The method must have the same effect as calling thesetBindings method ofScriptContext with the corresponding value ofscope on the defaultScriptContext of theScriptEngine.
      Parameters:
      bindings - TheBindings for the specified scope.
      scope - The specified scope. EitherScriptContext.ENGINE_SCOPE,ScriptContext.GLOBAL_SCOPE, or any other valid value of scope.
      Throws:
      IllegalArgumentException - if the scope is invalid
      NullPointerException - if the bindings is null and the scope isScriptContext.ENGINE_SCOPE

    • createBindings

      Bindings createBindings()
      Returns an uninitializedBindings.
      Returns:
      ABindings that can be used to replace the state of thisScriptEngine.

    • getContext

      ScriptContext getContext()
      Returns the defaultScriptContext of theScriptEngine whose Bindings, Reader and Writers are used for script executions when noScriptContext is specified.
      Returns:
      The defaultScriptContext of theScriptEngine.

    • setContext

      void setContext(ScriptContext context)
      Sets the defaultScriptContext of theScriptEngine whose Bindings, Reader and Writers are used for script executions when noScriptContext is specified.
      Parameters:
      context - AScriptContext that will replace the defaultScriptContext in theScriptEngine.
      Throws:
      NullPointerException - if context is null.

    • getFactory

      ScriptEngineFactory getFactory()
      Returns aScriptEngineFactory for the class to which thisScriptEngine belongs.
      Returns:
      TheScriptEngineFactory