org.rexxla.bsf.engines.rexx
Class RexxEngine

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

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.

  RexxEngine.java - this class makes (Object) Rexx available to IBM's BeanScriptingFramework (BSF)
  Copyright (C) 2001-2005 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:
2.5, 2003-06-02
Author:
Rony G. Flatscher (University of Essen & Wirtschaftsuniversität Wien & University of Augsburg), Proof of concept by Peter Kalender (Oct 2000 to Feb 2001, University of Essen)

Field Summary
private  boolean bDebug
           
private  java.lang.String lastScriptCode
          Stores the script code supplied with eval(), exec(), apply(), in order to be able to locate the code in call().
private  RexxAndJava rexxInterface
          Allows using the Rexx interpreter from Java.
 
Fields inherited from class org.apache.bsf.util.BSFEngineImpl
classLoader, classPath, dbgmgr, 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.
private  java.lang.Object[] args2RexxString(java.lang.Object o)
          Turns received object either into a String, if object is a primitive type or a Java wrapper class for primitive types.
 java.lang.Object call(java.lang.Object object, java.lang.String name, java.lang.Object[] args)
          Deprecated. " This call(...) method may be enhanced in the future, once an openly defined and available interface to the OO-part of Object Rexx is made available by IBM. Then the argument "object" would denote an Object Rexx object, the argument "name" the name of one of its methods and the argument "args" the arguments for the method.
If possible at all, use method apply(...) instead.
 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.
protected  RexxAndJava getRexxInterface()
           
 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.
 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, disconnectedDebuggerNotify, exec, getSpecificDebuggingInterface, placeBreakpointAtLine, placeBreakpointAtOffset, propertyChange, removeBreakpoint, setEntryExit, terminate
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

bDebug

private boolean bDebug

rexxInterface

private RexxAndJava rexxInterface
Allows using the Rexx interpreter from Java.


lastScriptCode

private java.lang.String lastScriptCode
Stores the script code supplied with eval(), exec(), apply(), in order to be able to locate the code in call(). [Hint: Xalan as per 2002-09 uses BSF in its extension mechanism such, that it first calls exec() to have the script pre-compiled and thereafter uses call() to invoke the script.

Constructor Detail

RexxEngine

public RexxEngine()
Method Detail

getRexxInterface

protected RexxAndJava getRexxInterface()

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.

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
Deprecated. " This call(...) method may be enhanced in the future, once an openly defined and available interface to the OO-part of Object Rexx is made available by IBM. Then the argument "object" would denote an Object Rexx object, the argument "name" the name of one of its methods and the argument "args" the arguments for the method.
If possible at all, use method apply(...) instead.

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.]

Parameters:
object - not used.
name - not used.
args - arguments to be passed to Rexx.
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.

Parameters:
source - not used.
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

args2RexxString

private java.lang.Object[] args2RexxString(java.lang.Object o)
Turns received object either into a String, if object is a primitive type or a Java wrapper class for primitive types. Otherwise it makes sure that a Bean will be created for it and returns the beanName instead (a String). null will get returned as null, hence no String representation is returned instead; this way the Rexx ARG() function can be used to determine, if such an argument was omitted or not. (2003-01-06, ---rgf).

Parameters:
o - object to be turned into a String or a Bean.
Returns:
a two-dimensional array of Object. The element with index 0 indicates whether a Bean had to be created (Boolean.TRUE or Boolean.FALSE), the second element with index 1 represents the object as a String or null if the received object is null.

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.

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.

Parameters:
bean - the bean to be declared for the already started language.
Throws:
org.apache.bsf.BSFException