001: /*BEGIN_COPYRIGHT_BLOCK
002: *
003: * Copyright (c) 2001-2007, JavaPLT group at Rice University (javaplt@rice.edu)
004: * All rights reserved.
005: *
006: * Redistribution and use in source and binary forms, with or without
007: * modification, are permitted provided that the following conditions are met:
008: * * Redistributions of source code must retain the above copyright
009: * notice, this list of conditions and the following disclaimer.
010: * * Redistributions in binary form must reproduce the above copyright
011: * notice, this list of conditions and the following disclaimer in the
012: * documentation and/or other materials provided with the distribution.
013: * * Neither the names of DrJava, the JavaPLT group, Rice University, nor the
014: * names of its contributors may be used to endorse or promote products
015: * derived from this software without specific prior written permission.
016: *
017: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
018: * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
019: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
020: * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
021: * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
022: * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
023: * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
024: * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
025: * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
026: * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
027: * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
028: *
029: * This software is Open Source Initiative approved Open Source Software.
030: * Open Source Initative Approved is a trademark of the Open Source Initiative.
031: *
032: * This file is part of DrJava. Download the current version of this project
033: * from http://www.drjava.org/ or http://sourceforge.net/projects/drjava/
034: *
035: * END_COPYRIGHT_BLOCK*/
036:
037: package edu.rice.cs.drjava.model.debug;
038:
039: import java.util.Vector;
040: import edu.rice.cs.drjava.model.DocumentRegion;
041: import edu.rice.cs.drjava.model.OpenDefinitionsDocument;
042:
043: /** Interface for any debugger implementation to be used by DrJava.
044: *
045: * @version $Id: Debugger.java 4255 2007-08-28 19:17:37Z mgricken $
046: */
047: public interface Debugger {
048:
049: public static enum StepType {
050: STEP_INTO, STEP_OVER, STEP_OUT;
051: }
052:
053: /** Adds a listener to this Debugger.
054: * @param listener a listener that reacts on events generated by the Debugger
055: */
056: public void addListener(DebugListener listener);
057:
058: /** Removes a listener to this Debugger.
059: * @param listener listener to remove
060: */
061: public void removeListener(DebugListener listener);
062:
063: /** Returns whether the debugger can be used in this copy of DrJava. This does not indicate whether it is ready to be
064: * used, which is indicated by isReady().
065: */
066: public boolean isAvailable();
067:
068: public DebugModelCallback callback();
069:
070: /** Attaches the debugger to the Interactions JVM to prepare for debugging. */
071: public void startUp() throws DebugException;
072:
073: /** Disconnects the debugger from the Interactions JVM and cleans up any state. */
074: public void shutdown();
075:
076: /** Returns whether the debugger is enabled. */
077: public boolean isReady();
078:
079: // /** Suspends execution of the thread referenced by d */
080: // public void suspend(DebugThreadData d) throws DebugException;
081:
082: // /** Suspends all the threads in the VM the debugger is attached to. */
083: // public void suspendAll();
084:
085: /** Sets the current thread we are debugging to the thread referenced by d. */
086: public void setCurrentThread(DebugThreadData d)
087: throws DebugException;
088:
089: /** Resumes execution of the currently loaded document. */
090: public void resume() throws DebugException;
091:
092: /** Resumes execution of the given thread.
093: * @param data the DebugThreadData representing the thread to resume
094: */
095: public void resume(DebugThreadData data) throws DebugException;
096:
097: /** Steps the execution of the currently loaded document. */
098: public void step(StepType type) throws DebugException;
099:
100: /** Adds a watch on the given field or variable.
101: * @param field the name of the field we will watch
102: */
103: public void addWatch(String field) throws DebugException;
104:
105: /** Removes any watches on the given field or variable.
106: * @param field the name of the field we will watch
107: */
108: public void removeWatch(String field) throws DebugException;
109:
110: /** Removes the watch at the given index.
111: * @param index Index of the watch to remove
112: */
113: public void removeWatch(int index) throws DebugException;
114:
115: /** Removes all watches on existing fields and variables. */
116: public void removeAllWatches() throws DebugException;
117:
118: /** Toggles whether a breakpoint is set at the given line in the given document.
119: * @param doc Document in which to set or remove the breakpoint
120: * @param offset Start offset on the line to set the breakpoint
121: * @param lineNum Line on which to set or remove the breakpoint, >=1
122: * @param isEnabled {@code true} if this breakpoint should be enabled
123: */
124: public void toggleBreakpoint(OpenDefinitionsDocument doc,
125: int offset, int lineNum, boolean isEnabled)
126: throws DebugException;
127:
128: /** Sets a breakpoint.
129: * @param breakpoint The new breakpoint to set
130: */
131: public void setBreakpoint(final Breakpoint breakpoint)
132: throws DebugException;
133:
134: /** Removes a breakpoint. Called from ToggleBreakpoint -- even with BPs that are not active.
135: * @param breakpoint The breakpoint to remove.
136: */
137: public void removeBreakpoint(final Breakpoint breakpoint)
138: throws DebugException;
139:
140: /** Returns all currently watched fields and variables. */
141: public Vector<DebugWatchData> getWatches() throws DebugException;
142:
143: /** Returns a Vector of ThreadData. */
144: public Vector<DebugThreadData> getCurrentThreadData()
145: throws DebugException;
146:
147: /** Returns a Vector of StackData for the current thread. */
148: public Vector<DebugStackData> getCurrentStackFrameData()
149: throws DebugException;
150:
151: /**
152: * @return true if there are any threads in the program currently being
153: * debugged which have been suspended (by the user or by hitting a breakpoint).
154: */
155: public boolean hasSuspendedThreads() throws DebugException;
156:
157: /**
158: * Returns whether the thread the debugger is tracking is now running.
159: */
160: public boolean hasRunningThread() throws DebugException;
161:
162: /**
163: * Returns whether the debugger's current thread is suspended.
164: */
165: public boolean isCurrentThreadSuspended() throws DebugException;
166:
167: /**
168: * scrolls to the source indicated by the given DebugStackData
169: * @param data the DebugStackData representing the source location
170: */
171: public void scrollToSource(DebugStackData data)
172: throws DebugException;
173:
174: /**
175: * scrolls to the source indicated by the given Breakpoint
176: * @param bp the Breakpoint representing the source location
177: */
178: public void scrollToSource(Breakpoint bp);
179:
180: /**
181: * Gets the Breakpoint object at the specified line in the given class.
182: * If the given data do not correspond to an actual breakpoint, null is returned.
183: * @param line the line number of the breakpoint
184: * @param className the name of the class the breakpoint's in
185: * @return the Breakpoint corresponding to the line and className, or null if
186: * there is no such breakpoint.
187: */
188: public Breakpoint getBreakpoint(int line, String className)
189: throws DebugException;
190: }
|