IDebugClient Interface

com.bea.ide.debug
IDebugClient Interface

public interface IDebugClient

This class deals with all the global debugging state. The debugging architecture consists of global debugging state and project specific debugging state. The DebugClient takes care of the global debugging state, such as breakpoints and dealing with start-up and shutdown. Each project then has its own DebugData which keeps track of the individual project debugging state. In addition, the DebugClient has many methods that will call through to the DebugData associated with various projects. For any of these functions, a null argument will refer to the active project. In general, callers should go through DebugSvc instead of IDebugClient, which will delegate calls correctly.

Field Summary

public static final Object
KEY
The object used to stash the debug client onto the projects.
public static final String
PROP_BREAKPOINTS
The PROP_BREAKPOINTS change event will be called when a breakpoint is either added or removed.
public static final String
PROP_BREAKPOINTS_ENABLED
The PROP_BREAKPOINTS_ENABLED chagne listener will be called whenever the number of enabled breakpoints changes, or the number of disabled breakpoints.
 

Method Summary

public void
addBreakPoint(IDebugBreakPoint breakPoint)
Adds a breakpoint to the IDebugClient.
public void
addBreakpointListener(DebugSvc.IBreakpointListener bpl)
adds a breakpoint listener to a listen to all breakpoint changes.
public void
addBreakpointListener(URI uri, DebugSvc.IBreakpointListener bpl)
adds a breakpoint listener to a given document.
public void
addDebugListener(DebugSvc.IDebugListener dbl)
adds a debug listener.
public void
breakpointHasChanged(IDebugBreakPoint bp)
notifies all people listening on breakpoint events, that this breakpoint has changed in some way.
public void
clearAllBreakpoints()
Removes all the breakpoints the DebugClient knows about.
public void
disableBreakpoint(IDebugBreakPoint bp, boolean fDisable)
disables or enables the specified breakpoint.
public IDebugBreakPoint
getBreakpoint(int id)
Gets a breakpoint specified by its unique id.
public ISourceBreakPoint
getBreakpoint(IDocument file, int line)
Gets a breakpoint specified by a file and line number.
public int
getBreakpointCount()
gets the count of all the breakpoints the DebugClient knows about.
public List
getBreakPointList(List startList)
Gets a list of all the breakpoints we know about.
public IDebugData
getDebugData(IProject proj)
Gets the IDebugData associated with project, proj.
public int
getEnabledBreakpointCount()
gets the count of all the enabled breakpoints the DebugClient knows about.
public boolean
getLogging(String loggingSet)
determines whether the specified logging set is turned on, or off.
public String[]
getLoggingOptions()
returns the list of logging options supported by this DebugClient.
public void
go(IProject proj)
Passes through a call to IDebugData.go on the supplied proj argument.
public boolean
hasBreakPoint(IDocument file, int line)
Determines whether a document has a breakpoint on a specific line.
public void
onExit()
This function will be called on the Debug client when the Debug client is no longer in use, but before it goes away.
public void
pause(IProject proj)
Passes through a call to IDebugData.pause on the supplied proj argument.
public void
removeBreakPoint(IDebugBreakPoint breakPointToRemove)
Removes a breakpoint from the VM and the file it is in.
public void
removeBreakpointListener(DebugSvc.IBreakpointListener bpl)
removes a breakpoint listener that was added from addBreakpointListener(IBreakpointListener bpl).
public void
removeBreakpointListener(URI uri, DebugSvc.IBreakpointListener bpl)
removes a breakpoint listener that was added from addBreakpointListener(URI uri, IBreakpointListener bpl).
public void
removedDebugListener(DebugSvc.IDebugListener dbl)
removes a debug listener.
public boolean
setLogging(String loggingSet, boolean value)
turns various logging options on and off.
public void
start(IProject proj)
Passes through a call to IDebugData.start on the supplied proj argument.
public void
stepInto(IProject proj)
Passes through a call to IDebugData.stepInto on the supplied proj argument.
public void
stepOut(IProject proj)
Passes through a call to IDebugData.stepOut on the supplied proj argument.
public void
stepOver(IProject proj)
Passes through a call to IDebugData.stepOver on the supplied proj argument.
public void
stop(IProject proj)
Passes through a call to IDebugData.stop on the supplied proj argument.
public void
toggleBreakPoint(IDocument file, int line)
Toggles a breakpoint on the current line.

Field Detail

KEY

public static final Object KEY
The object used to stash the debug client onto the projects. This has been deprecated. Use DebugSvc instead.


PROP_BREAKPOINTS

public static final String PROP_BREAKPOINTS
The PROP_BREAKPOINTS change event will be called when a breakpoint is either added or removed. In the case of an add, the newValue parameter will be the breakpoint, and the oldValue parameter will be null. In the case of a remove, the newValue parameter will be null, and the oldValue parameter will be the breakpoint that is being removed.


PROP_BREAKPOINTS_ENABLED

public static final String PROP_BREAKPOINTS_ENABLED
The PROP_BREAKPOINTS_ENABLED chagne listener will be called whenever the number of enabled breakpoints changes, or the number of disabled breakpoints. The event will be called with the number of enabled breakpoints as param1, and the number of total breakpoints as the second parameter.

 

Method Detail

addBreakPoint(IDebugBreakPoint) Method

public void addBreakPoint(IDebugBreakPoint breakPoint)
Adds a breakpoint to the IDebugClient. This will add the breakpoint to the DebugClient's internal collections, set the breakpoint in the VM, and add a glyph to the file the breakpoint is in.

Parameters

breakPoint
the breakpoint you want to add.

addBreakpointListener(DebugSvc.IBreakpointListener) Method

public void addBreakpointListener(DebugSvc.IBreakpointListener bpl)
adds a breakpoint listener to a listen to all breakpoint changes. This will fire the appropriate event when any breakpoint is enable/disabled/added/removed

Parameters

bpl
the listener to recieve breakpoint events.

addBreakpointListener(URI, DebugSvc.IBreakpointListener) Method

public void addBreakpointListener(URI uri, 
                                  DebugSvc.IBreakpointListener bpl)
adds a breakpoint listener to a given document. This will fire the appropriate event when any breakpoint within the specified document is enable/disabled/added/removed

Parameters

uri
the uri of the file to listen to.
bpl
the listener to recieve breakpoint events.

addDebugListener(DebugSvc.IDebugListener) Method

public void addDebugListener(DebugSvc.IDebugListener dbl)
adds a debug listener. This listener will be notified whenever the debug state changes.

Parameters

dbl
the listener to be notified.

breakpointHasChanged(IDebugBreakPoint) Method

public void breakpointHasChanged(IDebugBreakPoint bp)
notifies all people listening on breakpoint events, that this breakpoint has changed in some way.

Parameters

bp
the breakpoint that has chagned.

clearAllBreakpoints() Method

public void clearAllBreakpoints()
Removes all the breakpoints the DebugClient knows about. Each breakpoint will be removed from all VMs as well as from all the files they are in.


disableBreakpoint(IDebugBreakPoint, boolean) Method

public void disableBreakpoint(IDebugBreakPoint bp, 
                              boolean fDisable)
disables or enables the specified breakpoint. Disabling the breakpoint will cause it to still exist in the file and in the DebugClient's breakpoint collections, but the breakpoint will be removed from the VM. Enabling the breakpoint will re-add the breakpoint to the VM.

Parameters

bp
the breakpoint to enable or disable.
fDisable
if true, this will take an enabled breakpoint and disable it if false, this will take a disabled breakpoint and enable it.

getBreakpoint(int) Method

public IDebugBreakPoint getBreakpoint(int id)
Gets a breakpoint specified by its unique id.

Parameters

id
the unique id of the breakpoint you are looking for.

Returns

the breakpoint corresponding to this id, or null if no such breakpoint exists.

getBreakpoint(IDocument, int) Method

public ISourceBreakPoint getBreakpoint(IDocument file, 
                                       int line)
Gets a breakpoint specified by a file and line number.

Parameters

file
the file to look for the breakpoint in.
line
the line in the file to look for the breakpoint on.

Returns

the breakpoint on the line, or null if no such breakpoint exists.

getBreakpointCount() Method

public int getBreakpointCount()
gets the count of all the breakpoints the DebugClient knows about.

Returns

the number of breakpoints the DebugClient knows about.

getBreakPointList(List) Method

public List getBreakPointList(List startList)
Gets a list of all the breakpoints we know about. If a startList is passed in, this will populate it. Otherwise this will create a new list to populate.

Parameters

startList
the list to return the breakpoints in. If this is null, a new list will be created that will then be used to return the breakpoints.

Returns

a list filled with IDebugBreakpoint objects refering to each breakpoint.

getDebugData(IProject) Method

public IDebugData getDebugData(IProject proj)
Gets the IDebugData associated with project, proj.

Parameters

proj
this is the project to execute the command against. If this is null, the active project will be used.

Returns

the IDebugData interface assiciated with the project.

getEnabledBreakpointCount() Method

public int getEnabledBreakpointCount()
gets the count of all the enabled breakpoints the DebugClient knows about. This means any breakpoints that are disabled will not be counted in this number.

Returns

the number of breakpoints the DebugClient knows about.

getLogging(String) Method

public boolean getLogging(String loggingSet)
determines whether the specified logging set is turned on, or off. The currently supported logging options are all returned from getLoggingOptions.

Parameters

loggingSet
name of the logging set to query a value for.

Returns

boolean indicating whether logging is on or off

getLoggingOptions() Method

public String[] getLoggingOptions()
returns the list of logging options supported by this DebugClient.

Returns

an array of options that get/setLogging will support.

go(IProject) Method

public void go(IProject proj)
Passes through a call to IDebugData.go on the supplied proj argument. If proj is null, this will be called on the current project.

Parameters

proj
this is the project to execute the command against. If this is null, the active project will be used.

hasBreakPoint(IDocument, int) Method

public boolean hasBreakPoint(IDocument file, 
                             int line)
Determines whether a document has a breakpoint on a specific line. Since breakpoints are scoped to the application, this will not verify that the file is in the current project.

Parameters

file
the file the breakpoint is associated with.
line
the line the breakpoint is associated with.

Returns

true if a breakpoint exists on the specified line in the specified file. false if there is no breakpoint on the specified line in the specified file, or if the specified file does not support IDebugDriver as a driver.

onExit() Method

public void onExit()
This function will be called on the Debug client when the Debug client is no longer in use, but before it goes away. This will persist all the breakpoints to the user's workspace preference file, and close down all the IDebugData objects.


pause(IProject) Method

public void pause(IProject proj)
Passes through a call to IDebugData.pause on the supplied proj argument. If proj is null, this will be called on the current project.

Parameters

proj
this is the project to execute the command against. If this is null, the active project will be used.

removeBreakPoint(IDebugBreakPoint) Method

public void removeBreakPoint(IDebugBreakPoint breakPointToRemove)
Removes a breakpoint from the VM and the file it is in. This will make sure that each of the projects that has this breakpoint set will unset the breakpoint, the glyph will disappear, and the breakpoint will be taken out of the breakpoint collections.

Parameters

breakPointToRemove
the breakpoint to remove.

removeBreakpointListener(DebugSvc.IBreakpointListener) Method

public void removeBreakpointListener(DebugSvc.IBreakpointListener bpl)
removes a breakpoint listener that was added from addBreakpointListener(IBreakpointListener bpl).

Parameters

bpl
the listener to remove.

removeBreakpointListener(URI, DebugSvc.IBreakpointListener) Method

public void removeBreakpointListener(URI uri, 
                                     DebugSvc.IBreakpointListener bpl)
removes a breakpoint listener that was added from addBreakpointListener(URI uri, IBreakpointListener bpl).

Parameters

uri
the uri of the file to remove from.
bpl
the listener to remove.

removedDebugListener(DebugSvc.IDebugListener) Method

public void removedDebugListener(DebugSvc.IDebugListener dbl)
removes a debug listener. This will remove a listener that was added via IDebugClient.addDebugListener(DebugSvc.IDebugListener).

Parameters

dbl
the listener to remove.

setLogging(String, boolean) Method

public boolean setLogging(String loggingSet, 
                          boolean value)
turns various logging options on and off. The currently supported logging options are all returned from getLoggingOptions.

Parameters

loggingSet
name of the logging set to turn on or off.
value
true/false depending on whether logging should be turned on or off.

Returns

true if the DebugData knows about the loggingSet and was able to turn it on or off; false if the DebugData does not know about the loggingSet.

start(IProject) Method

public void start(IProject proj)
Passes through a call to IDebugData.start on the supplied proj argument. If proj is null, this will be called on the current project.

Parameters

proj
this is the project to execute the command against. If this is null, the active project will be used.

stepInto(IProject) Method

public void stepInto(IProject proj)
Passes through a call to IDebugData.stepInto on the supplied proj argument. If proj is null, this will be called on the current project.

Parameters

proj
this is the project to execute the command against. If this is null, the active project will be used.

stepOut(IProject) Method

public void stepOut(IProject proj)
Passes through a call to IDebugData.stepOut on the supplied proj argument. If proj is null, this will be called on the current project.

Parameters

proj
this is the project to execute the command against. If this is null, the active project will be used.

stepOver(IProject) Method

public void stepOver(IProject proj)
Passes through a call to IDebugData.stepOver on the supplied proj argument. If proj is null, this will be called on the current project.

Parameters

proj
this is the project to execute the command against. If this is null, the active project will be used.

stop(IProject) Method

public void stop(IProject proj)
Passes through a call to IDebugData.stop on the supplied proj argument. If proj is null, this will be called on the current project.

Parameters

proj
this is the project to execute the command against. If this is null, the active project will be used.

toggleBreakPoint(IDocument, int) Method

public void toggleBreakPoint(IDocument file, 
                             int line)
Toggles a breakpoint on the current line. If a breakpoint is already on that line, it will be removed. If there is no breakpoint on that line, one will be added. In order to call this function on an IDocument it needs to support the IDebugDriver driver. This call will not only add the breakpoint glyph to the file it will also set the breakpoint in any active debugging sessions.

Parameters

file
the file the breakpoint is associated with.
line
the line the breakpoint is associated with.