20120618, rgf

org.rexxla.bsf.engines.rexx
Class RexxHandler

java.lang.Object
  extended by org.rexxla.bsf.engines.rexx.RexxHandler

public abstract class RexxHandler
extends java.lang.Object

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 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-24
Version:
1.0
Author:
Rony G. Flatscher

Field Summary
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
RexxHandler()
           
 
Method Summary
static boolean checkCondition(java.lang.Object slot)
          Checks to see if any conditions have resulted from a call to a Rexx API (cf "rexxpg.pdf").
static void clearCondition(java.lang.Object slot)
          Clears any pending condition status (cf "rexxpg.pdf").
static void dropContextVariable(java.lang.Object slot, java.lang.String variableName)
          Drops a Rexx variable from the context.
static java.lang.Object getAllContextVariables(java.lang.Object slot)
          Fetches and returns a Rexx directory containing all context variables.
static 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.
static 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 "rexxpg.pdf").
static 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.
static java.lang.Object getGlobalEnvironment(java.lang.Object slot)
          Returns a reference to the Rexx interpreter global .environment directory.
static long getInterpreterVersion(java.lang.Object slot)
          (Copied from the ooRexx rexxpg.pdf documentation) "Returns the version of the interpreter.
static long getLanguageLevel(java.lang.Object slot)
          (Copied from the ooRexx rexxpg.pdf documentation) "Returns the language level of the interpreter.
static java.lang.Object getLocalEnvironment(java.lang.Object slot)
          Returns a reference to this Rexx interpreter instance .local environment directory.
static java.lang.Object getNil(java.lang.Object slot)
          Returns a reference to the Rexx sentinel value .nil.
static void haltThread(java.lang.Object slot)
          Raises a HALT condition on the current (Rexx) thread.
static 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.
static void raiseException(java.lang.Object slot, long definedErrorNumber, java.lang.Object[] substitutions)
          Raises a Rexx error of the given error number, call immediately before returning from Java.
static 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.
static 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.
static 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.
static 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.
static 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.
static void setThreadTrace(java.lang.Object slot, boolean state)
          Sets the interactive trace state for the current thread.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, 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
Constructor Detail

RexxHandler

public RexxHandler()
Method Detail

raiseCondition

public static 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 4.1 documentation in rexxpg.pdf, 9.14.126. 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

public static void raiseException(java.lang.Object slot,
                                  long definedErrorNumber,
                                  java.lang.Object[] substitutions)
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
substitutions - an Object array containing substitution values for the error message (if more entries get added, then they can be retrieved by ooRexx using the additional method of the condition object)

raiseException0

public static 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

public static 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

public static 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

public static 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 @{link RexxProxy} representing a Rexx directory with the currently defined context variables

getContextVariable

public static 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

public static 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

public static 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

public static 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

checkCondition

public static boolean checkCondition(java.lang.Object slot)
Checks to see if any conditions have resulted from a call to a Rexx API (cf "rexxpg.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

public static void clearCondition(java.lang.Object slot)
Clears any pending condition status (cf "rexxpg.pdf").

Parameters:
slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object

getConditionInfo

public static 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 "rexxpg.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

public static 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

public static 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

public static 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

public static 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

public static 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

public static 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

public static long getInterpreterVersion(java.lang.Object slot)
(Copied from the ooRexx rexxpg.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 0x00040000 for version 4.0.0."

Parameters:
slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
Returns:
the ooRexx interpreter version

getLanguageLevel

public static long getLanguageLevel(java.lang.Object slot)
(Copied from the ooRexx rexxpg.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

20120618, rgf