Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: 0acafdc6c414b26ee44539687b6c84159f3845c2 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
/*******************************************************************************
 * Copyright (c) 2000, 2006 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.debug.core.sourcelookup;

import org.eclipse.core.runtime.CoreException;
import org.eclipse.debug.core.ILaunchConfiguration;

/**
 * A source lookup director directs the source lookup process
 * among a set of participants and source containers.
 * <p>
 * Clients may implement this interface. An abstract implementation
 * is provided by <code>AbstractSourceLookupDirector</code>, which
 * clients should subclass.
 * </p>
 * @since 3.0
 */
public interface ISourceLookupDirector extends IPersistableSourceLocator2 {

	/**
	 * Returns the launch configuration associated with this source
	 * lookup director, or <code>null</code> if none.
	 *
	 * @return the launch configuration associated with this source
	 * lookup director, or <code>null</code> if none
	 */
	ILaunchConfiguration getLaunchConfiguration();

	/**
	 * Returns the source lookup participants currently registered with
	 * this director, possibly an empty collection.
	 *
	 * @return the source lookup participants currently registered with
	 * this director, possibly an empty collection
	 */
	ISourceLookupParticipant[] getParticipants();

	/**
	 * Returns the source containers currently registered with this
	 * director, possibly an empty collection.
	 *
	 * @return the source containers currently registered with this
	 * director, possibly an empty collection
	 */
	ISourceContainer[] getSourceContainers();

	/**
	 * Sets the source containers this source lookup director
	 * should search when looking for source, possibly an empty collection.
	 *
	 * @param containers the source containers this source lookup director
	 * should search when looking for source, possibly an empty collection
	 */
	void setSourceContainers(ISourceContainer[] containers);

	/**
	 * 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.
	 *
	 * @return whether to search exhaustively for all source elements
	 * with the same name
	 */
	boolean isFindDuplicates();

	/**
	 * 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.
	 *
	 * @param findDuplicates whether to search exhaustively for all source elements
	 * with the same name
	 */
	void setFindDuplicates(boolean findDuplicates);

	/**
	 * Notifies this source lookup director that it should initialize
	 * its set of source lookup participants.
	 */
	void initializeParticipants();

	/**
	 * Returns whether this source director supports the given type
	 * of source location.
	 *
	 * @param type source container type
	 * @return whether this source director supports the given type
	 * of source location
	 */
	boolean supportsSourceContainerType(ISourceContainerType type);

	/**
	 * Clears any source lookup results associated with the given
	 * debug artifact, such that a subsequent lookup will force a new search
	 * to be performed.
	 *
	 * @param element debug artifact to clear source lookup results for
	 */
	void clearSourceElements(Object element);

	/**
	 * Adds the given source lookup participants to this director.
	 *
	 * @param participants participants to add
	 */
	void addParticipants(ISourceLookupParticipant[] participants);

	/**
	 * Removes the given source lookup participants from this director.
	 *
	 * @param participants participants to remove
	 */
	void removeParticipants(ISourceLookupParticipant[] participants);

	/**
	 * Returns the identifier of this type of source locator.
	 *
	 * @return the identifier of this type of source locator
	 */
	String getId();

	/**
	 * Returns the source path computer to use with this source lookup
	 * director, possibly <code>null</code>. 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 <code>setSourcePathComputer(...)</code>.
	 *
	 * @return the source path computer to use with this source lookup
	 *  director, possibly <code>null</code>
	 */
	ISourcePathComputer getSourcePathComputer();

	/**
	 * 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 <code>null</code> is specified
	 * the default source path computer will be used (i.e. the one associated
	 * with this director's launch configuration's type).
	 *
	 * @param computer source path computer or <code>null</code>
	 */
	void setSourcePathComputer(ISourcePathComputer computer);

	/**
	 * 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 <code>isFindDuplicates()</code>.
	 * When <code>false</code> the returned collection should contain at most one
	 * source element.
	 *
	 * @param object the debug artifact for which source needs to be found (e.g., stack frame)
	 * @return a collection of source elements corresponding to the given
	 *  debug artifact, possibly empty
	 * @exception CoreException if an exception occurs while searching for source
	 */
	Object[] findSourceElements(Object object) throws CoreException;

	/**
	 * Returns a source element that corresponds to the given debug artifact, or
	 * <code>null</code> if a source element could not be located. This is a
	 * generalization of <code>getSourceElement(IStackFrame)</code> to allow
	 * source to be found for other types of elements.
	 *
	 * @param element the debug artifact for which to locate source
	 * @return an object representing a source element.
	 */
	 Object getSourceElement(Object element);

}

Back to the top