Eclipse Platform Release 3.7

## 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
`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 Detail

### 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

Eclipse Platform Release 3.7

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2011. All rights reserved.