Save This Page
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;
59 import java.rmi.RemoteException;
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 {
76
77 /**
78 * Allows the client debugger to poll the connection.
79 */
80 public boolean poll() throws RemoteException;
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;
88
89 /**
90 * Return the current debugger.
91 * @return the debugger, or null if none is attached.
92 */
93 public JsCallbacks getDebugger() throws RemoteException;
94
95
96 /**
97 * Allow the debugger to evaluate an expression
98 * within the current context.
99 */
100 public Object eval(String docname, String fnOrScript, int lineno)
101 throws RemoteException;
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;
111
112 /**
113 * Returns name of the thread currently running in the engine
114 */
115 public String getThread()
116 throws RemoteException;
117
118 /**
119 * Returns name of the ThreadGroup of the thread currently running in the engine
120 */
121 public String getThreadGroup()
122 throws RemoteException;
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;
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;
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;
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;
158 public void stepIn() throws RemoteException;
159 public void stepOut() throws RemoteException;
160 public void stepOver() throws RemoteException;
161
162 public boolean isSuspended() throws RemoteException;
163
164 }