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;
57
58 import java.rmi.Remote;
59 import java.rmi.RemoteException;
60
61 /**
62 * Debug Manager.
63 *
64 * This is a service for remote debuggers to gain access
65 * to remote debugging services on language engines.
66 *
67 * Currently, there is only one debugger supported per
68 * engine. However, multiple debuggers may register for
69 * different engines. There may be more than one engine
70 * per language given than more than one BSFManager can
71 * be instanciated within a Java virtual machine.
72 *
73 * Each debugger (instance of BSFDebugger) should first
74 * register itself to a debug manager running in the Java
75 * virtual machine in which debugging is intended.
76 * A debugger registers for a specific language, such as
77 * JavaScript.
78 * As a consequence of registration, the debugger will be
79 * notified of already existing engines as well as any
80 * future creation or termination of engines for the
81 * relevant language.
82 * Upon this notification, the debugger can ask the engine
83 * for its language-specific debugging interface and then
84 * register the debugger callbacks for debugging events.
85 * See org.apache.bsf.debug.jsdi.Callbacks for the JavaScript
86 * example.
87 *
88 * The debugging framework works on the concept of documents
89 * and breakpoints. A document is basically a container for
90 * scripts (be them functions, expressions, or actual scripts).
91 * These scripts are subsets of the document. Documents are
92 * declared to the BSFEngine when evaluating or executing some
93 * scripts. Scripts are defined as a range, either line or
94 * character range in their document. Correspondingly,
95 * breakpoints can be set at lines or offsets in a document.
96 * The line numbers and offsets are global numbers with respect
97 * to the entire document.
98 *
99 * So for instance, in a JSP with JavaScript, the document is
100 * the JSP file. The scripts are the tags containing JavaScript
101 * code. The Jasper compiler extracts the scripts from the JSP
102 * and produces a Servlet that will provide these scripts to
103 * the BSF JavaScript engine at execution time.
104 * Each of these scripts start at a given line, offsets are
105 * not supported. Breakpoints can therefore be set at lines
106 * belonging to these JavaScript scripts, considering line
107 * numbers at the document level, that is, the entire JSP file.
108 *
109 */
110 public interface BSFDebugManager extends Remote {
111
112 /**
113 * Determine the language of a script file by looking at the file
114 * extension.
115 *
116 * @param filename the name of the file
117 *
118 * @return the scripting language the file is in if the file extension
119 * is known to me (must have been registered via
120 * registerScriptingEngine).
121 *
122 * @exception BSFException if file's extension is unknown.
123 */
124 public String getLangFromFilename(String fileName) throws RemoteException;
125
126 /**
127 * Determine whether a language is registered.
128 *
129 * @param lang string identifying a language
130 *
131 * @return true iff it is
132 */
133 public boolean isLanguageRegistered(String lang) throws RemoteException;
134
135 /**
136 * Breakpoints are placed within documents either at a specific line
137 * or offset. While breakpoints can be set at lines and offsets in
138 * the same document, there is no conversions between lines and offsets.
139 * Some engines may support only offsets or only lines and therefore
140 * some breakpoints may be ignored.
141 *
142 * Placing a breakpoint is local to a debugger connection.
143 * In other words, breakpoints set by other debuggers are not visible
144 * to a given debugger.
145 *
146 * Breakpoints are given identifiers so to make easier for debuggers
147 * to manipulate breakpoints. Identifiers are allocated by the debugger;
148 * they must be unique for the entire session between that debugger
149 * and the debug manager.
150 *
151 */
152 public void placeBreakpointAtLine(int bpid, String docname, int lineno)
153 throws RemoteException;
154 public void placeBreakpointAtOffset(int bpid, String docname, int offset)
155 throws RemoteException;
156
157 /**
158 * Allows to remove a breakpoint.
159 */
160 public void removeBreakpoint(String docname, int brkptid)
161 throws RemoteException;
162
163 /**
164 * Allows setting entry/exit mode
165 */
166 public void setEntryExit(String docname, boolean on)
167 throws RemoteException;
168
169 /**
170 * Allows a debugger to ask if the engine for a given language
171 * will support either line or offset breakpoints.
172 * Note: this will most likely provoke the loading of the engine.
173 */
174 public boolean supportBreakpointAtOffset(String lang)
175 throws RemoteException;
176
177 public boolean supportBreakpointAtLine(String lang)
178 throws RemoteException;
179
180 /**
181 * Register a debugger for a scripting engine.
182 *
183 * @param lang string identifying language
184 * @exception RemoteException if the language is unknown (i.e., if it
185 * has not been registered) with a reason of
186 * REASON_UNKNOWN_LANGUAGE. If the language is known but
187 * if the interface can't be created for some reason, then
188 * the reason is set to REASON_OTHER_ERROR and the actual
189 * exception is passed on as well.
190 */
191 public void registerDebugger(String lang, BSFDebugger debugger)
192 throws RemoteException;
193
194 public void unregisterDebugger(String lang)
195 throws RemoteException;
196 }