KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > bsf > debug > jsdi > JsEngine


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.debug.jsdi;
57
58 import java.rmi.Remote JavaDoc;
59 import java.rmi.RemoteException JavaDoc;
60
61 /**
62  * Represents a remote engine as seen from the debugger.
63  * It matches the notion of global object in JavaScript
64  * specification. In other words, a JsEngine is an
65  * execution context rather than an explicit engine.
66  * This also means that a JsEngine is not multi-threaded,
67  * there is only one execution being carried.
68  * Hence, there is only one stack of JsContext for a
69  * JsEngine. The stack is only accesible if the engine is
70  * in a callback mode to the debugger, that is, the
71  * execution is stopped at a breakpoint or after a stepping
72  * order has completed.
73  *
74  */
75 public interface JsEngine extends Remote JavaDoc {
76
77     /**
78      * Allows the client debugger to poll the connection.
79      */
80     public boolean poll() throws RemoteException JavaDoc;
81
82     /**
83      * Set the associated debugger.
84      * @param debugger the debugger to be used on callbacks from
85      * the engine.
86      */
87     public void setDebugger(JsCallbacks debugger) throws RemoteException JavaDoc;
88
89     /**
90      * Return the current debugger.
91      * @return the debugger, or null if none is attached.
92      */
93     public JsCallbacks getDebugger() throws RemoteException JavaDoc;
94
95
96     /**
97      * Allow the debugger to evaluate an expression
98      * within the current context.
99      */
100     public Object JavaDoc eval(String JavaDoc docname, String JavaDoc fnOrScript, int lineno)
101         throws RemoteException JavaDoc;
102
103     /**
104      * Returns the count of JsContext on the current stack.
105      * This is a valid call only if the engine is stopped
106      * in a callback to the debugger (breakpoint or stepping
107      * completed).
108      */
109     public int getContextCount()
110                 throws RemoteException JavaDoc;
111
112         /**
113          * Returns name of the thread currently running in the engine
114          */
115         public String JavaDoc getThread()
116                 throws RemoteException JavaDoc;
117
118         /**
119          * Returns name of the ThreadGroup of the thread currently running in the engine
120          */
121         public String JavaDoc getThreadGroup()
122                 throws RemoteException JavaDoc;
123
124     /**
125      * Returns the JsContext at a certain depth.
126      * Depth zero is the top of the stack, that is,
127      * the inner execution context.
128      *
129      * This is a valid call only if the engine is stopped
130      * in a callback to the debugger (breakpoint or stepping
131      * completed).
132      */
133     public JsContext getContext(int depth)
134         throws RemoteException JavaDoc;
135     /**
136      * Any execution in JavaScript happen with respect to a
137      * global object, sort of the top-level name space for
138      * properties. This is global object return by this call.
139      */
140     public JsObject getGlobalObject()
141         throws RemoteException JavaDoc;
142
143     /**
144      * As per ECMA specification, each JavaScript execution
145      * defines a unique object for the undefined value.
146      */
147     public JsObject getUndefinedValue()
148         throws RemoteException JavaDoc;
149     
150     /**
151      * Stepping commands:
152      * run: resume execution until it finishes or a breakpoint is hit.
153      * stepIn: steps to the next statement, considering callee's statement if any.
154      * stepOut: steps until the current JsContext exits.
155      * stepOver: steps to the next statement within the same JsContext.
156      */
157     public void run() throws RemoteException JavaDoc;
158     public void stepIn() throws RemoteException JavaDoc;
159     public void stepOut() throws RemoteException JavaDoc;
160     public void stepOver() throws RemoteException JavaDoc;
161
162     public boolean isSuspended() throws RemoteException JavaDoc;
163
164 }
165
Popular Tags