Obtaining a program's source code
For certain kinds of launch modes, it may be important to obtain the source code that corresponds
with the current execution point in the code. This is typically important when debugging or profiling
a program. Several different extension points are provided by the debug plug-in that allow plug-ins to
register classes that can assist with locating source code.
Source locators
ISourceLocator
and
IPersistableSourceLocator
define interfaces for mapping from an executing program back to the source
code.
Source locators are typically implemented to work with a corresponding launch
configuration and launch configuration delegate. A source locator id may be specified when a launch configuration
type is defined, or it may be associated programmatically with a launch configuration using the
ILaunchConfiguration.ATTR_SOURCE_LOCATOR_ID attribute. In either case, at some point the id
of a source locator for a configuration must be resolved to the class that actually implements
IPersistableSourceLocator.
The association between a source locator id and its class is established using the
org.eclipse.debug.core.sourceLocators
extension point.
The following markup is from the Java tooling:
<extension point = "org.eclipse.debug.core.sourceLocators">
<sourceLocator
id = "org.eclipse.jdt.debug.ui.javaSourceLocator"
class="org.eclipse.jdt.debug.ui.JavaUISourceLocator"
name="%javaSourceLocator"/>
</extension>
Since launch configurations can be persisted, source locator ids may will be stored
with the launch configuration. When it's time to instantiate a source locator, the
debug plug-in looks up the source locator id attribute and instantiates the class associated with
that id.
The implementation for source lookup necessarily depends on the type of program being launched. However, the platform
defines an abstract implementation for a source locator that looks up source files on a given path that includes
directories, zip files, jar files, and the like. To take advantage of this implementation, your plug-in can extend
AbstractSourceLookupDirector.
All that is needed from the specific implementation is the ability to provide an appropriate
ISourceLookupParticipant, which can
map a stack frame to a file name. See the extenders of
AbstractSourceLookupDirector.
for examples.
Source path computers
The
AbstractSourceLookupDirector
searches for source files according to a particular source code lookup path. This path is expressed as an array of
ISourceContainer. The source containers
that should be searched for source are typically computed according to the particulars of the source configuration that is being
launched.
ISourcePathComputer
defines the interface for an object that computes the appropriate source path for a launch configuration. A source path computer,
much like a source locator, is specified by id, and can be specified in the extension definition for a launch configuration type, or
associated programmatically by setting the ISourceLocator.ATTR_SOURCE_PATH_COMPUTER_ID attribute for the launch configuration.
The id for a source path computer is associated with its implementing class in the
org.eclipse.debug.core.sourcePathComputers
extension point. The following markup shows the definition used by JDT for its Java source path computer:
<extension point="org.eclipse.debug.core.sourcePathComputers">
<sourcePathComputer
id="org.eclipse.jdt.launching.sourceLookup.javaSourcePathComputer"
class="org.eclipse.jdt.launching.sourcelookup.containers.JavaSourcePathComputer">
</sourcePathComputer>
...
The source path computer is responsible for computing an array of
ISourceContainer
that represents the source lookup path. For example, the Java source path computer considers the classpath when building the
path.
Source container types
The containers specified as part of a source lookup path must implement
ISourceContainer,
which can search the container represented for a named source element. Different kinds of source containers may be needed to represent the
different kinds of places source code is stored. For example, the JDT defines source containers that represent source in a Java project,
source on the classpath, and source in a package fragment. The source containers used for a launch configuration may be stored by id in
the launch configuration. Since launch configurations can be persisted, there must be a way to associate the id of a source container
with its implementation class. This is done using the
org.eclipse.debug.core.sourceContainerTypes
extension point. The following example comes from the JDT:
<extension point="org.eclipse.debug.core.sourceContainerTypes">
<sourceContainerType
id="org.eclipse.jdt.launching.sourceContainer.javaProject"
name="%javaProjectSourceContainerType.name"
description="%javaProjectSourceContainerType.description"
class="org.eclipse.jdt.internal.launching.JavaProjectSourceContainerTypeDelegate">
</sourceContainerType>
...