com.ibm.bsf.engines.rexx
Class RexxAndJava

java.lang.Object
  |
  +--com.ibm.bsf.engines.rexx.RexxAndJava

class RexxAndJava
extends java.lang.Object

This class manages the calls from Rexx or Object Rexx into Java.

  RexxAndJava.java - this class relays Java and (Object) Rexx
  Copyright (C) 2001 Rony G. Flatscher

  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Lesser General Public
  License as published by the Free Software Foundation; either
  version 2.1 of the License, or (at your option) any later version.

  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public
  License along with this library; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

  The following URL may be available for further information:

     http://www.gnu.org/copyleft/lesser.html

Since:
2001-03-01 by Rony G. Flatscher
Version:
0.9.91, 2001-05-12
Author:
Rony G. Flatscher (University of Essen & WU Wien University), Peter Kalender (Oct 2000 to Feb 2001, University of Essen)

Inner Class Summary
(package private)  class RexxAndJava.ExitDelayed
          Class to exit the JVM, will be executed concurrently, sleeps and then calls System.exit(exit_number).
protected  class RexxAndJava.SyncAddGet
          Inner class to implement a Synchronized ReaderWriter, where a read on an empty Vector blocks the read, until a write occurs (with optional timeout).
 
Field Summary
private static int ADD_EVENT_LISTENER
          Entry point for Rexx calls into Java.
private static int ARRAY_AT
           
private static int ARRAY_LENGTH
           
private static int ARRAY_PUT
           
protected static java.lang.String DLL_NAME
          Defines the name of DLL to be used to resolve the native functions.
protected static java.lang.String EVENT_TEXT
          Defines the string to indicate an 'eventText'.
protected  RexxAndJava.SyncAddGet eventTextList
          Allows Synchronized access to the vector storing the text sent by the eventListeners.
private static int EXIT
           
private static int GET_FIELD_VALUE
           
private static int GET_PROPERTY_VALUE
           
private static int GET_STATIC_VALUE
           
(package private)  com.ibm.bsf.util.type.TypeConvertorRegistry glob_tcr
          To store the default TypeConvertorRegistry, if needed.
private static int INVOKE
           
private static int LOOKUP_BEAN
           
(package private)  com.ibm.bsf.BSFManager mgr
          Stores the BSF manager.
protected static java.lang.String null4Rexx
          Defines the string which represents null, by default ".NIL".
(package private)  java.util.Hashtable orxReferences
          Stores the number of references from Object Rexx to Java objects using beanName as the key.
private static int POLL_EVENT_TEXT
           
private static int POST_EVENT_TEXT
           
private static int REGISTER_BEAN
           
(package private)  com.ibm.bsf.BSFEngine RexxEngine
          Stores the Rexx engine.
private static int SET_FIELD_VALUE
           
private static int SET_PROPERTY_VALUE
           
private static int SET_REXX_NULL_STRING
           
private static java.lang.String STRING_ADD_EVENT_LISTENER
           
private static java.lang.String STRING_ARRAY_AT
           
private static java.lang.String STRING_ARRAY_LENGTH
           
private static java.lang.String STRING_ARRAY_PUT
           
private static java.lang.String STRING_EXIT
           
private static java.lang.String STRING_GET_FIELD_VALUE
           
private static java.lang.String STRING_GET_PROPERTY_VALUE
           
private static java.lang.String STRING_GET_STATIC_VALUE
           
private static java.lang.String STRING_INVOKE
           
private static java.lang.String STRING_LOOKUP_BEAN
           
private static java.lang.String STRING_POLL_EVENT_TEXT
           
private static java.lang.String STRING_POST_EVENT_TEXT
           
private static java.lang.String STRING_REGISTER_BEAN
           
private static java.lang.String STRING_SET_FIELD_VALUE
           
private static java.lang.String STRING_SET_PROPERTY_VALUE
           
private static java.lang.String STRING_SET_REXX_NULL_STRING
           
private static java.lang.String STRING_UNREGISTER_BEAN
           
private static int UNREGISTER_BEAN
           
 
Constructor Summary
(package private) RexxAndJava(com.ibm.bsf.BSFManager mgr, com.ibm.bsf.BSFEngine rengine)
          Constructor to receive and store the BSF manager and the Rexx engine.
 
Method Summary
(package private) static void ()
          Load the DLL, which allows interfacing Java with Rexx or Object Rexx.
private  java.lang.Object convFromRexx(java.lang.String type, java.lang.String value)
          Converts the string from Rexx to the indicated type.
 java.lang.String javaCallBSF(java.lang.String[] args)
           
 long jniRegisterBSF()
          This native method makes sure that the function 'BSF' is registered with Rexx, making it thereby available to all Rexx and Object Rexx programs, called from Java.
 java.lang.String jniRexxStart(java.lang.String script, java.lang.String[] args)
          This native method Calls the Rexx interpreter, having it execute the passed in script with the given array of arguments.
private  java.lang.String makeResultString(java.lang.Object o)
          This method determines what String content to return.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait
 

Field Detail

DLL_NAME

protected static final java.lang.String DLL_NAME
Defines the name of DLL to be used to resolve the native functions.

EVENT_TEXT

protected static final java.lang.String EVENT_TEXT
Defines the string to indicate an 'eventText'.

null4Rexx

protected static java.lang.String null4Rexx
Defines the string which represents null, by default ".NIL". Arguments given by Rexx can in addition be indicated to be null by merely omitting them on the Rexx side.

eventTextList

protected RexxAndJava.SyncAddGet eventTextList
Allows Synchronized access to the vector storing the text sent by the eventListeners.

mgr

com.ibm.bsf.BSFManager mgr
Stores the BSF manager.

RexxEngine

com.ibm.bsf.BSFEngine RexxEngine
Stores the Rexx engine.

orxReferences

java.util.Hashtable orxReferences
Stores the number of references from Object Rexx to Java objects using beanName as the key. This way it becomes possible for the Object Rexx implementation using "BSF.cls" to transparently create Object Rexx proxy objects, if objects are returned from Java method invocations and to transparently unregister them, when the Object Rexx proxy objects are garbage collected.

glob_tcr

com.ibm.bsf.util.type.TypeConvertorRegistry glob_tcr
To store the default TypeConvertorRegistry, if needed.

ADD_EVENT_LISTENER

private static final int ADD_EVENT_LISTENER
Entry point for Rexx calls into Java. This method carries out all the necessary type conversions and finally calls/invokes the indicated Java method.

If a call needs to indicate arguments meant for invoking a Java method, than the following characters must be used for hinting at the type of the argument immediately preceding the respective argument (minimum letters needed are uppercased):

TypeIndicator Following Argument is of Type:
"BOolean" "boolean" i.e. the value 0 (false) or 1 (true)
"BYte" "byte" a byte value
"Char" "char" i.e. a single (UTF8) character
"Double" "double" a double value
"Float" "float" a float value
"Int" "int" an integer value
"Long" "long" a long value
"Object" "Object" an Object which must be registered already
"SHort" "short" a short value
"STring" "String" a string value (UTF8)

Hence, arguments for Java methods therefore must be given in pairs by Rexx: first the type followed by the argument.

The call syntax from Rexx looks like, e.g.:

    call BSF "FunctionName", "argument1", "argument2", "", ...
 or:
    a=BSF("FunctionName", "argument1", "argument2", ...)
 

The following BSF methods are made available to Rexx and can therefore be indicated as the first argument to the 'BSF' call from Rexx:

FunctionName Argument Description
"addEventListener" Adds an event listener to a bean and defines the eventText to be generated. These generated texts can be retrieved with the function pollEventText.
beanName Mandatory, name of a registered bean which should get monitored.
eventSetName Mandatory, name of the set the event belongs to. This name is used to create an event adapter at runtime.
filter Mandatory, name of the actual event which should cause a notification.
eventText Mandatory, text which should be sent by this event listener, each time the event occurs.
"arrayAt" Allows accessing a Java array element, supporting one through five array dimensions.
Returns the Java object at the indicated array element, or null, if no object is stored there.
arrayObject Mandatory, name of a registered arrayObject (received by Java).
idx1 Mandatory, integer indicating the position in dimension 1.
idx2 Mandatory, integer indicating the position in dimension 2.
idx3 Mandatory, integer indicating the position in dimension 3.
idx4 Mandatory, integer indicating the position in dimension 4.
idx5 Mandatory, integer indicating the position in dimension 5.
"arrayLength" Returns the 'lenght' of the arrayObject.
arrayObject Mandatory, name of a registered arrayObject (received by Java).
"arrayPut" Allows to put a new value into a Java array element at the indicated position, supporting one through five array dimensions.
arrayObject Mandatory, name of a registered arrayObject (received by Java).
typeIndicator Type indicator for newValue
newValue The new value to be set at the indicated position in the array.
idx1 Mandatory, integer indicating the position in dimension 1.
idx2 Mandatory, integer indicating the position in dimension 2.
idx3 Mandatory, integer indicating the position in dimension 3.
idx4 Mandatory, integer indicating the position in dimension 4.
idx5 Mandatory, integer indicating the position in dimension 5.
"exit" Terminates the Java Virtual Machine. Allows Rexx to shut down the JVM (and thereby Rexx as well). In order for Rexx being able to shutdown properly itself, the termination of the JVM is delayed by time2wait.
Returns the string "SHUTDOWN, REXX !".
retVal Optional integer return value. If omitted, then "0" will be used as argument for the System.exit(n) call.
time2wait Optional number of milliseconds (msecs) to wait until the JVM will be terminated. This allows Rexx to shutdown (clean up) its side as well. Default value, if omitted: 100, i.e. 100 msecs, i.e. 1/10th second.
"getFieldValue" Looks up a public field of the registered object.
Returns the value of the field.
beanName Mandatory, name of the object to be looked up.
fieldName Mandatory, name of the public field of the object.
"getPropertyValue" (untested!) Looks up a property of the registered Java Bean object.
Returns the value of the property.
beanName Mandatory, name of the Java Bean object to be looked up.
propertyName Mandatory, name of the Java Bean property.
index Mandatory, null, if Java Bean property is not indexed, a valid integer number else.
"getStaticValue" Looks up a public static field of the given class or interface. This function does not instantiate the class (would not be possible for abstract classes or interfaces).
Returns the value of the public static field.
className Mandatory, name of the class, abstract class or interface to be looked up.
fieldName Mandatory, name of the public static field of the object.
"invoke" Invokes (calls) the method with the given arguments on the bean.
Returns the result of the method invocation or null.
beanName Mandatory, name of a registered bean on which the method (function) should get invoked.
methodName Mandatory, name of the method which should get invoked.
typeIndicator Type indicator for argument #1 (if given).
arg The argument #1 itself (if given).
Any additional arguments must be given in pairs of "argType" and "arg" as well.
"lookupBean" Looks up an object in the BSF manager object registry. (Allows for retrieving pre-declared beans as well.)
Returns the object or null, if not found.
beanName Mandatory, name of the object to be looked up. Returns the object rendered to a string or null, if not found.
"pollEventText" Polls for the eventText defined in the above function "addEventListener", placed into a queue by the appropriate event listeners. If no timeout value is supplied, "0" will be used, which blocks the return of this function (forever) until some text is available for return.
Returns available eventText, or if a timeout occurred while waiting null.
timeOut Optional, timeout in milliseconds, i.e. time to wait for an eventText to appear, before returning.
"postEventText" Adds eventText to the eventText vector (list), can be retrieved via pollEventText.
Returns the received eventText
eventText Mandatory, text which should be put into the eventText vector.
priority Optional, priority level of eventText, can be one of:

  • "2": high ('alarm level') priority.
  • "1": normal (default) priority, and
  • "0": low ('batch level') priority,
"registerBean" Creates a new object (instantiating the given Java class with the given arguments) and registers it using the given beanName.
Returns beanName (always use this returned beanName for looking up the object in the registry).
beanName Name of the object to be created and registered. if no name is given (empty string or null) then a unique one will be created and returned; the code to create the unique name is the same as the documented "Object.hashCode()":
o.getClass().getName() + "@" + Integer.toHexString(o.hashCode()).
beanType Mandatory, type (Java class name) of the bean (Java object) to be created and registered.
typeIndicator Type indicator for the optional argument.
arg The optional argument itself.
Any additional arguments must be given in pairs of "argType" and "arg" as well.
"setFieldValue" Looks up a public field of the registered object.
Returns the new value of the field.
beanName Mandatory, name of the object to be looked up.
fieldName Mandatory, name of the public field of the object.
typeIndicator Type indicator for the immediately following argument (newValue).
newValue The new value the field gets set to.
"setPropertyValue" (untested!) Looks up a property of the registered Java Bean object.
Returns the new value of the property.
beanName Mandatory, name of the Java Bean object to be looked up.
propertyName Mandatory, name of the Java Bean property.
index Mandatory, null, if Java Bean property is not indexed, a valid integer number else.
typeIndicator Type indicator for the immediately following argument (newValue).
newValue The new value the property gets set to.
"setRexxNullString" Sets the field null4Rexx to the string which serves as the representation for null.
  • The Java side will return this value to Rexx to indicate a Java null ("no value"). This conversion is done in method makeResultString(Object o).
  • The Rexx side can use this string for an argument for which no value is supplied. This option is available in addition to the standard Rexx option of just leaving the missing argument empty. The conversion of Rexx arguments to Java is done in convFromRexx(String type, String value).
newString Mandatory, the new string to be used to indicate a Java null.
"unregisterBean" Unregisters an object from the BSF manager's object registry.
Returns the former beanName of the just unregistered object.
beanName Mandatory, name of bean (Java object) to be unregistered.


ARRAY_AT

private static final int ARRAY_AT

ARRAY_LENGTH

private static final int ARRAY_LENGTH

ARRAY_PUT

private static final int ARRAY_PUT

EXIT

private static final int EXIT

GET_FIELD_VALUE

private static final int GET_FIELD_VALUE

GET_PROPERTY_VALUE

private static final int GET_PROPERTY_VALUE

GET_STATIC_VALUE

private static final int GET_STATIC_VALUE

INVOKE

private static final int INVOKE

LOOKUP_BEAN

private static final int LOOKUP_BEAN

POLL_EVENT_TEXT

private static final int POLL_EVENT_TEXT

POST_EVENT_TEXT

private static final int POST_EVENT_TEXT

REGISTER_BEAN

private static final int REGISTER_BEAN

SET_FIELD_VALUE

private static final int SET_FIELD_VALUE

SET_PROPERTY_VALUE

private static final int SET_PROPERTY_VALUE

SET_REXX_NULL_STRING

private static final int SET_REXX_NULL_STRING

UNREGISTER_BEAN

private static final int UNREGISTER_BEAN

STRING_ADD_EVENT_LISTENER

private static final java.lang.String STRING_ADD_EVENT_LISTENER

STRING_ARRAY_AT

private static final java.lang.String STRING_ARRAY_AT

STRING_ARRAY_LENGTH

private static final java.lang.String STRING_ARRAY_LENGTH

STRING_ARRAY_PUT

private static final java.lang.String STRING_ARRAY_PUT

STRING_EXIT

private static final java.lang.String STRING_EXIT

STRING_GET_FIELD_VALUE

private static final java.lang.String STRING_GET_FIELD_VALUE

STRING_GET_PROPERTY_VALUE

private static final java.lang.String STRING_GET_PROPERTY_VALUE

STRING_GET_STATIC_VALUE

private static final java.lang.String STRING_GET_STATIC_VALUE

STRING_INVOKE

private static final java.lang.String STRING_INVOKE

STRING_LOOKUP_BEAN

private static final java.lang.String STRING_LOOKUP_BEAN

STRING_POLL_EVENT_TEXT

private static final java.lang.String STRING_POLL_EVENT_TEXT

STRING_POST_EVENT_TEXT

private static final java.lang.String STRING_POST_EVENT_TEXT

STRING_REGISTER_BEAN

private static final java.lang.String STRING_REGISTER_BEAN

STRING_SET_FIELD_VALUE

private static final java.lang.String STRING_SET_FIELD_VALUE

STRING_SET_PROPERTY_VALUE

private static final java.lang.String STRING_SET_PROPERTY_VALUE

STRING_SET_REXX_NULL_STRING

private static final java.lang.String STRING_SET_REXX_NULL_STRING

STRING_UNREGISTER_BEAN

private static final java.lang.String STRING_UNREGISTER_BEAN
Constructor Detail

RexxAndJava

RexxAndJava(com.ibm.bsf.BSFManager mgr,
            com.ibm.bsf.BSFEngine rengine)
Constructor to receive and store the BSF manager and the Rexx engine.
Method Detail

static void ()
Load the DLL, which allows interfacing Java with Rexx or Object Rexx.

jniRegisterBSF

public long jniRegisterBSF()
This native method makes sure that the function 'BSF' is registered with Rexx, making it thereby available to all Rexx and Object Rexx programs, called from Java.

jniRexxStart

public java.lang.String jniRexxStart(java.lang.String script,
                                     java.lang.String[] args)
This native method Calls the Rexx interpreter, having it execute the passed in script with the given array of arguments.
Parameters:
script - a String consisting of Rexx statements separated by by line-end characters (';' or CR-LF).
args - an array of Strings representing the arguments or null, if no arguments are available.
Returns:
a String containing the result or null, if no result is returned or the Rexx interpreter stopped execution due to a runtime error.

javaCallBSF

public java.lang.String javaCallBSF(java.lang.String[] args)
                             throws com.ibm.bsf.BSFException

convFromRexx

private java.lang.Object convFromRexx(java.lang.String type,
                                      java.lang.String value)
                               throws com.ibm.bsf.BSFException
Converts the string from Rexx to the indicated type. If a type 'O' is indicated and the value for it is an empty string, then null is returned for it.
Parameters:
type - one of "BOolean" (i.e. '0' or '1'), "BYte", "Char", "Double", "Float", "Int", "Long", "Object" (Object, i.e. a registered bean), "SHort", and "STring".
value - the value from Rexx (a string) to be converted to the Java type.
Returns:
the converted value.

makeResultString

private java.lang.String makeResultString(java.lang.Object o)
This method determines what String content to return.
Parameters:
o - the object which should get returned as a string to Rexx.
Returns:
a String rendering of the primitive types and String. Otherwise create a unique bean name, register the object under it and return the bean name. If null, then the string of null4Rexx is returned to Rexx.