Source Lookup
Overview
A necessary function of most debuggers is to display the code that is
being executed by the debugee. The Eclipse
framework provides several mechanisms to allow the debugger integration
to link the debug
model elements to a source viewer capable of displaying the code. The
simplest of these mechanisms is the Source Locator.
Source Locator
The source locator refers to the ISourceLocator
interface that has to be implemented by the debugger integration.
However, it is only one part of the mechanism involved in displaying
the source. In order to enable source display for a debugger, the
following steps need to be completed:
- Implement a method for
retrieving the source file path from the stack frame.
IStackFrame
interface does not define such a method, so it will be specific to your
debugger.
- Implement the
IPersistableSourceLocator
interface. The main method
to implement here is ISourceLocator.getSourceElement()
,
which normally should retrieve the source file information from the
stack frame and return an IFile
object. Other methods can be left empty if the source locator
does not persist any data. Note
that IPersistableSourceLocator
interface (as opposed to just ISourceLookup) must be implemented, in
order to register the source locator with the debug framework.
- Register the source locator
with the Eclispe framework using the
org.eclipse.debug.core.sourceLocators
extension point. The source
locator is actually created by the framework when a new launch is
created.
- Add the source locator ID to
the
org.eclipse.debug.core.launchConfigurationTypes
extension. This is the
second part of registering the source locator, which tells the
framework what source locator to create for a new launch.
- Implement the
ISourcePresentation.getEditorInput()
and ISourcePresentation.getEditorId()
methods. These methods allow
the framework to translate the non-UI object returned by
ISourceLocator.getSourceElement()
into data which can be used to open an
editor. The ISourcePresentation
interface is a base interface of IDebugModelPresentation
,
and is typically implemented by debuggers to customize the display of
debug model elements.
- Make sure that
IStackFrame.getLineNumber()
methodd is property implemented.
The framework uses this method to position the edtior on the correct
line.
When all requirements are satisfied, the Eclipse framework will be able
to display source corresponding to the debugger location. The
following diagram illustrates how the various components interact to
display the source.
Sequence
diagram showing the steps of displaying source for a given stack frame
selected in Debug view.
Exercise
This tutorial contains
an exercise to implement the source locator. From the Welcome Samples
Page (Help -> Welcome -> Samples) Import the
Push Down Automata (PDA)
sample into your project, then follow the
steps above to
implement the source lookup feature. Hint: to quickly find the
locations in the code that need to be completed, search for the text
"Exercise 4", or look for it in
the
Tasks
view. Note: Tasks in the plugin.xml file do now show
up
automatically in the task view, only the tasks in the java files will
be there.
Answers
Further Information
As mentioned the Source Locator is the simplest mechanism for
performing source lookup. The Adding
launchers to the platform section in Platform Plug-in Developer
Guide
gives an overview of Source Locator's more sophisticated extension: ISourceLookupDirector
.
Also, the framework allows a debugger to bypass the Source Locator
mechanism completely, and implement a much more generic interface: ISourceDisplay
.