Package org.eclipse.debug.core.sourcelookup

# Interface ISourceLookupParticipant

All Known Implementing Classes:
  `AbstractSourceLookupParticipant`

public interface ISourceLookupParticipant
A source lookup participant participates in source lookup by searching an ordered list of source containers for source elements corresponding to a debug artifact. For example, a participant may be asked to find source corresponding to a stack frame or breakpoint. An implementation of a source lookup participant is debug model specific, since it must convert the debug model artifact (stack frame, breakpoint, etc.), into a source name that can be recognized by a source container (`ISourceContainer`), to search for source elements. Source containers are generally debug model independent, whereas source lookup participants are debug model specific.

Clients may implement this interface. An abstract implementation is provided by `AbstractSourceLookupParticipant`, which clients should subclass.

Since:
  3.0

## Method Summary

Modifier and Type
Method
Description
`void`
`dispose()`
Disposes this source lookup participant.
`Object[]`
`findSourceElements(Object object)`
Returns a collection of source elements corresponding to the given debug artifact (for example, a stack frame or breakpoint).
`String`
`getSourceName(Object object)`
Returns the source file name associated with the given debug artifact that source needs to be found for, or `null` if none.
`void`
`init(ISourceLookupDirector director)`
Notification this participant has been added to the specified source lookup director.
`void`
`sourceContainersChanged(ISourceLookupDirector director)`
Notification that the source lookup containers in the given source lookup director have changed.

## Method Details

### init

void init(ISourceLookupDirector director)
Notification this participant has been added to the specified source lookup director.

Parameters:
  `director` - the source lookup director that this participant has been added to

### findSourceElements

Object[] findSourceElements(Object object) throws CoreException
Returns a collection of source elements corresponding to the given debug artifact (for example, a stack frame or breakpoint). Returns an empty collection if no source elements are found. This participant's source lookup director specifies if duplicate source elements should be searched for, via `isFindDuplicates()`. When `false` the returned collection should contain at most one source element.

If the given debug artifact is not recognized by this participant, an empty collection is returned. Otherwise, this participant generates a source name from the given artifact and performs a search for associated source elements in its source containers.

Parameters:
  `object` - the debug artifact for which source needs to be found (e.g., stack frame)
Returns:
  a collection of source elements corresponding to the given debug artifact, possibly empty
Throws:
  `CoreException` - if an exception occurs while searching for source

### getSourceName

String getSourceName(Object object) throws CoreException
Returns the source file name associated with the given debug artifact that source needs to be found for, or `null` if none.

Parameters:
  `object` - the debug artifact for which source needs to be found (e.g., stack frame)
Returns:
  the source file name associated with the given debug artifact, or `null` if none.
Throws:
  `CoreException` - if unable to determine a source file name

### dispose

void dispose()
Disposes this source lookup participant. This method is called when the source lookup director associated with this participant is disposed.

### sourceContainersChanged

void sourceContainersChanged(ISourceLookupDirector director)
Notification that the source lookup containers in the given source lookup director have changed.

Parameters:
  `director` - source lookup director that is directing this participant