1 /******************************************************************************* 2 * Copyright (c) 2000, 2006 IBM Corporation and others. 3 * 4 * This program and the accompanying materials 5 * are made available under the terms of the Eclipse Public License 2.0 6 * which accompanies this distribution, and is available at 7 * https://www.eclipse.org/legal/epl-2.0/ 8 * 9 * SPDX-License-Identifier: EPL-2.0 10 * 11 * Contributors: 12 * IBM Corporation - initial API and implementation 13 *******************************************************************************/ 14 package org.eclipse.debug.core.sourcelookup; 15 16 import org.eclipse.core.runtime.CoreException; 17 import org.eclipse.debug.core.ILaunchConfiguration; 18 19 /** 20 * A source lookup director directs the source lookup process 21 * among a set of participants and source containers. 22 * <p> 23 * Clients may implement this interface. An abstract implementation 24 * is provided by <code>AbstractSourceLookupDirector</code>, which 25 * clients should subclass. 26 * </p> 27 * @since 3.0 28 */ 29 public interface ISourceLookupDirector extends IPersistableSourceLocator2 { 30 31 /** 32 * Returns the launch configuration associated with this source 33 * lookup director, or <code>null</code> if none. 34 * 35 * @return the launch configuration associated with this source 36 * lookup director, or <code>null</code> if none 37 */ getLaunchConfiguration()38 ILaunchConfiguration getLaunchConfiguration(); 39 40 /** 41 * Returns the source lookup participants currently registered with 42 * this director, possibly an empty collection. 43 * 44 * @return the source lookup participants currently registered with 45 * this director, possibly an empty collection 46 */ getParticipants()47 ISourceLookupParticipant[] getParticipants(); 48 49 /** 50 * Returns the source containers currently registered with this 51 * director, possibly an empty collection. 52 * 53 * @return the source containers currently registered with this 54 * director, possibly an empty collection 55 */ getSourceContainers()56 ISourceContainer[] getSourceContainers(); 57 58 /** 59 * Sets the source containers this source lookup director 60 * should search when looking for source, possibly an empty collection. 61 * 62 * @param containers the source containers this source lookup director 63 * should search when looking for source, possibly an empty collection 64 */ setSourceContainers(ISourceContainer[] containers)65 void setSourceContainers(ISourceContainer[] containers); 66 67 /** 68 * Returns whether to search exhaustively for all source elements 69 * with the same name in all registered source containers, or 70 * whether to stop searching when the first source element matching 71 * the required name is found. 72 * 73 * @return whether to search exhaustively for all source elements 74 * with the same name 75 */ isFindDuplicates()76 boolean isFindDuplicates(); 77 78 /** 79 * Sets whether to search exhaustively for all source elements 80 * with the same name in all registered source containers, or 81 * whether to stop searching when the first source element matching 82 * the required name is found. 83 * 84 * @param findDuplicates whether to search exhaustively for all source elements 85 * with the same name 86 */ setFindDuplicates(boolean findDuplicates)87 void setFindDuplicates(boolean findDuplicates); 88 89 /** 90 * Notifies this source lookup director that it should initialize 91 * its set of source lookup participants. 92 */ initializeParticipants()93 void initializeParticipants(); 94 95 /** 96 * Returns whether this source director supports the given type 97 * of source location. 98 * 99 * @param type source container type 100 * @return whether this source director supports the given type 101 * of source location 102 */ supportsSourceContainerType(ISourceContainerType type)103 boolean supportsSourceContainerType(ISourceContainerType type); 104 105 /** 106 * Clears any source lookup results associated with the given 107 * debug artifact, such that a subsequent lookup will force a new search 108 * to be performed. 109 * 110 * @param element debug artifact to clear source lookup results for 111 */ clearSourceElements(Object element)112 void clearSourceElements(Object element); 113 114 /** 115 * Adds the given source lookup participants to this director. 116 * 117 * @param participants participants to add 118 */ addParticipants(ISourceLookupParticipant[] participants)119 void addParticipants(ISourceLookupParticipant[] participants); 120 121 /** 122 * Removes the given source lookup participants from this director. 123 * 124 * @param participants participants to remove 125 */ removeParticipants(ISourceLookupParticipant[] participants)126 void removeParticipants(ISourceLookupParticipant[] participants); 127 128 /** 129 * Returns the identifier of this type of source locator. 130 * 131 * @return the identifier of this type of source locator 132 */ getId()133 String getId(); 134 135 /** 136 * Returns the source path computer to use with this source lookup 137 * director, possibly <code>null</code>. By default, the source path 138 * computer returned is the one associated with this director's launch 139 * configuration's type. However, the source path computer can be specified 140 * programmatically by calling <code>setSourcePathComputer(...)</code>. 141 * 142 * @return the source path computer to use with this source lookup 143 * director, possibly <code>null</code> 144 */ getSourcePathComputer()145 ISourcePathComputer getSourcePathComputer(); 146 147 /** 148 * Sets the source path computer for this source lookup director. 149 * This method can be used to override the default source path computer 150 * for a launch configuration type. When <code>null</code> is specified 151 * the default source path computer will be used (i.e. the one associated 152 * with this director's launch configuration's type). 153 * 154 * @param computer source path computer or <code>null</code> 155 */ setSourcePathComputer(ISourcePathComputer computer)156 void setSourcePathComputer(ISourcePathComputer computer); 157 158 /** 159 * Returns a collection of source elements corresponding to the given debug 160 * artifact (for example, a stack frame or breakpoint). Returns an empty 161 * collection if no source elements are found. 162 * This participant's source lookup director specifies if duplicate 163 * source elements should be searched for, via <code>isFindDuplicates()</code>. 164 * When <code>false</code> the returned collection should contain at most one 165 * source element. 166 * 167 * @param object the debug artifact for which source needs to be found (e.g., stack frame) 168 * @return a collection of source elements corresponding to the given 169 * debug artifact, possibly empty 170 * @exception CoreException if an exception occurs while searching for source 171 */ findSourceElements(Object object)172 Object[] findSourceElements(Object object) throws CoreException; 173 174 /** 175 * Returns a source element that corresponds to the given debug artifact, or 176 * <code>null</code> if a source element could not be located. This is a 177 * generalization of <code>getSourceElement(IStackFrame)</code> to allow 178 * source to be found for other types of elements. 179 * 180 * @param element the debug artifact for which to locate source 181 * @return an object representing a source element. 182 */ getSourceElement(Object element)183 Object getSourceElement(Object element); 184 185 } 186