org.rexxla.bsf.engines.rexx

## Class RexxCompiledScript

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

- All Implemented Interfaces:
    javax.script.Invocable

      public class RexxCompiledScript
      extends javax.script.CompiledScript
      implements javax.script.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

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Object` | `eval(javax.script.ScriptContext sc)` Evaluates (executes, runs) the Rexx program stored in this `RexxCompiledScript` object.
    `java.lang.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.
    `java.lang.String` | `getFilename()` Getter method to return the current value of `filename`.
    `<T> T` | `getInterface(java.lang.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(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`.
    `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.
    `java.lang.String` | `getScriptSource()` Getter for the Rexx script source code.
    `boolean` | `getSupplyBSFExceptionObject()` Getter for the Rexx script which got compiled (tokenized).
    `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` | `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 Detail

    - #### 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 java.lang.String getFilename()

      Getter method to return the current value of `filename`.
      Returns:
        the current value of `filename`

    - #### getScriptSource

          public java.lang.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 java.lang.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 java.lang.Object eval(javax.script.ScriptContext sc)
                                throws javax.script.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 `javax.script.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:
        `javax.script.ScriptException`

    - #### getEngine

          public RexxScriptEngine getEngine()

      Returns the `ScriptEngine` whose compile method created this CompiledScript.
      Specified by:
        `getEngine` in class `javax.script.CompiledScript`

    - #### getInterface

          public <T> T getInterface(java.lang.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 `javax.script.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(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`.

      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 `javax.script.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 java.lang.Object invokeFunction(java.lang.String name,
                                                 java.lang.Object... args)
                                          throws javax.script.ScriptException,
                                                 java.lang.NoSuchMethodException

      Invokes (calls) a public Rexx routine defined in this compiled script.
      Specified by:
        `invokeFunction` in interface `javax.script.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:
        `javax.script.ScriptException`
        `java.lang.NoSuchMethodException`

    - #### invokeMethod

          public java.lang.Object invokeMethod(java.lang.Object thiz,
                                               java.lang.String name,
                                               java.lang.Object... args)
                                        throws javax.script.ScriptException,
                                               java.lang.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 `javax.script.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:
        `javax.script.ScriptException`
        `java.lang.NoSuchMethodException`