Java tutorial
/* * Copyright 2004,2004 The Apache Software Foundation. * * 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. */ package org.apache.bsf; import java.beans.PropertyChangeSupport; import java.io.IOException; import java.io.InputStream; import java.net.URL; import java.security.AccessController; import java.security.PrivilegedActionException; import java.security.PrivilegedExceptionAction; import java.util.Enumeration; import java.util.Hashtable; import java.util.Iterator; import java.util.MissingResourceException; import java.util.NoSuchElementException; import java.util.Properties; import java.util.StringTokenizer; import java.util.Vector; import org.apache.bsf.util.CodeBuffer; import org.apache.bsf.util.ObjectRegistry; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; /** * 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. * <p> * 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 * @author Matthew J. Duftler * @author Sam Ruby * @author Olivier Gruber (added original debugging support) * @author Don Schwarz (added support for registering languages dynamically) */ public class BSFManager { // version string is 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: "240.20060925" stands for: BSF version "2.4.0" as of "2006-09-25" protected static String version = "240.20061006"; // table of registered scripting engines protected static Hashtable registeredEngines = new Hashtable(); // mapping of file extensions to languages protected static Hashtable extn2Lang = new Hashtable(); // table of scripting engine instances created by this manager. // only one instance of a given language engine is created by a single // manager instance. protected Hashtable loadedEngines = new Hashtable(); // table of registered beans for use by scripting engines. protected ObjectRegistry objectRegistry = new ObjectRegistry(); // prop change support containing loaded engines to inform when any // of my interesting properties change protected PropertyChangeSupport pcs; // the class loader to use if a class loader is needed. Default is // he who loaded me (which may be null in which case its Class.forName). // protected ClassLoader classLoader = getClass().getClassLoader(); protected ClassLoader classLoader = Thread.currentThread().getContextClassLoader(); // rgf, 2006-01-05 // temporary directory to use to dump temporary files into. Note that // if class files are dropped here then unless this dir is in the // classpath or unless the classloader knows to look here, the classes // will not be found. protected String tempDir = "."; // classpath used by those that need a classpath protected String classPath; // stores BSFDeclaredBeans representing objects // introduced by a client of BSFManager protected Vector declaredBeans = new Vector(); private Log logger = LogFactory.getLog(this.getClass().getName()); ////////////////////////////////////////////////////////////////////// // // pre-register engines that BSF supports off the shelf // ////////////////////////////////////////////////////////////////////// static { try { Enumeration e = BSFManager.class.getClassLoader().getResources("org/apache/bsf/Languages.properties"); while (e.hasMoreElements()) { URL url = (URL) e.nextElement(); InputStream is = url.openStream(); Properties p = new Properties(); p.load(is); for (Enumeration keys = p.propertyNames(); keys.hasMoreElements();) { String key = (String) keys.nextElement(); String value = p.getProperty(key); String className = value.substring(0, value.indexOf(",")); // get the extensions for this language String exts = value.substring(value.indexOf(",") + 1, value.length()); StringTokenizer st = new StringTokenizer(exts, "|"); String[] extensions = new String[st.countTokens()]; for (int i = 0; st.hasMoreTokens(); i++) { extensions[i] = ((String) st.nextToken()).trim(); } registerScriptingEngine(key, className, extensions); } } } catch (IOException ex) { ex.printStackTrace(); System.err.println("Error reading Languages file " + ex); } catch (NoSuchElementException nsee) { nsee.printStackTrace(); System.err.println("Syntax error in Languages resource bundle"); } catch (MissingResourceException mre) { mre.printStackTrace(); System.err.println("Initialization error: " + mre.toString()); } } public BSFManager() { pcs = new PropertyChangeSupport(this); } /** Returns the version string of BSF. * * @return 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. * <br>Example: "<code>240.20061006</code>" stands for: BSF version <code>2.4.0</code> as of <code>2006-10-06</code>. * * * @since 2006-01-17 */ public static String getVersion() { return version; } /** * Apply the given anonymous function of the given language to the given * parameters and return the resulting value. * * @param lang language identifier * @param source (context info) the source of this expression (e.g., filename) * @param lineNo (context info) the line number in source for expr * @param columnNo (context info) the column number in source for expr * @param funcBody the multi-line, value returning script to evaluate * @param paramNames the names of the parameters above assumes * @param arguments values of the above parameters * * @exception BSFException if anything goes wrong while running the script */ public Object apply(String lang, String source, int lineNo, int columnNo, Object funcBody, Vector paramNames, Vector arguments) throws BSFException { logger.debug("BSFManager:apply"); final BSFEngine e = loadScriptingEngine(lang); final String sourcef = source; final int lineNof = lineNo, columnNof = columnNo; final Object funcBodyf = funcBody; final Vector paramNamesf = paramNames; final Vector argumentsf = arguments; Object result = null; try { final Object resultf = AccessController.doPrivileged(new PrivilegedExceptionAction() { public Object run() throws Exception { return e.apply(sourcef, lineNof, columnNof, funcBodyf, paramNamesf, argumentsf); } }); result = resultf; } catch (PrivilegedActionException prive) { logger.error("Exception: ", prive); throw (BSFException) prive.getException(); } return result; } /** * Compile the application of the given anonymous function of the given * language to the given parameters into the given <tt>CodeBuffer</tt>. * * @param lang language identifier * @param source (context info) the source of this expression (e.g., filename) * @param lineNo (context info) the line number in source for expr * @param columnNo (context info) the column number in source for expr * @param funcBody the multi-line, value returning script to evaluate * @param paramNames the names of the parameters above assumes * @param arguments values of the above parameters * @param cb code buffer to compile into * * @exception BSFException if anything goes wrong while running the script */ public void compileApply(String lang, String source, int lineNo, int columnNo, Object funcBody, Vector paramNames, Vector arguments, CodeBuffer cb) throws BSFException { logger.debug("BSFManager:compileApply"); final BSFEngine e = loadScriptingEngine(lang); final String sourcef = source; final int lineNof = lineNo, columnNof = columnNo; final Object funcBodyf = funcBody; final Vector paramNamesf = paramNames; final Vector argumentsf = arguments; final CodeBuffer cbf = cb; try { AccessController.doPrivileged(new PrivilegedExceptionAction() { public Object run() throws Exception { e.compileApply(sourcef, lineNof, columnNof, funcBodyf, paramNamesf, argumentsf, cbf); return null; } }); } catch (PrivilegedActionException prive) { logger.error("Exception :", prive); throw (BSFException) prive.getException(); } } /** * Compile the given expression of the given language into the given * <tt>CodeBuffer</tt>. * * @param lang language identifier * @param source (context info) the source of this expression (e.g., filename) * @param lineNo (context info) the line number in source for expr * @param columnNo (context info) the column number in source for expr * @param expr the expression to compile * @param cb code buffer to compile into * * @exception BSFException if any error while compiling the expression */ public void compileExpr(String lang, String source, int lineNo, int columnNo, Object expr, CodeBuffer cb) throws BSFException { logger.debug("BSFManager:compileExpr"); final BSFEngine e = loadScriptingEngine(lang); final String sourcef = source; final int lineNof = lineNo, columnNof = columnNo; final Object exprf = expr; final CodeBuffer cbf = cb; try { AccessController.doPrivileged(new PrivilegedExceptionAction() { public Object run() throws Exception { e.compileExpr(sourcef, lineNof, columnNof, exprf, cbf); return null; } }); } catch (PrivilegedActionException prive) { logger.error("Exception :", prive); throw (BSFException) prive.getException(); } } /** * Compile the given script of the given language into the given * <tt>CodeBuffer</tt>. * * @param lang language identifier * @param source (context info) the source of this script (e.g., filename) * @param lineNo (context info) the line number in source for script * @param columnNo (context info) the column number in source for script * @param script the script to compile * @param cb code buffer to compile into * * @exception BSFException if any error while compiling the script */ public void compileScript(String lang, String source, int lineNo, int columnNo, Object script, CodeBuffer cb) throws BSFException { logger.debug("BSFManager:compileScript"); final BSFEngine e = loadScriptingEngine(lang); final String sourcef = source; final int lineNof = lineNo, columnNof = columnNo; final Object scriptf = script; final CodeBuffer cbf = cb; try { AccessController.doPrivileged(new PrivilegedExceptionAction() { public Object run() throws Exception { e.compileScript(sourcef, lineNof, columnNof, scriptf, cbf); return null; } }); } catch (PrivilegedActionException prive) { logger.error("Exception :", prive); throw (BSFException) prive.getException(); } } /** * 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." * <p> * 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. * <p> * 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. * <p> * 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. * * @param beanName name to declare bean as * @param bean the bean that's being declared * @param type the type to represent the bean as * * @exception BSFException if any of the languages that are already * running decides to throw an exception when asked to * declare this bean. */ public void declareBean(String beanName, Object bean, Class type) throws BSFException { logger.debug("BSFManager:declareBean"); registerBean(beanName, bean); BSFDeclaredBean tempBean = new BSFDeclaredBean(beanName, bean, type); declaredBeans.addElement(tempBean); Enumeration enginesEnum = loadedEngines.elements(); BSFEngine engine; while (enginesEnum.hasMoreElements()) { engine = (BSFEngine) enginesEnum.nextElement(); engine.declareBean(tempBean); } } /** * Evaluate the given expression of the given language and return the * resulting value. * * @param lang language identifier * @param source (context info) the source of this expression (e.g., filename) * @param lineNo (context info) the line number in source for expr * @param columnNo (context info) the column number in source for expr * @param expr the expression to evaluate * * @exception BSFException if anything goes wrong while running the script */ public Object eval(String lang, String source, int lineNo, int columnNo, Object expr) throws BSFException { logger.debug("BSFManager:eval"); final BSFEngine e = loadScriptingEngine(lang); final String sourcef = source; final int lineNof = lineNo, columnNof = columnNo; final Object exprf = expr; Object result = null; try { final Object resultf = AccessController.doPrivileged(new PrivilegedExceptionAction() { public Object run() throws Exception { return e.eval(sourcef, lineNof, columnNof, exprf); } }); result = resultf; } catch (PrivilegedActionException prive) { logger.error("Exception: ", prive); throw (BSFException) prive.getException(); } return result; } ////////////////////////////////////////////////////////////////////// // // Convenience functions for exec'ing and eval'ing scripts directly // without loading and dealing with engines etc.. // ////////////////////////////////////////////////////////////////////// /** * Execute the given script of the given language. * * @param lang language identifier * @param source (context info) the source of this expression (e.g., filename) * @param lineNo (context info) the line number in source for expr * @param columnNo (context info) the column number in source for expr * @param script the script to execute * * @exception BSFException if anything goes wrong while running the script */ public void exec(String lang, String source, int lineNo, int columnNo, Object script) throws BSFException { logger.debug("BSFManager:exec"); final BSFEngine e = loadScriptingEngine(lang); final String sourcef = source; final int lineNof = lineNo, columnNof = columnNo; final Object scriptf = script; try { AccessController.doPrivileged(new PrivilegedExceptionAction() { public Object run() throws Exception { e.exec(sourcef, lineNof, columnNof, scriptf); return null; } }); } catch (PrivilegedActionException prive) { logger.error("Exception :", prive); throw (BSFException) prive.getException(); } } /** * Execute the given script of the given language, attempting to * emulate an interactive session w/ the language. * * @param lang language identifier * @param source (context info) the source of this expression * (e.g., filename) * @param lineNo (context info) the line number in source for expr * @param columnNo (context info) the column number in source for expr * @param script the script to execute * * @exception BSFException if anything goes wrong while running the script */ public void iexec(String lang, String source, int lineNo, int columnNo, Object script) throws BSFException { logger.debug("BSFManager:iexec"); final BSFEngine e = loadScriptingEngine(lang); final String sourcef = source; final int lineNof = lineNo, columnNof = columnNo; final Object scriptf = script; try { AccessController.doPrivileged(new PrivilegedExceptionAction() { public Object run() throws Exception { e.iexec(sourcef, lineNof, columnNof, scriptf); return null; } }); } catch (PrivilegedActionException prive) { logger.error("Exception :", prive); throw (BSFException) prive.getException(); } } /** * Get classLoader */ public ClassLoader getClassLoader() { logger.debug("BSFManager:getClassLoader"); return classLoader; } /** * Get classPath */ public String getClassPath() { logger.debug("BSFManager:getClassPath"); if (classPath == null) { try { classPath = System.getProperty("java.class.path"); } catch (Throwable t) { logger.debug("Exception :", t); // prolly a security exception .. so no can do } } return classPath; } /** * Determine the language of a script file by looking at the file * extension. * * @param fileName the name of the file * * @return the scripting language the file is in if the file extension * is known to me (must have been registered via * registerScriptingEngine). * * @exception BSFException if file's extension is unknown. */ public static String getLangFromFilename(String fileName) throws BSFException { int dotIndex = fileName.lastIndexOf("."); if (dotIndex != -1) { String extn = fileName.substring(dotIndex + 1); String langval = (String) extn2Lang.get(extn); String lang = null; int index, loops = 0; if (langval != null) { while ((index = langval.indexOf(":", 0)) != -1) { // Great. Multiple language engines registered // for this extension. // Try to find first one that is in our classpath. lang = langval.substring(0, index); langval = langval.substring(index + 1); loops++; // Test to see if in classpath try { String engineName = (String) registeredEngines.get(lang); Class.forName(engineName); } catch (ClassNotFoundException cnfe) { // Bummer. lang = langval; continue; } // Got past that? Good. break; } if (loops == 0) { lang = langval; } } if (lang != null && lang != "") { return lang; } } throw new BSFException(BSFException.REASON_OTHER_ERROR, "file extension missing or unknown: " + "unable to determine language for '" + fileName + "'"); } /** * Return the current object registry of the manager. * * @return the current registry. */ public ObjectRegistry getObjectRegistry() { return objectRegistry; } /** * Get tempDir */ public String getTempDir() { return tempDir; } /** * Determine whether a language is registered. * * @param lang string identifying a language * * @return true iff it is */ public static boolean isLanguageRegistered(String lang) { return (registeredEngines.get(lang) != null); } ////////////////////////////////////////////////////////////////////// // // Bean scripting framework services // ////////////////////////////////////////////////////////////////////// /** * Load a scripting engine based on the lang string identifying it. * * @param lang string identifying language * @exception 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. */ public BSFEngine loadScriptingEngine(String lang) throws BSFException { logger.debug("BSFManager:loadScriptingEngine"); // if its already loaded return that BSFEngine eng = (BSFEngine) loadedEngines.get(lang); if (eng != null) { return eng; } // is it a registered language? String engineClassName = (String) registeredEngines.get(lang); if (engineClassName == null) { logger.error("unsupported language: " + lang); throw new BSFException(BSFException.REASON_UNKNOWN_LANGUAGE, "unsupported language: " + lang); } // create the engine and initialize it. if anything goes wrong // except. try { Class engineClass = (classLoader == null) ? Class.forName(engineClassName) : classLoader.loadClass(engineClassName); final BSFEngine engf = (BSFEngine) engineClass.newInstance(); final BSFManager thisf = this; final String langf = lang; final Vector dbf = declaredBeans; AccessController.doPrivileged(new PrivilegedExceptionAction() { public Object run() throws Exception { engf.initialize(thisf, langf, dbf); return null; } }); eng = engf; loadedEngines.put(lang, eng); pcs.addPropertyChangeListener(eng); return eng; } catch (PrivilegedActionException prive) { logger.error("Exception :", prive); throw (BSFException) prive.getException(); } catch (Throwable t) { logger.error("Exception :", t); throw new BSFException(BSFException.REASON_OTHER_ERROR, "unable to load language: " + lang, t); } } /** * 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. * * @param beanName name of bean to look up * * @return the bean if its found or null */ public Object lookupBean(String beanName) { logger.debug("BSFManager:lookupBean"); try { return ((BSFDeclaredBean) objectRegistry.lookup(beanName)).bean; } catch (IllegalArgumentException e) { logger.debug("Exception :", e); return null; } } /** * Registering a bean allows a scripting engine or the application to * access that bean by name and to manipulate it. * * @param beanName name to register under * @param bean the bean to register */ public void registerBean(String beanName, Object bean) { logger.debug("BSFManager:registerBean"); BSFDeclaredBean tempBean; if (bean == null) { tempBean = new BSFDeclaredBean(beanName, null, null); } else { tempBean = new BSFDeclaredBean(beanName, bean, bean.getClass()); } objectRegistry.register(beanName, tempBean); } /** * Register a scripting engine in the static registry of the * BSFManager. * * @param lang string identifying language * @param engineClassName fully qualified name of the class interfacing * the language to BSF. * @param extensions array of file extensions that should be mapped to * this language type. may be null. */ public static void registerScriptingEngine(String lang, String engineClassName, String[] extensions) { registeredEngines.put(lang, engineClassName); if (extensions != null) { for (int i = 0; i < extensions.length; i++) { String langstr = (String) extn2Lang.get(extensions[i]); langstr = (langstr == null) ? lang : lang + ":" + langstr; extn2Lang.put(extensions[i], langstr); } } } /** * Set the class loader for those that need to use it. Default is he * who loaded me or null (i.e., its Class.forName). * * @param classLoader the class loader to use. */ public void setClassLoader(ClassLoader classLoader) { logger.debug("BSFManager:setClassLoader"); pcs.firePropertyChange("classLoader", this.classLoader, classLoader); this.classLoader = classLoader; } /** * Set the classpath for those that need to use it. Default is the value * of the java.class.path property. * * @param classPath the classpath to use */ public void setClassPath(String classPath) { logger.debug("BSFManager:setClassPath"); pcs.firePropertyChange("classPath", this.classPath, classPath); this.classPath = classPath; } /** * 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. * * @param objectRegistry the registry to use */ public void setObjectRegistry(ObjectRegistry objectRegistry) { logger.debug("BSFManager:setObjectRegistry"); this.objectRegistry = objectRegistry; } /** * 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). * * @param tempDir the temporary directory */ public void setTempDir(String tempDir) { logger.debug("BSFManager:setTempDir"); pcs.firePropertyChange("tempDir", this.tempDir, tempDir); this.tempDir = tempDir; } /** * Gracefully terminate all engines */ public void terminate() { logger.debug("BSFManager:terminate"); Enumeration enginesEnum = loadedEngines.elements(); BSFEngine engine; while (enginesEnum.hasMoreElements()) { engine = (BSFEngine) enginesEnum.nextElement(); engine.terminate(); } loadedEngines = new Hashtable(); } /** * 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. * * @param beanName name of bean to undeclare * * @exception BSFException if any of the languages that are already * running decides to throw an exception when asked to * undeclare this bean. */ public void undeclareBean(String beanName) throws BSFException { logger.debug("BSFManager:undeclareBean"); unregisterBean(beanName); BSFDeclaredBean tempBean = null; boolean found = false; for (Iterator i = declaredBeans.iterator(); i.hasNext();) { tempBean = (BSFDeclaredBean) i.next(); if (tempBean.name.equals(beanName)) { found = true; break; } } if (found) { declaredBeans.removeElement(tempBean); Enumeration enginesEnum = loadedEngines.elements(); while (enginesEnum.hasMoreElements()) { BSFEngine engine = (BSFEngine) enginesEnum.nextElement(); engine.undeclareBean(tempBean); } } } /** * Unregister a previously registered bean. Silent if name is not found. * * @param beanName name of bean to unregister */ public void unregisterBean(String beanName) { logger.debug("BSFManager:unregisterBean"); objectRegistry.unregister(beanName); } }