001: /*
002: * Copyright 2004,2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.apache.bsf;
018:
019: import java.beans.PropertyChangeListener;
020: import java.util.Vector;
021:
022: import org.apache.bsf.util.CodeBuffer;
023:
024: /**
025: * This is the view of a scripting engine assumed by the Bean Scripting
026: * Framework. This interface is used when an application decides to
027: * run some script under application control. (This is the reverse of
028: * the more common situation, which is that of the scripting language
029: * calling into the application.)
030: * <p>
031: * When a scripting engine is first fired up, the initialize()
032: * method is called right after construction.
033: * <p>
034: * A scripting engine must provide two access points for applications
035: * to call into them: via function calls and via expression evaluation.
036: * It must also support loading scripts.
037: * <p>
038: * A scripting engine is a property change listener and will be notified
039: * when any of the relevant properties of the manager change. (See
040: * BSFManager to see which of its properties are bound.)
041: *
042: * @author Sanjiva Weerawarana
043: * @author Matthew J. Duftler
044: */
045: public interface BSFEngine extends PropertyChangeListener {
046:
047: /**
048: * This is used by an application to invoke an anonymous function. An
049: * anonymous function is a multi-line script which when evaluated will
050: * produce a value. These are separated from expressions and scripts
051: * because the prior are spsed to be good 'ol expressions and scripts
052: * are not value returning. We allow anonymous functions to have parameters
053: * as well for completeness.
054: *
055: * @param source (context info) the source of this expression
056: * (e.g., filename)
057: * @param lineNo (context info) the line number in source for expr
058: * @param columnNo (context info) the column number in source for expr
059: * @param funcBody the multi-line, value returning script to evaluate
060: * @param paramNames the names of the parameters above assumes
061: * @param arguments values of the above parameters
062: *
063: * @exception BSFException if anything goes wrong while doin' it.
064: */
065: public Object apply(String source, int lineNo, int columnNo,
066: Object funcBody, Vector paramNames, Vector arguments)
067: throws BSFException;
068:
069: /**
070: * This is used by an application to call into the scripting engine
071: * to make a function/method call. The "object" argument is the object
072: * whose method is to be called, if that applies. For non-OO languages,
073: * this is typically ignored and should be given as null. For pretend-OO
074: * languages such as VB, this would be the (String) name of the object.
075: * The arguments are given in the args array.
076: *
077: * @param object object on which to make the call
078: * @param name name of the method / procedure to call
079: * @param args the arguments to be given to the procedure
080: *
081: * @exception BSFException if anything goes wrong while eval'ing a
082: * BSFException is thrown. The reason indicates the problem.
083: */
084: public Object call(Object object, String name, Object[] args)
085: throws BSFException;
086:
087: /**
088: * This is used by an application to compile an anonymous function. See
089: * comments in apply for more hdetails.
090: *
091: * @param source (context info) the source of this expression
092: * (e.g., filename)
093: * @param lineNo (context info) the line number in source for expr
094: * @param columnNo (context info) the column number in source for expr
095: * @param funcBody the multi-line, value returning script to evaluate
096: * @param paramNames the names of the parameters above assumes
097: * @param arguments values of the above parameters
098: * @param cb the CodeBuffer to compile into
099: *
100: * @exception BSFException if anything goes wrong while doin' it.
101: */
102: public void compileApply(String source, int lineNo, int columnNo,
103: Object funcBody, Vector paramNames, Vector arguments,
104: CodeBuffer cb) throws BSFException;
105:
106: /**
107: * This is used by an application to compile a value-returning expression.
108: * The expr may be string or some other type, depending on the language.
109: * The generated code is dumped into the <tt>CodeBuffer</tt>.
110: *
111: * @param source (context info) the source of this expression
112: * (e.g., filename)
113: * @param lineNo (context info) the line number in source for expr
114: * @param columnNo (context info) the column number in source for expr
115: * @param expr the expression to compile
116: * @param cb the CodeBuffer to compile into
117: *
118: * @exception BSFException if anything goes wrong while compiling a
119: * BSFException is thrown. The reason indicates the problem.
120: */
121: public void compileExpr(String source, int lineNo, int columnNo,
122: Object expr, CodeBuffer cb) throws BSFException;
123:
124: /**
125: * This is used by an application to compile some script. The
126: * script may be string or some other type, depending on the
127: * language. The generated code is dumped into the <tt>CodeBuffer</tt>.
128: *
129: * @param source (context info) the source of this script
130: * (e.g., filename)
131: * @param lineNo (context info) the line number in source for script
132: * @param columnNo (context info) the column number in source for script
133: * @param script the script to compile
134: * @param cb the CodeBuffer to compile into
135: *
136: * @exception BSFException if anything goes wrong while compiling a
137: * BSFException is thrown. The reason indicates the problem.
138: */
139: public void compileScript(String source, int lineNo, int columnNo,
140: Object script, CodeBuffer cb) throws BSFException;
141:
142: /**
143: * Declare a bean after the engine has been started. Declared beans
144: * are beans that are named and which the engine must make available
145: * to the scripts it runs in the most first class way possible.
146: *
147: * @param bean the bean to declare
148: *
149: * @exception BSFException if the engine cannot do this operation
150: */
151: public void declareBean(BSFDeclaredBean bean) throws BSFException;
152:
153: /**
154: * This is used by an application to evaluate an expression. The
155: * expression may be string or some other type, depending on the
156: * language. (For example, for BML it'll be an org.w3c.dom.Element
157: * object.)
158: *
159: * @param source (context info) the source of this expression
160: * (e.g., filename)
161: * @param lineNo (context info) the line number in source for expr
162: * @param columnNo (context info) the column number in source for expr
163: * @param expr the expression to evaluate
164: *
165: * @exception BSFException if anything goes wrong while eval'ing a
166: * BSFException is thrown. The reason indicates the problem.
167: */
168: public Object eval(String source, int lineNo, int columnNo,
169: Object expr) throws BSFException;
170:
171: /**
172: * This is used by an application to execute some script. The
173: * expression may be string or some other type, depending on the
174: * language. Returns nothing but if something goes wrong it excepts
175: * (of course).
176: *
177: * @param source (context info) the source of this expression
178: * (e.g., filename)
179: * @param lineNo (context info) the line number in source for expr
180: * @param columnNo (context info) the column number in source for expr
181: * @param script the script to execute
182: *
183: * @exception BSFException if anything goes wrong while exec'ing a
184: * BSFException is thrown. The reason indicates the problem.
185: */
186: public void exec(String source, int lineNo, int columnNo,
187: Object script) throws BSFException;
188:
189: /**
190: * This is used by an application to execute some script, as though
191: * one were interacting with the language in an interactive session.
192: * The expression may be string or some other type, depending on the
193: * language. Returns nothing but if something goes wrong it excepts (of
194: * course).
195: *
196: * @param source (context info) the source of this expression
197: * (e.g., filename)
198: * @param lineNo (context info) the line number in source for expr
199: * @param columnNo (context info) the column number in source for expr
200: * @param script the script to execute
201: *
202: * @exception BSFException if anything goes wrong while exec'ing a
203: * BSFException is thrown. The reason indicates the problem.
204: */
205: public void iexec(String source, int lineNo, int columnNo,
206: Object script) throws BSFException;
207:
208: /**
209: * This method is used to initialize the engine right after construction.
210: * This method will be called before any calls to eval or call. At this
211: * time the engine should capture the current values of interesting
212: * properties from the manager. In the future, any changes to those
213: * will be mirrored to me by the manager via a property change event.
214: *
215: * @param mgr The BSFManager that's hosting this engine.
216: * @param lang Language string which this engine is handling.
217: * @param declaredBeans Vector of BSFDeclaredObject containing beans
218: * that should be declared into the language runtime at init
219: * time as best as possible.
220: *
221: * @exception BSFException if anything goes wrong while init'ing a
222: * BSFException is thrown. The reason indicates the problem.
223: */
224: public void initialize(BSFManager mgr, String lang,
225: Vector declaredBeans) throws BSFException;
226:
227: /**
228: * Graceful termination
229: */
230: public void terminate();
231:
232: /**
233: * Undeclare a previously declared bean.
234: *
235: * @param bean the bean to undeclare
236: *
237: * @exception BSFException if the engine cannot do this operation
238: */
239: public void undeclareBean(BSFDeclaredBean bean) throws BSFException;
240: }
|