ISourceLookupDirector


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