org.apache.bsf

## Class BSFManager

- java.lang.Object
- - org.apache.bsf.BSFManager

-     public class BSFManager
      extends java.lang.Object

  This class is the entry point to the bean scripting framework. An application wishing to integrate scripting to a Java app would place an instance of a BSFManager in their code and use its services to register the beans they want to make available for scripting, load scripting engines, and run scripts.

  BSFManager serves as the registry of available scripting engines as well. Loading and unloading of scripting engines is supported as well. Each BSFManager loads one engine per language. Several BSFManagers can be created per JVM.

  Author:
    Sanjiva Weerawarana, Matthew J. Duftler, Sam Ruby, Olivier Gruber (added original debugging support), Don Schwarz (added support for registering languages dynamically), Rony G. Flatscher (added BSF_Log[Factory] to allow BSF to run without org.apache.commons.logging present)

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.lang.ClassLoader` | `classLoader`
    `protected java.lang.String` | `classPath`
    `protected java.util.Vector` | `declaredBeans`
    `protected static java.lang.ClassLoader` | `definedClassLoader`
    `protected static java.util.Hashtable` | `extn2Lang`
    `protected java.util.Hashtable` | `loadedEngines`
    `protected ObjectRegistry` | `objectRegistry`
    `protected java.beans.PropertyChangeSupport` | `pcs`
    `protected static java.util.Hashtable` | `registeredEngines`
    `protected java.lang.String` | `tempDir`
    `protected static java.lang.String` | `version`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `BSFManager()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Object` | `apply(java.lang.String lang, java.lang.String source, int lineNo, int columnNo, java.lang.Object funcBody, java.util.Vector paramNames, java.util.Vector arguments)` Apply the given anonymous function of the given language to the given parameters and return the resulting value.
    `void` | `compileApply(java.lang.String lang, java.lang.String source, int lineNo, int columnNo, java.lang.Object funcBody, java.util.Vector paramNames, java.util.Vector arguments, CodeBuffer cb)` Compile the application of the given anonymous function of the given language to the given parameters into the given `CodeBuffer`.
    `void` | `compileExpr(java.lang.String lang, java.lang.String source, int lineNo, int columnNo, java.lang.Object expr, CodeBuffer cb)` Compile the given expression of the given language into the given `CodeBuffer`.
    `void` | `compileScript(java.lang.String lang, java.lang.String source, int lineNo, int columnNo, java.lang.Object script, CodeBuffer cb)` Compile the given script of the given language into the given `CodeBuffer`.
    `void` | `declareBean(java.lang.String beanName, java.lang.Object bean, java.lang.Class type)` Declare a bean.
    `java.lang.Object` | `eval(java.lang.String lang, java.lang.String source, int lineNo, int columnNo, java.lang.Object expr)` Evaluate the given expression of the given language and return the resulting value.
    `void` | `exec(java.lang.String lang, java.lang.String source, int lineNo, int columnNo, java.lang.Object script)` Execute the given script of the given language.
    `java.lang.ClassLoader` | `getClassLoader()` Get classLoader
    `java.lang.String` | `getClassPath()` Get classPath
    `static java.lang.ClassLoader` | `getDefinedClassLoader()` Returns the defined ClassLoader (the ClassLoader that got used to define the org.apache.bsf.BSFManager class object).
    `static java.lang.String` | `getLangFromFilename(java.lang.String fileName)` Determine the language of a script file by looking at the file extension.
    `ObjectRegistry` | `getObjectRegistry()` Return the current object registry of the manager.
    `java.lang.String` | `getTempDir()` Get tempDir
    `static java.lang.String` | `getVersion()` Returns the version string of BSF.
    `void` | `iexec(java.lang.String lang, java.lang.String source, int lineNo, int columnNo, java.lang.Object script)` Execute the given script of the given language, attempting to emulate an interactive session w/ the language.
    `static boolean` | `isLanguageRegistered(java.lang.String lang)` Determine whether a language is registered.
    `BSFEngine` | `loadScriptingEngine(java.lang.String lang)` Load a scripting engine based on the lang string identifying it.
    `java.lang.Object` | `lookupBean(java.lang.String beanName)` return a handle to a bean registered in the bean registry by the application or a scripting engine.
    `void` | `registerBean(java.lang.String beanName, java.lang.Object bean)` Registering a bean allows a scripting engine or the application to access that bean by name and to manipulate it.
    `static void` | `registerScriptingEngine(java.lang.String lang, java.lang.String engineClassName, java.lang.String[] extensions)` Register a scripting engine in the static registry of the BSFManager.
    `void` | `setClassLoader(java.lang.ClassLoader classLoader)` Set the class loader for those that need to use it.
    `void` | `setClassPath(java.lang.String classPath)` Set the classpath for those that need to use it.
    `void` | `setObjectRegistry(ObjectRegistry objectRegistry)` Set the object registry used by this manager.
    `void` | `setTempDir(java.lang.String tempDir)` Temporary directory to put stuff into (for those who need to).
    `void` | `terminate()` Gracefully terminate all engines
    `void` | `undeclareBean(java.lang.String beanName)` Undeclare a previously declared bean.
    `void` | `unregisterBean(java.lang.String beanName)` Unregister a previously registered bean.

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

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

- - ### Field Detail

    - #### version

          protected static java.lang.String version

    - #### registeredEngines

          protected static java.util.Hashtable registeredEngines

    - #### extn2Lang

          protected static java.util.Hashtable extn2Lang

    - #### definedClassLoader

          protected static java.lang.ClassLoader definedClassLoader

    - #### loadedEngines

          protected java.util.Hashtable loadedEngines

    - #### objectRegistry

          protected ObjectRegistry objectRegistry

    - #### pcs

          protected java.beans.PropertyChangeSupport pcs

    - #### classLoader

          protected java.lang.ClassLoader classLoader

    - #### tempDir

          protected java.lang.String tempDir

    - #### classPath

          protected java.lang.String classPath

    - #### declaredBeans

          protected java.util.Vector declaredBeans

  - ### Constructor Detail

    - #### BSFManager

          public BSFManager()

  - ### Method Detail

    - #### getDefinedClassLoader

          public static java.lang.ClassLoader getDefinedClassLoader()

      Returns the defined ClassLoader (the ClassLoader that got used to define the org.apache.bsf.BSFManager class object).
      Returns:
        the defined ClassLoader instance

    - #### getVersion

          public static java.lang.String getVersion()

      Returns the version string of BSF.
      Returns:
        version string in the form "abc.yyyymmdd" where "abc" represents a dewey decimal number (three levels, each between 0 and 9), and "yyyy" a four digit year, "mm" a two digit month, "dd" a two digit day.
        Example: "`244.20080623`" stands for: BSF version `2.4.5` as of `2009-09-10`.
      Since:
        2006-01-17

    - #### apply

          public java.lang.Object apply(java.lang.String lang,
                                        java.lang.String source,
                                        int lineNo,
                                        int columnNo,
                                        java.lang.Object funcBody,
                                        java.util.Vector paramNames,
                                        java.util.Vector arguments)
                                 throws BSFException

      Apply the given anonymous function of the given language to the given parameters and return the resulting value.
      Parameters:
        `lang` - language identifier
        `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
        `funcBody` - the multi-line, value returning script to evaluate
        `paramNames` - the names of the parameters above assumes
        `arguments` - values of the above parameters
      Throws:
        `BSFException` - if anything goes wrong while running the script

    - #### compileApply

          public void compileApply(java.lang.String lang,
                                   java.lang.String source,
                                   int lineNo,
                                   int columnNo,
                                   java.lang.Object funcBody,
                                   java.util.Vector paramNames,
                                   java.util.Vector arguments,
                                   CodeBuffer cb)
                            throws BSFException

      Compile the application of the given anonymous function of the given language to the given parameters into the given `CodeBuffer`.
      Parameters:
        `lang` - language identifier
        `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
        `funcBody` - the multi-line, value returning script to evaluate
        `paramNames` - the names of the parameters above assumes
        `arguments` - values of the above parameters
        `cb` - code buffer to compile into
      Throws:
        `BSFException` - if anything goes wrong while running the script

    - #### compileExpr

          public void compileExpr(java.lang.String lang,
                                  java.lang.String source,
                                  int lineNo,
                                  int columnNo,
                                  java.lang.Object expr,
                                  CodeBuffer cb)
                           throws BSFException

      Compile the given expression of the given language into the given `CodeBuffer`.
      Parameters:
        `lang` - language identifier
        `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
        `expr` - the expression to compile
        `cb` - code buffer to compile into
      Throws:
        `BSFException` - if any error while compiling the expression

    - #### compileScript

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

      Compile the given script of the given language into the given `CodeBuffer`.
      Parameters:
        `lang` - language identifier
        `source` - (context info) the source of this script (e.g., filename)
        `lineNo` - (context info) the line number in source for script
        `columnNo` - (context info) the column number in source for script
        `script` - the script to compile
        `cb` - code buffer to compile into
      Throws:
        `BSFException` - if any error while compiling the script

    - #### declareBean

          public void declareBean(java.lang.String beanName,
                                  java.lang.Object bean,
                                  java.lang.Class type)
                           throws BSFException

      Declare a bean. The difference between declaring and registering is that engines are spsed to make declared beans "pre-available" in the scripts as far as possible. That is, if a script author needs a registered bean, he needs to look it up in some way. However if he needs a declared bean, the language has the responsibility to make those beans avaialable "automatically."

      When a bean is declared it is automatically registered as well so that any declared bean can be gotton to by looking it up as well.

      If any of the languages that are already running in this manager says they don't like this (by throwing an exception) then this method will simply quit with that exception. That is, any engines that come after than in the engine enumeration will not even be told about this new bean.

      So, in general its best to declare beans before the manager has been asked to load any engines because then the user can be informed when an engine rejects it. Also, its much more likely that an engine can declare a bean at start time than it can at any time.

      Parameters:
        `beanName` - name to declare bean as
        `bean` - the bean that's being declared
        `type` - the type to represent the bean as
      Throws:
        `BSFException` - if any of the languages that are already running decides to throw an exception when asked to declare this bean.

    - #### eval

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

      Evaluate the given expression of the given language and return the resulting value.
      Parameters:
        `lang` - language identifier
        `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
        `expr` - the expression to evaluate
      Throws:
        `BSFException` - if anything goes wrong while running the script

    - #### exec

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

      Execute the given script of the given language.
      Parameters:
        `lang` - language identifier
        `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 running the script

    - #### iexec

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

      Execute the given script of the given language, attempting to emulate an interactive session w/ the language.
      Parameters:
        `lang` - language identifier
        `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 running the script

    - #### getClassLoader

          public java.lang.ClassLoader getClassLoader()

      Get classLoader

    - #### getClassPath

          public java.lang.String getClassPath()

      Get classPath

    - #### getLangFromFilename

          public static java.lang.String getLangFromFilename(java.lang.String fileName)
                                                      throws BSFException

      Determine the language of a script file by looking at the file extension.
      Parameters:
        `fileName` - the name of the file
      Returns:
        the scripting language the file is in if the file extension is known to me (must have been registered via registerScriptingEngine).
      Throws:
        `BSFException` - if file's extension is unknown.

    - #### getObjectRegistry

          public ObjectRegistry getObjectRegistry()

      Return the current object registry of the manager.
      Returns:
        the current registry.

    - #### getTempDir

          public java.lang.String getTempDir()

      Get tempDir

    - #### isLanguageRegistered

          public static boolean isLanguageRegistered(java.lang.String lang)

      Determine whether a language is registered.
      Parameters:
        `lang` - string identifying a language
      Returns:
        true iff it is

    - #### loadScriptingEngine

          public BSFEngine loadScriptingEngine(java.lang.String lang)
                                        throws BSFException

      Load a scripting engine based on the lang string identifying it.
      Parameters:
        `lang` - string identifying language
      Throws:
        `BSFException` - if the language is unknown (i.e., if it has not been registered) with a reason of REASON_UNKNOWN_LANGUAGE. If the language is known but if the interface can't be created for some reason, then the reason is set to REASON_OTHER_ERROR and the actual exception is passed on as well.

    - #### lookupBean

          public java.lang.Object lookupBean(java.lang.String beanName)

      return a handle to a bean registered in the bean registry by the application or a scripting engine. Returns null if bean is not found.
      Parameters:
        `beanName` - name of bean to look up
      Returns:
        the bean if its found or null

    - #### registerBean

          public void registerBean(java.lang.String beanName,
                                   java.lang.Object bean)

      Registering a bean allows a scripting engine or the application to access that bean by name and to manipulate it.
      Parameters:
        `beanName` - name to register under
        `bean` - the bean to register

    - #### registerScriptingEngine

          public static void registerScriptingEngine(java.lang.String lang,
                                                     java.lang.String engineClassName,
                                                     java.lang.String[] extensions)

      Register a scripting engine in the static registry of the BSFManager.
      Parameters:
        `lang` - string identifying language
        `engineClassName` - fully qualified name of the class interfacing the language to BSF.
        `extensions` - array of file extensions that should be mapped to this language type. may be null.

    - #### setClassLoader

          public void setClassLoader(java.lang.ClassLoader classLoader)

      Set the class loader for those that need to use it. Default is he who loaded me or null (i.e., its Class.forName).
      Parameters:
        `classLoader` - the class loader to use.

    - #### setClassPath

          public void setClassPath(java.lang.String classPath)

      Set the classpath for those that need to use it. Default is the value of the java.class.path property.
      Parameters:
        `classPath` - the classpath to use

    - #### setObjectRegistry

          public void setObjectRegistry(ObjectRegistry objectRegistry)

      Set the object registry used by this manager. By default a new one is created when the manager is new'ed and this overwrites that one.
      Parameters:
        `objectRegistry` - the registry to use

    - #### setTempDir

          public void setTempDir(java.lang.String tempDir)

      Temporary directory to put stuff into (for those who need to). Note that unless this directory is in the classpath or unless the classloader knows to look in here, any classes here will not be found! BSFManager provides a service method to load a class which uses either the classLoader provided by the class loader property or, if that fails, a class loader which knows to load from the tempdir to try to load the class. Default value of tempDir is "." (current working dir).
      Parameters:
        `tempDir` - the temporary directory

    - #### terminate

          public void terminate()

      Gracefully terminate all engines

    - #### undeclareBean

          public void undeclareBean(java.lang.String beanName)
                             throws BSFException

      Undeclare a previously declared bean. This removes the bean from the list of declared beans in the manager as well as asks every running engine to undeclared the bean. As with above, if any of the engines except when asked to undeclare, this method does not catch that exception. Quietly returns if the bean is unknown.
      Parameters:
        `beanName` - name of bean to undeclare
      Throws:
        `BSFException` - if any of the languages that are already running decides to throw an exception when asked to undeclare this bean.

    - #### unregisterBean

          public void unregisterBean(java.lang.String beanName)

      Unregister a previously registered bean. Silent if name is not found.
      Parameters:
        `beanName` - name of bean to unregister