oracle.ide.runner
Interface DebuggerExtender

All Superinterfaces:

DebuggerListener, java.util.EventListener

public interface DebuggerExtender
extends DebuggerListener

A DebuggerExtender can modify and enhance certain functionalities of a Debugger. Use the Debugger method: DebuggerExtenderCallback addDebuggerExtender( DebuggerExtender extender ); to add a DebuggerExtender to a Debugger. The existing DebuggerListener interface, from which DebuggerExtender derives, provides callbacks for some basic Debugger events, such as start, stop, resume, finish

Method Summary

void	breakpointAdded(DebuggerBreakpoint breakpoint) Called by the Debugger when a breakpoint has been added.
void	breakpointChanged(DebuggerBreakpoint breakpoint, DebuggerBreakpoint.BreakpointState newState) Called by the Debugger when a previously added breakpoint has changed
void	breakpointDeleted(DebuggerBreakpoint breakpoint) Called by the Debugger when a previously added breakpoint has been deleted by the user.
void	breakpointInScope(DebuggerBreakpoint breakpoint) Called by the debugger to tell the DebuggerExtender that a breakpoint has become visible in the scope of the current context, and the Icon of the breakpoint can be shown if appropriate.
void	breakpointOutOfScope(DebuggerBreakpoint breakpoint) Called by the debugger to tell the DebuggerExtender that a breakpoint has become invisible in the scope of the current context, and the Icon of the breakpoint should be hidden if appropriate.
boolean	breakpointsEqual(DebuggerBreakpoint debuggerBreakpoint, DebuggerBreakpoint debuggerExtenderBreakpoint) Called by the debugger to ask the DebuggerExtender if two DebuggerBreakpoints are equal.
void	breakpointsLoaded() Called by the Debugger to signal that persistent breakpoints have been loaded from storage.
boolean	canCreateCustomBreakpoint(java.lang.String customBreakpointType, Workspace workspace, Project project) Called by the debugger to ask the DebuggerExtender if new breakpoints of a certain type can be created for the incoming workspace and project
boolean	canRunToCursor(Context context, DebuggerBreakpoint breakpoint) Called when the debugger determines if runToCursor is allowed at a breakpoint.
boolean	canShowBreakpointLocation(Context context, DebuggerBreakpoint breakpoint) Called by the debugger when actions are enabled/disabled to inquire if the DebuggerExtender wants to disable the action that shows the location corresponding to the breakpoint.
boolean	canShowIPLocation(Context context, DebuggerBreakpoint breakpoint) Called by the debugger when the debuggee is stopped at a previously added breakpoint.
boolean	canStepInto(Context context, DebuggerBreakpoint breakpoint) Called when the debugger determines if stepInto is allowed at a breakpoint.
boolean	canStepOut(Context context, DebuggerBreakpoint breakpoint) Called when the debugger determines if stepOut is allowed at a breakpoint.
boolean	canStepOver(Context context, DebuggerBreakpoint breakpoint) Called by the debugger to determine if the DebuggerExtender wants to override the StepOver behavior.
boolean	canStepToEndOfMethod(Context context, DebuggerBreakpoint breakpoint) Called when the debugger determines if stepToEndOfMethod is allowed at a breakpoint.
void	debuggeeStoppedAtBreakpoint(Context context, DebuggerBreakpoint breakpoint) Called by the Debugger when the debuggee has stopped at a previously added breakpoint.
DebuggerBreakpointPanel	getCustomBreakpointPanel(java.lang.String customBreakpointType, DebuggerBreakpoint breakpoint, javax.swing.event.ChangeListener changeListener) Called by the debugger to ask the DebuggerExtender for the panel to create or edit a custom breakpoint.
java.lang.String	getID() Called by the Debugger to get the unique ID that identifies this DebuggerExtender Warning: This method will be called during the call to method: DebuggerExtenderCallback addDebuggerExtender( DebuggerExtender extender );
void	newDebugSession(Context context) Called by the debugger before a new debug session is started on the incoming context.
DebuggerBreakpoint	runToCursor(Context context, DebuggerBreakpoint breakpoint) Called when the debugger will execute a RunToCursor command.
void	setEvaluator(Context context, DebuggerEvaluator evaluator) Called after the debuggee has stopped and the stack window is refreshed.
boolean	showBreakpointLocation(Context context, DebuggerBreakpoint breakpoint) Called by the debugger when the user double-clicks on a previously added breakpoint.
boolean	showIPLocation(Context context, DebuggerBreakpoint breakpoint) Called by the debugger when the debuggee is stopped at a previously added breakpoint.
DebuggerBreakpoint	stepInto(Context context, DebuggerBreakpoint breakpoint) Called when the debugger will execute a StepInto command.
DebuggerBreakpoint	stepOut(Context context, DebuggerBreakpoint breakpoint) Called when the debugger will execute a StepOut command.
DebuggerBreakpoint	stepOver(Context context, DebuggerBreakpoint breakpoint) Called when the debugger will execute a StepOver command.
DebuggerBreakpoint	stepToEndOfMethod(Context context, DebuggerBreakpoint breakpoint) Called when the debugger will execute a StepToEndOfMethod command.
void	temporaryBreakpointSet(Context context, DebuggerBreakpoint breakpoint) Called by the debugger to tell the DebuggerExtender that the temporary breakpoint, requested by the DebuggerExtender for the overriding stepping behavior, has been set
void	updateBreakpointIcon(DebuggerBreakpoint breakpoint) Called by the debugger to tell the DebuggerExtender that the Icon of a breakpoint should be updated, which only makes sense if the breakpoint is currently visible in the IDE.

Methods inherited from interface oracle.ide.runner.DebuggerListener

debuggerFinished, debuggerResuming, debuggerStarted, debuggerStopping

Method Detail

getID

java.lang.String getID()

Called by the Debugger to get the unique ID that identifies this DebuggerExtender Warning: This method will be called during the call to method: DebuggerExtenderCallback addDebuggerExtender( DebuggerExtender extender );

Returns:

The unique ID of this DebuggerExtender which should not be null

breakpointsLoaded

void breakpointsLoaded()

Called by the Debugger to signal that persistent breakpoints have been loaded from storage. Warning: This method might be called during the call to method: DebuggerExtenderCallback addDebuggerExtender( DebuggerExtender extender );

newDebugSession

void newDebugSession(Context context)

Called by the debugger before a new debug session is started on the incoming context. This is an excellent time to add breakpoints relevant to the new debug sessions or delete non-relevant breakpoints

Parameters:

context - The context for the new debug session

debuggeeStoppedAtBreakpoint

void debuggeeStoppedAtBreakpoint(Context context,
                                 DebuggerBreakpoint breakpoint)

Called by the Debugger when the debuggee has stopped at a previously added breakpoint. This is not the call that asks the DebuggerExtender to render the stopped debuggee location, that will arrive later

Parameters:

context - The context of the debug session

breakpoint - The breakpoint where the debuggee stopped, which is guaranteed to be a breakpoint belonging to this DebuggerExtender

breakpointAdded

void breakpointAdded(DebuggerBreakpoint breakpoint)

Called by the Debugger when a breakpoint has been added. This can be a breakpoint previously added by the DebuggerExtenderCallback, or a breakpoint loaded from disk, or a breakpoint created by the user.

Parameters:

breakpoint - A breakpoint which is guaranteed to be a breakpoint belonging to this DebuggerExtender

breakpointChanged

void breakpointChanged(DebuggerBreakpoint breakpoint,
                       DebuggerBreakpoint.BreakpointState newState)

Called by the Debugger when a previously added breakpoint has changed

Parameters:

breakpoint - The breakpoint that has changed, which is guaranteed to be a breakpoint belonging to this DebuggerExtender

newState - The new state of the breakpoint

breakpointDeleted

void breakpointDeleted(DebuggerBreakpoint breakpoint)

Called by the Debugger when a previously added breakpoint has been deleted by the user. This method will not be called when the DebuggerExtenderCallback initiated the breakpoint deletion

Parameters:

breakpoint - The breakpoint that has been deleted, which is guaranteed to be a breakpoint belonging to this DebuggerExtender

canShowBreakpointLocation

boolean canShowBreakpointLocation(Context context,
                                  DebuggerBreakpoint breakpoint)

Called by the debugger when actions are enabled/disabled to inquire if the DebuggerExtender wants to disable the action that shows the location corresponding to the breakpoint.

Parameters:

context - The context of the debug session if there is an active debug session, otherwise null

breakpoint - The breakpoint, which is guaranteed to be a breakpoint belonging to this DebuggerExtender

Returns:

False if the action to show the location of this breakpoint should be disabled, true otherwise

showBreakpointLocation

boolean showBreakpointLocation(Context context,
                               DebuggerBreakpoint breakpoint)

Called by the debugger when the user double-clicks on a previously added breakpoint. This gives the DebuggerExtender the chance to display the visuals that represent the place where the debuggee would stop. This is not the time to display any execution point, but instead any relevant breakpoints should be displayed with their state

Parameters:

context - The context of the debug session if there is an active debug session, otherwise null

breakpoint - The breakpoint, which is guaranteed to be a breakpoint belonging to this DebuggerExtender

Returns:

True if the DebuggerExtender successfully showed the location of the breakpoint, false if the DebuggerExtender wants the Debugger to show the location instead

canShowIPLocation

boolean canShowIPLocation(Context context,
                          DebuggerBreakpoint breakpoint)

Called by the debugger when the debuggee is stopped at a previously added breakpoint. The debugger is asking if the DebuggerExtender will display all visuals to represent the stopped debuggee (IP) location, including the execution point. There are several situations where this method can be called: - the first time the debuggee stops at a previously added breakpoint - any time the user executes the 'show IP' action when the debuggee is stopped at a previously added breakpoint - any time the user clicks on the top frame of the current stack when the debuggee is stopped at a previously added breakpoint

Parameters:

context - The context of the debug session

breakpoint - The breakpoint where the debuggee is stopped, which is guaranteed to be a breakpoint belonging to this DebuggerExtender

Returns:

True if the DebuggerExtender will display the IP location. False if the debugger should display the IP location

showIPLocation

boolean showIPLocation(Context context,
                       DebuggerBreakpoint breakpoint)

Called by the debugger when the debuggee is stopped at a previously added breakpoint. The debugger is giving the DebuggerExtender the chance to display all visuals to represent the stopped debuggee (IP) location, including the execution point. There are several situations where this method can be called: - the first time the debuggee stops at a previously added breakpoint - any time the user executes the 'show IP' action when the debuggee is stopped at a previously added breakpoint - any time the user clicks on the top frame of the current stack when the debuggee is stopped at a previously added breakpoint

Parameters:

context - The context of the debug session

breakpoint - The breakpoint where the debuggee is stopped, which is guaranteed to be a breakpoint belonging to this DebuggerExtender

Returns:

True if the DebuggerExtender successfully rendered the IP location, false if for some reason the DebuggerExtender failed to render the IP location (e.g. an Exception), and the debugger will attempt to render the IP location instead.

setEvaluator

void setEvaluator(Context context,
                  DebuggerEvaluator evaluator)

Called after the debuggee has stopped and the stack window is refreshed. Will be called after the 'showIPLocation' call. If the DebuggerExtender needs access to an evaluator during the rendering, it should delay that rendering till after setEvaluator is called. The first time this is called (after the debuggee has stopped), the stackFrameIndex will always be 0 (zero), and the thread will be the 'stopped' thread. Each time the user changes stackframe or thread, this method will be called again with a new Evaluator, valid for that thread and stackframe. Evaluators are keyed to a particular stop, thread and stackframe and will be expired in any other situation. Don't hold on to expired evaluators. Let them be garbage collected after each 'resume' and 'finish'.

Parameters:

context - The context of the debug session

evaluator - An evaluator that can be used during this debuggee stop.

stepOver

DebuggerBreakpoint stepOver(Context context,
                            DebuggerBreakpoint breakpoint)

Called when the debugger will execute a StepOver command. Allows the DebuggerExtender to modify the semantics of 'StepOver' issued at a certain breakpoint. StepOver cannot be disabled by DebuggerExtenders since it is part of standard stepping functionality. The DebuggerExtender can either change a StepOver command into a run to a temporary breakpoint or into a resume.

Parameters:

context - The context of the debug session

breakpoint - The breakpoint where the debuggee is stopped, which is guaranteed to be a breakpoint belonging to this DebuggerExtender

Returns:

A DebuggerBreakpoint (implemented by the DebuggerExtender) if the DebuggerExtender wants the debugger to attempt to run to this breakpoint. Return null if the DebuggerExtender wants the debugger to just resume. There is no guarantee that the debuggee will indeed make its next stop at the returned breakpoint, since any other breakpoint can be hit first instead. The returned breakpoint is a temporary, invisible breakpoint which is automatically deleted at the end of this command

canStepOver

boolean canStepOver(Context context,
                    DebuggerBreakpoint breakpoint)

Called by the debugger to determine if the DebuggerExtender wants to override the StepOver behavior. StepOver cannot be disabled, since it is part of standard stepping functionality. However, the DebuggerExtender can choose to override StepOver OR let the debugger do a default StepOver action. Overriding StepOver can be done by requesting the debugger to run to a temporary breakpoint, or by requesting the debugger to resume. This method can be called several times after the debuggee stops at a breakpoint. The debugger guarantees to call this method after the setEvaluator call, so if this DebugExtender needs evaluator services for this method, it should ignore this method till after the setEvaluator call.

Parameters:

context - The context of the debug session

breakpoint - The breakpoint where the debuggee is stopped, which is guaranteed to be a breakpoint belonging to this DebuggerExtender

Returns:

True if the DebuggerExtender wants to override the StepOver action, false if the DebuggerExtender wants the debugger to execute a default StepOver action.

stepInto

DebuggerBreakpoint stepInto(Context context,
                            DebuggerBreakpoint breakpoint)

Called when the debugger will execute a StepInto command. Allows the DebuggerExtender to modify the semantics of 'StepInto' issued at a certain breakpoint. StepInto can be disabled by the DebuggerExtender through the canStepInto call

Parameters:

context - The context of the debug session

breakpoint - The breakpoint where the debuggee is stopped, which is guaranteed to be a breakpoint belonging to this DebuggerExtender

Returns:

A DebuggerBreakpoint (implemented by the DebuggerExtender) if the DebuggerExtender wants the debugger to attempt to run to this breakpoint instead of doing a normal StepInto which is step into the current statement. Return null if the DebuggerExtender wants the debugger to perform the normal StepInto command. There is no guarantee that the debuggee will indeed make its next stop at the returned breakpoint, since any other breakpoint can be hit first instead. The returned breakpoint is a temporary, invisible breakpoint which is automatically deleted at the end of this command

canStepInto

boolean canStepInto(Context context,
                    DebuggerBreakpoint breakpoint)

Called when the debugger determines if stepInto is allowed at a breakpoint. Allows the DebuggerExtender to disable stepInto at a breakpoint This method can be called several times after the debuggee stops at a breakpoint. The debugger guarantees to call this method after the setEvaluator call, so if this DebugExtender needs evaluator services for this method, it should ignore this method till after the setEvaluator call.

Parameters:

context - The context of the debug session

breakpoint - The breakpoint where the debuggee is stopped, which is guaranteed to be a breakpoint belonging to this DebuggerExtender

Returns:

False if stepInto should be disabled at this breakpoint, true otherwise.

stepOut

DebuggerBreakpoint stepOut(Context context,
                           DebuggerBreakpoint breakpoint)

Called when the debugger will execute a StepOut command. Allows the DebuggerExtender to modify the semantics of 'StepOut' issued at a certain breakpoint. StepOut can be disabled by the DebuggerExtender through the canStepOut call

Parameters:

context - The context of the debug session

breakpoint - The breakpoint where the debuggee is stopped, which is guaranteed to be a breakpoint belonging to this DebuggerExtender

Returns:

A DebuggerBreakpoint (implemented by the DebuggerExtender) if the DebuggerExtender wants the debugger to attempt to run to this breakpoint instead of doing a normal StepOut which is step out of the current function. Return null if the DebuggerExtender wants the debugger to perform the normal StepOut command. There is no guarantee that the debuggee will indeed make its next stop at the returned breakpoint, since any other breakpoint can be hit first instead. The returned breakpoint is a temporary, invisible breakpoint which is automatically deleted at the end of this command

canStepToEndOfMethod

boolean canStepToEndOfMethod(Context context,
                             DebuggerBreakpoint breakpoint)

Called when the debugger determines if stepToEndOfMethod is allowed at a breakpoint. Allows the DebuggerExtender to disable stepToEndOfMethod. This method can be called several times after the debuggee stops at a breakpoint. The debugger guarantees to call this method after the setEvaluator call, so if this DebugExtender needs evaluator services for this method, it should ignore this method till after the setEvaluator call.

Parameters:

context - The context of the debug session

breakpoint - The breakpoint where the debuggee is stopped, which is guaranteed to be a breakpoint belonging to this DebuggerExtender

Returns:

False if the stepToEndOfMethod functionality should be disabled, true otherwise.

stepToEndOfMethod

DebuggerBreakpoint stepToEndOfMethod(Context context,
                                     DebuggerBreakpoint breakpoint)

Called when the debugger will execute a StepToEndOfMethod command. Allows the DebuggerExtender to modify the semantics of 'StepToEndOfMethod' issued at a certain breakpoint. StepToEndOfMethod can be disabled by the DebuggerExtender through the canStepToEndOfMethod call

Parameters:

context - The context of the debug session

breakpoint - The breakpoint where the debuggee is stopped, which is guaranteed to be a breakpoint belonging to this DebuggerExtender

Returns:

A DebuggerBreakpoint (implemented by the DebuggerExtender) if the DebuggerExtender wants the debugger to attempt to run to this breakpoint instead of doing a normal StepToEndOfMethod which is step to the end of the current function. Return null if the DebuggerExtender wants the debugger to perform the normal StepToEndOfMethod command. There is no guarantee that the debuggee will indeed make its next stop at the returned breakpoint, since any other breakpoint can be hit first instead. The returned breakpoint is a temporary, invisible breakpoint which is automatically deleted at the end of this command

canStepOut

boolean canStepOut(Context context,
                   DebuggerBreakpoint breakpoint)

Called when the debugger determines if stepOut is allowed at a breakpoint. Allows the DebuggerExtender to disable stepOut at a breakpoint This method can be called several times after the debuggee stops at a breakpoint. The debugger guarantees to call this method after the setEvaluator call, so if this DebugExtender needs evaluator services for this method, it should ignore this method till after the setEvaluator call.

Parameters:

context - The context of the debug session

breakpoint - The breakpoint where the debuggee is stopped, which is guaranteed to be a breakpoint belonging to this DebuggerExtender

Returns:

False if the stepOut functionality should be disabled, true otherwise.

runToCursor

DebuggerBreakpoint runToCursor(Context context,
                               DebuggerBreakpoint breakpoint)

Called when the debugger will execute a RunToCursor command. Allows the DebuggerExtender to modify the semantics of 'RunToCursor' issued at a certain breakpoint. RunToCursor can be disabled by the DebuggerExtender through the canRunToCursor call

Parameters:

context - The context of the debug session

breakpoint - The breakpoint where the debuggee is stopped, which is guaranteed to be a breakpoint belonging to this DebuggerExtender

Returns:

A DebuggerBreakpoint (implemented by the DebuggerExtender) if the DebuggerExtender wants the debugger to attempt to run to this breakpoint instead of doing a normal RunToCursor which is run to the location where the cursor is. Return null if the DebuggerExtender wants the debugger to perform the normal RunToCursor command. There is no guarantee that the debuggee will indeed make its next stop at the returned breakpoint, since any other breakpoint can be hit first instead. The returned breakpoint is a temporary, invisible breakpoint which is automatically deleted at the end of this command

canRunToCursor

boolean canRunToCursor(Context context,
                       DebuggerBreakpoint breakpoint)

Called when the debugger determines if runToCursor is allowed at a breakpoint. Allows the DebuggerExtender to disable runToCursor This method can be called several times after the debuggee stops at a breakpoint. The debugger guarantees to call this method after the setEvaluator call, so if this DebugExtender needs evaluator services for this method, it should ignore this method till after the setEvaluator call.

Parameters:

context - The context of the debug session

breakpoint - The breakpoint where the debuggee is stopped, which is guaranteed to be a breakpoint belonging to this DebuggerExtender

Returns:

False if the runToCursor functionality should be disabled, true otherwise.

breakpointInScope

void breakpointInScope(DebuggerBreakpoint breakpoint)

Called by the debugger to tell the DebuggerExtender that a breakpoint has become visible in the scope of the current context, and the Icon of the breakpoint can be shown if appropriate. It is up to the DebuggerExtender to keep an internal state of the visiblity of the breakpoint. The DebuggerExtender can call getBreakpointState and getBreakpointIcon to determine what to show

Parameters:

breakpoint - The breakpoint, which is guaranteed to be a breakpoint belonging to this DebuggerExtender

breakpointOutOfScope

void breakpointOutOfScope(DebuggerBreakpoint breakpoint)

Called by the debugger to tell the DebuggerExtender that a breakpoint has become invisible in the scope of the current context, and the Icon of the breakpoint should be hidden if appropriate. It is up to the DebuggerExtender to keep an internal state of the visiblity of the breakpoint.

Parameters:

breakpoint - The breakpoint, which is guaranteed to be a breakpoint belonging to this DebuggerExtender

updateBreakpointIcon

void updateBreakpointIcon(DebuggerBreakpoint breakpoint)

Called by the debugger to tell the DebuggerExtender that the Icon of a breakpoint should be updated, which only makes sense if the breakpoint is currently visible in the IDE. The DebuggerExtender can call back with getBreakpointState and getBreakpointIcon to determine what to show

Parameters:

breakpoint - The breakpoint, which is guaranteed to be a breakpoint belonging to this DebuggerExtender

temporaryBreakpointSet

void temporaryBreakpointSet(Context context,
                            DebuggerBreakpoint breakpoint)

Called by the debugger to tell the DebuggerExtender that the temporary breakpoint, requested by the DebuggerExtender for the overriding stepping behavior, has been set

Parameters:

context - The context of the debug session

breakpoint - The temporary breakpoint set by the debugger, which is guaranteed to be a breakpoint belonging to this DebuggerExtender

breakpointsEqual

boolean breakpointsEqual(DebuggerBreakpoint debuggerBreakpoint,
                         DebuggerBreakpoint debuggerExtenderBreakpoint)

Called by the debugger to ask the DebuggerExtender if two DebuggerBreakpoints are equal. This method will be used to resolve DebuggerBreakpoints that the debugger does not recognize as its own.

Parameters:

debuggerBreakpoint - A DebuggerBreakpoint as backed by the debugger

debuggerExtenderBreakpoint - A DebuggerBreakpoint as backed by the DebuggerExtender

Returns:

true if the DebuggerExtender thinks the two breakpoints are equal

canCreateCustomBreakpoint

boolean canCreateCustomBreakpoint(java.lang.String customBreakpointType,
                                  Workspace workspace,
                                  Project project)

Called by the debugger to ask the DebuggerExtender if new breakpoints of a certain type can be created for the incoming workspace and project

Parameters:

customBreakpointType - The type of the new breakpoint, which is one of the types registered by the DebuggerExtenderCallback in the registerCustomBreakpointType call

workspace - The workspace which might be null but is usually not null

project - The project which might be null but is usually not null

Returns:

True if this DebuggerExtender can create the specific breakpoint in the context of the workspace and project

getCustomBreakpointPanel

DebuggerBreakpointPanel getCustomBreakpointPanel(java.lang.String customBreakpointType,
                                                 DebuggerBreakpoint breakpoint,
                                                 javax.swing.event.ChangeListener changeListener)

Called by the debugger to ask the DebuggerExtender for the panel to create or edit a custom breakpoint.

Parameters:

customBreakpointType - The type of the new breakpoint, which is one of the types registered by the DebuggerExtenderCallback in the registerCustomBreakpointType call

breakpoint - The breakpoint which will be null when the user will create a new breakpoint, and not null when the user will edit an existing breakpoint

changeListener - The DebuggerExtender can notify the debugger through this listener when anything has changed on the DebuggerBreakpointPanel; this will cause the debugger to check if the OK button can be enabled or not.

Returns:

A panel; if null is returned the debugger will create a panel based on the kind of the breakpoint