BSFEngine


1   /*
2    * The Apache Software License, Version 1.1
3    *
4    * Copyright (c) 2002 The Apache Software Foundation.  All rights
5    * reserved.
6    *
7    * Redistribution and use in source and binary forms, with or without
8    * modification, are permitted provided that the following conditions
9    * are met:
10   *
11   * 1. Redistributions of source code must retain the above copyright
12   *    notice, this list of conditions and the following disclaimer.
13   *
14   * 2. Redistributions in binary form must reproduce the above copyright
15   *    notice, this list of conditions and the following disclaimer in
16   *    the documentation and/or other materials provided with the
17   *    distribution.
18   *
19   * 3. The end-user documentation included with the redistribution, if
20   *    any, must include the following acknowlegement:
21   *       "This product includes software developed by the
22   *        Apache Software Foundation (http://www.apache.org/)."
23   *    Alternately, this acknowlegement may appear in the software itself,
24   *    if and wherever such third-party acknowlegements normally appear.
25   *
26   * 4. The names "Apache BSF", "Apache", and "Apache Software Foundation"
27   *    must not be used to endorse or promote products derived from
28   *    this software without prior written permission. For written
29   *    permission, please contact apache@apache.org.
30   *
31   * 5. Products derived from this software may not be called "Apache"
32   *    nor may "Apache" appear in their names without prior written
33   *    permission of the Apache Group.
34   *
35   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
36   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
37   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
38   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
39   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
40   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
41   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
42   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
43   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
44   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
45   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
46   * SUCH DAMAGE.
47   * ====================================================================
48   *
49   * This software consists of voluntary contributions made by many individuals
50   * on behalf of the Apache Software Foundation and was originally created by
51   * Sanjiva Weerawarana and others at International Business Machines
52   * Corporation. For more information on the Apache Software Foundation,
53   * please see <http://www.apache.org/>.
54   */
55  
56  package org.apache.bsf;
57  
58  import java.util.Vector  ;
59  import java.beans.PropertyChangeListener  ;
60  
61  import org.apache.bsf.util.CodeBuffer;
62  
63  /**
64   * This is the view of a scripting engine assumed by the bean scripting
65   * framework. This interface is used when an application decides to
66   * run some script under application control. (This is the reverse of
67   * the more common situation, which is that of the scripting language
68   * calling into the application.)
69   * <p>
70   * When a scripting engine is first fired up, the initialize() 
71   * method is called right after construction.
72   * <p>
73   * A scripting engine must provide two access points for applications
74   * to call into them: via function calls and via expression evaluation.
75   * It must also support loading scripts.
76   * <p>
77   * A scripting engine is a property change listener and will be notified
78   * when any of the relevant properties of the manager change. (See
79   * BSFManager to see which of its properties are bound.)
80   *
81   * @author  Sanjiva Weerawarana
82   * @author  Matthew J. Duftler
83   */
84  public interface BSFEngine extends PropertyChangeListener   {
85      
86      /**
87       * Notify the engine that the connection to its
88       * debugger has been lost.
89       */
90      public void disconnectedDebuggerNotify();
91  
92      /** 
93       * The language-specific interface on the engine
94       * for debugging...
95       */
96      public Object   getSpecificDebuggingInterface();
97  
98      /**
99       */
100     public void placeBreakpointAtLine(int brkptid, String   docname, int lineno)
101         throws BSFException;
102 
103     public void placeBreakpointAtOffset(int brkptid, String   docname, int offset)
104         throws BSFException;
105 
106     public void removeBreakpoint(String   docname, int brkptid)
107         throws BSFException;
108 
109         public void setEntryExit(String   docname, boolean on)
110                 throws BSFException;
111         
112     /**
113      * This is used by an application to invoke an anonymous function. An
114      * anonymous function is a multi-line script which when evaluated will
115      * produce a value. These are separated from expressions and scripts
116      * because the prior are spsed to be good 'ol expressions and scripts
117      * are not value returning. We allow anonymous functions to have parameters
118      * as well for completeness.
119      *
120      * @param source   (context info) the source of this expression
121      *                 (e.g., filename)
122      * @param lineNo   (context info) the line number in source for expr
123      * @param columnNo (context info) the column number in source for expr
124      * @param funcBody the multi-line, value returning script to evaluate
125      * @param paramNames the names of the parameters above assumes
126      * @param arguments values of the above parameters
127      *
128      * @exception BSFException if anything goes wrong while doin' it.
129      */
130     public Object   apply(
131         String   source,
132         int lineNo,
133         int columnNo,
134         Object   funcBody,
135         Vector   paramNames,
136         Vector   arguments)
137         throws BSFException;
138     /**
139      * This is used by an application to call into the scripting engine
140      * to make a function/method call. The "object" argument is the object
141      * whose method is to be called, if that applies. For non-OO languages,
142      * this is typically ignored and should be given as null. For pretend-OO
143      * languages such as VB, this would be the (String) name of the object.
144      * The arguments are given in the args array.
145      *
146      * @param object object on which to make the call
147      * @param name   name of the method / procedure to call
148      * @param args   the arguments to be given to the procedure
149      *
150      * @exception BSFException if anything goes wrong while eval'ing a
151      *            BSFException is thrown. The reason indicates the problem.
152      */
153     public Object   call(Object   object, String   name, Object  [] args)
154         throws BSFException;
155     /**
156      * This is used by an application to compile an anonymous function. See
157      * comments in apply for more hdetails.
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 funcBody the multi-line, value returning script to evaluate
164      * @param paramNames the names of the parameters above assumes
165      * @param arguments values of the above parameters
166      * @param cb       the CodeBuffer to compile into
167      *
168      * @exception BSFException if anything goes wrong while doin' it.
169      */
170     public void compileApply(
171         String   source,
172         int lineNo,
173         int columnNo,
174         Object   funcBody,
175         Vector   paramNames,
176         Vector   arguments,
177         CodeBuffer cb)
178         throws BSFException;
179     /**
180      * This is used by an application to compile a value-returning expression.
181      * The expr may be string or some other type, depending on the language.
182      * The generated code is dumped into the <tt>CodeBuffer</tt>.
183      *
184      * @param source   (context info) the source of this expression
185      *                 (e.g., filename)
186      * @param lineNo   (context info) the line number in source for expr
187      * @param columnNo (context info) the column number in source for expr
188      * @param expr     the expression to compile
189      * @param cb       the CodeBuffer to compile into
190      *
191      * @exception BSFException if anything goes wrong while compiling a
192      *            BSFException is thrown. The reason indicates the problem.
193      */
194     public void compileExpr(
195         String   source,
196         int lineNo,
197         int columnNo,
198         Object   expr,
199         CodeBuffer cb)
200         throws BSFException;
201     /**
202      * This is used by an application to compile some script. The
203      * script may be string or some other type, depending on the
204      * language. The generated code is dumped into the <tt>CodeBuffer</tt>.
205      *
206      * @param source   (context info) the source of this script
207      *                 (e.g., filename)
208      * @param lineNo   (context info) the line number in source for script
209      * @param columnNo (context info) the column number in source for script
210      * @param script   the script to compile
211      * @param cb       the CodeBuffer to compile into
212      *
213      * @exception BSFException if anything goes wrong while compiling a
214      *            BSFException is thrown. The reason indicates the problem.
215      */
216     public void compileScript(
217         String   source,
218         int lineNo,
219         int columnNo,
220         Object   script,
221         CodeBuffer cb)
222         throws BSFException;
223     /**
224      * Declare a bean after the engine has been started. Declared beans
225      * are beans that are named and which the engine must make available
226      * to the scripts it runs in the most first class way possible.
227      *
228      * @param bean the bean to declare
229      *
230      * @exception BSFException if the engine cannot do this operation
231      */
232     public void declareBean(BSFDeclaredBean bean) throws BSFException;
233     /**
234      * This is used by an application to evaluate an expression. The
235      * expression may be string or some other type, depending on the
236      * language. (For example, for BML it'll be an org.w3c.dom.Element
237      * object.)
238      *
239      * @param source   (context info) the source of this expression
240      *                 (e.g., filename)
241      * @param lineNo   (context info) the line number in source for expr
242      * @param columnNo (context info) the column number in source for expr
243      * @param expr     the expression to evaluate
244      *
245      * @exception BSFException if anything goes wrong while eval'ing a
246      *            BSFException is thrown. The reason indicates the problem.
247      */
248     public Object   eval(String   source, int lineNo, int columnNo, Object   expr)
249         throws BSFException;
250     /**
251      * This is used by an application to execute some script. The
252      * expression may be string or some other type, depending on the
253      * language. Returns nothing but if something goes wrong it excepts
254      * (of course).
255      *
256      * @param source   (context info) the source of this expression
257      *                 (e.g., filename)
258      * @param lineNo   (context info) the line number in source for expr
259      * @param columnNo (context info) the column number in source for expr
260      * @param script   the script to execute
261      *
262      * @exception BSFException if anything goes wrong while exec'ing a
263      *            BSFException is thrown. The reason indicates the problem.
264      */
265     public void exec(String   source, int lineNo, int columnNo, Object   script)
266         throws BSFException;
267         
268     /**
269      * This method is used to initialize the engine right after construction.
270      * This method will be called before any calls to eval or call. At this
271      * time the engine should capture the current values of interesting
272      * properties from the manager. In the future, any changes to those 
273      * will be mirrored to me by the manager via a property change event.
274      * 
275      * @param mgr           The BSFManager that's hosting this engine.
276      * @param lang          Language string which this engine is handling.
277      * @param declaredBeans Vector of BSFDeclaredObject containing beans
278      *        that should be declared into the language runtime at init
279      *        time as best as possible.
280      *
281      * @exception BSFException if anything goes wrong while init'ing a
282      *            BSFException is thrown. The reason indicates the problem.
283      */
284     public void initialize(BSFManager mgr, String   lang, Vector   declaredBeans)
285         throws BSFException;
286     /**
287      * Graceful termination
288      */
289     public void terminate();
290     /**
291      * Undeclare a previously declared bean.
292      *
293      * @param bean the bean to undeclare
294      *
295      * @exception BSFException if the engine cannot do this operation
296      */
297     public void undeclareBean(BSFDeclaredBean bean) throws BSFException;
298 }
299
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags