-
- All Known Implementing Classes:
AbstractScriptEngine
public interface ScriptEngine
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 String
ARGV
Reserved key for a named value that passes an array of positional arguments to a script.static String
ENGINE
Reserved key for a named value that is the name of theScriptEngine
implementation.static String
ENGINE_VERSION
Reserved key for a named value that identifies the version of theScriptEngine
implementation.static String
FILENAME
Reserved key for a named value that is the name of the file being executed.static String
LANGUAGE
Reserved key for a named value that is the full name of Scripting Language supported by the implementation.static String
LANGUAGE_VERSION
Reserved key for the named value that identifies the version of the scripting language supported by the implementation.static String
NAME
Reserved key for a named value that identifies the short name of the scripting language.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description Bindings
createBindings()
Returns an uninitializedBindings
.Object
eval(Reader reader)
Same aseval(String)
except that the source of the script is provided as aReader
Object
eval(Reader reader, Bindings n)
Same aseval(String, Bindings)
except that the source of the script is provided as aReader
.Object
eval(Reader reader, ScriptContext context)
Same aseval(String, ScriptContext)
where the source of the script is read from aReader
.Object
eval(String script)
Executes the specified script.Object
eval(String script, Bindings n)
Executes the script using theBindings
argument as theENGINE_SCOPE
Bindings
of theScriptEngine
during the script execution.Object
eval(String script, ScriptContext context)
Causes the immediate execution of the script whose source is the String passed as the first argument.Object
get(String key)
Retrieves a value set in the state of this engine.Bindings
getBindings(int scope)
Returns a scope of named values.ScriptContext
getContext()
Returns the defaultScriptContext
of theScriptEngine
whose Bindings, Reader and Writers are used for script executions when noScriptContext
is specified.ScriptEngineFactory
getFactory()
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
setContext(ScriptContext context)
Sets the defaultScriptContext
of theScriptEngine
whose Bindings, Reader and Writers are used for script executions when noScriptContext
is specified.
-
-
-
Field Detail
-
ARGV
static final String ARGV
Reserved key for a named value that passes an array of positional arguments to a script.- See Also:
- Constant Field Values
-
FILENAME
static final String FILENAME
Reserved key for a named value that is the name of the file being executed.- See Also:
- Constant Field Values
-
ENGINE
static final String ENGINE
Reserved key for a named value that is the name of theScriptEngine
implementation.- See Also:
- Constant Field Values
-
ENGINE_VERSION
static final String ENGINE_VERSION
Reserved key for a named value that identifies the version of theScriptEngine
implementation.- See Also:
- Constant Field Values
-
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:
- Constant Field Values
-
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:
- Constant Field Values
-
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:
- Constant Field Values
-
-
Method Detail
-
eval
Object eval(String script, ScriptContext context) throws ScriptException
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_SCOPE
Bindings
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) throws ScriptException
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) throws ScriptException
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) throws ScriptException
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) throws ScriptException
Executes the script using theBindings
argument as theENGINE_SCOPE
Bindings
of theScriptEngine
during the script execution. TheReader
,Writer
and non-ENGINE_SCOPE
Bindings
of the defaultScriptContext
are used. TheENGINE_SCOPE
Bindings
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) throws ScriptException
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 addvalue
- 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 default
ScriptContext
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:
- The
Bindings
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 default
ScriptContext
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 invalidNullPointerException
- if the bindings is null and the scope isScriptContext.ENGINE_SCOPE
-
createBindings
Bindings createBindings()
Returns an uninitializedBindings
.- Returns:
- A
Bindings
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 default
ScriptContext
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:
- The
ScriptEngineFactory
-
-