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:
-
ISourceLocator
,
ISourceContainer
,
ISourceContainerType
,
ISourcePathComputer
,
ISourceLookupParticipant
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 element. |
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 void
|
doInitializeFromMemento
(
String memento,
boolean dispose)
Initializes this source lookup director from the given memento. |
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. |
ISourceLookupParticipant
|
getCurrentParticipant
()
Returns the participant currently looking up source or null
if none. |
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 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
|
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
|
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
AbstractSourceLookupDirector
public AbstractSourceLookupDirector()
- Constructs source lookup director
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)
-
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 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 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 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
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.