edu.rice.cs.drjava.model.debug.jpda
Class JPDADebugger

java.lang.Object
  edu.rice.cs.drjava.model.debug.jpda.JPDADebugger

All Implemented Interfaces:

Debugger

public class JPDADebugger
extends Object
implements Debugger

An integrated debugger which attaches to the Interactions JVM using Sun's Java Platform Debugger Architecture (JPDA/JDI) interface. Every public method in this class throws an llegalStateException if it is called while the debugger is not active, except for isAvailable, isReady, and startUp. Public methods also throw a DebugException if the EventHandlerThread has caught an exception.

Version:

$Id: JPDADebugger.java 4691 2008-12-02 23:33:27Z dlsmith $

Nested Class Summary

Nested classes/interfaces inherited from interface edu.rice.cs.drjava.model.debug.Debugger

Debugger.StepType

Constructor Summary

JPDADebugger(GlobalModel model)
Builds a new JPDADebugger to debug code in the Interactions JVM, using the JPDA/JDI interfaces.

Method Summary

void	addListener(DebugListener listener) Adds a listener to this JPDADebugger.
void	addWatch(String field) Adds a watch on the given field or variable.
DebugModelCallback	callback()
Breakpoint	getBreakpoint(int line, String className) Gets the Breakpoint object at the specified line in the given class.
ArrayList<DebugStackData>	getCurrentStackFrameData() Returns a Vector of DebugStackData for the current suspended thread.
ArrayList<DebugThreadData>	getCurrentThreadData() Returns a list of all threads being tracked by the debugger.
ArrayList<DebugWatchData>	getWatches() Returns all currently watched fields and variables.
boolean	hasRunningThread() Returns whether the thread the debugger is tracking is now running.
boolean	hasSuspendedThreads() Returns whether the debugger currently has any suspended threads.
boolean	isAvailable() Returns whether the debugger is available in this copy of DrJava.
boolean	isCurrentThreadSuspended() Returns whether the debugger's current thread is suspended.
boolean	isReady() Returns whether the debugger is currently enabled.
void	notifyBreakpointChange(Breakpoint breakpoint) Enable or disable the specified breakpoint.
OpenDefinitionsDocument	preloadDocument(com.sun.jdi.Location location) Return the document associated with this location.
void	removeAllWatches() Removes all watches on existing fields and variables.
void	removeBreakpoint(Breakpoint bp) Removes a breakpoint.
void	removeListener(DebugListener listener) Removes a listener to this JPDADebugger.
void	removeWatch(int index) Removes the watch at the given index.
void	removeWatch(String field) Removes any watches on the given field or variable.
void	resume() Resumes the thread currently being debugged, copying back all variables from the current debug interpreter.
void	resume(DebugThreadData threadData) Resumes the given thread, copying back any variables from its associated debug interpreter.
void	scrollToSource(Breakpoint bp) Scrolls to the source of the given breakpoint.
void	scrollToSource(DebugStackData stackData) Scrolls to the source location specified by the the debug stack data.
void	setBreakpoint(Breakpoint breakpoint) Sets a breakpoint.
void	setCurrentThread(DebugThreadData threadData) Sets the notion of current thread to the one contained in threadData.
void	shutdown() Disconnects the debugger from the Interactions JVM and cleans up any state.
void	startUp() Attaches the debugger to the Interactions JVM to prepare for debugging.
void	step(Debugger.StepType type) Steps the execution of the currently loaded document.
boolean	toggleBreakpoint(OpenDefinitionsDocument doc, int offset, int lineNum, boolean isEnabled) Toggles whether a breakpoint is set at the given line in the given document.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JPDADebugger

public JPDADebugger(GlobalModel model)

Builds a new JPDADebugger to debug code in the Interactions JVM, using the JPDA/JDI interfaces. Does not actually connect to the interpreterJVM until startUp().

Method Detail

addListener

public void addListener(DebugListener listener)

Adds a listener to this JPDADebugger.

Specified by:

addListener in interface Debugger

Parameters:

listener - a listener that reacts on events generated by the JPDADebugger

removeListener

public void removeListener(DebugListener listener)

Removes a listener to this JPDADebugger.

Specified by:

removeListener in interface Debugger

Parameters:

listener - listener to remove

isAvailable

public boolean isAvailable()

Returns whether the debugger is available in this copy of DrJava. This method does not indicate whether the debugger is ready to be used, which is indicated by isReady().

Specified by:

isAvailable in interface Debugger

callback

public DebugModelCallback callback()

Specified by:

callback in interface Debugger

isReady

public boolean isReady()

Returns whether the debugger is currently enabled.

Specified by:

isReady in interface Debugger

startUp

public void startUp()
             throws DebugException

Attaches the debugger to the Interactions JVM to prepare for debugging. Only runs in event thread.

Specified by:

startUp in interface Debugger

Throws:

DebugException

shutdown

public void shutdown()

Disconnects the debugger from the Interactions JVM and cleans up any state.

Specified by:

shutdown in interface Debugger

Throws:

IllegalStateException - if debugger is not ready

setCurrentThread

public void setCurrentThread(DebugThreadData threadData)
                      throws DebugException

Sets the notion of current thread to the one contained in threadData. The thread must be suspended. (Note: the intention is for this method to suspend the thread if necessary, but this is not yet implemented. The catch is that any manually suspended threads won't cooperate with the debug interpreters; the thread must be suspended by a breakpoint or step.)

Specified by:

setCurrentThread in interface Debugger

Parameters:

threadData - The Thread to set as current.

Throws:

IllegalStateException - if debugger is not ready

IllegalArgumentException - if threadData is null or not suspended

DebugException

hasSuspendedThreads

public boolean hasSuspendedThreads()
                            throws DebugException

Returns whether the debugger currently has any suspended threads.

Specified by:

hasSuspendedThreads in interface Debugger

Returns:

true if there are any threads in the program currently being debugged which have been suspended (by the user or by hitting a breakpoint).

Throws:

DebugException

isCurrentThreadSuspended

public boolean isCurrentThreadSuspended()
                                 throws DebugException

Returns whether the debugger's current thread is suspended.

Specified by:

isCurrentThreadSuspended in interface Debugger

Throws:

DebugException

hasRunningThread

public boolean hasRunningThread()
                         throws DebugException

Returns whether the thread the debugger is tracking is now running.

Specified by:

hasRunningThread in interface Debugger

Throws:

DebugException

resume

public void resume()
            throws DebugException

Resumes the thread currently being debugged, copying back all variables from the current debug interpreter.

Specified by:

resume in interface Debugger

Throws:

DebugException

resume

public void resume(DebugThreadData threadData)
            throws DebugException

Resumes the given thread, copying back any variables from its associated debug interpreter.

Specified by:

resume in interface Debugger

Parameters:

threadData - Thread to resume

Throws:

DebugException

step

public void step(Debugger.StepType type)
          throws DebugException

Steps the execution of the currently loaded document.

Specified by:

step in interface Debugger

Throws:

DebugException

addWatch

public void addWatch(String field)
              throws DebugException

Adds a watch on the given field or variable.

Specified by:

addWatch in interface Debugger

Parameters:

field - the name of the field we will watch

Throws:

DebugException

removeWatch

public void removeWatch(String field)
                 throws DebugException

Removes any watches on the given field or variable. Has no effect if the given field is not being watched.

Specified by:

removeWatch in interface Debugger

Parameters:

field - the name of the field we will watch

Throws:

DebugException

removeWatch

public void removeWatch(int index)
                 throws DebugException

Removes the watch at the given index.

Specified by:

removeWatch in interface Debugger

Parameters:

index - Index of the watch to remove

Throws:

DebugException

removeAllWatches

public void removeAllWatches()
                      throws DebugException

Removes all watches on existing fields and variables.

Specified by:

removeAllWatches in interface Debugger

Throws:

DebugException

notifyBreakpointChange

public void notifyBreakpointChange(Breakpoint breakpoint)

Enable or disable the specified breakpoint.

Parameters:

breakpoint - breakpoint to change

toggleBreakpoint

public boolean toggleBreakpoint(OpenDefinitionsDocument doc,
                                int offset,
                                int lineNum,
                                boolean isEnabled)
                         throws DebugException

Toggles whether a breakpoint is set at the given line in the given document.

Specified by:

toggleBreakpoint in interface Debugger

Parameters:

doc - Document in which to set or remove the breakpoint

offset - Start offset on the line to set the breakpoint

lineNum - Line on which to set or remove the breakpoint, >=1

isEnabled - true if this breakpoint should be enabled

Returns:

true if breakpoint is set

Throws:

DebugException

setBreakpoint

public void setBreakpoint(Breakpoint breakpoint)
                   throws DebugException

Sets a breakpoint.

Specified by:

setBreakpoint in interface Debugger

Parameters:

breakpoint - The new breakpoint to set

Throws:

DebugException

removeBreakpoint

public void removeBreakpoint(Breakpoint bp)
                      throws DebugException

Removes a breakpoint. Called from toggleBreakpoint -- even with BPs that are not active.

Specified by:

removeBreakpoint in interface Debugger

Parameters:

bp - The breakpoint to remove.

Throws:

DebugException

getWatches

public ArrayList<DebugWatchData> getWatches()
                                     throws DebugException

Returns all currently watched fields and variables. No synchronization required because _watches is final.

Specified by:

getWatches in interface Debugger

Throws:

DebugException

getCurrentThreadData

public ArrayList<DebugThreadData> getCurrentThreadData()
                                                throws DebugException

Returns a list of all threads being tracked by the debugger. Does not return any threads known to be dead.

Specified by:

getCurrentThreadData in interface Debugger

Throws:

DebugException

getCurrentStackFrameData

public ArrayList<DebugStackData> getCurrentStackFrameData()
                                                   throws DebugException

Returns a Vector of DebugStackData for the current suspended thread.

Specified by:

getCurrentStackFrameData in interface Debugger

Throws:

DebugException - if the current thread is running or there are no suspended threads TO DO: Config option for hiding DrJava subset of stack trace

preloadDocument

public OpenDefinitionsDocument preloadDocument(com.sun.jdi.Location location)

Return the document associated with this location. A document is preloaded when a debugger step is made to avoid the deadlock described in [ 1696060 ] Debugger Infinite Loop.

scrollToSource

public void scrollToSource(DebugStackData stackData)
                    throws DebugException

Scrolls to the source location specified by the the debug stack data.

Specified by:

scrollToSource in interface Debugger

Parameters:

stackData - Stack data containing location to display

Throws:

DebugException - if current thread is not suspended

scrollToSource

public void scrollToSource(Breakpoint bp)

Scrolls to the source of the given breakpoint.

Specified by:

scrollToSource in interface Debugger

Parameters:

bp - the breakpoint

getBreakpoint

public Breakpoint getBreakpoint(int line,
                                String className)

Gets the Breakpoint object at the specified line in the given class. If the given data do not correspond to an actual breakpoint, null is returned.

Specified by:

getBreakpoint in interface Debugger

Parameters:

line - The line number of the breakpoint

className - The name of the class the breakpoint's in

Returns:

the Breakpoint corresponding to the line and className, or null if there is no such breakpoint.