org.rexxla.bsf.engines.rexx

## Interface RexxHandler

- All Known Subinterfaces:
    RexxCommandHandler, RexxExitHandler, RexxRedirectingCommandHandler
  All Known Implementing Classes:
    AbstractDirectCommandHandler, AbstractExitHandler, AbstractRedirectingCommandHandler, JavaDrawingHandler

      public interface RexxHandler

  Abstract class to allow Rexx exit and command handlers implemented in Java to use some of the ooRexx exit APIs directly.

  Please note: these methods allow interfacing with the running instance of the Rexx interpreter instance on the same (!) thread in which the Rexx command or Rexx exit Java handler got invoked on. It is necessary to supply the opaque argument named slot from the Java handler methods unaltered.
  If neither of these two restrictions holds, then the results of executing any of these static methods will be undefined, mostlikely tearing down ooRexx and Java!

      ------------------------ Apache Version 2.0 license -------------------------
          Copyright (C) 2012-2024 Rony G. Flatscher

          Licensed under the Apache License, Version 2.0 (the "License");
          you may not use this file except in compliance with the License.
          You may obtain a copy of the License at

              http://www.apache.org/licenses/LICENSE-2.0

          Unless required by applicable law or agreed to in writing, software
          distributed under the License is distributed on an "AS IS" BASIS,
          WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
          See the License for the specific language governing permissions and
          limitations under the License.
       -----------------------------------------------------------------------------

  Since:
    2022-08-22
  Version:
    850.20220901
  Author:
    Rony G. Flatscher

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `version` Version string indicating version of this class (majorVersion*100+minorVersion concatenated with a dot and the sorted date of last change), e.g.

  - ### Method Summary

    All Methods Instance Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default boolean` | `checkCondition(java.lang.Object slot)` Checks to see if any conditions have resulted from a call to a Rexx API (cf "rexxapi.pdf").
    `default void` | `clearCondition(java.lang.Object slot)` Clears any pending condition status (cf "rexxapi.pdf").
    `default void` | `dropContextVariable(java.lang.Object slot, java.lang.String variableName)` Drops a Rexx variable from the context.
    `default java.lang.Object` | `getAllContextVariables(java.lang.Object slot)` Fetches and returns a Rexx directory containing all context variables.
    `default java.lang.Object` | `getCallerContext(java.lang.Object slot)` Returns the Rexx context object `.context` that can be analyzed to learn about the context of the command/exit.
    `default java.lang.Object` | `getConditionInfo(java.lang.Object slot)` Returns a directory object containing the condition information; this is equivalent to calling `condition('O')` from within Rexx code (cf "rexxapi.pdf").
    `default java.lang.Object` | `getContextVariable(java.lang.Object slot, java.lang.String variableName)` Fetches and returns the Rexx variable value in the Rexx program for which the handler runs.
    `default java.lang.Object` | `getGlobalEnvironment(java.lang.Object slot)` Returns a reference to the Rexx interpreter global `.environment` directory.
    `default long` | `getInterpreterVersion(java.lang.Object slot)` (Copied from the ooRexx rexxapi.pdf documentation) "Returns the version of the interpreter." "The returned version is encoded in the 3 least significant bytes of the returned value, using 1 byte each for the interpreter version, release, and revision values." "For example, on a 32-bit platform, this value would be `0x00050000` for version 5.0.0."
    `default long` | `getLanguageLevel(java.lang.Object slot)` (Copied from the ooRexx rexxapi.pdf documentation) "Returns the language level of the interpreter." "The returned language level is encoded in the 2 least significant bytes of the returned value, using 1 byte each for the interpreter version, release, and revision values.
    `default java.lang.Object` | `getLocalEnvironment(java.lang.Object slot)` Returns a reference to this Rexx interpreter instance `.local` environment directory.
    `default java.lang.Object` | `getNil(java.lang.Object slot)` Returns a reference to the Rexx sentinel value `.nil`.
    `default void` | `haltThread(java.lang.Object slot)` Raises a `HALT` condition on the current (Rexx) thread.
    `default java.lang.Object` | `newArray(java.lang.Object slot)` Returns a newly created ooRexx `Array` collection object.
    `default java.lang.Object` | `newDirectory(java.lang.Object slot)` Returns a newly created ooRexx `Directory` collection object.
    `default java.lang.Object` | `newStem(java.lang.Object slot, java.lang.String stemName)` Returns a newly created ooRexx `Stem` collection object.
    `default java.lang.Object` | `newStringTable(java.lang.Object slot)` Returns a newly created ooRexx `StringTable` collection object.
    `default void` | `raiseCondition(java.lang.Object slot, java.lang.String conditionName, java.lang.String description, java.lang.Object[] additional, java.lang.Object result)` Raises a condition in the current Rexx thread, pass-through method to the Rexx API, which should be called immediately before returning to Rexx.
    `default void` | `raiseException(java.lang.Object slot, long definedErrorNumber, java.lang.Object[] substitutions)` Raises a Rexx syntax condition of the given error number, call immediately before returning from Java to Rexx.
    `default void` | `raiseException0(java.lang.Object slot, long definedErrorNumber)` Raises a Rexx error without substitution values of the given error number, call immediately before returning from Java.
    `default void` | `raiseException1(java.lang.Object slot, long definedErrorNumber, java.lang.String substitution1)` Raises a Rexx error of the given error number, call immediately before returning from Java.
    `default void` | `raiseException2(java.lang.Object slot, long definedErrorNumber, java.lang.String substitution1, java.lang.String substitution2)` Raises a Rexx error of the given error number, call immediately before returning from Java.
    `default void` | `setContextVariable(java.lang.Object slot, java.lang.String variableName, java.lang.Object variableValue)` Allows to set a variable with a value in the Rexx program for which the handler runs.
    `default void` | `setContextVariableToNil(java.lang.Object slot, java.lang.String variableName)` Allows to set a variable to `.nil` in the Rexx program for which the handler runs.
    `default void` | `setThreadTrace(java.lang.Object slot, boolean state)` Sets the interactive trace state for the current thread.

- - ### Field Detail

    - #### version

          static final java.lang.String version

      Version string indicating version of this class (majorVersion*100+minorVersion concatenated with a dot and the sorted date of last change), e.g. 850.20240620.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### raiseCondition

          default void raiseCondition(java.lang.Object slot,
                                      java.lang.String conditionName,
                                      java.lang.String description,
                                      java.lang.Object[] additional,
                                      java.lang.Object result)

      Raises a condition in the current Rexx thread, pass-through method to the Rexx API, which should be called immediately before returning to Rexx. Cf. the ooRexx documentation in `rexxapi.pdf`, 1.17.148. RaiseCondition.
      Parameters:
        `slot` - opaque argument supplied to the handler methods by the Rexx native code interface
        `conditionName` - Rexx condition name, usually `"ERROR"` or `"FAILURE"`
        `description` - optional String describing the condition
        `additional` - optional additional object
        `result` - optional result object, if routine or method does not trap the condition; may contain the error or failure number

    - #### raiseException

          default void raiseException(java.lang.Object slot,
                                      long definedErrorNumber,
                                      java.lang.Object[] substitutions)

      Raises a Rexx syntax condition of the given error number, call immediately before returning from Java to Rexx. Please note: the value of `definedErrorNumber` has to be calculated as `errorNumber*1000+subcode`. Cf. the ooRexx reference manual (`rexxref.pdf`), "Appendix C. Error Numbers and Messages".
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object
        `definedErrorNumber` - `errorNumber*1000+subcode`
        `substitutions` - an Object array containing substitution values for the error message (if more entries than needed by the secondary message get added, then they can be retrieved by ooRexx using the additional method of the condition object)

    - #### raiseException0

          default void raiseException0(java.lang.Object slot,
                                       long definedErrorNumber)

      Raises a Rexx error without substitution values of the given error number, call immediately before returning from Java. Please note: the value of `definedErrorNumber` has to be calculated as `errorNumber*1000+subcode`. Cf. the ooRexx reference manual (`rexxref.pdf`), "Appendix C. Error Numbers and Messages".
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object
        `definedErrorNumber` - `errorNumber*1000+subcode`

    - #### raiseException1

          default void raiseException1(java.lang.Object slot,
                                       long definedErrorNumber,
                                       java.lang.String substitution1)

      Raises a Rexx error of the given error number, call immediately before returning from Java. Please note: the value of `definedErrorNumber` has to be calculated as `errorNumber*1000+subcode`. Cf. the ooRexx reference manual (`rexxref.pdf`), "Appendix C. Error Numbers and Messages".
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object
        `definedErrorNumber` - `errorNumber*1000+subcode`
        `substitution1` - String used as the first substition value for the error message

    - #### raiseException2

          default void raiseException2(java.lang.Object slot,
                                       long definedErrorNumber,
                                       java.lang.String substitution1,
                                       java.lang.String substitution2)

      Raises a Rexx error of the given error number, call immediately before returning from Java. Please note: the value of `definedErrorNumber` has to be calculated as `errorNumber*1000+subcode`. Cf. the ooRexx reference manual (`rexxref.pdf`), "Appendix C. Error Numbers and Messages".
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object
        `definedErrorNumber` - `errorNumber*1000+subcode`
        `substitution1` - String used as the first substition value for the error message
        `substitution2` - String used as the second substition value for the error message

    - #### getAllContextVariables

          default java.lang.Object getAllContextVariables(java.lang.Object slot)

      Fetches and returns a Rexx directory containing all context variables.
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object
      Returns:
        a `RexxProxy` representing a Rexx directory with the currently defined context variables

    - #### getContextVariable

          default java.lang.Object getContextVariable(java.lang.Object slot,
                                                      java.lang.String variableName)

      Fetches and returns the Rexx variable value in the Rexx program for which the handler runs.
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object
        `variableName` - name of the Rexx variable
      Returns:
        value of the Rexx variable

    - #### setContextVariable

          default void setContextVariable(java.lang.Object slot,
                                          java.lang.String variableName,
                                          java.lang.Object variableValue)

      Allows to set a variable with a value in the Rexx program for which the handler runs.
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object
        `variableName` - name of the Rexx variable
        `variableValue` - the Rexx variable should be set to

    - #### setContextVariableToNil

          default void setContextVariableToNil(java.lang.Object slot,
                                               java.lang.String variableName)

      Allows to set a variable to `.nil` in the Rexx program for which the handler runs.
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object
        `variableName` - name of the Rexx variable

    - #### dropContextVariable

          default void dropContextVariable(java.lang.Object slot,
                                           java.lang.String variableName)

      Drops a Rexx variable from the context.
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object
        `variableName` - name of the Rexx variable

    - #### newArray

          default java.lang.Object newArray(java.lang.Object slot)

      Returns a newly created ooRexx `Array` collection object.
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object
      Returns:
        the newly created ooRexx collection object

    - #### newDirectory

          default java.lang.Object newDirectory(java.lang.Object slot)

      Returns a newly created ooRexx `Directory` collection object.
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object
      Returns:
        the newly created ooRexx collection object

    - #### newStem

          default java.lang.Object newStem(java.lang.Object slot,
                                           java.lang.String stemName)

      Returns a newly created ooRexx `Stem` collection object.
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object
        `stemName` - the stem's base name
      Returns:
        the newly created ooRexx collection object

    - #### newStringTable

          default java.lang.Object newStringTable(java.lang.Object slot)

      Returns a newly created ooRexx `StringTable` collection object.
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object
      Returns:
        the newly created ooRexx collection object

    - #### checkCondition

          default boolean checkCondition(java.lang.Object slot)

      Checks to see if any conditions have resulted from a call to a Rexx API (cf "rexxapi.pdf").
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object
      Returns:
        `true`, if Rexx condition is set, `false` else

    - #### clearCondition

          default void clearCondition(java.lang.Object slot)

      Clears any pending condition status (cf "rexxapi.pdf").
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object

    - #### getConditionInfo

          default java.lang.Object getConditionInfo(java.lang.Object slot)

      Returns a directory object containing the condition information; this is equivalent to calling `condition('O')` from within Rexx code (cf "rexxapi.pdf").
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object
      Returns:
        returns a `RexxProxy` for a Rexx Directory object or `NULL`, if no pending Rexx condition

    - #### getCallerContext

          default java.lang.Object getCallerContext(java.lang.Object slot)

      Returns the Rexx context object `.context` that can be analyzed to learn about the context of the command/exit.
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object
      Returns:
        returns a `RexxProxy` for the Rexx `.context` object

    - #### setThreadTrace

          default void setThreadTrace(java.lang.Object slot,
                                      boolean state)

      Sets the interactive trace state for the current thread.
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object
        `state` - new state for interactive trace

    - #### haltThread

          default void haltThread(java.lang.Object slot)

      Raises a `HALT` condition on the current (Rexx) thread.
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object

    - #### getLocalEnvironment

          default java.lang.Object getLocalEnvironment(java.lang.Object slot)

      Returns a reference to this Rexx interpreter instance `.local` environment directory.
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object
      Returns:
        a `RexxProxy` for the Rexx `.local` object

    - #### getGlobalEnvironment

          default java.lang.Object getGlobalEnvironment(java.lang.Object slot)

      Returns a reference to the Rexx interpreter global `.environment` directory.
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object
      Returns:
        a `RexxProxy` for the Rexx `.environment` object

    - #### getNil

          default java.lang.Object getNil(java.lang.Object slot)

      Returns a reference to the Rexx sentinel value `.nil`.
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object
      Returns:
        a `RexxProxy` referring to the `.nil` object

    - #### getInterpreterVersion

          default long getInterpreterVersion(java.lang.Object slot)

      (Copied from the ooRexx rexxapi.pdf documentation) "Returns the version of the interpreter." "The returned version is encoded in the 3 least significant bytes of the returned value, using 1 byte each for the interpreter version, release, and revision values." "For example, on a 32-bit platform, this value would be `0x00050000` for version 5.0.0."
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object
      Returns:
        the ooRexx interpreter version

    - #### getLanguageLevel

          default long getLanguageLevel(java.lang.Object slot)

      (Copied from the ooRexx rexxapi.pdf documentation) "Returns the language level of the interpreter." "The returned language level is encoded in the 2 least significant bytes of the returned value, using 1 byte each for the interpreter version, release, and revision values. For example, on a 32-bit platform, this value would be `0x00000603` for language level 6.03."
      Parameters:
        `slot` - an opaque Object array as passed to the `RexxExitHandler` or `RexxCommandHandler` object
      Returns:
        the ooRexx language level