Package org.eclipse.debug.core.sourcelookup

Class AbstractSourceLookupDirector

java.lang.Object
org.eclipse.debug.core.sourcelookup.AbstractSourceLookupDirector
All Implemented Interfaces:
ILaunchConfigurationListener, ILaunchListener, IPersistableSourceLocator, ISourceLocator, IPersistableSourceLocator2, ISourceLookupDirector
public abstract class AbstractSourceLookupDirector extends Object implements ISourceLookupDirector, ILaunchConfigurationListener, ILaunchListener
Directs source lookup among a collection of source lookup participants, and a common collection of source containers. Each source lookup participant is a source locator itself, which allows more than one source locator to participate in source lookup for a launch. Each source lookup participant searches for source in the source containers managed by this director, and each participant is notified of changes in the source containers (i.e. when the set of source containers changes).

When a source director is initialized, it adds it self as a launch listener, and automatically disposes itself when its associated launch is removed from the launch manager. If a source director is instantiated by a client that is not part of a launch, that client is responsible for disposing the source director.

Clients may subclass this class.

Since:
3.0
See Also:

  • Field Details

  • Constructor Details

    • AbstractSourceLookupDirector

      public AbstractSourceLookupDirector()
      Constructs source lookup director

  • Method Details

    • setId

      public void setId(String id)
      Sets the type identifier for this source locator's type
      Parameters:
      id - corresponds to source locator type identifier for a persistable source locator

    • dispose

      public void dispose()
      Description copied from interface: IPersistableSourceLocator2
      Disposes this source locator. This method is called when a source locator's associated launch is removed from the launch manager.
      Specified by:
      dispose in interface IPersistableSourceLocator2

    • abort

      protected void abort(String message, Throwable exception) throws CoreException
      Throws an exception with the given message and underlying exception.
      Parameters:
      message - error message
      exception - underlying exception, or null
      Throws:
      CoreException - if a problem is encountered

    • getSourceContainers

      public ISourceContainer[] getSourceContainers()
      Description copied from interface: ISourceLookupDirector
      Returns the source containers currently registered with this director, possibly an empty collection.
      Specified by:
      getSourceContainers in interface ISourceLookupDirector
      Returns:
      the source containers currently registered with this director, possibly an empty collection

    • isFindDuplicates

      public boolean isFindDuplicates()
      Description copied from interface: ISourceLookupDirector
      Returns whether to search exhaustively for all source elements with the same name in all registered source containers, or whether to stop searching when the first source element matching the required name is found.
      Specified by:
      isFindDuplicates in interface ISourceLookupDirector
      Returns:
      whether to search exhaustively for all source elements with the same name

    • setFindDuplicates

      public void setFindDuplicates(boolean duplicates)
      Description copied from interface: ISourceLookupDirector
      Sets whether to search exhaustively for all source elements with the same name in all registered source containers, or whether to stop searching when the first source element matching the required name is found.
      Specified by:
      setFindDuplicates in interface ISourceLookupDirector
      Parameters:
      duplicates - whether to search exhaustively for all source elements with the same name

    • launchConfigurationAdded

      public void launchConfigurationAdded(ILaunchConfiguration configuration)
      Description copied from interface: ILaunchConfigurationListener
      The given launch configuration has been created.
      Specified by:
      launchConfigurationAdded in interface ILaunchConfigurationListener
      Parameters:
      configuration - the newly created launch configuration

    • launchConfigurationChanged

      public void launchConfigurationChanged(ILaunchConfiguration configuration)
      Description copied from interface: ILaunchConfigurationListener
      The given launch configuration has changed in some way. The configuration may be a working copy.
      Specified by:
      launchConfigurationChanged in interface ILaunchConfigurationListener
      Parameters:
      configuration - the launch configuration that has changed

    • launchConfigurationRemoved

      public void launchConfigurationRemoved(ILaunchConfiguration configuration)
      Description copied from interface: ILaunchConfigurationListener
      The given launch configuration has been deleted.

      The launch configuration no longer exists. Data stored in the configuration can no longer be accessed, however handle-only attributes of the launch configuration can be retrieved.

      Specified by:
      launchConfigurationRemoved in interface ILaunchConfigurationListener
      Parameters:
      configuration - the deleted launch configuration

    • getMemento

      public String getMemento() throws CoreException
      Description copied from interface: IPersistableSourceLocator
      Returns a memento that can be used to reconstruct this source locator
      Specified by:
      getMemento in interface IPersistableSourceLocator
      Returns:
      a memento that can be used to reconstruct this source locator
      Throws:
      CoreException - if unable to construct a memento

    • initializeFromMemento

      public void initializeFromMemento(String memento) throws CoreException
      Description copied from interface: IPersistableSourceLocator
      Initializes this source locator based on the given memento.
      Specified by:
      initializeFromMemento in interface IPersistableSourceLocator
      Parameters:
      memento - a memento to initialize this source locator
      Throws:
      CoreException - on failure to initialize

    • doInitializeFromMemento

      protected void doInitializeFromMemento(String memento, boolean dispose) throws CoreException
      Initializes this source lookup director from the given memento. Disposes itself before initialization if specified.
      Parameters:
      memento - source locator memento
      dispose - whether to dispose any current source containers and participants before initializing
      Throws:
      CoreException - if an exception occurs during initialization
      Since:
      3.1

    • setSourceContainers

      public void setSourceContainers(ISourceContainer[] containers)
      Sets the source containers used by this source lookup director.
      Specified by:
      setSourceContainers in interface ISourceLookupDirector
      Parameters:
      containers - source containers to search

    • getSourceElement

      public Object getSourceElement(IStackFrame stackFrame)
      Description copied from interface: ISourceLocator
      Returns a source element that corresponds to the given stack frame, or null if a source element could not be located. The object returned by this method will be used by the debug UI plug-in to display source. The debug UI uses the debug model presentation associated with the given stack frame's debug model to translate a source object into an {editor input, editor id} pair in which to display source.

      For example, a java source locator could return an object representing a compilation unit or class file. The java debug model presentation would then be responsible for providing an editor input and editor id for each compilation unit and class file such that the debug UI could display source.

      Specified by:
      getSourceElement in interface ISourceLocator
      Parameters:
      stackFrame - the stack frame for which to locate source
      Returns:
      an object representing a source element.

    • doSourceLookup

      protected List<Object> doSourceLookup(Object element)
      Performs a source lookup query for the given element returning the source elements associated with the element.
      Parameters:
      element - stack frame
      Returns:
      list of associated source elements

    • resolveSourceElement

      public Object resolveSourceElement(Object element, List<Object> sources)
      Returns the source element to associate with the given element. This method is called when more than one source element has been found for an element, and allows the source director to select a single source element to associate with the element.

      Subclasses should override this method as appropriate. For example, to prompt the user to choose a source element.

      Parameters:
      element - the debug artifact for which source is being searched for
      sources - the source elements found for the given element
      Returns:
      a single source element for the given element

    • initializeFromMemento

      public void initializeFromMemento(String memento, ILaunchConfiguration configuration) throws CoreException
      Description copied from interface: IPersistableSourceLocator2
      Initializes this source locator based on the given memento, for the given launch configuration. This method is called instead of initializeFrom(String memento) defined in IPersistableSourceLocator when a source locator implements this interface.
      Specified by:
      initializeFromMemento in interface IPersistableSourceLocator2
      Parameters:
      memento - a memento to initialize this source locator
      configuration - the launch configuration this source locator is being created for
      Throws:
      CoreException - on failure to initialize

    • initializeDefaults

      public void initializeDefaults(ILaunchConfiguration configuration) throws CoreException
      Description copied from interface: IPersistableSourceLocator
      Initializes this source locator to perform default source lookup for the given launch configuration.
      Specified by:
      initializeDefaults in interface IPersistableSourceLocator
      Parameters:
      configuration - launch configuration this source locator will be performing source lookup for
      Throws:
      CoreException - on failure to initialize

    • getLaunchConfiguration

      public ILaunchConfiguration getLaunchConfiguration()
      Description copied from interface: ISourceLookupDirector
      Returns the launch configuration associated with this source lookup director, or null if none.
      Specified by:
      getLaunchConfiguration in interface ISourceLookupDirector
      Returns:
      the launch configuration associated with this source lookup director, or null if none

    • setLaunchConfiguration

      protected void setLaunchConfiguration(ILaunchConfiguration configuration)
      Sets the launch configuration associated with this source lookup director. If the given configuration is a working copy, this director will respond to changes the working copy. If the given configuration is a persisted launch configuration, this director will respond to changes in the persisted launch configuration.
      Parameters:
      configuration - launch configuration to associate with this source lookup director, or null if none

    • launchAdded

      public void launchAdded(ILaunch launch)
      Description copied from interface: ILaunchListener
      Notifies this listener that the specified launch has been added.
      Specified by:
      launchAdded in interface ILaunchListener
      Parameters:
      launch - the newly added launch

    • launchChanged

      public void launchChanged(ILaunch launch)
      Description copied from interface: ILaunchListener
      Notifies this listener that the specified launch has changed. For example, a process or debug target has been added to the launch.
      Specified by:
      launchChanged in interface ILaunchListener
      Parameters:
      launch - the changed launch

    • launchRemoved

      public void launchRemoved(ILaunch launch)
      Description copied from interface: ILaunchListener
      Notifies this listener that the specified launch has been removed.
      Specified by:
      launchRemoved in interface ILaunchListener
      Parameters:
      launch - the removed launch

    • getParticipants

      public ISourceLookupParticipant[] getParticipants()
      Description copied from interface: ISourceLookupDirector
      Returns the source lookup participants currently registered with this director, possibly an empty collection.
      Specified by:
      getParticipants in interface ISourceLookupDirector
      Returns:
      the source lookup participants currently registered with this director, possibly an empty collection

    • supportsSourceContainerType

      public boolean supportsSourceContainerType(ISourceContainerType type)
      Description copied from interface: ISourceLookupDirector
      Returns whether this source director supports the given type of source location.
      Specified by:
      supportsSourceContainerType in interface ISourceLookupDirector
      Parameters:
      type - source container type
      Returns:
      whether this source director supports the given type of source location

    • cacheResolvedElement

      protected void cacheResolvedElement(List<Object> duplicates, Object sourceElement)
      Caches the resolved source element to use when one of the following duplicates is found.
      Parameters:
      duplicates - duplicates source elements
      sourceElement - chosen source element to use in place of the duplicates

    • getCachedElement

      protected Object getCachedElement(Object duplicate)
      Returns the cached source element to use when the given duplicate is encountered.
      Parameters:
      duplicate - duplicates source element
      Returns:
      element to use in the duplicate's place

    • clearCachedElement

      protected void clearCachedElement(Object duplicate)
      Clears any cached source element associated with the given duplicate is source element.
      Parameters:
      duplicate - duplicate source element to cache resolved results for

    • clearSourceElements

      public void clearSourceElements(Object element)
      Description copied from interface: ISourceLookupDirector
      Clears any source lookup results associated with the given debug artifact, such that a subsequent lookup will force a new search to be performed.
      Specified by:
      clearSourceElements in interface ISourceLookupDirector
      Parameters:
      element - debug artifact to clear source lookup results for

    • addParticipants

      public void addParticipants(ISourceLookupParticipant[] participants)
      Description copied from interface: ISourceLookupDirector
      Adds the given source lookup participants to this director.
      Specified by:
      addParticipants in interface ISourceLookupDirector
      Parameters:
      participants - participants to add

    • removeParticipants

      public void removeParticipants(ISourceLookupParticipant[] participants)
      Description copied from interface: ISourceLookupDirector
      Removes the given source lookup participants from this director.
      Specified by:
      removeParticipants in interface ISourceLookupDirector
      Parameters:
      participants - participants to remove

    • getId

      public String getId()
      Description copied from interface: ISourceLookupDirector
      Returns the identifier of this type of source locator.
      Specified by:
      getId in interface ISourceLookupDirector
      Returns:
      the identifier of this type of source locator

    • getSourcePathComputer

      public ISourcePathComputer getSourcePathComputer()
      Description copied from interface: ISourceLookupDirector
      Returns the source path computer to use with this source lookup director, possibly null. By default, the source path computer returned is the one associated with this director's launch configuration's type. However, the source path computer can be specified programmatically by calling setSourcePathComputer(...).
      Specified by:
      getSourcePathComputer in interface ISourceLookupDirector
      Returns:
      the source path computer to use with this source lookup director, possibly null

    • setSourcePathComputer

      public void setSourcePathComputer(ISourcePathComputer computer)
      Description copied from interface: ISourceLookupDirector
      Sets the source path computer for this source lookup director. This method can be used to override the default source path computer for a launch configuration type. When null is specified the default source path computer will be used (i.e. the one associated with this director's launch configuration's type).
      Specified by:
      setSourcePathComputer in interface ISourceLookupDirector
      Parameters:
      computer - source path computer or null

    • findSourceElements

      public Object[] findSourceElements(Object object) throws CoreException
      Description copied from interface: ISourceLookupDirector
      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.
      Specified by:
      findSourceElements in interface ISourceLookupDirector
      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

    • getSourceElement

      public Object getSourceElement(Object element)
      Description copied from interface: ISourceLookupDirector
      Returns a source element that corresponds to the given debug artifact, or null if a source element could not be located. This is a generalization of getSourceElement(IStackFrame) to allow source to be found for other types of elements.
      Specified by:
      getSourceElement in interface ISourceLookupDirector
      Parameters:
      element - the debug artifact for which to locate source
      Returns:
      an object representing a source element.

    • getCurrentParticipant

      public ISourceLookupParticipant getCurrentParticipant()
      Returns the participant currently looking up source or null if none.
      Returns:
      the participant currently looking up source or null if none
      Since:
      3.5