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  ;
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 }
197
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags