public class RexxScriptEngine
extends javax.script.AbstractScriptEngine
implements javax.script.Compilable, javax.script.Invocable
javax.script.ScriptEngine
class and implements the
javax.script.Compilalbe
and * the javax.script.Invocable
interface,
although the latter one would only make sense in RexxCompiledScript
class, because of the
T getInterface(Class clasz)
method. Therefore the author (Rony
G. Flatscher who served on the JSR-223 specification committee) thinks that the documentation
in javax.script.Invocable
is false, as it states that Invocable
gets implemented by a
ScriptEngine
, somehow indicating it has to operate on some "state" of the script engine.
ScriptEngine
sharing as much code between
the tow (and caching compiled scripts for invoking the aforementioned method in a sensible way.Modifier and Type | Class and Description |
---|---|
static class |
RexxScriptEngine.RexxAnnotation
Inner class for determining a RexxScript annotation, if one exists, the annotation field will
refer to the appropriate enum value and all fields are filled in to ease processing of the
script's code by the caller.
|
Modifier and Type | Field and Description |
---|---|
(package private) boolean |
bAddLatestPackageDynamically
This controls per RexxScriptEngine instance whether the Rexx package of a run script gets added
to the Rexx package of the next compiled script.
|
(package private) boolean |
bInitialBSFRequiresDone
This controls whether the initial requires for 'BSF.CLS' has been carried out or not, which is necessary
to allow the very first Rexx script to pass Java objects as arguments already.
|
static boolean |
bPrependDynamicRequiresStatement
This controls whether the supplied Rexx scripts should get a dynamic requires statement prepended that
makes sure that the Java support is present.
|
static boolean |
bRedirectStandardFiles
Determines whether the ScriptContext's Reader, Writer and ErrorWriter should replace the Rexx script
.input (and also .debugInput, if present), .output, .error (and also .traceOutput if present).
|
(package private) org.apache.bsf.BSFManager |
bsfMgr
Stores the BSF Rexx manager that is used for loading the BSF Rexx engine.
|
(package private) RexxEngine |
bsfRexxEngine
Stores the BSF Rexx engine which gets used to invoke the scripts
|
static boolean |
bSupplyBSFExceptionObject
This controls whether ScriptExceptions should supply the
RexxException object (extends BSFException ) or fill in the ScriptException
fields (message, line and column number, if present). |
(package private) java.io.Writer |
cachedErrorWriter
Caches the latest writer fetched from the script context.
|
(package private) java.io.Reader |
cachedReader
Caches the latest reader fetched from the script context.
|
(package private) java.io.Writer |
cachedWriter
Caches the latest writer fetched from the script context.
|
(package private) RexxCompiledScript |
currentScript
Caches the last compiled script.
|
static java.lang.String |
dynamicallyRequireBSF
Rexx code to dynamically require "
BSF.CLS ". |
(package private) RexxProxy |
latestRexxPackage
This field stores the Rexx package of the last Rexx script that got compiled and added the
previous Rexx package stored in this field prior to it.
|
(package private) java.lang.String |
rexxCreateRoutineAndPackageCode
Rexx code to create and return a Rexx RoutineAndPackage, optionally allowing for one entry-name and entry-value.
|
(package private) java.lang.String |
rexxCreateRoutineCode
Rexx code to create and return a Rexx routine object from Rexx code.
|
(package private) java.lang.String |
rexxCreateSlotArgumentCode
Rexx code to create and return a subclass of the Rexx directory class, which carries the name
"Slot.Argument", optionally allowing for one entry-name and entry-value.
|
(package private) java.lang.String |
rexxMonitorWrapperCode
Rexx code to create and return a Rexx routine object from Rexx code.
|
(package private) java.lang.String |
rexxRedirectStandardFilesCode
Rexx code to create and return a Rexx directory, optionally allowing for one entry-name and entry-value.
|
(package private) java.lang.String |
rexxRoutineWrapperCode
Rexx code to create and return a Rexx routine object from Rexx code.
|
static java.lang.String |
strFormatGET
The Rexx code to inject for the Rexx script annotation
@GET . |
static java.lang.String |
strFormatSET
The Rexx code to inject for the Rexx script annotation
@SET . |
Constructor and Description |
---|
RexxScriptEngine()
Default constructor which creates the peer BSF Rexx engine instance.
|
Modifier and Type | Method and Description |
---|---|
javax.script.CompiledScript |
compile(java.io.Reader script)
Compiles (tokenizes) the script (source read from Reader) for later execution.
|
javax.script.CompiledScript |
compile(java.lang.String script)
Compiles (tokenizes) the script (source given as a String) for later execution.
|
(package private) javax.script.CompiledScript |
compile(java.lang.String script,
java.lang.String filename)
Compiles the script (source represented as a String) for later execution.
|
javax.script.Bindings |
createBindings()
Creates and returns a SimpleBindings instance.
|
static void |
dumpScriptContext(javax.script.ScriptContext sc)
Utility method to dump the content of the supplied
ScriptContext . |
java.lang.Object |
eval(java.io.Reader r,
javax.script.ScriptContext sc)
Creates the script from the supplied
Reader and uses eval (String script, ScriptContext sc)
to carry out the operation. |
java.lang.Object |
eval(java.lang.String script,
javax.script.ScriptContext sc)
Creates a
RexxCompiledScript object for the supplied Rexx script and then uses
RexxCompiledScript.eval(ScriptContext sc) to carry out the operation. |
boolean |
getAddLatestPackageDynamically()
Returns the current setting of
bAddLatestPackageDynamically . |
org.apache.bsf.BSFManager |
getBsfManager()
Getter method that returns the BSF manager used for managing this BSF scripting engine.
|
RexxEngine |
getBsfRexxEngine()
Getter method that returns the BSF scripting engine in use.
|
(package private) RexxProxy |
getCreateRoutine()
Getter method to return
rexxCreateRoutineCode . |
(package private) RexxProxy |
getCreateRoutineAndPackage()
Getter method to return
rexxCreateRoutineAndPackage . |
(package private) RexxProxy |
getCreateSlotArgument()
Getter method to return
rexxCreateSlotArgument . |
RexxCompiledScript |
getCurrentScript()
Getter method for "current" (the latest evaluated) script.
|
javax.script.ScriptEngineFactory |
getFactory()
Returns the default RexxScriptEngineFactory instance for the Rexx scripting language.
|
static java.lang.String |
getGMTFormattedDate4Filename()
Utility method to format a
SimpleDateFormat such that it can be used as part of a generated filename. |
<T> T |
getInterface(java.lang.Class<T> clasz)
Returns an implementation of an interface using functions compiled in the interpreter.
|
<T> T |
getInterface(java.lang.Object thiz,
java.lang.Class<T> clasz)
Returns an implementation of a Java interface where the Java method invocations will be implemented
by the methods of the supplied Rexx object (a
RexxProxy . |
(package private) RexxProxy |
getMonitorWrapper()
Getter method to return the ooRexx routine.
|
java.lang.Object |
getNil()
Getter method that returns the ooRexx
.nil object. |
(package private) static java.lang.String |
getReaderAsString(java.io.Reader r)
Utility method to read all characters of a
Reader using a BufferedReader
if necessary. |
(package private) RexxProxy |
getRedirectStandardFiles()
Getter method to return
rexxRedirectStandardFiles . |
(package private) RexxProxy |
getRoutineWrapper()
Getter method to return the ooRexx routine.
|
java.lang.Object |
invokeFunction(java.lang.String name,
java.lang.Object... args)
Invokes (calls) a public Rexx routine defined in this compiled script.
|
java.lang.Object |
invokeMethod(java.lang.Object thiz,
java.lang.String name,
java.lang.Object... args)
Sends a Rexx message to the Rexx object contained in the addressed
RexxProxy object. |
void |
setAddLatestPackageDynamically(boolean newValue)
Allows to change the behaviour from adding the
latestRexxPackage to new Rexx routines. |
(package private) void |
updateRexxEngine(javax.script.ScriptContext sc)
Utility method that makes sure that the native
BSF4ooRexx interface for this Rexx
interpreter instance is using BSF.CLS for making exchange of Java objects in
arguments transparent to the Rexx program. |
public static boolean bSupplyBSFExceptionObject
RexxException
object (extends BSFException
) or fill in the ScriptException
fields (message, line and column number, if present). Using BSFException.getCause()
will return
the RexxException
object, that has a method getRexxConditionObject
which is a RexxProxy
for
the Rexx directory (cf. the ooRexx condition object documentation for its entries).
false
, then an attempt is made to supply as much information according to
the ScriptException
constructors, which might ease generic script editors that use JSR223 script engines.public static boolean bRedirectStandardFiles
java.io.Reader cachedReader
.input
, such that
it is not necessary to set this value each time a script gets invoked or evaluated.java.io.Writer cachedWriter
.output
, such that
it is not necessary to set this value each time a script gets invoked or evaluated.java.io.Writer cachedErrorWriter
.error
, such that
it is not necessary to set this value each time a script gets invoked or evaluated.RexxCompiledScript currentScript
Invocation
methods
get invoked (namely "<T> T getInterface(Class;<T> clasz)/code>")
via the ScriptEngine as the javax.script.Invocable
documentation (in
the author's (Rony G. Flatscher) opinion, who also has served on the JSR-223 specification
team for javax.script) erroneously states that Invocable
should be implemented
by a ScriptEngine
rather than a CompiledScript
.public static java.lang.String strFormatGET
@GET
. Get the last
argument (a Rexx Directory, dubbed "slotDir") and fetch the entry "ScriptContext" from it.public static java.lang.String strFormatSET
@SET
.
Get the last argument (a Rexx Directory, dubbed "slotDir") and fetch the entry "ScriptContext" from it.public static final java.lang.String dynamicallyRequireBSF
BSF.CLS
". This makes sure that the
native part of BSF4ooRexx
is set to support the camouflaging support from the beginning.public static boolean bPrependDynamicRequiresStatement
bAddLatestPackageDynamically
is set to false
.boolean bAddLatestPackageDynamically
boolean bInitialBSFRequiresDone
RexxProxy latestRexxPackage
RexxEngine bsfRexxEngine
org.apache.bsf.BSFManager bsfMgr
java.lang.String rexxCreateRoutineCode
java.lang.String rexxMonitorWrapperCode
java.lang.String rexxRoutineWrapperCode
java.lang.String rexxRedirectStandardFilesCode
java.lang.String rexxCreateSlotArgumentCode
java.lang.String rexxCreateRoutineAndPackageCode
public RexxScriptEngine()
public RexxCompiledScript getCurrentScript()
currentScript
object.
Fetching this RexxCompiledScript
allows one to execute it as many times as needed, but also
use all of the implemented Invocable
methods.RexxCompiledScript
object or null
if no script has
been evaluated or compiled yetpublic void setAddLatestPackageDynamically(boolean newValue)
latestRexxPackage
to new Rexx routines.
Default is true
, which makes sure that any new Rexx routine will get the latest
Rexx package added to it, thereby gaining access to the package BSF.CLS
and all
previously defined public routines and public classes.newValue
- true
or false
public boolean getAddLatestPackageDynamically()
bAddLatestPackageDynamically
.bAddLatestPackageDynamically
.public RexxEngine getBsfRexxEngine()
public java.lang.Object getNil()
.nil
object.RexxProxy
referring to the ooRexx .nil
objectpublic org.apache.bsf.BSFManager getBsfManager()
RexxProxy getCreateRoutine() throws javax.script.ScriptException
rexxCreateRoutineCode
. If rexxCreateRoutineCode
is null
the Rexx routine object will get created, stored and returned.RexxProxy
for the Rexx routine object
a single entry)javax.script.ScriptException
RexxProxy getMonitorWrapper() throws javax.script.ScriptException
rexxMonitorWrapper
is null
the Rexx routine object will get created, stored and returned.RexxProxy
for the Rexx routine objectjavax.script.ScriptException
RexxProxy getRoutineWrapper() throws javax.script.ScriptException
rexxRoutineWrapper
is null
the Rexx routine object will get created, stored and returned.RexxProxy
for the Rexx routine objectjavax.script.ScriptException
RexxProxy getRedirectStandardFiles() throws javax.script.ScriptException
rexxRedirectStandardFiles
. If rexxRedirectStandardFiles
is null
the Rexx routine object will get created, stored and returned.RexxProxy
for the Rexx routine objectjavax.script.ScriptException
RexxProxy getCreateSlotArgument() throws javax.script.ScriptException
rexxCreateSlotArgument
. If rexxCreateSlotArgument
is null
the Rexx routine object will get created, stored and returned.RexxProxy
for the Rexx routine to create a Rexx directory (and optionally supply
a single entry)javax.script.ScriptException
RexxProxy getCreateRoutineAndPackage() throws javax.script.ScriptException
rexxCreateRoutineAndPackage
. If rexxCreateRoutineAndPackage
is null
the Rexx routine object will get created, stored and returned.RexxProxy
for the Rexx routine to create a Rexx RoutineAndPackage (and optionally supply
a single entry)javax.script.ScriptException
public javax.script.ScriptEngineFactory getFactory()
getFactory
in interface javax.script.ScriptEngine
public javax.script.Bindings createBindings()
createBindings
in interface javax.script.ScriptEngine
public java.lang.Object eval(java.io.Reader r, javax.script.ScriptContext sc) throws javax.script.ScriptException
Reader
and uses eval (String script, ScriptContext sc)
to carry out the operation.eval
in interface javax.script.ScriptEngine
r
- - A Reader
supplying the Rexx code to evaluate.sc
- - A RexxProxy
. Supplying a RexxProxy
as an
argument to a Rexx routine will cause the contained Rexx object to be used in Rexx instead.
RexxProxy
by sending
it messages from Java using its sendMessage
methods.javax.script.ScriptException
public java.lang.Object eval(java.lang.String script, javax.script.ScriptContext sc) throws javax.script.ScriptException
RexxCompiledScript
object for the supplied Rexx script and then uses
RexxCompiledScript.eval(ScriptContext sc)
to carry out the operation.eval
in interface javax.script.ScriptEngine
script
- - The Rexx script to evaluate.sc
- - A ScriptContext
object supplying information for evaluating the Rexx scriptRexxProxy
. Supplying a RexxProxy
as an
argument to a Rexx routine will cause the contained Rexx object to be used in Rexx instead.
RexxProxy
by sending
it messages from Java using its sendMessage
methods.javax.script.ScriptException
public javax.script.CompiledScript compile(java.io.Reader script) throws javax.script.ScriptException
compile(String script)
.compile
in interface javax.script.Compilable
script
- a Reader that supplies the characters of the scriptjavax.script.ScriptException
public javax.script.CompiledScript compile(java.lang.String script) throws javax.script.ScriptException
compile(String script, String filename)
.compile
in interface javax.script.Compilable
script
- - The Rexx script to be compiled (tokenized).javax.script.ScriptException
javax.script.CompiledScript compile(java.lang.String script, java.lang.String filename) throws javax.script.ScriptException
script
- - The Rexx script to be compiled (tokenized).filename
- - The filename to be used for evaluating the Rexx script. If this value is null
then a filename gets generated, which will include the time of generation in its name.
Hint: this filename can be fetched from Rexx using the
javax.script.ScriptException
public <T> T getInterface(java.lang.Class<T> clasz)
Note: Uses the implementation in RexxCompiledScript.getInterface(Class
.
getInterface
in interface javax.script.Invocable
clasz
- - The Java interface class object <T>
, whose methods are implemented as public Rexx routines.<T>
public <T> T getInterface(java.lang.Object thiz, java.lang.Class<T> clasz)
RexxProxy
.
Hint #1: the external BSF4ooRexx
external Rexx function BSFCreateRexxProxy(...)
is much more versatile and among other things allows for implementing multiple Java interface
classes in a single Rexx class.
Hint #2: when an interface method gets invoked, the Rexx method routine gets all its arguments in the
same order supplied to, plus an appended RexxSlotArgument
"slot directory
object, which contains information about this particular method invocation. This slot directory
will also contain an entry, named "SCRIPTCONTEXT"
, which allows the
Rexx routine to fully interact with the ScriptContext
used for its invocation.
(Hint: one can always access this object from Rexx code with the statement
scriptcontext=arg('A')~lastItem~scriptContext
).)
getInterface
in interface javax.script.Invocable
thiz
- - The Java object (must be a clasz
- - The Java interface class object <T>
, whose methods are implemented in the
thiz
object<T>
public java.lang.Object invokeFunction(java.lang.String name, java.lang.Object... args) throws javax.script.ScriptException, java.lang.NoSuchMethodException
Note: Uses the implementation in RexxCompiledScript
where this method belongs to.
invokeFunction
in interface javax.script.Invocable
name
- - The name of the public routine to invoke.args
- - The arguments (a Java array of type Object
) for the routine.
Note # 1: If any argument is of type RexxProxy
, then the Rexx routine will
receive the contained Rexx object instead.
Note # 2: This method will append an additional Rexx directory object argument with an entry named
"SCRIPTCONTEXT"
, which allows the Rexx routine to fully interact
with the ScriptContext
used for its invocation.
(Hint: one can always access this object from Rexx code with the statement
scriptcontext=arg('A')~lastItem~scriptContext
).)
RexxProxy
. Supplying a RexxProxy
as an
argument to a Rexx routine will cause the contained Rexx object to be used in Rexx instead.
RexxProxy
by sending
it messages from Java using its sendMessage
methods or the
invokeMethod(Object thiz, String name, Object... args
method.javax.script.ScriptException
java.lang.NoSuchMethodException
public java.lang.Object invokeMethod(java.lang.Object thiz, java.lang.String name, java.lang.Object... args) throws javax.script.ScriptException, java.lang.NoSuchMethodException
RexxProxy
object.invokeMethod
in interface javax.script.Invocable
thiz
- - The wrapped (as a name
- - The Rexx message (method) name.args
- - The arguments (a Java array of type Object
) for the Rexx method.
Note # 1: If any argument is of type RexxProxy
, then the Rexx routine will
receive the contained Rexx object instead.
Note # 2: This method will append an additional Rexx directory object argument with an entry named
"SCRIPTCONTEXT"
, which allows the Rexx routine to fully interact
with the ScriptContext
used for its invocation.
(Hint: one can always access this object from Rexx code with the statement
scriptcontext=arg('A')~lastItem~scriptContext
).)
RexxProxy
. Supplying a RexxProxy
as an
argument to a Rexx routine will cause the contained Rexx object to be used in Rexx instead.
RexxProxy
by sending
it messages from Java using its sendMessage
methods or the
invokeMethod(Object thiz, String name, Object... args
method.javax.script.ScriptException
java.lang.NoSuchMethodException
public static void dumpScriptContext(javax.script.ScriptContext sc)
ScriptContext
.public static java.lang.String getGMTFormattedDate4Filename()
SimpleDateFormat
such that it can be used as part of a generated filename.static java.lang.String getReaderAsString(java.io.Reader r) throws javax.script.ScriptException
Reader
using a BufferedReader
if necessary.r
- - The Reader
object to read from.String
representing built from the characters or null, if the
supplied Reader
was null
javax.script.ScriptException
void updateRexxEngine(javax.script.ScriptContext sc) throws javax.script.ScriptException, org.apache.bsf.BSFException
BSF4ooRexx
interface for this Rexx
interpreter instance is using BSF.CLS
for making exchange of Java objects in
arguments transparent to the Rexx program. In addition it will redirect the Rexx script's
standard monitors .input
, .output
and .error
to those
supplied by the ScriptContext
, if supplied at all.sc
- - The ScriptContext
the Rexx script should use or null
.
If supplied, then the ScriptContext
's defined Reader
,
Writer
and ErrorWriter
get used to redirect the Rexx
script's standard monitors .input
, .output
and
.error
.javax.script.ScriptException
org.apache.bsf.BSFException