IDebugData Interface

com.bea.ide.debug
IDebugData Interface

public interface IDebugData

The interface that represents most of the project level debugging operations. This interface allows access to debugging state.

Nested Class Summary

public static interfaceIDebugData.IValueChangeListener
           This interface allows an implementer to get notified whenever a value has been set via the debugger.

Field Summary

public static final String
APPEND_LIBRARIES_CLASS_PATH_PREF
This preference stores whether or not to append the library class path to the end of the class path when starting a new Java application.
public static final String
APPEND_SERVER_CLASS_PATH_PREF
This preference stores whether or not to append the server class path to the end of the class path when starting a new Java application.
public static final String
ATTACH_SHMEM_ADDRESS
This preference stores the shared memory address for attaching to a running virtual machine via shared memory.
public static final String
ATTACH_TYPE
This preference stores whether we should attach via sockets or shared memory, if we are attaching to a running virtual machine.
public static final String
BUILD_BEFORE_DEBUGGING_PREF
This preference tells the debugger whether to try to build the project before running.
public static final String
CLASS_PATH_PREF
This preference stores the class path to use when starting a new Java application.
public static final String
DEBUG_TYPE
The preference telling the debugger how it should debug.
public static final String
DEBUG_WEBAPP_NAME
This preference tells the debugger which webapp it should start for this debugging session.
public static final String
HOME_PATH_PREF
This preference stores what path to start a new Java application from.
public static final String
KEY
This is the string we use to store the IDebugData on an IProject object.
public static final String
MAIN_CLASS_PREF
This preference stores the main class when starting a new Java application.
public static final int
NO_INSTRUCTION_POINT
int
public static final String
PARAMS_PREF
This preference stores the parameters to pass the application when starting a new Java application.
public static final String
PORT_PREF
This preference stores the port to attach the debugger to, if we are attaching to a running virtual machine.
public static final String
PROP_CURRENT_THREAD
property containing the current thread the user is looking at.
public static final String
PROP_CURRENTSTACKFRAME
property determining what stack frame the user is looking at.
public static final String
PROP_ENABLED
property determining whether this IDebugData is currently debugging something.
public static final String
PROP_LOCALS
property contains the list of local variables.
public static final String
PROP_PAUSABLE
property saying whether or not the debugger is in such a state that pausing makes sense.
public static final String
PROP_SUSPENDED
property determining whether the vm is suspended.
public static final String
PROP_THREADS
property containing the list of threads.
public static final String
SERVER_PREF
This preference stores the server name the debugger will attach to.
public static final String
SMART_DEBUGGING_PREF
This preference tells the debugger whether it should use smart debugging in this debugging session.
public static final String
START_COMMAND_PREF
This preference stores the start command for the debugger.
public static final int
STATE_DEBUGGING
The enabled state saying that the IDE is currently debugging.
public static final int
STATE_NOT_DEBUGGING
The enabled state saying that the IDE is not currently debugging.
public static final int
STATE_TRANSITION
The enabled state saying that the IDE is in the process of moving from debugging to non-debugging or vice versa.
public static final String
SUSPEND_ALL_STEPPING_PREF
This preference tells the debugger whether to suspend all threads when hitting a step point.
public static final String
VM_PARAMS_PREF
This preference stores the parameters to pass the Virtual Machine when starting a new Java application, such as -D and -X options.
 

Method Summary

public void
addClassToFileCache(String sourceName, String className, URI uri)
adds a classname->URI mapping to the debugger's file cache.
public void
addPropertyChangeListener(String prop, PropertyChangeListener l)
adds a listener on a specific property.
public void
addValueChangeListener(IDebugData.IValueChangeListener listener)
Adds a listener that will listen to whenever the debugger changes a value on an expression.
public void
clearFileCaches()
Removes all files from the classname->URI and file name->URI mappings
public void
close()
closes the debugging session.
public IDebugExpression
evaluateExpression(String expression, IDebugExpressionListener listener)
Requests the value of the expression from the proxy, including: value, value type, complex/not complex, editable, etc.
public boolean
filesChanged()
returns whether files have changed since the last time the debugger was started.
public IDebugBreakPoint.IBreakpointContext
getBreakpointContext()
gets the IDebugBreakPoint.IBreakpointContext interface used to send debugging commands.
public IDebugStackFrame
getCurrentStackFrame()
Gets the current stack frame for the currently selected thread.
public IDebugThread
getCurrentThread()
Gets the thread that is currently considered the active thread.
public int
getEnabled()
Gets the enabled state of this DebugData.
public URI
getFile(String className, String sourceName)
does an exhaustive search to try to find a file.
public URI
getFileFromClass(String className)
gets a file for a class name.
public URI
getFileFromSource(String sourceName)
gets a file from a source name.
public IDebugInstructionPoint
getInstructionPoint()
Gets the current execution point for the currently selected thread.
public List
getLocals()
Gets all Locals for this DebugData
public IDebugExpression
getLocals(int index)
Gets a specific IDebugExpression in this IDebugData's local variable list
public IProject
getProject()
gets the project associated with this DebugData.
public boolean
getSuspended()
Gets the Suspended state of the current debugging session.
public List
getThreads()
Gets all threads for this DebugData, all elements in the list will implement IDebugThread.
public void
invalidateValues()
Called when something has happened that may have caused expression values to be invalidated, such as evaluating an expression in the immediate window, which might have side effects.
public boolean
isPausable()
Gets whether the VM can be caused in its current state.
public void
removeExpressionListener(String expression, IDebugExpressionListener listener)
Removes the listener from the expression.
public void
removePropertyChangeListener(String prop, PropertyChangeListener l)
removes a specific listener on a specific property.
public void
removeValueChangeListener(IDebugData.IValueChangeListener listener)
Removes a listener that was added via IDebugData.addValueChangeListener(IDebugData.IValueChangeListener).
public void
requestFields(String expression, IDebugExpressionListener listener)
Requests the child fields of the given expression from the proxy.
public void
resyncValues()
Informs all registered IValueChangeListeners that they should refresh their expressions.
public void
setCurrentStackFrame(IDebugStackFrame newDebugStackFrame, IDebugThread thread)
Sets the current stack frame of the specified thread.
public void
setEnabled(int newState)
Sets the enabled state of this IDebugData.
public void
setInstructionPoint(IDebugInstructionPoint newIDebugInstructionPoint)
Sets the current execution point for the current thread.
public void
setLocals(List locals)
Sets a new set of local variables.
public void
setPausable(boolean fPausable)
Sets the whether the VM can be paused.
public void
setSuspended(boolean fSuspended)
Sets the suspended state of this DebugData, you should be very careful about calling this, as this is set via interactions with the target VM.
public void
setValue(String expression, String value)
Passes the set value request on to the proxy
public void
start()
starts the DebugData debugging.
public void
stop()
stops the debugging session.

Field Detail

APPEND_LIBRARIES_CLASS_PATH_PREF

public static final String APPEND_LIBRARIES_CLASS_PATH_PREF
This preference stores whether or not to append the library class path to the end of the class path when starting a new Java application.


APPEND_SERVER_CLASS_PATH_PREF

public static final String APPEND_SERVER_CLASS_PATH_PREF
This preference stores whether or not to append the server class path to the end of the class path when starting a new Java application.


ATTACH_SHMEM_ADDRESS

public static final String ATTACH_SHMEM_ADDRESS
This preference stores the shared memory address for attaching to a running virtual machine via shared memory.


ATTACH_TYPE

public static final String ATTACH_TYPE
This preference stores whether we should attach via sockets or shared memory, if we are attaching to a running virtual machine.


BUILD_BEFORE_DEBUGGING_PREF

public static final String BUILD_BEFORE_DEBUGGING_PREF
This preference tells the debugger whether to try to build the project before running.


CLASS_PATH_PREF

public static final String CLASS_PATH_PREF
This preference stores the class path to use when starting a new Java application.


DEBUG_TYPE

public static final String DEBUG_TYPE
The preference telling the debugger how it should debug. this will contain values such as "AttachToProcess", "CreateProcess", and "WebApp"


DEBUG_WEBAPP_NAME

public static final String DEBUG_WEBAPP_NAME
This preference tells the debugger which webapp it should start for this debugging session.


HOME_PATH_PREF

public static final String HOME_PATH_PREF
This preference stores what path to start a new Java application from.


KEY

public static final String KEY
This is the string we use to store the IDebugData on an IProject object. To get an IDebugData now, you should go through the DebugSvc.


MAIN_CLASS_PREF

public static final String MAIN_CLASS_PREF
This preference stores the main class when starting a new Java application.


NO_INSTRUCTION_POINT

public static final int NO_INSTRUCTION_POINT


PARAMS_PREF

public static final String PARAMS_PREF
This preference stores the parameters to pass the application when starting a new Java application.


PORT_PREF

public static final String PORT_PREF
This preference stores the port to attach the debugger to, if we are attaching to a running virtual machine.


PROP_CURRENT_THREAD

public static final String PROP_CURRENT_THREAD
property containing the current thread the user is looking at. This property will change whenever the current thread changes. The current thread will change by either the stack frame changing or a breakpoint/step event getting hit.


PROP_CURRENTSTACKFRAME

public static final String PROP_CURRENTSTACKFRAME
property determining what stack frame the user is looking at. This property will change when a user switches the active stack frame, when a user switches the active thread, or when a breakpoint or step event is hit (because the stack will change).


PROP_ENABLED

public static final String PROP_ENABLED
property determining whether this IDebugData is currently debugging something. Registering for this property will notify you whenever we stop or start debugging for the associated project.


PROP_LOCALS

public static final String PROP_LOCALS
property contains the list of local variables. This property will change when a user switches the active stack frame, when a user switches the active thread, or when a breakpoint or step event is hit (because the stack will change).


PROP_PAUSABLE

public static final String PROP_PAUSABLE
property saying whether or not the debugger is in such a state that pausing makes sense. This is the same property the pause button is cued off of.


PROP_SUSPENDED

public static final String PROP_SUSPENDED
property determining whether the vm is suspended. This property will change whenever a step is started, a step is finished, a breakpoint is hit, the VM is paused or the VM is continued.


PROP_THREADS

public static final String PROP_THREADS
property containing the list of threads. This property will change when when a breakpoint or step event is hit and the list of threads is updated.


SERVER_PREF

public static final String SERVER_PREF
This preference stores the server name the debugger will attach to.


SMART_DEBUGGING_PREF

public static final String SMART_DEBUGGING_PREF
This preference tells the debugger whether it should use smart debugging in this debugging session. Smart debugging filters out classes like JDK source from stepping.


START_COMMAND_PREF

public static final String START_COMMAND_PREF
This preference stores the start command for the debugger.


STATE_DEBUGGING

public static final int STATE_DEBUGGING
The enabled state saying that the IDE is currently debugging.


STATE_NOT_DEBUGGING

public static final int STATE_NOT_DEBUGGING
The enabled state saying that the IDE is not currently debugging.


STATE_TRANSITION

public static final int STATE_TRANSITION
The enabled state saying that the IDE is in the process of moving from debugging to non-debugging or vice versa.


SUSPEND_ALL_STEPPING_PREF

public static final String SUSPEND_ALL_STEPPING_PREF
This preference tells the debugger whether to suspend all threads when hitting a step point.


VM_PARAMS_PREF

public static final String VM_PARAMS_PREF
This preference stores the parameters to pass the Virtual Machine when starting a new Java application, such as -D and -X options.

 

Method Detail

addClassToFileCache(String, String, URI) Method

public void addClassToFileCache(String sourceName, 
                                String className, 
                                URI uri)
adds a classname->URI mapping to the debugger's file cache. This will be used for finding a file that is listed in the Stack Frames or finding the file the current instruction point is in.

Parameters

sourceName
- The name of the source file, as marked in the .class file
className
- The name of the class
uri
- The URI of the file to associate with this class name

addPropertyChangeListener(String, PropertyChangeListener) Method

public void addPropertyChangeListener(String prop, 
                                      PropertyChangeListener l)
adds a listener on a specific property. This listener will get fired whenever the pecified property is changed.

Parameters

prop
the property to set a listener on.
l
the listener object to get called back.

addValueChangeListener(IDebugData.IValueChangeListener) Method

public void addValueChangeListener(IDebugData.IValueChangeListener listener)
Adds a listener that will listen to whenever the debugger changes a value on an expression.

Parameters

listener
the object that will get called back when the value changes.

clearFileCaches() Method

public void clearFileCaches()
Removes all files from the classname->URI and file name->URI mappings


close() Method

public void close()
closes the debugging session. This will release all the state associated with a debugging session, but will basicly be a subset of Stop, that does not send messages to the proxy for shutting down.


evaluateExpression(String, IDebugExpressionListener) Method

public IDebugExpression evaluateExpression(String expression, 
                                           IDebugExpressionListener listener)
Requests the value of the expression from the proxy, including: value, value type, complex/not complex, editable, etc. If not already known, the value will be populated asynchronously. The listener will be notified when the value has been loaded, or immediately if they are already known.

The listener will be removed when execution resumes through a step or continue action, and must be re-added when the target VM is suspended again if desired. Before being removed, the listener will be called to indicate that the IDebugExpression has become stale.

Parameters

expression
the expression to listen on.
listener
the object that will be notified when the value is known.

Returns

an IDebugExpression representing the expression to be evaluated. If the value is already known, this will be fully populated. Otherwise the expression will be marked as stale and will not be updated with the values when they are loaded - a new IDebugExpression will be created.

filesChanged() Method

public boolean filesChanged()
returns whether files have changed since the last time the debugger was started.

Returns

whether the files have changed.

getBreakpointContext() Method

public IDebugBreakPoint.IBreakpointContext getBreakpointContext()
gets the IDebugBreakPoint.IBreakpointContext interface used to send debugging commands.

Returns

DebugCommands interface

getCurrentStackFrame() Method

public IDebugStackFrame getCurrentStackFrame()
Gets the current stack frame for the currently selected thread.

Returns

an IDebugStackFrame representing the current stack frame for the current thread.

getCurrentThread() Method

public IDebugThread getCurrentThread()
Gets the thread that is currently considered the active thread. This is the thread that will be operated in if the user steps, and is the one that will have its stack shown in the call stack window.

Returns

an IDebugThread representing the current thread.

getEnabled() Method

public int getEnabled()
Gets the enabled state of this DebugData. The possible return values are: IDebugData.STATE_NOT_DEBUGGING IDebugData.STATE_DEBUGGING IDebugData.STATE_TRANSITION

Returns

the enabled state of the IDebugData

getFile(String, String) Method

public URI getFile(String className, 
                   String sourceName)
does an exhaustive search to try to find a file. You can give it both a className and a sourceName, in which case it will try to find the source file you specified, and if it can't find that will try to find the most appropriate file that could have created the class specified.

Parameters

className
- the name of the class
sourceName
- the name of the source file

Returns

the URI for the document that defines the source code.

getFileFromClass(String) Method

public URI getFileFromClass(String className)
gets a file for a class name. This will walk through all the normal file lookup code to find an actual file in the same manner we do when a breakpoint gets hit.

Parameters

className
- the name of the class

Returns

the URI for the document that defines the source code.

getFileFromSource(String) Method

public URI getFileFromSource(String sourceName)
gets a file from a source name. This will walk through all the normal file lookup code to find an actual file in the same manner we do when a breakpoint gets hit.

Parameters

sourceName
- the name of a source file. This will be the name in the .class file.

Returns

the IDocument object for the file that defines the Java class.

getInstructionPoint() Method

public IDebugInstructionPoint getInstructionPoint()
Gets the current execution point for the currently selected thread.

Returns

an IDebugInstructionPoint representing the current execution point for the current thread.

getLocals() Method

public List getLocals()
Gets all Locals for this DebugData

Returns

a List of IDebugExpression representing the local varaibles.

getLocals(int) Method

public IDebugExpression getLocals(int index)
Gets a specific IDebugExpression in this IDebugData's local variable list

Parameters

index
into the list of Locals

Returns

the IDebugExpression at the specified index

getProject() Method

public IProject getProject()
gets the project associated with this DebugData.

Returns

the project associated with this DebugData.

getSuspended() Method

public boolean getSuspended()
Gets the Suspended state of the current debugging session.

Returns

whether or not the target VM is currently suspended.

getThreads() Method

public List getThreads()
Gets all threads for this DebugData, all elements in the list will implement IDebugThread.

Returns

a List of IDebugThread representing all the known threads.

invalidateValues() Method

public void invalidateValues()
Called when something has happened that may have caused expression values to be invalidated, such as evaluating an expression in the immediate window, which might have side effects.


isPausable() Method

public boolean isPausable()
Gets whether the VM can be caused in its current state. This will be dependant on whether the VM is currently running, paused, and the thread suspension strategy being used.

Returns

whether the VM can be paused in its current state.

removeExpressionListener(String, IDebugExpressionListener) Method

public void removeExpressionListener(String expression, 
                                     IDebugExpressionListener listener)
Removes the listener from the expression. It may still get called again if the IDebugData is in the middle of notifying listeners, but will be removed from the list for future notifications

Parameters

expression
the expression to remove the listener from.
listener
the listener object to remove.

removePropertyChangeListener(String, PropertyChangeListener) Method

public void removePropertyChangeListener(String prop, 
                                         PropertyChangeListener l)
removes a specific listener on a specific property.

Parameters

prop
the property to remove the listener from.
l
the listener object to remove.

removeValueChangeListener(IDebugData.IValueChangeListener) Method

public void removeValueChangeListener(IDebugData.IValueChangeListener listener)
Removes a listener that was added via IDebugData.addValueChangeListener(IDebugData.IValueChangeListener).

Parameters

listener
the object to remove from getting called back.

requestFields(String, IDebugExpressionListener) Method

public void requestFields(String expression, 
                          IDebugExpressionListener listener)
Requests the child fields of the given expression from the proxy. If not already known, the fields will be populated asynchronously. The listener will be notified when the value has been loaded. If already known, the listener's fieldsChanged method will be invoked immediately.

The listener will be removed when execution resumes through a step or continue action, and must be re-added when the target VM is suspended again if desired.

Parameters

expression
the expression to listen on.
listener
the object that will be notified when the fields are populated.

resyncValues() Method

public void resyncValues()
Informs all registered IValueChangeListeners that they should refresh their expressions. Usually called shortly after a call to invalidateValues().


setCurrentStackFrame(IDebugStackFrame, IDebugThread) Method

public void setCurrentStackFrame(IDebugStackFrame newDebugStackFrame, 
                                 IDebugThread thread)
Sets the current stack frame of the specified thread. This will only affect what the user sees, it will not affect the actual stackframe in the target VM.

Parameters

newDebugStackFrame
an IDebugStackFrame representing the new stack frame for the thread.
thread
an IDebugThread representing the thread.

setEnabled(int) Method

public void setEnabled(int newState)
Sets the enabled state of this IDebugData. You should be very careful calling this, as this is set by the interactions with the target VM.

Parameters

newState
whether or not the IDebugData should be enabled.

setInstructionPoint(IDebugInstructionPoint) Method

public void setInstructionPoint(IDebugInstructionPoint newIDebugInstructionPoint)
Sets the current execution point for the current thread. This will only change what is shown to the user in the IDE, it will not actually change the execution point in the target VM.

Parameters

newIDebugInstructionPoint
an IDebugInstructionPoint representing the new execution point for the current thread.

setLocals(List) Method

public void setLocals(List locals)
Sets a new set of local variables. These will be what the Locals window will display while debugging.

Parameters

locals
a List of IDebugExpression representing the new set of local varaibles.

setPausable(boolean) Method

public void setPausable(boolean fPausable)
Sets the whether the VM can be paused. You should be very careful about using this API, as it is set by the debugger service.

Parameters

fPausable
whether the VM is able to be paused.

setSuspended(boolean) Method

public void setSuspended(boolean fSuspended)
Sets the suspended state of this DebugData, you should be very careful about calling this, as this is set via interactions with the target VM.

Parameters

fSuspended
the new suspended state.

setValue(String, String) Method

public void setValue(String expression, 
                     String value)
Passes the set value request on to the proxy

Parameters

expression
the expression to set the value on.
value
the value to set on the expression.

start() Method

public void start()
starts the DebugData debugging. In the case of a WebApp, this will simply mean we will attach to the proxy and begin debugging. In the case of a JavaApp, we will either create the process to debug and debug it or attach to an existing process.


stop() Method

public void stop()
stops the debugging session. If the debugging session created a process, we will destroy it. Otherwise, we will just stop debugging.