20110531, rgf

org.rexxla.bsf.engines.rexx
Class RexxEngine

java.lang.Object
  extended by org.apache.bsf.util.BSFEngineImpl
      extended by org.rexxla.bsf.engines.rexx.RexxEngine
All Implemented Interfaces:
java.beans.PropertyChangeListener, java.util.EventListener, org.apache.bsf.BSFEngine

public class RexxEngine
extends org.apache.bsf.util.BSFEngineImpl

This class manages the calls from Java via JNI to Rexx or Object Rexx using the RexxSAA interface.

------------------------ Apache Version 2.0 license -------------------------
    Copyright (C) 2001-2009 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.
 ----------------------------------------------------------------------------- 

Version:
4.0.0, 20090827
Author:
Rony G. Flatscher (WU-Wien/Wirtschaftsuniversität Wien, http://www.wu-wien.ac.at/english)

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.
 
Fields inherited from class org.apache.bsf.util.BSFEngineImpl
classLoader, classPath, declaredBeans, lang, mgr, tempDir
 
Constructor Summary
RexxEngine()
           
 
Method Summary
 java.lang.Object apply(java.lang.String source, int lineNo, int columnNo, java.lang.Object oscript, java.util.Vector vArgNames, java.util.Vector vArgs)
          Applies (evaluates) a piece of Rexx code (can be a whole program as well) with Java-supplied arguments and returns the result.
 java.lang.Object call(java.lang.Object object, java.lang.String name, java.lang.Object[] args)
          Calls (executes) a Rexx program which code has been supplied before via an invocation of "apply()", "exec()" or "eval()" with the Java-supplied arguments and returns the result.
 java.lang.Object call(RexxProxy proxy, java.lang.reflect.Method methodObject, java.lang.Object[] args)
          Allows forwarding a messages to a RexxProxy using the method name of the supplied methodObject object with the supplied arguments, if any.
 java.lang.Object call(RexxProxy proxy, java.lang.Object javaObject, java.lang.String methodName, java.lang.String methodDescriptor, java.lang.Object[] args)
          Allows forwarding a messages to a RexxProxy using the supplied methodName the supplied arguments, if any.
 void declareBean(org.apache.bsf.BSFDeclaredBean bean)
          Method implemented in order to avoid an exeption to be thrown by the default implementation.
 java.lang.Object eval(java.lang.String source, int lineNo, int columnNo, java.lang.Object oscript)
          Evaluates (executes) a piece of Rexx code (can be a whole program as well) without any Java-supplied arguments and returns the result.
 java.lang.String get_rii_ID()
          Getter method.
 RexxAndJava getRexxInterface()
          Returns the RexxAndJava instance that is used for interfacing with Rexx.
 void halt()
          Halt (raise the HALT condition) all Rexx threads of this engine's peer Rexx interperter instance (using the new ooRExx 4.0 APIs).
 int halt(java.lang.String tid)
          Allow halting an individual Rexx thread (raising the HALT condition) having the given thread ID.
 void initialize(org.apache.bsf.BSFManager mgr, java.lang.String lang, java.util.Vector declaredBeans)
          Initializes the Rexx engine and causes the external functions 'BSF' and 'BSFPollEvents' to be registered with the Rexx interpreter.
protected  void set_rii_ID(java.lang.String rii_ID)
          Setter method.
 void terminate()
          Waits until all Rexx threads of this engine's Rexx interpreter instance peer have terminated (using the new ooRExx 4.0 APIs); this method must be called from the same thread that created the Rexx interpreter instance (i.e. the thread that created this instance of the RexxEngine).
 void undeclareBean(org.apache.bsf.BSFDeclaredBean bean)
          Method implemented in order to avoid an exeption to be thrown by the default implementation.
 
Methods inherited from class org.apache.bsf.util.BSFEngineImpl
compileApply, compileExpr, compileScript, exec, iexec, propertyChange
 
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

RexxEngine

public RexxEngine()
Method Detail

get_rii_ID

public java.lang.String get_rii_ID()
Getter method.

Returns:
the RexxInterpreter instance ID

set_rii_ID

protected void set_rii_ID(java.lang.String rii_ID)
Setter method. Only meant to be used by Java4Rexx.java.


getRexxInterface

public RexxAndJava getRexxInterface()
Returns the RexxAndJava instance that is used for interfacing with Rexx.


initialize

public void initialize(org.apache.bsf.BSFManager mgr,
                       java.lang.String lang,
                       java.util.Vector declaredBeans)
                throws org.apache.bsf.BSFException
Initializes the Rexx engine and causes the external functions 'BSF' and 'BSFPollEvents' to be registered with the Rexx interpreter. Therefore Rexx programs invoked from Java have these two functions available to them and are therefore able to communicate with Java.

Specified by:
initialize in interface org.apache.bsf.BSFEngine
Overrides:
initialize in class org.apache.bsf.util.BSFEngineImpl
Throws:
org.apache.bsf.BSFException

eval

public java.lang.Object eval(java.lang.String source,
                             int lineNo,
                             int columnNo,
                             java.lang.Object oscript)
                      throws org.apache.bsf.BSFException
Evaluates (executes) a piece of Rexx code (can be a whole program as well) without any Java-supplied arguments and returns the result.

Parameters:
source - if set to RexxAndJava.EVENT_TEXT, then oscript is put into the event queue to be polled by Rexx. If this text starts with the string "/*2*/" it is put into the alarm (highest dispatch) level vector, if it starts with the string "/*0*/" it is put into the batch (lowest dispatch) level vector, else it is put into the normal level vector.
lineNo - not used.
columnNo - not used.
oscript - the String version of this object [using toString()] represents the Rexx code to be executed. Its statements are delimited with a ';' or a CR (carriage-return) and/or LF (line-feed).
Returns:
a String object with the result from Rexx or null.
Throws:
org.apache.bsf.BSFException

call

public java.lang.Object call(java.lang.Object object,
                             java.lang.String name,
                             java.lang.Object[] args)
                      throws org.apache.bsf.BSFException
Calls (executes) a Rexx program which code has been supplied before via an invocation of "apply()", "exec()" or "eval()" with the Java-supplied arguments and returns the result.

[Hint: This follows after learning how Xalan is employing BSF: it first calls "exec()" and then "call()", hence "call()" does not receive the source to be executed.]

As of 2009-05-17 using the new ooRexx 4.0 APIs the following fundamental change has been implemented: if the argument object is an instance of RexxProxy, then a callback on the RexxProxy object is carried out, using method as the ooRexx message name, supplying arguments, if any. Otherwise, the original behaviour takes place.

Note: if the RexxProxy's userDataID field is not set (i.e. null), then no slot argument will be supplied as the last argument to the Rexx method.

Parameters:
object - if an instance of RexxProxy, then a callback is carried out
name - if given, name of the message to send to the ooRexx object
args - arguments to be passed to Rexx, if any
Returns:
a String object with the result from Rexx or null.
Throws:
org.apache.bsf.BSFException

call

public java.lang.Object call(RexxProxy proxy,
                             java.lang.reflect.Method methodObject,
                             java.lang.Object[] args)
                      throws org.apache.bsf.BSFException
Allows forwarding a messages to a RexxProxy using the method name of the supplied methodObject object with the supplied arguments, if any. This method will be mostlikely invoked employing a Proxy object.

As of 2009-05-17 using the new ooRexx 4.0 APIs the following fundamental change has been implemented: if the argument object is an instance of RexxProxy, then a callback on the RexxProxy object is carried out, using method as the ooRexx message name, supplying arguments, if any. Otherwise, the original behaviour takes place.

Parameters:
proxy - a RexxProxy to which the callback is to be carried out
methodObject - the java.lang.reflect.Method object that is supposed to be invoked originally
args - arguments to be passed to Rexx, if any
Returns:
a String object with the result from Rexx or null.
Throws:
org.apache.bsf.BSFException

call

public java.lang.Object call(RexxProxy proxy,
                             java.lang.Object javaObject,
                             java.lang.String methodName,
                             java.lang.String methodDescriptor,
                             java.lang.Object[] args)
                      throws org.apache.bsf.BSFException
Allows forwarding a messages to a RexxProxy using the supplied methodName the supplied arguments, if any. This method will be mostlikely invoked employing a RexxProxy object in the context of a dynamically created (proxy) Java class (e.g. an abstract class, where the abstract methods will forward their invocation to the RexxProxy object).

Parameters:
proxy - a RexxProxy to which the callback is to be carried out
javaObject - object that invoked this callback
methodName - this name is used as the message to be sent to the Rexx object
methodDescriptor - the Java internal representation of the method's arguments and return type, if any
args - arguments to be passed to Rexx, if any
Returns:
a String object with the result from Rexx or null.
Throws:
org.apache.bsf.BSFException

apply

public java.lang.Object apply(java.lang.String source,
                              int lineNo,
                              int columnNo,
                              java.lang.Object oscript,
                              java.util.Vector vArgNames,
                              java.util.Vector vArgs)
                       throws org.apache.bsf.BSFException
Applies (evaluates) a piece of Rexx code (can be a whole program as well) with Java-supplied arguments and returns the result.

Specified by:
apply in interface org.apache.bsf.BSFEngine
Overrides:
apply in class org.apache.bsf.util.BSFEngineImpl
Parameters:
source - name of source containing the script (e.g. fully qualified file name) or null
lineNo - not used.
columnNo - not used.
oscript - the String version of this object [using toString()] represents the Rexx code to be executed. Its statements are delimited with a ';' or a an LF (line-feed, "0x0a"), preceeded by an optional CR (carriage-return, "0x0d").
vArgNames - not used.
vArgs - arguments to be passed to Rexx.
Returns:
a String object with the result from Rexx or null.
Throws:
org.apache.bsf.BSFException

declareBean

public void declareBean(org.apache.bsf.BSFDeclaredBean bean)
                 throws org.apache.bsf.BSFException
Method implemented in order to avoid an exeption to be thrown by the default implementation.

Specified by:
declareBean in interface org.apache.bsf.BSFEngine
Overrides:
declareBean in class org.apache.bsf.util.BSFEngineImpl
Parameters:
bean - the bean to be declared for the already started language.
Throws:
org.apache.bsf.BSFException

undeclareBean

public void undeclareBean(org.apache.bsf.BSFDeclaredBean bean)
                   throws org.apache.bsf.BSFException
Method implemented in order to avoid an exeption to be thrown by the default implementation.

Specified by:
undeclareBean in interface org.apache.bsf.BSFEngine
Overrides:
undeclareBean in class org.apache.bsf.util.BSFEngineImpl
Parameters:
bean - the bean to be declared for the already started language.
Throws:
org.apache.bsf.BSFException

terminate

public void terminate()
Waits until all Rexx threads of this engine's Rexx interpreter instance peer have terminated (using the new ooRExx 4.0 APIs); this method must be called from the same thread that created the Rexx interpreter instance (i.e. the thread that created this instance of the RexxEngine). To halt all Rexx threads of this engine's Rexx interpreter instance peer use halt().

Specified by:
terminate in interface org.apache.bsf.BSFEngine
Overrides:
terminate in class org.apache.bsf.util.BSFEngineImpl

halt

public void halt()
          throws RexxException
Halt (raise the HALT condition) all Rexx threads of this engine's peer Rexx interperter instance (using the new ooRExx 4.0 APIs).

Throws:
RexxException

halt

public int halt(java.lang.String tid)
Allow halting an individual Rexx thread (raising the HALT condition) having the given thread ID.

Parameters:
a - string with the target thread ID, or the string "0" (raises the HALT condition in all ooRexx threads)
Returns:
return code from RexxSetHalt(...): 0 (o.k.), 1 (tid not found), or 2 (failure)

20110531, rgf