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
        name="%javaSourceLocatorName"
        class="org.eclipse.jdt.launching.sourcelookup.JavaSourceLocator"
        id="org.eclipse.jdt.launching.javaSourceLocator">
    </sourceLocator>
</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> 
	...