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:
  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
Source locator sequence diagram
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.