org.rexxla.bsf.engines.rexx

## Class RexxConfiguration

- java.lang.Object
- - org.rexxla.bsf.engines.rexx.RexxConfiguration

-     public class RexxConfiguration
      extends java.lang.Object

  This class allows to configure a Rexx interpreter instance, before it gets created employing `RexxAndJava.createRexxInterpreterInstance(RexxConfiguration rc)`. Cf. ooRexx' `rexxpg.pdf` documentation for the Rexx interpreter creation options. All final static fields that use ooRexx names also use the ooRexx constant values from `rexxapidefs.h` and `oorexxapi.h`.

      ------------------------ Apache Version 2.0 license -------------------------
          Copyright (C) 2012-2022 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-20
  Version:
    850
  Author:
    Rony G. Flatscher

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.lang.String` | `initial_address_environment` If set, determines the name of the default Rexx address environment.
    `protected boolean` | `modifiable` If flag is false, then the configuration cannot be changed anymore.
    `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.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RexxConfiguration()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addCommandHandler(java.lang.String name, RexxCommandHandler commandHandler)` Allows to define an environment name and a `RexxCommandHandler` to serve the given environment.
    `void` | `addExitHandler(int function, RexxExitHandler exitHandler)` Allows to define a `RexxExitHandler` to serve the given Rexx exit.
    `void` | `addRequiredLibrary(java.lang.String libraryName)` Allows to add a required native (implemented in C++) library that should be loaded when the Rexx interpreter instance gets created.
    `java.lang.Object[]` | `getAllCommandHandlers()` Returns an array with two elements, where the first element is a String array denoting the command environment name and the second element is an array of type RexxCommandHandler and RexxDirectingCommandHandler with the matching Java command handler object.
    `java.lang.Object[]` | `getArguments4JNI()` Returns an array of type Object that contains the following options: index `0`: `INITIAL_ADDRESS_ENVIRONMENT` (null or String) index `1`: `EXTERNAL_CALL_PATH` (null or String) index `2`: `EXTERNAL_CALL_EXTENSIONS` (null or String) index `3`: `LOAD_REQUIRED_LIBRARY` (null or String[]) index `4`: `DIRECT_EXITS` (null or Object[]={int[],RexxExitHandler[]}) index `5`: `DIRECT_ENVIRONMENTS` (null or Object[]={String[],RexxCommandHandler[]})
    `RexxCommandHandler` | `getCommandHandler(java.lang.String name)` Returns the `RexxCommandHandler` object associated with the supplied command `name` or `null`, if none found.
    `java.lang.String[]` | `getCommandHandlerNames4JNI()` Returns a String array denoting the environment names defined at the moment that are backed by a Java implemented non redirectable RexxCommandHandler.
    `java.lang.Object[]` | `getCommandHandlers_ori()` Returns an array with two elements, where the first element is a String array denoting the command environment name and the second element is an array of type RexxCommandHandler with the matching Java command handler object.
    `java.lang.Object[]` | `getCommandHandlers()` Returns an array with two elements, where the first element is a String array denoting the command environment name and the second element is an array of type RexxCommandHandler with the matching Java command handler object.
    `java.lang.String[]` | `getCommandHandlersAsStringArray()` Returns a String array where the first word represents the environment followed by a blank and the command handler's String representation.
    `java.util.BitSet` | `getDefinedExits()` Returns a cloned BitSet object indicating which Rexx exits got defined to be handled.
    `RexxExitHandler` | `getExitHandler(int function)`
    `java.lang.Object[]` | `getExitHandlers()` Returns an array with two elements, where the first element is an int array of exit numbers and the second element is an array of RexxExitHandler with the matching Java exit handler object (or `null`, if not yet handled by the Java side).
    `int[]` | `getExitHandlers4JNI()` Returns an an int array of exit numbers for which Java exit handlers got defined.
    `java.lang.String` | `getExternalCallExtensions()` Returns the current value of the externalCallExtensions field.
    `java.lang.String` | `getExternalCallPath()` Returns the current value of the externalCallPath field.
    `java.lang.String` | `getInitialAddressEnvironment()` Returns the default address environment or `null`, if none set.
    `java.lang.String[]` | `getRedirectingCommandHandlerNames4JNI()` Returns a String array denoting the environment names defined at the moment that are backed by a Java implemented RexxRedirectableCommandHandler.
    `java.lang.Object[]` | `getRedirectingCommandHandlers()` Returns an array with two elements, where the first element is a String array denoting the command environment name and the second element is an array of type RexxRedirectingCommandHandler with the matching Java command handler object.
    `java.lang.String[]` | `getRequiredLibraries()` Returns an array of native library names.
    `java.lang.String[]` | `getRequiredLibraries4JNI()` Returns an array of native library names or `null`, if none were defined.
    `boolean` | `isModifiable()` Access method for field `modifiable`
    `RexxCommandHandler` | `setCommandHandler(java.lang.String name, RexxCommandHandler commandHandler)` Allows to replace a defined `RexxCommandHandler` with a new one.
    `RexxExitHandler` | `setExitHandler(int function, RexxExitHandler exitHandler)` Allows to replace a defined `RexxExitHandler` with a new one or to remove it.
    `void` | `setExternalCallExtensions(java.lang.String externalCallExtensions)` Allows to set additional directories for Rexx to lookup.
    `void` | `setExternalCallPath(java.lang.String externalCallPath)` Allows to set additional directories for Rexx to lookup called Rexx programs.
    `void` | `setInitialAddressEnvironment(java.lang.String name)` Allows to set the default Rexx address environment.
    `java.lang.String` | `toString()` Returns a String representation of the configuration.

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

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

- - ### Field Detail

    - #### version

          public 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.
      See Also:
        Constant Field Values

    - #### initial_address_environment

          protected java.lang.String initial_address_environment

      If set, determines the name of the default Rexx address environment.

    - #### modifiable

          protected boolean modifiable

      If flag is false, then the configuration cannot be changed anymore. It is possible however, to nullify handler objects, by using the respective methods native-code TODO: setExitHandler(), native-code TODO: setCommandHandler().

  - ### Constructor Detail

    - #### RexxConfiguration

          public RexxConfiguration()

  - ### Method Detail

    - #### setExternalCallPath

          public void setExternalCallPath(java.lang.String externalCallPath)
                                   throws org.apache.bsf.BSFException

      Allows to set additional directories for Rexx to lookup called Rexx programs. Please note: on Windows the delimiter character is a semicolon (;), on Unix the colon (:). `null` resets the external call path.
      Throws:
        `org.apache.bsf.BSFException`

    - #### getExternalCallPath

          public java.lang.String getExternalCallPath()

      Returns the current value of the externalCallPath field.
      Returns:
        the current value of the externalCallPath field

    - #### setExternalCallExtensions

          public void setExternalCallExtensions(java.lang.String externalCallExtensions)
                                         throws org.apache.bsf.BSFException

      Allows to set additional directories for Rexx to lookup. This field is preset to `".rxj,.rxo,.rxjo,.jrexx"`. `null` resets the external call extension.
      Throws:
        `org.apache.bsf.BSFException`

    - #### getExternalCallExtensions

          public java.lang.String getExternalCallExtensions()

      Returns the current value of the externalCallExtensions field.
      Returns:
        the current value of the externalCallExtensions field

    - #### addRequiredLibrary

          public void addRequiredLibrary(java.lang.String libraryName)
                                  throws org.apache.bsf.BSFException

      Allows to add a required native (implemented in C++) library that should be loaded when the Rexx interpreter instance gets created.
      Parameters:
        `libraryName` - the name of the native required library as used in an ooRexx "::REQUIRES" directive
      Throws:
        `org.apache.bsf.BSFException`

    - #### getRequiredLibraries

          public java.lang.String[] getRequiredLibraries()

      Returns an array of native library names.
      Returns:
        array of type String containing all required native library names that should get loaded with the creation of the Rexx interpreter instance

    - #### getRequiredLibraries4JNI

          public java.lang.String[] getRequiredLibraries4JNI()

      Returns an array of native library names or `null`, if none were defined.
      Returns:
        array of type String containing all required native library names that should get loaded with the creation of the Rexx interpreter instance or `null`, if none defined

    - #### getExitHandlers

          public java.lang.Object[] getExitHandlers()

      Returns an array with two elements, where the first element is an int array of exit numbers and the second element is an array of RexxExitHandler with the matching Java exit handler object (or `null`, if not yet handled by the Java side).
      Returns:
        array of Object where at index `[0]` an `int[]` and at index `[1]` a `RexxExitHandler[]` array object gets returned

    - #### getExitHandlers4JNI

          public int[] getExitHandlers4JNI()

      Returns an an int array of exit numbers for which Java exit handlers got defined. If no exit handlers got defined, then `null` gets returned.
      Returns:
        int array containing the exit numbers or null, if no exit handlers should be defined

    - #### getDefinedExits

          public java.util.BitSet getDefinedExits()

      Returns a cloned BitSet object indicating which Rexx exits got defined to be handled.
      Returns:
        a cloned BitSet object

    - #### getCommandHandlers_ori

          public java.lang.Object[] getCommandHandlers_ori()

      Returns an array with two elements, where the first element is a String array denoting the command environment name and the second element is an array of type RexxCommandHandler with the matching Java command handler object.
      Returns:
        array of Object where at index `[0]` a `String[]` and at index `[1]` a `RexxCommandHandler[]` array object gets returned

    - #### getAllCommandHandlers

          public java.lang.Object[] getAllCommandHandlers()

      Returns an array with two elements, where the first element is a String array denoting the command environment name and the second element is an array of type RexxCommandHandler and RexxDirectingCommandHandler with the matching Java command handler object.
      Returns:
        array of Object where at index `[0]` a `String[]` and at index `[1]` a `RexxCommandHandler[]` array object gets returned

    - #### getCommandHandlersAsStringArray

          public java.lang.String[] getCommandHandlersAsStringArray()

      Returns a String array where the first word represents the environment followed by a blank and the command handler's String representation.
      Returns:
        String array

    - #### getCommandHandlers

          public java.lang.Object[] getCommandHandlers()

      Returns an array with two elements, where the first element is a String array denoting the command environment name and the second element is an array of type RexxCommandHandler with the matching Java command handler object.
      Returns:
        array of Object where at index `[0]` a `String[]` and at index `[1]` a `RexxCommandHandler[]` array object gets returned

    - #### getRedirectingCommandHandlers

          public java.lang.Object[] getRedirectingCommandHandlers()

      Returns an array with two elements, where the first element is a String array denoting the command environment name and the second element is an array of type RexxRedirectingCommandHandler with the matching Java command handler object.
      Returns:
        array of Object where at index `[0]` a `String[]` and at index `[1]` a `RexxCommandHandler[]` array object gets returned
      Since:
        8.50 (2022-08-19)

    - #### getCommandHandlerNames4JNI

          public java.lang.String[] getCommandHandlerNames4JNI()

      Returns a String array denoting the environment names defined at the moment that are backed by a Java implemented non redirectable RexxCommandHandler. If no such command handlers got defined, then `null` gets returned.
      Returns:
        a String array of the environment names or `null` if no non redirectable RexxCommandHandlers got defined

    - #### getRedirectingCommandHandlerNames4JNI

          public java.lang.String[] getRedirectingCommandHandlerNames4JNI()

      Returns a String array denoting the environment names defined at the moment that are backed by a Java implemented RexxRedirectableCommandHandler. If no such command handlers got defined, then `null` gets returned.
      Returns:
        a String array of the environment names or `null` if no RexxRedirectableCommandHandlers got defined

    - #### setInitialAddressEnvironment

          public void setInitialAddressEnvironment(java.lang.String name)
                                            throws org.apache.bsf.BSFException

      Allows to set the default Rexx address environment. `null` resets the external call path.
      Parameters:
        `name` - the name of the environment that Rexx should address by default, if `null`, then Rexx' default address environment (`CMD`) is used
      Throws:
        `org.apache.bsf.BSFException`

    - #### getInitialAddressEnvironment

          public java.lang.String getInitialAddressEnvironment()

      Returns the default address environment or `null`, if none set.
      Returns:
        the default address environment or `null`, if none set

    - #### isModifiable

          public boolean isModifiable()

      Access method for field `modifiable`
      Returns:
        current setting of field `modifiable`

    - #### addExitHandler

          public void addExitHandler(int function,
                                     RexxExitHandler exitHandler)
                              throws org.apache.bsf.BSFException

      Allows to define a `RexxExitHandler` to serve the given Rexx exit. The `RexxExitHandler` object may be null, which causes the Rexx exit handling to be switched on for this Rexx interpreter instance; in this case it becomes possible at runtime to change to a RexxExitHandler object using `setExitHandler(int function, RexxExitHandler exitHandler)`.
      Parameters:
        `function` - the Rexx exit function number
        `exitHandler` - a `RexxExitHandler` object
      Throws:
        `org.apache.bsf.BSFException`

    - #### setExitHandler

          public RexxExitHandler setExitHandler(int function,
                                                RexxExitHandler exitHandler)
                                         throws org.apache.bsf.BSFException

      Allows to replace a defined `RexxExitHandler` with a new one or to remove it.
      Parameters:
        `function` - the Rexx exit function number
        `exitHandler` - a RexxExitHandler object or `null`, if the exit should not be served anymore
      Throws:
        `org.apache.bsf.BSFException`

    - #### getExitHandler

          public RexxExitHandler getExitHandler(int function)

    - #### addCommandHandler

          public void addCommandHandler(java.lang.String name,
                                        RexxCommandHandler commandHandler)
                                 throws org.apache.bsf.BSFException

      Allows to define an environment name and a `RexxCommandHandler` to serve the given environment.
      Parameters:
        `name` - the Rexx environment name
        `commandHandler` - a RexxCommandHandler object
      Throws:
        `org.apache.bsf.BSFException`

    - #### setCommandHandler

          public RexxCommandHandler setCommandHandler(java.lang.String name,
                                                      RexxCommandHandler commandHandler)
                                               throws org.apache.bsf.BSFException

      Allows to replace a defined `RexxCommandHandler` with a new one.
      Parameters:
        `name` - the Rexx environment name
        `commandHandler` - a RexxCommandHandler object
      Returns:
        the previous stored RexxCommandHandler object
      Throws:
        `org.apache.bsf.BSFException`

    - #### getCommandHandler

          public RexxCommandHandler getCommandHandler(java.lang.String name)

      Returns the `RexxCommandHandler` object associated with the supplied command `name` or `null`, if none found. This will be used from native code as well.
      Parameters:
        `name` - a String denoting the name of the command environment
      Returns:
        the `RexxCommandHandler` object or `null` if none found

    - #### getArguments4JNI

          public java.lang.Object[] getArguments4JNI()

      Returns an array of type Object that contains the following options:
      - index `0`: `INITIAL_ADDRESS_ENVIRONMENT` (null or String)
      - index `1`: `EXTERNAL_CALL_PATH` (null or String)
      - index `2`: `EXTERNAL_CALL_EXTENSIONS` (null or String)
      - index `3`: `LOAD_REQUIRED_LIBRARY` (null or String[])
      - index `4`: `DIRECT_EXITS` (null or Object[]={int[],RexxExitHandler[]})
      - index `5`: `DIRECT_ENVIRONMENTS` (null or Object[]={String[],RexxCommandHandler[]})

    - #### toString

          public java.lang.String toString()

      Returns a String representation of the configuration.
      Overrides:
        `toString` in class `java.lang.Object`