org.apache.bsf.engines.netrexx

## Class NetRexxEngine

- java.lang.Object
- - org.apache.bsf.util.BSFEngineImpl
  - - org.apache.bsf.engines.netrexx.NetRexxEngine

- All Implemented Interfaces:
    java.beans.PropertyChangeListener, java.util.EventListener, BSFEngine

      public class NetRexxEngine
      extends BSFEngineImpl

  This is the interface to NetRexx from the Bean Scripting Framework.

  The NetRexx code must be written script-style, without a "class" or "properties" section preceeding the executable code. The NetRexxEngine will generate a prefix for this code:

       class $$CLASSNAME$$;
       method BSFNetRexxEngineEntry(bsf=org.apache.bsf.BSFManager) public static;

  $$CLASSNAME$$ will be replaced by a generated classname of the form BSFNetRexx*, and the bsf parameter can be used to retrieve application objects registered with the Bean Scripting Framework.

  If you use the placeholder string $$CLASSNAME$$ elsewhere in your script -- including within text strings -- BSFNetRexxEngine will replace it with the generated name of the class before the NetRexx code is compiled.

  If you need to use full NetRexx functionality, we recommend that your NetRexx script define and invoke a "minor class", with or without the "dependent" keyword as suits your needs. You'll have to use $$CLASSNAME$$ in naming the minor class, since the name of the main class is synthesized; for example, to create the minor class "bar" you'd write "class $$CLASSNAME$$.Bar".

  ## Hazards:

  Since NetRexx has to be _compiled_ to a Java classfile, invoking it involves a fair amount of computation to load and execute the compiler. We are currently making an attempt to manage that by caching the class after it has been loaded, but the indexing is fairly primitive; we hash against the script string to find the class for it.

  Minor-class .class files are now being deleted after the major class loads. This coould potentially cause problems.

  Author:
    Joe Kesselman, Sanjiva Weerawarana, Rony G. Flatscher (added BSF_Log[Factory] to allow BSF to run without org.apache.commons.logging present)

- - ### Field Summary

    - ### Fields inherited from class org.apache.bsf.util.BSFEngineImpl

      `classLoader, classPath, declaredBeans, lang, mgr, tempDir`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `NetRexxEngine()` Constructor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Object` | `call(java.lang.Object object, java.lang.String method, java.lang.Object[] args)` Return an object from an extension.
    `void` | `declareBean(BSFDeclaredBean bean)` Declare a bean after the engine has been started.
    `java.lang.Object` | `eval(java.lang.String source, int lineNo, int columnNo, java.lang.Object script)` Override impl of execute.
    `void` | `exec(java.lang.String source, int lineNo, int columnNo, java.lang.Object script)` Override impl of execute.
    `java.lang.Object` | `execEvalShared(java.lang.String source, int lineNo, int columnNo, java.lang.Object oscript, boolean returnsObject)` This is shared code for the exec() and eval() operations.
    `void` | `initialize(BSFManager mgr, java.lang.String lang, java.util.Vector declaredBeans)` initialize the engine; called right after construction by the manager.
    `void` | `undeclareBean(BSFDeclaredBean bean)` Undeclare a previously declared bean.

    - ### Methods inherited from class org.apache.bsf.util.BSFEngineImpl

      `apply, compileApply, compileExpr, compileScript, iexec, propertyChange, terminate`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### NetRexxEngine

          public NetRexxEngine()

      Constructor.

  - ### Method Detail

    - #### call

          public java.lang.Object call(java.lang.Object object,
                                       java.lang.String method,
                                       java.lang.Object[] args)
                                throws BSFException

      Return an object from an extension.
      Parameters:
        `object` - object from which to call our static method
        `method` - The name of the method to call.
        `args` - an array of arguments to be passed to the extension, which may be either Vectors of Nodes, or Strings.
      Throws:
        `BSFException` - if anything goes wrong while eval'ing a BSFException is thrown. The reason indicates the problem.

    - #### declareBean

          public void declareBean(BSFDeclaredBean bean)
                           throws BSFException

      Description copied from interface: `BSFEngine`
      Declare a bean after the engine has been started. Declared beans are beans that are named and which the engine must make available to the scripts it runs in the most first class way possible.
      Specified by:
        `declareBean` in interface `BSFEngine`
      Overrides:
        `declareBean` in class `BSFEngineImpl`
      Parameters:
        `bean` - the bean to declare
      Throws:
        `BSFException` - if the engine cannot do this operation

    - #### eval

          public java.lang.Object eval(java.lang.String source,
                                       int lineNo,
                                       int columnNo,
                                       java.lang.Object script)
                                throws BSFException

      Override impl of execute. In NetRexx, methods which do not wish to return a value should be invoked via exec, which will cause them to be generated without the "returns" clause. Those which wish to return a value should call eval instead. which will add "returns java.lang.Object" to the header. Note: It would be nice to have the "real" return type avaialable, so we could do something more type-safe than Object, and so we could return primitive types without having to enclose them in their object wrappers. BSF does not currently support that concept.
      Parameters:
        `source` - (context info) the source of this expression (e.g., filename)
        `lineNo` - (context info) the line number in source for expr
        `columnNo` - (context info) the column number in source for expr
        `script` - the expression to evaluate
      Throws:
        `BSFException` - if anything goes wrong while eval'ing a BSFException is thrown. The reason indicates the problem.

    - #### exec

          public void exec(java.lang.String source,
                           int lineNo,
                           int columnNo,
                           java.lang.Object script)
                    throws BSFException

      Override impl of execute. In NetRexx, methods which do not wish to return a value should be invoked via exec, which will cause them to be generated without the "returns" clause. Those which wish to return a value should call eval instead. which will add "returns java.lang.Object" to the header.
      Specified by:
        `exec` in interface `BSFEngine`
      Overrides:
        `exec` in class `BSFEngineImpl`
      Parameters:
        `source` - (context info) the source of this expression (e.g., filename)
        `lineNo` - (context info) the line number in source for expr
        `columnNo` - (context info) the column number in source for expr
        `script` - the script to execute
      Throws:
        `BSFException` - if anything goes wrong while exec'ing a BSFException is thrown. The reason indicates the problem.

    - #### execEvalShared

          public java.lang.Object execEvalShared(java.lang.String source,
                                                 int lineNo,
                                                 int columnNo,
                                                 java.lang.Object oscript,
                                                 boolean returnsObject)
                                          throws BSFException

      This is shared code for the exec() and eval() operations. It will evaluate a string containing a NetRexx method body -- which may be as simple as a single return statement. It should store the "bsf" handle where the script can get to it, for callback purposes.

      Note that NetRexx compilation imposes serious overhead -- 11 seconds for the first compile, about 3 thereafter -- but in exchange you get Java-like speeds once the classes have been created (minus the cache lookup cost).

      Nobody knows whether javac is threadsafe. I'm going to serialize access to the compilers to protect it.

      Throws:
        `BSFException`

    - #### initialize

          public void initialize(BSFManager mgr,
                                 java.lang.String lang,
                                 java.util.Vector declaredBeans)
                          throws BSFException

      Description copied from class: `BSFEngineImpl`
      initialize the engine; called right after construction by the manager. Declared beans are simply kept in a vector and that's it. Subclasses must do whatever they want with it.
      Specified by:
        `initialize` in interface `BSFEngine`
      Overrides:
        `initialize` in class `BSFEngineImpl`
      Parameters:
        `mgr` - The BSFManager that's hosting this engine.
        `lang` - Language string which this engine is handling.
        `declaredBeans` - Vector of BSFDeclaredObject containing beans that should be declared into the language runtime at init time as best as possible.
      Throws:
        `BSFException` - if anything goes wrong while init'ing a BSFException is thrown. The reason indicates the problem.

    - #### undeclareBean

          public void undeclareBean(BSFDeclaredBean bean)
                             throws BSFException

      Description copied from interface: `BSFEngine`
      Undeclare a previously declared bean.
      Specified by:
        `undeclareBean` in interface `BSFEngine`
      Overrides:
        `undeclareBean` in class `BSFEngineImpl`
      Parameters:
        `bean` - the bean to undeclare
      Throws:
        `BSFException` - if the engine cannot do this operation