| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You 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.PropertyChangeListener; |
| import java.util.Vector; |
| |
| import org.apache.bsf.util.CodeBuffer; |
| |
| /** |
| * This is the view of a scripting engine assumed by the Bean Scripting Framework. This interface is used when an application decides to run some script under |
| * application control. (This is the reverse of the more common situation, which is that of the scripting language calling into the application.) |
| * <p> |
| * When a scripting engine is first fired up, the initialize() method is called right after construction. |
| * <p> |
| * A scripting engine must provide two access points for applications to call into them: via function calls and via expression evaluation. It must also support |
| * loading scripts. |
| * <p> |
| * A scripting engine is a property change listener and will be notified when any of the relevant properties of the manager change. (See BSFManager to see which |
| * of its properties are bound.) |
| */ |
| public interface BSFEngine extends PropertyChangeListener { |
| |
| /** |
| * This is used by an application to invoke an anonymous function. An anonymous function is a multi-line script which when evaluated will produce a value. |
| * These are separated from expressions and scripts because the prior are spsed to be good 'ol expressions and scripts are not value returning. We allow |
| * anonymous functions to have parameters as well for completeness. |
| * |
| * @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 doin' it. |
| */ |
| Object apply(String source, int lineNo, int columnNo, Object funcBody, Vector paramNames, Vector arguments) throws BSFException; |
| |
| /** |
| * This is used by an application to call into the scripting engine to make a function/method call. The "object" argument is the object whose method is to |
| * be called, if that applies. For non-OO languages, this is typically ignored and should be given as null. For pretend-OO languages such as VB, this would |
| * be the (String) name of the object. The arguments are given in the args array. |
| * |
| * @param object object on which to make the call |
| * @param name name of the method / procedure to call |
| * @param args the arguments to be given to the procedure |
| * |
| * @exception BSFException if anything goes wrong while eval'ing a BSFException is thrown. The reason indicates the problem. |
| */ |
| Object call(Object object, String name, Object[] args) throws BSFException; |
| |
| /** |
| * This is used by an application to compile an anonymous function. See comments in apply for more hdetails. |
| * |
| * @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 the CodeBuffer to compile into |
| * |
| * @exception BSFException if anything goes wrong while doin' it. |
| */ |
| void compileApply(String source, int lineNo, int columnNo, Object funcBody, Vector paramNames, Vector arguments, CodeBuffer cb) throws BSFException; |
| |
| /** |
| * This is used by an application to compile a value-returning expression. The expr may be string or some other type, depending on the language. The |
| * generated code is dumped into the {@code CodeBuffer}. |
| * |
| * @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 the CodeBuffer to compile into |
| * |
| * @exception BSFException if anything goes wrong while compiling a BSFException is thrown. The reason indicates the problem. |
| */ |
| void compileExpr(String source, int lineNo, int columnNo, Object expr, CodeBuffer cb) throws BSFException; |
| |
| /** |
| * This is used by an application to compile some script. The script may be string or some other type, depending on the language. The generated code is |
| * dumped into the {@code CodeBuffer}. |
| * |
| * @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 the CodeBuffer to compile into |
| * |
| * @exception BSFException if anything goes wrong while compiling a BSFException is thrown. The reason indicates the problem. |
| */ |
| void compileScript(String source, int lineNo, int columnNo, Object script, CodeBuffer cb) throws BSFException; |
| |
| /** |
| * 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. |
| * |
| * @param bean the bean to declare |
| * |
| * @exception BSFException if the engine cannot do this operation |
| */ |
| void declareBean(BSFDeclaredBean bean) throws BSFException; |
| |
| /** |
| * This is used by an application to evaluate an expression. The expression may be string or some other type, depending on the language. (For example, for |
| * BML it'll be an org.w3c.dom.Element object.) |
| * |
| * @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 eval'ing a BSFException is thrown. The reason indicates the problem. |
| */ |
| Object eval(String source, int lineNo, int columnNo, Object expr) throws BSFException; |
| |
| /** |
| * This is used by an application to execute some script. The expression may be string or some other type, depending on the language. Returns nothing but if |
| * something goes wrong it excepts (of course). |
| * |
| * @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 exec'ing a BSFException is thrown. The reason indicates the problem. |
| */ |
| void exec(String source, int lineNo, int columnNo, Object script) throws BSFException; |
| |
| /** |
| * This is used by an application to execute some script, as though one were interacting with the language in an interactive session. The expression may be |
| * string or some other type, depending on the language. Returns nothing but if something goes wrong it excepts (of course). |
| * |
| * @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 exec'ing a BSFException is thrown. The reason indicates the problem. |
| */ |
| void iexec(String source, int lineNo, int columnNo, Object script) throws BSFException; |
| |
| /** |
| * This method is used to initialize the engine right after construction. This method will be called before any calls to eval or call. At this time the |
| * engine should capture the current values of interesting properties from the manager. In the future, any changes to those will be mirrored to me by the |
| * manager via a property change event. |
| * |
| * @param mgr The BSFManager that's hosting this engine. |
| * @param lang Language string which this engine is handling. |
| * @param declaredBeans Vector of BSFDeclaredObject containing beans that should be declared into the language runtime at init time as best as possible. |
| * |
| * @exception BSFException if anything goes wrong while init'ing a BSFException is thrown. The reason indicates the problem. |
| */ |
| void initialize(BSFManager mgr, String lang, Vector declaredBeans) throws BSFException; |
| |
| /** |
| * Graceful termination |
| */ |
| void terminate(); |
| |
| /** |
| * Undeclare a previously declared bean. |
| * |
| * @param bean the bean to undeclare |
| * |
| * @exception BSFException if the engine cannot do this operation |
| */ |
| void undeclareBean(BSFDeclaredBean bean) throws BSFException; |
| } |