20120618, rgf

org.rexxla.bsf.engines.rexx
Class RexxConfiguration

java.lang.Object
  extended by 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 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:
2012-02-04
Version:
0.01
Author:
Rony G. Flatscher

Field Summary
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
RexxConfiguration()
           
 
Method Summary
 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[] 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 an array with two elements, where the first element is a String array denoting the 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 environment name and the second element is an array of type RexxCommandHandler with the matching Java command handler object.
 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[] 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

public java.lang.Object[] getCommandHandlers()
Returns an array with two elements, where the first element is a String array denoting the 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] an int[] and at index [1] a RexxCommandHandler[] array object gets returned

getCommandHandlerNames4JNI

public java.lang.String[] getCommandHandlerNames4JNI()
Returns an array with two elements, where the first element is a String array denoting the environment name and the second element is an array of type RexxCommandHandler with the matching Java command handler object. If no command handlers got defined, then null gets returned.

Returns:
a String array of the environment names or null if no RexxCommandHandlers 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:


toString

public java.lang.String toString()
Returns a String representation of the configuration.

Overrides:
toString in class java.lang.Object

20120618, rgf