| /* |
| * 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.) |
| * |
| * @author Sanjiva Weerawarana |
| * @author Matthew J. Duftler |
| */ |
| 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. |
| */ |
| public 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. |
| */ |
| public 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. |
| */ |
| public 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 <tt>CodeBuffer</tt>. |
| * |
| * @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. |
| */ |
| public 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 <tt>CodeBuffer</tt>. |
| * |
| * @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. |
| */ |
| public 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 |
| */ |
| public 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. |
| */ |
| public 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. |
| */ |
| public 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. |
| */ |
| public 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. |
| */ |
| public void initialize(BSFManager mgr, String lang, Vector declaredBeans) |
| throws BSFException; |
| /** |
| * Graceful termination |
| */ |
| public void terminate(); |
| /** |
| * Undeclare a previously declared bean. |
| * |
| * @param bean the bean to undeclare |
| * |
| * @exception BSFException if the engine cannot do this operation |
| */ |
| public void undeclareBean(BSFDeclaredBean bean) throws BSFException; |
| } |