Package org.rexxla.bsf.engines.rexx

# Class RexxCompiledScript

java.lang.Object
javax.script.CompiledScript
org.rexxla.bsf.engines.rexx.RexxCompiledScript

All Implemented Interfaces:
  `Invocable`

public class RexxCompiledScript extends CompiledScript implements Invocable
Class that extends the `javax.script.CompiledScript` class and implements the `javax.script.Invocable` interface as this only makes sense in this class for `getInterface(Class clasz)`. 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.
Please note: the JSR-223 specification does not imply that ScriptEngine should implement this interface!
The [oo]Rexx implementation of JSR-223 tries to be as flexible as possible and also implements this interface in its implementation of `ScriptEngine` sharing as much code between the tow (and caching compiled scripts for invoking the aforementioned method in a sensible way.

Since:
  2015-05-11
Version:
  100.20200128
Author:
  Rony G. Flatscher

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Object`
  `eval(ScriptContext sc)`
  Evaluates (executes, runs) the Rexx program stored in this `RexxCompiledScript` object.
  `String`
  `getEditedScriptSource()`
  Getter for the Rexx edited script source code which got compiled (tokenized), it will have injected code, if any of the Rexx script annotations @GET, @GET("attribute list") or @SET("attribute list") was found in `scriptSource`.
  `RexxScriptEngine`
  `getEngine()`
  Returns the `ScriptEngine` whose compile method created this CompiledScript.
  `String`
  `getFilename()`
  Getter method to return the current value of `filename`.
  `<T> T`
  `getInterface(Class<T> clasz)`
  Returns an implementation of a Java interface where the Java method invocations will be carried out by the public Rexx routines in the script.
  `<T> T`
  `getInterface(Object thiz, 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`.
  `RexxProxy`
  `getPackageObject()`
  Getter for the `RexxProxy` representing the Rexx routine object the script got compiled (tokenized) into.
  `RexxScriptEngine`
  `getRexxScriptEngine()`
  Getter to retrieve the RexxScriptEngine used to create this compiled script.
  `RexxProxy`
  `getScriptObject()`
  Getter for the `RexxProxy` representing the Rexx routine object the script got compiled (tokenized) to.
  `String`
  `getScriptSource()`
  Getter for the Rexx script source code.
  `boolean`
  `getSupplyBSFExceptionObject()`
  Getter for the Rexx script which got compiled (tokenized).
  `Object`
  `invokeFunction(String name, Object... args)`
  Invokes (calls) a public Rexx routine defined in this compiled script.
  `Object`
  `invokeMethod(Object thiz, String name, Object... args)`
  Sends a Rexx message to the Rexx object contained in the addressed `RexxProxy` object.
  `void`
  `setSupplyBSFExceptionObject(boolean newValue)`
  Setter for the Rexx script which got compiled (tokenized).

  ### Methods inherited from class javax.script.CompiledScript

  `eval, eval`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### getRexxScriptEngine

    public RexxScriptEngine getRexxScriptEngine()
    Getter to retrieve the RexxScriptEngine used to create this compiled script.
    Returns:
      the RexxScriptEngine that created this RexxCompiledScript object

  - ### getSupplyBSFExceptionObject

    public boolean getSupplyBSFExceptionObject()
    Getter for the Rexx script which got compiled (tokenized).
    Returns:
      the current value of `bSupplyBSFExceptionObject`

  - ### setSupplyBSFExceptionObject

    public void setSupplyBSFExceptionObject(boolean newValue)
    Setter for the Rexx script which got compiled (tokenized).
    Parameters:
      `newValue` - the value to be used for the field `bSupplyBSFExceptionObject`

  - ### getFilename

    public String getFilename()
    Getter method to return the current value of `filename`.
    Returns:
      the current value of `filename`

  - ### getScriptSource

    public String getScriptSource()
    Getter for the Rexx script source code. If there are no Rexx script annotations present, then this code got compiled (tokenized), else the edited code stored in the field `editedScriptSource`. .
    Returns:
      the string representing the Rexx script program

  - ### getEditedScriptSource

    public String getEditedScriptSource()
    Getter for the Rexx edited script source code which got compiled (tokenized), it will have injected code, if any of the Rexx script annotations @GET, @GET("attribute list") or @SET("attribute list") was found in `scriptSource`. If this version exists, it got compiled instead of `scriptSource`.
    Returns:
      the string representing of the edited Rexx script program

  - ### getScriptObject

    public RexxProxy getScriptObject()
    Getter for the `RexxProxy` representing the Rexx routine object the script got compiled (tokenized) to.
    Returns:
      a `RexxProxy` representing the Rexx routine object

  - ### getPackageObject

    public RexxProxy getPackageObject()
    Getter for the `RexxProxy` representing the Rexx routine object the script got compiled (tokenized) into.
    Returns:
      a `RexxProxy` representing the Rexx package object of this compiled script

  - ### eval

    public Object eval(ScriptContext sc) throws ScriptException
    Evaluates (executes, runs) the Rexx program stored in this `RexxCompiledScript` object. The `sc` parameter will always be passed on to the Rexx routine by storing it in a `RexxDirectory` under the index `"SCRIPTCONTEXT"` and appending it as the last argument to the Rexx script. This way any Rexx routine is able to access and manipulate the `ScriptContext`.
    Specified by:
      `eval` in class `CompiledScript`
    Parameters:
      `sc` - - A `ScriptContext` object, which will be supplied to the Rexx routine in a `RexxDirectory` under the index `"SCRIPTCONTEXT"`, by appending it to the Rexx argument list. (Hint: one can always access this object from Rexx code with the statement `scriptcontext=arg('A')~lastItem~scriptContext`).)

      If this parameter contains a `ScriptEngine.ARGV` (the String `"javax.script.argv"`) entry (a Java `Object` array), then these objects are used as arguments for the Rexx routine in the supplied order. Java `null` values will be represented as ooRexx `.nil` values.
      Note: 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

      If this parameter contains a `ScriptEngine.FILENAME` (the String `"javax.script.filename"`) entry (a string), then this is used as the filename for the Rexx routine to execute and can be fetched from Rexx with the statement `parse source . . thisFilename`.

    Returns:
      the object the Rexx routine returns. In the case that a Rexx object gets returned it will be wrapped (boxed) in a `RexxProxy`. Supplying a `RexxProxy` as an argument to a Rexx routine will cause the contained Rexx object to be used in Rexx instead.
      Hint: one can interact with the contained Rexx object of a `RexxProxy` by sending it messages from Java using its `sendMessage` methods.
    Throws:
      `ScriptException`

  - ### getEngine

    public RexxScriptEngine getEngine()
    Returns the `ScriptEngine` whose compile method created this CompiledScript.
    Specified by:
      `getEngine` in class `CompiledScript`

  - ### getInterface

    public <T> T getInterface(Class<T> clasz)
    Returns an implementation of a Java interface where the Java method invocations will be carried out by the public Rexx routines in the script. Therefore there must be a public Rexx routine defined for each Java interface method.

    Hint: when an interface method gets invoked, the Rexx routine gets all its arguments in the same order supplied to, plus an appended `RexxDirectory` "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`).)

    Specified by:
      `getInterface` in interface `Invocable`
    Parameters:
      `clasz` - - The Java interface class object `<T>`, whose methods are implemented as public Rexx routines.
    Returns:
      a Java object of type `<T>`

  - ### getInterface

    public <T> T getInterface(Object thiz, 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`.

    Note: Uses the implementation in `RexxScriptEngine.getInterface(Object thiz, Class clasz)`.

    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 `RexxDirectory` "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`).)

    Specified by:
      `getInterface` in interface `Invocable`
    Parameters:
      `thiz` - - The Java object (must be a `RexxProxy`) that implements the Java interface methods
      `clasz` - - The Java interface class object `<T>`, whose methods are implemented in the `thiz` object
    Returns:
      a Java object of type `<T>`

  - ### invokeFunction

    public Object invokeFunction(String name, Object... args) throws ScriptException, NoSuchMethodException
    Invokes (calls) a public Rexx routine defined in this compiled script.
    Specified by:
      `invokeFunction` in interface `Invocable`
    Parameters:
      `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`).)

    Returns:
      the object the Rexx routine returns. In the case that a Rexx object gets returned it will be wrapped (boxed) in a `RexxProxy`. Supplying a `RexxProxy` as an argument to a Rexx routine will cause the contained Rexx object to be used in Rexx instead.
      Hint: one can interact with the contained Rexx object of a `RexxProxy` by sending it messages from Java using its `sendMessage` methods or the `invokeMethod(Object thiz, String name, Object...args)` method.
    Throws:
      `ScriptException`
      `NoSuchMethodException`

  - ### invokeMethod

    public Object invokeMethod(Object thiz, String name, Object... args) throws ScriptException, NoSuchMethodException
    Sends a Rexx message to the Rexx object contained in the addressed `RexxProxy` object.

    Note: Uses the implementation in `RexxScriptEngine.invokeMethod(Object thiz, String name, Object...args)` where this method belongs to.

    Specified by:
      `invokeMethod` in interface `Invocable`
    Parameters:
      `thiz` - - The wrapped (as a `RexxProxy`) Rexx object to receive the message
      `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`).)

    Returns:
      the object the Rexx routine returns. In the case that a Rexx object gets returned it will be wrapped (boxed) in a `RexxProxy`. Supplying a `RexxProxy` as an argument to a Rexx routine will cause the contained Rexx object to be used in Rexx instead.
      Hint: one can interact with the contained Rexx object of a `RexxProxy` by sending it messages from Java using its `sendMessage` methods or the `invokeMethod(Object thiz, String name, Object...args)` method.
    Throws:
      `ScriptException`
      `NoSuchMethodException`