KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > bsf > debug > BSFDebugManager


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 JavaDoc;
59 import java.rmi.RemoteException JavaDoc;
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 JavaDoc {
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 JavaDoc getLangFromFilename(String JavaDoc fileName) throws RemoteException JavaDoc;
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 JavaDoc lang) throws RemoteException JavaDoc;
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 JavaDoc docname, int lineno)
153         throws RemoteException JavaDoc;
154     public void placeBreakpointAtOffset(int bpid, String JavaDoc docname, int offset)
155         throws RemoteException JavaDoc;
156
157     /**
158     * Allows to remove a breakpoint.
159     */

160     public void removeBreakpoint(String JavaDoc docname, int brkptid)
161         throws RemoteException JavaDoc;
162
163         /**
164         * Allows setting entry/exit mode
165         */

166         public void setEntryExit(String JavaDoc docname, boolean on)
167                 throws RemoteException JavaDoc;
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 JavaDoc lang)
175         throws RemoteException JavaDoc;
176
177     public boolean supportBreakpointAtLine(String JavaDoc lang)
178         throws RemoteException JavaDoc;
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 JavaDoc lang, BSFDebugger debugger)
192         throws RemoteException JavaDoc;
193     
194     public void unregisterDebugger(String JavaDoc lang)
195         throws RemoteException JavaDoc;
196 }
197
Popular Tags