Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.eclipse.debug.core.sourcelookup
Class AbstractSourceLookupDirector

    java.lang.Object
      org.eclipse.debug.core.sourcelookup.AbstractSourceLookupDirector

All Implemented Interfaces:
  ILaunchConfigurationListener, ILaunchListener, IPersistableSourceLocator, IPersistableSourceLocator2, ISourceLocator, 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 intilaized, 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.

This class is yet experimental.

Clients may subclass this class.

Since:
  3.0
See Also:
  `ISourceLocator`, `ISourceContainer`, `ISourceContainerType`, `ISourcePathComputer`, `ISourceLookupParticipant`

Field Summary
`protected static String` | `CONTAINER_MEMENTO_ATTR`
`protected static String` | `CONTAINER_NODE`
`protected static String` | `CONTAINER_TYPE_ATTR`
`protected static String` | `CONTAINERS_NODE`
`protected static String` | `DIRECTOR_ROOT_NODE`
`protected static String` | `DUPLICATES_ATTR`
`protected ISourcePathComputer` | `fComputer`
`protected ILaunchConfiguration` | `fConfig`
`protected boolean` | `fDuplicates`
`protected String` | `fId`
`protected ArrayList` | `fParticipants`
`protected static IStatus` | `fPromptStatus`
`protected Map` | `fResolvedElements` Cache of resolved source elements when duplicates exist.
`protected static IStatus` | `fResolveDuplicatesStatus`
`protected ISourceContainer[]` | `fSourceContainers`

Constructor Summary
`AbstractSourceLookupDirector()` Constructs source lookup director

Method Summary
`protected void` | `abort(String message, Throwable exception)` Throws an exception with the given message and underlying exception.
`void` | `addParticipants(ISourceLookupParticipant[] participants)` Adds the given source lookup participants to this director.
`protected void` | `cacheResolvedElement(List duplicates, Object sourceElement)` Caches the resolved source element to use when one of the following duplicates is found.
`protected void` | `clearCachedElement(Object duplicate)` Clears any cached source element associated with the given duplicate is source elemnet.
`void` | `clearSourceElements(Object element)` Clears any source lookup results associated with the given debug artifact, such that a subsequent lookup will force a new search to be performed.
`void` | `dispose()` Disposes this source locator.
`protected List` | `doSourceLookup(Object element)` Performs a source lookup query for the given element returning the source elements associated with the element.
`Object[]` | `findSourceElements(Object object)` Returns a collection of source elements corresponding to the given debug artifact (for example, a stack frame or breakpoint).
`protected Object` | `getCachedElement(Object duplicate)` Returns the cached source element to use when the given duplicate is encountered.
`String` | `getId()` Returns the identifier of this type of source locator.
`ILaunchConfiguration` | `getLaunchConfiguration()` Returns the launch configuration associated with this source lookup director, or `null` if none.
`String` | `getMemento()` Returns a memento that can be used to reconstruct this source locator
`ISourceLookupParticipant[]` | `getParticipants()` Returns the source lookup participants currently registered with this director, possibly an empty collection.
`ISourceContainer[]` | `getSourceContainers()` Returns the source containers currently registered with this director, possibly an empty collection.
`Object` | `getSourceElement(IStackFrame stackFrame)` Returns a source element that corresponds to the given stack frame, or `null` if a source element could not be located.
`Object` | `getSourceElement(Object element)` Returns a source element that corresponds to the given debug artifact, or `null` if a source element could not be located.
`ISourcePathComputer` | `getSourcePathComputer()` Returns the source path computer to use with this source lookup director, possibly `null`.
`void` | `initializeDefaults(ILaunchConfiguration configuration)` Initializes this source locator to perform default source lookup for the given launch configuration.
`void` | `initializeFromMemento(String memento)` Initializes this source locator based on the given memento.
`void` | `initializeFromMemento(String memento, ILaunchConfiguration configuration)` Initializes this source locator based on the given memento, for the given launch configuration.
`boolean` | `isFindDuplicates()` 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.
`void` | `launchAdded(ILaunch launch)` Notifies this listener that the specified launch has been added.
`void` | `launchChanged(ILaunch launch)` Notifies this listener that the specified launch has changed.
`void` | `launchConfigurationAdded(ILaunchConfiguration configuration)` The given launch configuration has been created.
`void` | `launchConfigurationChanged(ILaunchConfiguration configuration)` The given launch configuration has changed in some way.
`void` | `launchConfigurationRemoved(ILaunchConfiguration configuration)` The given launch configuration has been deleted.
`void` | `launchRemoved(ILaunch launch)` Notifies this listener that the specified launch has been removed.
`void` | `removeParticipants(ISourceLookupParticipant[] participants)` Removes the given source lookup participants from this director.
`Object` | `resolveSourceElement(Object element, List sources)` Returns the source element to associate with the given element.
`void` | `setFindDuplicates(boolean duplicates)` Sets whether source containers should be searched exhaustively for applicable source elements or if only the first match should be located.
`void` | `setId(String id)` Sets the type identifier for this source locator's type
`protected void` | `setLaunchConfiguration(ILaunchConfiguration configuration)` Sets the launch configuration associated with this source lookup director.
`void` | `setSourceContainers(ISourceContainer[] containers)` Sets the source containers used by this source lookup director.
`void` | `setSourcePathComputer(ISourcePathComputer computer)` Sets the source path computer for this source lookup director.
`boolean` | `supportsSourceContainerType(ISourceContainerType type)` Returns whether this source director supports the given type of source location.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface org.eclipse.debug.core.sourcelookup.ISourceLookupDirector
`initializeParticipants`

Field Detail

### fId

    protected String fId

### fParticipants

    protected ArrayList fParticipants

### fSourceContainers

    protected ISourceContainer[] fSourceContainers

### fConfig

    protected ILaunchConfiguration fConfig

### fDuplicates

    protected boolean fDuplicates

### fComputer

    protected ISourcePathComputer fComputer

### fResolvedElements

    protected Map fResolvedElements

  Cache of resolved source elements when duplicates exist. Keys are the duplicates, values are the source element to use.

### fPromptStatus

    protected static final IStatus fPromptStatus

### fResolveDuplicatesStatus

    protected static final IStatus fResolveDuplicatesStatus

### DIRECTOR_ROOT_NODE

    protected static final String DIRECTOR_ROOT_NODE

See Also:
  Constant Field Values

### CONTAINERS_NODE

    protected static final String CONTAINERS_NODE

See Also:
  Constant Field Values

### DUPLICATES_ATTR

    protected static final String DUPLICATES_ATTR

See Also:
  Constant Field Values

### CONTAINER_NODE

    protected static final String CONTAINER_NODE

See Also:
  Constant Field Values

### CONTAINER_TYPE_ATTR

    protected static final String CONTAINER_TYPE_ATTR

See Also:
  Constant Field Values

### CONTAINER_MEMENTO_ATTR

    protected static final String CONTAINER_MEMENTO_ATTR

See Also:
  Constant Field Values

Constructor Detail

### AbstractSourceLookupDirector

    public AbstractSourceLookupDirector()

  Constructs source lookup director

Method Detail

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

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

  Sets whether source containers should be searched exhaustively for applicable source elements or if only the first match should be located.

  Specified by:
    `setFindDuplicates` in interface `ISourceLookupDirector`
  Parameters:
    `duplicates` - whether source containers should be searched exhaustively for applicable source elements or if only the first match should be located

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

  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

### 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 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 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 souce 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 configration, 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 duplicates,
                                        Object sourceElement)

  Caches the resolved source element to use when one of the following duplicates is found.

  Parameters:
    `duplicates` - duplicates source elemnets
    `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 elemnet.

  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 assocaited 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 occurrs 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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.